BCryptDeriveKey 関数 (bcrypt.h)

[アーティクル]
07/16/2024

BCryptDeriveKey 関数は、秘密契約値からキーを派生させます。

特定のシークレットからのキーの派生については、「BCryptKeyDerivationを参照してください。

構文

NTSTATUS BCryptDeriveKey(
  [in]            BCRYPT_SECRET_HANDLE hSharedSecret,
  [in]            LPCWSTR              pwszKDF,
  [in, optional]  BCryptBufferDesc     *pParameterList,
  [out, optional] PUCHAR               pbDerivedKey,
  [in]            ULONG                cbDerivedKey,
  [out]           ULONG                *pcbResult,
  [in]            ULONG                dwFlags
);

パラメーター

[in] hSharedSecret

キーの作成に使用する秘密契約ハンドル。このハンドルは、BCryptSecretAgreement 関数から取得されます。

[in] pwszKDF

キーの派生に使用する キー派生関数 (KDF) を識別する、null で終わる Unicode 文字列へのポインター。次のいずれかの文字列を指定できます。

BCRYPT_KDF_HASH (L"HASH")

ハッシュキー派生関数を使用します。

cbDerivedKey パラメーターが派生キーのサイズより小さい場合、この関数は指定されたバイト数のみを pbDerivedKey バッファーにコピーします。 cbDerivedKey パラメーターが派生キーのサイズより大きい場合、この関数はキーを pbDerivedKey バッファーにコピーし、pcbResult が指す変数をコピーした実際のバイト数に設定します。

pParameterList パラメーターによって識別されるパラメーターは、Required 列または省略可能な列で示されているように、次のパラメーターを含めることができます。または含まれている必要があります。

パラメーター	形容	必須または省略可能
KDF_HASH_ALGORITHM	使用するハッシュアルゴリズムを識別する null で終わる Unicode 文字列。これには、CNG アルゴリズム識別子からの標準ハッシュアルゴリズム識別子の 1 つ、または別の登録済みハッシュアルゴリズムの識別子を指定できます。このパラメーターを指定しない場合は、SHA1 ハッシュアルゴリズムが使用されます。	随意
KDF_SECRET_PREPEND	ハッシュ関数へのメッセージ入力の先頭に追加する値。詳細については、「解説」を参照してください。	随意
KDF_SECRET_APPEND	ハッシュ関数へのメッセージ入力の末尾に追加する値。詳細については、「解説」を参照してください。	随意

KDF の呼び出しは、次の擬似コードに示すように行われます。

KDF-Prepend = KDF_SECRET_PREPEND[0] + 
    KDF_SECRET_PREPEND[1] + 
    ... +
    KDF_SECRET_PREPEND[n]

KDF-Append = KDF_SECRET_APPEND[0] + 
    KDF_SECRET_APPEND[1] + 
    ... + 
    KDF_SECRET_APPEND[n]

KDF-Output = Hash(
    KDF-Prepend + 
    hSharedSecret + 
    KDF-Append)

BCRYPT_KDF_HMAC (L"HMAC")

Hash-Based メッセージ認証コード (HMAC) キー派生関数を使用します。

パラメーター	形容	必須または省略可能
KDF_HASH_ALGORITHM	使用するハッシュアルゴリズムを識別する null で終わる Unicode 文字列。これには、CNG アルゴリズム識別子からの標準ハッシュアルゴリズム識別子の 1 つ、または別の登録済みハッシュアルゴリズムの識別子を指定できます。このパラメーターを指定しない場合は、SHA1 ハッシュアルゴリズムが使用されます。	随意
KDF_HMAC_KEY	擬似ランダム関数 (PRF) に使用するキー。	随意
KDF_SECRET_PREPEND	ハッシュ関数へのメッセージ入力の先頭に追加する値。詳細については、「解説」を参照してください。	随意
KDF_SECRET_APPEND	ハッシュ関数へのメッセージ入力の末尾に追加する値。詳細については、「解説」を参照してください。	随意

KDF の呼び出しは、次の擬似コードに示すように行われます。

KDF-Prepend = KDF_SECRET_PREPEND[0] + 
    KDF_SECRET_PREPEND[1] + 
    ... +
    KDF_SECRET_PREPEND[n]

KDF-Append = KDF_SECRET_APPEND[0] + 
    KDF_SECRET_APPEND[1] + 
    ... + 
    KDF_SECRET_APPEND[n]

KDF-Output = HMAC-Hash(
    KDF_HMAC_KEY,
    KDF-Prepend + 
    hSharedSecret + 
    KDF-Append)

BCRYPT_KDF_TLS_PRF (L"TLS_PRF")

トランスポート層セキュリティ (TLS) 擬似ランダム関数 (PRF) キー派生関数を使用します。派生キーのサイズは常に 48 バイトであるため、cbDerivedKey パラメーターは 48 である必要があります。

パラメーター	形容	必須または省略可能
KDF_TLS_PRF_LABEL	PRF ラベルを含む ANSI 文字列。	必須
KDF_TLS_PRF_SEED	PRF シード。シードの長さは 64 バイトである必要があります。	必須
KDF_TLS_PRF_PROTOCOL	PRF アルゴリズムを使用する TLS プロトコルバージョンを指定する DWORD 値。有効な値は次のとおりです。 SSL2_PROTOCOL_VERSION (0x0002) SSL3_PROTOCOL_VERSION (0x0300) TLS1_PROTOCOL_VERSION (0x0301) TLS1_0_PROTOCOL_VERSION (0x0301) TLS1_1_PROTOCOL_VERSION (0x0302) TLS1_2_PROTOCOL_VERSION (0x0303) DTLS1_0_PROTOCOL_VERSION (0xfeff) Windows Server 2008 および Windows Vista: TLS1_1_PROTOCOL_VERSION、TLS1_2_PROTOCOL_VERSION、DTLS1_0_PROTOCOL_VERSIONはサポートされていません。 Windows Server 2008 R2、Windows 7、Windows Server 2008、Windows Vista: DTLS1_0_PROTOCOL_VERSION はサポートされていません。	随意
KDF_HASH_ALGORITHM	TLS 1.2 プロトコルバージョンの PRF の HMAC で使用されるハッシュの CNG アルゴリズム ID。有効な選択肢は SHA-256 と SHA-384 です。指定しない場合は、SHA-256 が使用されます。	随意

KDF の呼び出しは、次の擬似コードに示すように行われます。

KDF-Output = PRF(
    hSharedSecret, 
    KDF_TLS_PRF_LABEL, 
    KDF_TLS_PRF_SEED)

BCRYPT_KDF_SP80056A_CONCAT (L"SP800_56A_CONCAT")

SP800-56A キー派生関数を使用します。

pParameterList パラメーターによって識別されるパラメーターは、Required 列または省略可能な列で示されているように、次のパラメーターを含めることができます。または含まれている必要があります。すべてのパラメーター値は、不透明なバイト配列として扱われます。

パラメーター	形容	必須または省略可能
KDF_ALGORITHMID	SP800-56A キー派生関数の OtherInfo フィールドのサブフィールド AlgorithmID を指定します。派生キーの目的を示します。	必須
KDF_PARTYUINFO	SP800-56A キー派生関数の OtherInfo フィールドの PartyUInfo サブフィールドを指定します。このフィールドには、イニシエーターが提供するパブリック情報が含まれています。	必須
KDF_PARTYVINFO	SP800-56A キー派生関数の OtherInfo フィールドの PartyVInfo サブフィールドを指定します。このフィールドには、レスポンダーによって提供された公開情報が含まれます。	必須
KDF_SUPPPUBINFO	SP800-56A キー派生関数の OtherInfo フィールドの SuppPubInfo サブフィールドを指定します。このフィールドには、イニシエーターとレスポンダーの両方に既知のパブリック情報が含まれています。	随意
KDF_SUPPPRIVINFO	SP800-56A キー派生関数の OtherInfo フィールドの SuppPrivInfo サブフィールドを指定します。これには、共有シークレットなど、イニシエーターとレスポンダーの両方に知られている個人情報が含まれています。	随意

KDF の呼び出しは、次の擬似コードに示すように行われます。

KDF-Output = SP_800-56A_KDF(
	   hSharedSecret,
	   KDF_ALGORITHMID,
	   KDF_PARTYUINFO,
	   KDF_PARTYVINFO,
	   KDF_SUPPPUBINFO,
	   KDF_SUPPPRIVINFO)

Windows Server 2008、Windows Vista、Windows Server 2003、Windows XP: この値はサポートされていません。

BCRYPT_KDF_RAW_SECRET (L"TRUNCATE")

未加工のシークレットのリトルエンディアン表現を変更せずに返します。

Windows 8、Windows Server 2008、Windows Vista、Windows Server 2003、Windows XP: この値はサポートされていません。

[in, optional] pParameterList

KDF パラメーターを含む BCryptBufferDesc 構造体のアドレス。このパラメーターは省略可能であり、必要ない場合は NULL できます。

[out, optional] pbDerivedKey

キーを受け取るバッファーのアドレス。 cbDerivedKey パラメーターには、このバッファーのサイズが含まれています。このパラメーターが NULL場合、この関数は必要なサイズ (バイト単位) を、pcbResult パラメーターによって指 ULONG に配置します。

[in] cbDerivedKey

pbDerivedKey バッファーのサイズ (バイト単位)。

[out] pcbResult

pbDerivedKey バッファーにコピーされたバイト数を受け取る ULONG へのポインター。 pbDerivedKey パラメーターが NULL場合、この関数は必要なサイズ (バイト単位) を、このパラメーターで指 ULONG に配置します。

[in] dwFlags

この関数の動作を変更するフラグのセット。 0 または次の値を指定できます。

価値	意味
KDF_USE_SECRET_AS_HMAC_KEY_FLAG	秘密契約の値は、HMAC キーとしても機能します。このフラグを指定した場合、KDF_HMAC_KEY パラメーターは、pParameterList パラメーターのパラメーターのセットに含めないようにする必要があります。このフラグは、BCRYPT_KDF_HMAC キー派生関数でのみ使用されます。

戻り値

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

可能な戻りコードには、以下が含まれますが、これらに限定されません。

リターンコード	形容
STATUS_SUCCESS	関数が成功しました。
STATUS_INTERNAL_ERROR	内部エラーが発生しました。
STATUS_INVALID_HANDLE	hSharedSecret パラメーターのハンドルが無効です。
STATUS_INVALID_PARAMETER	1 つ以上のパラメーターが無効です。

備考

pParameterList パラメーターの BCryptBufferDesc 構造体には、複数の KDF_SECRET_PREPEND パラメーターと KDF_SECRET_APPEND パラメーターを含めることができます。これらのパラメーターが複数指定されている場合、パラメーター値は、KDF が呼び出される前に配列に含まれる順序で連結されます。たとえば、次のパラメーター値が指定されているとします。

BYTE pbValue0[1] = {0x01};
BYTE pbValue1[2] = {0x04, 0x05};
BYTE pbValue2[3] = {0x10, 0x11, 0x12};
BYTE pbValue3[4] = {0x20, 0x21, 0x22, 0x23};

Parameter[0].type = KDF_SECRET_APPEND
Parameter[0].value = pbValue0;
Parameter[0].length = sizeof  (pbValue0);
Parameter[1].type = KDF_SECRET_PREPEND
Parameter[1].value = pbValue1;
Parameter[1].length = sizeof (pbValue1);
Parameter[2].type = KDF_SECRET_APPEND
Parameter[2].value = pbValue2;
Parameter[2].length = sizeof (pbValue2);
Parameter[3].type = KDF_SECRET_PREPEND
Parameter[3].value = pbValue3;
Parameter[3].length = sizeof (pbValue3);

上記のパラメーター値を指定した場合、実際の KDF に連結された値は次のようになります。

Type: KDF_SECRET_PREPEND
Value: {0x04, 0x05, 0x20, 0x21, 0x22, 0x23}, length 6

Type: KDF_SECRET_APPEND
Value: {0x01, 0x10, 0x11, 0x12}, length 4

pwszKDF パラメーターが BCRYPT_KDF_RAW_SECRETに設定されている場合、返されるシークレットは (他の pwszKDF 値とは異なり) リトルエンディアン形式でエンコードされます。他の CNG 関数で生のシークレットを使用する場合は、ビッグエンディアンでエンコードされた入力を取り込むため、この点に注意することが重要です。

プロバイダーがサポートするプロセッサモードに応じて、BCryptDeriveKey をユーザーモードまたはカーネルモードから呼び出すことができます。カーネルモードの呼び出し元は、PASSIVE_LEVELIRQL または DISPATCH_LEVEL IRQL で実行できます。現在の IRQL レベルが DISPATCH_LEVELされている場合、hSharedSecret パラメーターで提供されるハンドルは、非ページ (またはロックされた) メモリ内にあり、BCRYPT_PROV_DISPATCH フラグを使用して開かれたプロバイダーによって返されるアルゴリズムハンドルから派生する必要があります。

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

必要条件

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

次の方法で共有

BCryptDeriveKey 関数 (bcrypt.h)

構文

パラメーター

BCRYPT_KDF_HASH (L"HASH")

BCRYPT_KDF_HMAC (L"HMAC")

BCRYPT_KDF_TLS_PRF (L"TLS_PRF")

BCRYPT_KDF_SP80056A_CONCAT (L"SP800_56A_CONCAT")

BCRYPT_KDF_RAW_SECRET (L"TRUNCATE")

戻り値

備考

必要条件

関連項目

フィードバック

その他のリソース