Win32 API 日本語リファレンス
ホーム › Security.Cryptography › BCryptGenerateSymmetricKeyFn

BCryptGenerateSymmetricKeyFn

コールバック

シグネチャ

NTSTATUS BCryptGenerateSymmetricKeyFn(
    BCRYPT_ALG_HANDLE hAlgorithm,
    BCRYPT_KEY_HANDLE* phKey,
    BYTE* pbKeyObject,
    DWORD cbKeyObject,
    BYTE* pbSecret,
    DWORD cbSecret,
    DWORD dwFlags
);

パラメーター

フィールド型説明
hAlgorithmBCRYPT_ALG_HANDLE対称キーを使用するアルゴリズムプロバイダーのハンドルです。アルゴリズムの種類としては、暗号 (Cipher) やキー派生関数 (KDF) などがあります。このハンドルは BCryptOpenAlgorithmProvider 関数を呼び出して取得します。CNG アルゴリズム疑似ハンドルを指定することもできます。
phKeyBCRYPT_KEY_HANDLE*キーのハンドルを受け取る BCRYPT_KEY_HANDLE へのポインターです。このハンドルは、BCryptEncrypt や BCryptKeyDerivation など、対称キーを必要とする後続の関数で使用します。このハンドルが不要になったら、BCryptDestroyKey 関数に渡して解放する必要があります。
pbKeyObjectBYTE*

キーオブジェクトを受け取るバッファーへのポインターです。このバッファーのサイズは cbKeyObject パラメーターで指定します。必要なバッファーサイズは、BCryptGetProperty 関数を呼び出し、アルゴリズムハンドルから BCRYPT_OBJECT_LENGTH プロパティを取得することで求められます。これにより、指定したアルゴリズムにおけるキーオブジェクトのサイズが得られます。

このメモリを解放できるのは、phKey のキーハンドルを破棄した後だけです。

このパラメーターの値が NULL で、cbKeyObject パラメーターの値が 0 の場合、キーオブジェクト用のメモリはこの関数によって割り当てられ、BCryptDestroyKey によって解放されます。Windows 7: このメモリ管理機能は Windows 7 以降で利用できます。

cbKeyObjectDWORD

pbKeyObject バッファーのサイズ (バイト単位) です。

このパラメーターの値が 0 で、pbKeyObject パラメーターの値が NULL の場合、キーオブジェクト用のメモリはこの関数によって割り当てられ、BCryptDestroyKey によって解放されます。Windows 7: このメモリ管理機能は Windows 7 以降で利用できます。

pbSecretBYTE*

キーオブジェクトの作成元となるキーデータが格納されたバッファーへのポインターです。このバッファーのサイズは cbSecret パラメーターで指定します。通常は BCryptDeriveKey の呼び出し結果か、その他の再現可能なシークレットデータを指定します。渡されたデータが対象のキーサイズを超える場合、データは切り詰められ、超過分は無視されます。

メモ

アプリケーションは、対象のキーが必要とする正確なバイト数を渡すことを強く推奨します。

cbSecretDWORDpbSecret バッファーのサイズ (バイト単位) です。
dwFlagsDWORDこの関数の動作を変更するフラグのセットです。現在定義されているフラグはないため、このパラメーターには 0 を指定します。

公式ドキュメント

BCryptGenerateSymmetricKey 関数は、指定された秘密キーデータを使用して、対称キーを使用するアルゴリズム用のキーオブジェクトを作成します。

戻り値

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

返される可能性のあるコードには、以下のものが含まれます (これらに限りません)。

戻り値 説明
STATUS_SUCCESS 関数は成功しました。
STATUS_BUFFER_TOO_SMALL cbKeyObject パラメーターで指定されたキーオブジェクトのサイズが、キーオブジェクトを格納するには不足しています。
STATUS_INVALID_HANDLE hAlgorithm パラメーターのアルゴリズムハンドルが無効です。
STATUS_INVALID_PARAMETER 1 つ以上のパラメーターが無効です。

解説(Remarks)

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

この関数をカーネルモードで呼び出すには、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)