NCryptDeriveKey 関数 (ncrypt.h)

NCryptDeriveKey 関数は、シークレット アグリーメント値からキーを派生させます。 この関数は、永続化された秘密契約キーを使用するシークレット 契約手順の一部として使用することを目的としています。 代わりに永続化されたシークレットを使用してキー マテリアルを派生するには、 NCryptKeyDerivation 関数を使用します。

構文

SECURITY_STATUS NCryptDeriveKey(
  [in]            NCRYPT_SECRET_HANDLE hSharedSecret,
  [in]            LPCWSTR              pwszKDF,
  [in, optional]  NCryptBufferDesc     *pParameterList,
  [out, optional] PBYTE                pbDerivedKey,
  [in]            DWORD                cbDerivedKey,
  [out]           DWORD                *pcbResult,
  [in]            ULONG                dwFlags
);

パラメーター

[in] hSharedSecret

キーを作成するシークレット アグリーメント ハンドル。 このハンドルは 、NCryptSecretAgreement 関数から取得されます。

[in] pwszKDF

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

BCRYPT_KDF_HASH (L"HASH")

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

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

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

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

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

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

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

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 である必要があります。

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

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 の呼び出しは、次の擬似コードに示すように行われます。

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: この値はサポートされていません。

[in, optional] pParameterList

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

[out, optional] pbDerivedKey

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

[in] cbDerivedKey

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

[out] pcbResult

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

[in] dwFlags

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

戻り値

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

可能なリターン コードには、次のものが含まれますが、これらに限定されません。

注釈

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

サービスは 、StartService 関数からこの関数を呼び出してはなりません。 サービスが StartService 関数からこの関数を呼び出すと、デッドロックが発生し、サービスが応答を停止する可能性があります。

要件

こちらもご覧ください

NCryptBufferDesc