BCryptOpenAlgorithmProvider 関数 (bcrypt.h)

  • [アーティクル]

BCryptOpenAlgorithmProvider 関数は、CNG プロバイダーを読み込んで初期化します。

構文

NTSTATUS BCryptOpenAlgorithmProvider(
  [out] BCRYPT_ALG_HANDLE *phAlgorithm,
  [in]  LPCWSTR           pszAlgId,
  [in]  LPCWSTR           pszImplementation,
  [in]  ULONG             dwFlags
);

パラメーター

[out] phAlgorithm

CNG プロバイダー ハンドルを受け取る BCRYPT_ALG_HANDLE 変数へのポインター。 このハンドルの使用が完了したら、 BCryptCloseAlgorithmProvider 関数に渡して解放します。

[in] pszAlgId

要求された暗号化アルゴリズムを識別する null で終わる Unicode 文字列へのポインター。 これには、標準の CNG アルゴリズム識別子 の 1 つ、または別の登録済みアルゴリズムの識別子を指定できます。

[in] pszImplementation

読み込む特定のプロバイダーを識別する null で終わる Unicode 文字列へのポインター。 これは、暗号化プリミティブ プロバイダーの登録済みエイリアスです。 このパラメーターは省略可能であり、必要ない場合は NULL にすることができます 。 このパラメーターが NULL の場合、指定したアルゴリズムの既定のプロバイダーが読み込まれます。

メモpszImplementation パラメーター値が NULL の場合、CNG は pszAlgId パラメーターで指定されたアルゴリズムに対して、登録されている各プロバイダーを優先度順に開こうとし、正常に開かれた最初のプロバイダーのハンドルを返します。 ハンドルの有効期間中、BCrypt*** 暗号化 API では、正常に開かれたプロバイダーが使用されます。
 
Windows Server 2008 と Windows Vista: CNG は、Microsoft CNG プロバイダーにフォールバックしようとします。

定義済みのプロバイダー名を次に示します。

値 意味
MS_PRIMITIVE_PROVIDER
"Microsoft プリミティブ プロバイダー"
 基本的な Microsoft CNG プロバイダーを識別します。
MS_PLATFORM_CRYPTO_PROVIDER
L"Microsoft Platform Crypto Provider"
 Microsoft によって提供される TPM キー ストレージ プロバイダーを識別します。

[in] dwFlags

関数の動作を変更するフラグ。 これは、0 または次の値の 1 つ以上の組み合わせにすることができます。

値 意味
BCRYPT_ALG_HANDLE_HMAC_FLAG
 プロバイダーは、指定されたハッシュ アルゴリズムを使用して ハッシュ ベースのメッセージ認証コード (HMAC) アルゴリズムを実行します。 このフラグは、ハッシュ アルゴリズム プロバイダーによってのみ使用されます。
BCRYPT_PROV_DISPATCH
 非ページ メモリ プールにプロバイダーを読み込みます。 このフラグが存在しない場合、プロバイダーはページ メモリ プールに読み込まれます。 このフラグを指定した場合、すべての依存オブジェクトが解放される前に、返されるハンドルを閉じてはなりません。
メモ このフラグはカーネル モードでのみサポートされ、プロバイダーに対する後続の操作をディスパッチ レベルで処理できます。 プロバイダーがディスパッチ レベルでの呼び出しをサポートしていない場合は、このフラグを使用して開いたときにエラーが返されます。
 
Windows Server 2008 と Windows Vista: このフラグは、Microsoft アルゴリズム プロバイダーによってのみサポートされ、 ハッシュ アルゴリズム と 対称キー暗号化アルゴリズムでのみサポートされます。
BCRYPT_HASH_REUSABLE_FLAG
 再利用可能なハッシュ オブジェクトを作成します。 オブジェクトは、 BCryptFinishHash を呼び出した直後に新しいハッシュ操作に使用できます。 詳細については、「 CNG を使用したハッシュの作成」を参照してください。

Windows Server 2008 R2、Windows 7、Windows Server 2008、Windows Vista: このフラグはサポートされていません。

戻り値

関数の成功または失敗を示す状態コードを返します。

可能なリターン コードには、次のものが含まれますが、これらに限定されません。

リターン コード 説明
STATUS_SUCCESS
 関数は成功しました。
STATUS_NOT_FOUND
 指定したアルゴリズム ID のプロバイダーが見つかりませんでした。
STATUS_INVALID_PARAMETER
 1 つ以上のパラメーターが無効です。
STATUS_NO_MEMORY
 メモリ割り当てエラーが発生しました。

注釈

アルゴリズム プロバイダーを検索、読み込み、初期化するために必要な操作の数と種類により、 BCryptOpenAlgorithmProvider 関数は比較的時間のかかる関数です。 このため、アルゴリズム プロバイダーを何度も開いたり閉じたりするのではなく、複数回使用するアルゴリズム プロバイダー ハンドルをキャッシュすることをお勧めします。

BCryptOpenAlgorithmProvider は、ユーザー モードまたはカーネル モードから呼び出すことができます。 カーネル モードの呼び出し元は、PASSIVE_LEVEL IRQL で実行されている必要があります。

カーネル モードでこの関数を呼び出すには、ドライバー開発キット (DDK) の一部である Cng.lib を使用します。 Windows Server 2008 と Windows Vista: カーネル モードでこの関数を呼び出すには、Ksecdd.lib を使用します。

Windows 10以降、CNG は暗号化構成のすべての更新に従う必要がなくなりました。 新しい既定のプロバイダーの追加やアルゴリズム プロバイダーの優先順位の変更など、特定の変更には再起動が必要な場合があります。 このため、新しく構成されたプロバイダーで BCryptOpenAlgorithmProvider を 呼び出す前に再起動する必要があります。

要件

要件 値
サポートされている最小のクライアント Windows Vista [デスクトップ アプリのみ | UWP アプリ]
サポートされている最小のサーバー Windows Server 2008 [デスクトップ アプリ | UWP アプリ]
対象プラットフォーム Windows
ヘッダー bcrypt.h
Library Bcrypt.lib
[DLL] Bcrypt.dll

こちらもご覧ください

BCryptCloseAlgorithmProvider