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 アルゴリズム識別子 のいずれか、または別の登録済みアルゴリズムの識別子です。

[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
 プロバイダーは、指定されたハッシュ アルゴリズムを使用して Hash-Based Message Authentication Code (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_LEVELIRQLで実行されている必要があります。

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

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

必要条件

要件 価値
サポートされる最小クライアント Windows Vista [デスクトップ アプリ |UWP アプリ]
サポートされる最小サーバー Windows Server 2008 [デスクトップ アプリ |UWP アプリ]
ターゲット プラットフォーム の ウィンドウズ
ヘッダー bcrypt.h
ライブラリ Bcrypt.lib
DLL Bcrypt.dll

関連項目

BCryptCloseAlgorithmProvider の