ホーム › Security.Cryptography › BCryptGenerateKeyPairFn

BCryptGenerateKeyPairFn

コールバック

シグネチャ

NTSTATUS BCryptGenerateKeyPairFn(
    BCRYPT_ALG_HANDLE hAlgorithm,
    BCRYPT_KEY_HANDLE* phKey,
    DWORD dwLength,
    DWORD dwFlags
);

パラメーター

フィールド

型

説明

hAlgorithm

BCRYPT_ALG_HANDLE

非対称キーのペアを使用するアルゴリズムプロバイダーのハンドルです。アルゴリズムの種類の例としては、署名、非対称暗号化、キー合意、キーカプセル化メカニズムなどがあります。このハンドルは BCryptOpenAlgorithmProvider 関数を呼び出して取得します。また、CNG アルゴリズム疑似ハンドルの場合もあります。

phKey

BCRYPT_KEY_HANDLE*

キーのハンドルを受け取る BCRYPT_KEY_HANDLE へのポインターです。このハンドルは、BCryptEncrypt のようにキーを必要とする後続の関数で使用します。このハンドルが不要になったら、BCryptDestroyKey 関数に渡して解放する必要があります。

dwLength

DWORD

キーの長さ(ビット単位)です。アルゴリズムプロバイダーは、標準的な非対称アルゴリズムごとに異なるキーサイズの制限を持ちます。

アルゴリズム識別子	意味
BCRYPT_DH_ALGORITHM	キーサイズは 512 ビット以上 4096 ビット以下で、かつ 64 の倍数である必要があります。
BCRYPT_DSA_ALGORITHM	Windows 8 より前では、キーサイズは 512 ビット以上 1024 ビット以下で、かつ 64 の倍数である必要があります。 Windows 8 以降では、キーサイズは 512 ビット以上 3072 ビット以下で、かつ 64 の倍数である必要があります。1024 ビット以下のキーサイズの処理は FIPS 186-2 に準拠します。1024 ビットより大きく 3072 ビット以下のキーサイズの処理は FIPS 186-3 に準拠します。
BCRYPT_ECDH_P256_ALGORITHM	キーサイズは 256 ビットである必要があります。
BCRYPT_ECDH_P384_ALGORITHM	キーサイズは 384 ビットである必要があります。
BCRYPT_ECDH_P521_ALGORITHM	キーサイズは 521 ビットである必要があります。
BCRYPT_ECDSA_P256_ALGORITHM	キーサイズは 256 ビットである必要があります。
BCRYPT_ECDSA_P384_ALGORITHM	キーサイズは 384 ビットである必要があります。
BCRYPT_ECDSA_P521_ALGORITHM	キーサイズは 521 ビットである必要があります。
BCRYPT_MLDSA_ALGORITHM	キーサイズは 0 である必要があります。 ML-DSA では、BCryptSetProperty と BCRYPT_PARAMETER_SET_NAME を使用して、キーのパラメーターセットを指定します。これは、BCryptFinalizeKeyPair でキーを確定する前に行う必要があります。 Windows Insiders (build 27843): ML-DSA のサポートが開始されます。
BCRYPT_MLKEM_ALGORITHM	キーサイズは 0 である必要があります。 ML-KEM では、BCryptSetProperty と BCRYPT_PARAMETER_SET_NAME を使用して、キーのパラメーターセットを指定します。これは、BCryptFinalizeKeyPair でキーを確定する前に行う必要があります。 Windows Insiders (build 27843): ML-KEM のサポートが開始されます。
BCRYPT_RSA_ALGORITHM	キーサイズは 512 ビット以上 16384 ビット以下で、かつ 64 の倍数である必要があります。

dwFlags

DWORD

この関数の動作を変更するフラグのセットです。使用できるフラグのセットは、hAlgorithm パラメーターで指定されたアルゴリズムによって異なります。

ゼロ、または次の値を指定できます。

値	意味
BCRYPT_NO_KEY_VALIDATION	キー生成時に適用される FIPS セルフテストをオプトアウトします。注: 現在は ML-KEM でのみサポートされています。 Windows Insiders (build 27843): ML-KEM のサポートが開始されます。

公式ドキュメント

BCryptGenerateKeyPair 関数は、空の公開キー/秘密キーのペアを作成します。この関数でキーを作成した後、BCryptSetProperty 関数を使用してそのプロパティを設定できます。ただし、BCryptFinalizeKeyPair 関数が呼び出されるまで、そのキーは使用できません。

戻り値

関数の成功または失敗を示すステータスコードを返します。

返される可能性のあるコードには、次のものが含まれます(ただし、これらに限定されません)。

戻り値	説明
STATUS_SUCCESS	関数は成功しました。
STATUS_INVALID_HANDLE	hAlgorithm パラメーターのアルゴリズムハンドルが無効です。
STATUS_INVALID_PARAMETER	1 つ以上のパラメーターが無効です。
STATUS_NOT_SUPPORTED	指定されたアルゴリズムは非対称キーのペアを使用しません。

解説(Remarks)

サポートされているアルゴリズムプロバイダーを使用する場合、BCryptGenerateKeyPair はユーザーモードとカーネルモードのいずれからでも呼び出せます。カーネルモードの呼び出し元は、PASSIVE_LEVEL IRQL または DISPATCH_LEVEL IRQL のどちらでも実行できます。現在の IRQL レベルが DISPATCH_LEVEL の場合、hAlgorithm パラメーターに渡すハンドルは BCRYPT_PROV_DISPATCH フラグを使用して開かれている必要があり、BCryptGenerateKeyPair 関数に渡すポインターはすべて、ページング不可の(またはロックされた)メモリを参照している必要があります。

呼び出し元は、キーが不要になった時点で BCryptDestroyKey を使用して phKey を解放してください。

この関数をカーネルモードで呼び出すには、Driver Development Kit (DDK) に含まれる Cng.lib を使用します。Windows Server 2008 および Windows Vista: この関数をカーネルモードで呼び出すには、Ksecdd.lib を使用します。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)