BCryptDeriveKeyFn

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

BCRYPT_KDF_HASH (L"HASH")

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

cbDerivedKey パラメーターが派生キーのサイズより小さい場合、この関数は指定されたバイト数だけを pbDerivedKey バッファーにコピーします。これは結果として得られるキーのセキュリティ強度を大幅に低下させる可能性があるため、通常は望ましくありません。

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

pParameterList パラメーターで指定するパラメーターには、次のパラメーターを含めることができます。必須かどうかは「必須または省略可能」列のとおりです。

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

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

BCRYPT_KDF_HMAC (L"HMAC")

ハッシュ ベース メッセージ認証コード (HMAC) キー派生関数を使用します。

cbDerivedKey パラメーターが派生キーのサイズより小さい場合、この関数は指定されたバイト数だけを pbDerivedKey バッファーにコピーします。これは結果として得られるキーのセキュリティ強度を大幅に低下させる可能性があるため、通常は望ましくありません。

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

pParameterList パラメーターで指定するパラメーターには、次のパラメーターを含めることができます。必須かどうかは「必須または省略可能」列のとおりです。

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

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

BCRYPT_KDF_TLS_PRF (L"TLS_PRF")

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

pParameterList パラメーターで指定するパラメーターには、次のパラメーターを含めることができます。必須かどうかは「必須または省略可能」列のとおりです。

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

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

BCRYPT_KDF_SP80056A_CONCAT (L"SP800_56A_CONCAT")

SP800-56A キー派生関数を使用します。これは SP800-56C rev2 のワンステップ KDF としても知られています。

この KDF は承認されたハッシュ関数をパラメーターとして受け取りますが、この API はハッシュ関数を内部で選択し、ハッシュ アルゴリズムのセキュリティ強度を、シークレット ハンドルの生成に使用されたアルゴリズムに合わせます (たとえば ECDH P-256 では SHA256、ECDH P-384 では SHA384 を使用します)。

pParameterList パラメーターで指定するパラメーターには、次のパラメーターを含めることができます。必須かどうかは「必須または省略可能」列のとおりです。パラメーターの値はすべて、不透明なバイト配列として扱われます。

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")

生のシークレットを何も変更せずに、リトル エンディアン表現で返します。このオプションの使用は通常は望ましくありませんが、サポートされていない KDF と相互運用する必要がある場合には必要になることがあります。

cbDerivedKey パラメーターが派生キーのサイズより小さい場合、この関数は指定されたバイト数だけを pbDerivedKey バッファーにコピーします。これは結果として得られるキーのセキュリティ強度を大幅に低下させる可能性があるため、通常は望ましくありません。

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

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

BCRYPT_KDF_HKDF (L"HKDF")

RFC 5869 の HKDF (HMAC ベースの抽出および拡張 KDF) 関数を使用します。

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

1. シークレット アグリーメント関数の出力。これは一様にランダムではなく、入力キー マテリアル (IKM) と見なされます。BCryptDeriveKey の利用者のほとんどは、この形式のシークレット ハンドルを扱います。
2. 一様にランダムなシークレット値。

第 1 段階では、シークレット ハンドルから擬似乱数キー (PRK) を「抽出」します。

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

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

第 2 段階では、PRK を出力となる派生キーへ「拡張」します。

この段階は、確定済みのシークレット ハンドルに対して BCryptDeriveKey を呼び出すことで行います。

pParameterList パラメーターで指定するパラメーターには、次のパラメーターを含めることができます。必須かどうかは「必須または省略可能」列のとおりです。パラメーターの値はすべて、不透明なバイト配列として扱われます。

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

KDF-Output = HKDF-Expand(
    hSharedSecret.PRK,
    info,
    cbDerivedKey)

Windows 10: HKDF のサポートが開始されました。

この関数の動作を変更するフラグのセットです。

0 または次の値を指定できます。