ホーム › Security.Cryptography › BCryptKeyDerivationFn

BCryptKeyDerivationFn

コールバック

シグネチャ

NTSTATUS BCryptKeyDerivationFn(
    BCRYPT_KEY_HANDLE hKey,
    BCryptBufferDesc* pParameterList,
    BYTE* pbDerivedKey,
    DWORD cbDerivedKey,
    DWORD* pcbResult,
    DWORD dwFlags
);

パラメーター

フィールド型説明

hKey BCRYPT_KEY_HANDLE 鍵導出関数 (KDF) キーのハンドルです。「解説」を参照してください。

pParameterList

BCryptBufferDesc*

KDF のパラメーターを格納した BCryptBufferDesc 構造体のアドレスです。このパラメーターは省略可能で、不要な場合は NULL を指定できます。

パラメーターには、鍵導出関数 (KDF) 固有のものと汎用のものがあります。次の表は、Microsoft Primitive プロバイダーが実装する個々の KDF について、必須および省略可能なパラメーターを示しています。補足情報は BCryptBuffer のドキュメントにもあります。

KDF	パラメーター	必須	既定値
SP800-108 HMAC (カウンターモード)	KDF_LABEL	はい
	KDF_CONTEXT	はい
	KDF_HASH_ALGORITHM	はい
SP800-56A	KDF_ALGORITHMID	はい
	KDF_PARTYUINFO	はい
	KDF_PARTYVINFO	はい
	KDF_HASH_ALGORITHM	はい
	KDF_SUPPPUBINFO	いいえ	""
	KDF_SUPPPRIVINFO	いいえ	""
PBKDF2	KDF_HASH_ALGORITHM	はい
	KDF_SALT	はい
	KDF_ITERATION_COUNT	いいえ	10000
CAPI_KDF	KDF_HASH_ALGORITHM	はい
TLS1_1_PRF	KDF_TLS_PRF_LABEL	はい
	KDF_TLS_PRF_SEED	はい
TLS1_2_PRF	KDF_TLS_PRF_LABEL	はい
	KDF_TLS_PRF_SEED	はい
	KDF_HASH_ALGORITHM	はい
HKDF	KDF_HKDF_INFO	いいえ	""

一部のアルゴリズムでは、複数のパラメーターを指定する代わりに KDF_GENERIC_PARAMETER を使用できます。これは KDF 固有のパラメーターに次のように対応します。

SP800-108 HMAC (カウンターモード):

KDF_GENERIC_PARAMETER = KDF_LABEL || 0x00 || KDF_CONTEXT

SP800-56A:

KDF_GENERIC_PARAMETER = KDF_ALGORITHMID || KDF_PARTYUINFO || KDF_PARTYVINFO {|| KDF_SUPPPUBINFO } {|| KDF_SUPPPRIVINFO }

PBKDF2:

KDF_GENERIC_PARAMETER = KDF_SALT

pbDerivedKey BYTE* キーを受け取るバッファーのアドレスです。cbDerivedKey パラメーターには、このバッファーのサイズを指定します。

cbDerivedKey DWORD pbDerivedKey パラメーターが指すバッファーのサイズ (バイト単位) です。

pcbResult DWORD* pbDerivedKey パラメーターが指すバッファーにコピーされたバイト数を受け取る ULONG へのポインターです。

dwFlags

DWORD

この関数の動作を変更するフラグです。Microsoft Primitive プロバイダーでは次の値を使用できます。

値	意味
BCRYPT_CAPI_AES_FLAG	対象のアルゴリズムが AES であり、そのためキーを二重に展開する必要があることを指定します。このフラグは CAPI_KDF アルゴリズムでのみ有効です。

公式ドキュメント

BCryptKeyDerivation 関数は、すべてのパラメーターを明示的に指定した状態で鍵導出関数 (KDF) を呼び出すことにより、キーを派生させます。

BCryptDeriveKey と機能は似ていますが、KDF アルゴリズムを直接呼び出すため、入力として BCRYPT_SECRET_HANDLE 値を必要としません。

戻り値

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

解説(Remarks)

BCryptKeyDerivation を使用する流れは次のとおりです。

使用する KDF アルゴリズムを決定し、そのアルゴリズムハンドルを取得します。BCryptOpenAlgorithmProvider では次のアルゴリズム識別子を使用できます。

キーの派生元となるシークレットデータを決定し、アルゴリズムハンドルとともに BCryptGenerateSymmetricKey に渡して、KDF キーハンドルを生成します。
KDF キーハンドルを指定して BCryptKeyDerivation を呼び出します。

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

HKDF

HKDF では、次のどちらからキーを派生させるかが区別されます。

シークレットアグリーメント関数の出力。これは一様にランダムではなく、入力キーマテリアル (IKM) と見なされます。
一様にランダムなシークレット値。

第 1 段階は、指定されたシークレットデータから疑似乱数キー (PRK) を「抽出 (Extract)」することです。

この手順では、KDF キーハンドルに対して BCRYPT_HKDF_HASH_ALGORITHM を指定して BCryptSetProperty を呼び出し、HKDF の HMAC 計算で使用するハッシュアルゴリズムを設定します。続いて、次のいずれかを指定して BCryptSetProperty をもう一度呼び出します。

指定したシークレットデータが IKM を表す場合は、BCRYPT_HKDF_SALT_AND_FINALIZE を使用して省略可能なソルト値を指定し、IKM から PRK を抽出して KDF キーハンドルを確定します。
それ以外の場合は、BCRYPT_HKDF_PRK_AND_FINALIZE を使用して、指定したシークレットを HKDF の PRK に直接変換し、KDF キーハンドルを確定します。

第 2 段階は、PRK を出力の派生キーへと「拡張 (Expand)」することです。

この手順では、確定済みの KDF キーハンドルに対して BCryptKeyDerivation を呼び出します。

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