BCryptDeriveKey function

The BCryptDeriveKey function derives a key from a secret agreement value.

Syntax

NTSTATUS WINAPI BCryptDeriveKey(
  _In_      BCRYPT_SECRET_HANDLE hSharedSecret,
  _In_      LPCWSTR              pwszKDF,
  _In_opt_  BCryptBufferDesc     *pParameterList,
  _Out_opt_ PUCHAR               pbDerivedKey,
  _In_      ULONG                cbDerivedKey,
  _Out_     ULONG                *pcbResult,
  _In_      ULONG                dwFlags
);

Parameters

hSharedSecret [in]

The secret agreement handle to create the key from. This handle is obtained from the BCryptSecretAgreement function.

pwszKDF [in]

A pointer to a null-terminated Unicode string that identifies the key derivation function (KDF) to use to derive the key. This can be one of the following strings.

BCRYPT_KDF_HASH (L"HASH")

Use the hash key derivation function.

If the cbDerivedKey parameter is less than the size of the derived key, this function will only copy the specified number of bytes to the pbDerivedKey buffer. If the cbDerivedKey parameter is greater than the size of the derived key, this function will copy the key to the pbDerivedKey buffer and set the variable pointed to by the pcbResult to the actual number of bytes copied.

The parameters identified by the pParameterList parameter either can or must contain the following parameters, as indicated by the Required or optional column.

Parameter	Description	Required or optional
KDF_HASH_ALGORITHM	A null-terminated Unicode string that identifies the hash algorithm to use. This can be one of the standard hash algorithm identifiers from CNG Algorithm Identifiers or the identifier for another registered hash algorithm. If this parameter is not specified, the SHA1 hash algorithm is used.	Optional
KDF_SECRET_PREPEND	A value to add to the beginning of the message input to the hash function. For more information, see Remarks.	Optional
KDF_SECRET_APPEND	A value to add to the end of the message input to the hash function. For more information, see Remarks.	Optional

 

The call to the KDF is made as shown in the following pseudocode.

Copy

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

Use the Hash-Based Message Authentication Code (HMAC) key derivation function.

If the cbDerivedKey parameter is less than the size of the derived key, this function will only copy the specified number of bytes to the pbDerivedKey buffer. If the cbDerivedKey parameter is greater than the size of the derived key, this function will copy the key to the pbDerivedKey buffer and set the variable pointed to by the pcbResult to the actual number of bytes copied.

The parameters identified by the pParameterList parameter either can or must contain the following parameters, as indicated by the Required or optional column.

Parameter	Description	Required or optional
KDF_HASH_ALGORITHM	A null-terminated Unicode string that identifies the hash algorithm to use. This can be one of the standard hash algorithm identifiers from CNG Algorithm Identifiers or the identifier for another registered hash algorithm. If this parameter is not specified, the SHA1 hash algorithm is used.	Optional
KDF_HMAC_KEY	The key to use for the pseudo-random function (PRF).	Optional
KDF_SECRET_PREPEND	A value to add to the beginning of the message input to the hash function. For more information, see Remarks.	Optional
KDF_SECRET_APPEND	A value to add to the end of the message input to the hash function. For more information, see Remarks.	Optional

 

The call to the KDF is made as shown in the following pseudocode.

Copy

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

Use the transport layer security (TLS) pseudo-random function (PRF) key derivation function. The size of the derived key is always 48 bytes, so the cbDerivedKey parameter must be 48.

The parameters identified by the pParameterList parameter either can or must contain the following parameters, as indicated by the Required or optional column.

Parameter	Description	Required or optional
KDF_TLS_PRF_LABEL	An ANSI string that contains the PRF label.	Required
KDF_TLS_PRF_SEED	The PRF seed. The seed must be 64 bytes long.	Required
KDF_TLS_PRF_PROTOCOL	A DWORD value that specifies the TLS protocol version whose PRF algorithm is to be used. Valid values are: 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 and Windows Vista:  TLS1_1_PROTOCOL_VERSION, TLS1_2_PROTOCOL_VERSION and DTLS1_0_PROTOCOL_VERSION are not supported. Windows Server 2008 R2, Windows 7, Windows Server 2008 and Windows Vista:  DTLS1_0_PROTOCOL_VERSION is not supported.	Optional
KDF_HASH_ALGORITHM	The CNG algorithm ID of the hash to be used with the HMAC in the PRF, for the TLS 1.2 protocol version. Valid choices are SHA-256 and SHA-384. If not specified, SHA-256 is used.	Optional

 

The call to the KDF is made as shown in the following pseudocode.

Copy

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

BCRYPT_KDF_SP80056A_CONCAT (L"SP800_56A_CONCAT")

Use the SP800-56A key derivation function.

The parameters identified by the pParameterList parameter either can or must contain the following parameters, as indicated by the Required or optional column. All parameter values are treated as opaque byte arrays.

Parameter	Description	Required or optional
KDF_ALGORITHMID	Specifies the AlgorithmID subfield of the OtherInfo field in the SP800-56A key derivation function. Indicates the intended purpose of the derived key.	Required
KDF_PARTYUINFO	Specifies the PartyUInfo subfield of the OtherInfo field in the SP800-56A key derivation function. The field contains public information contributed by the initiator.	Required
KDF_PARTYVINFO	Specifies the PartyVInfo subfield of the OtherInfo field in the SP800-56A key derivation function. The field contains public information contributed by the responder.	Required
KDF_SUPPPUBINFO	Specifies the SuppPubInfo subfield of the OtherInfo field in the SP800-56A key derivation function. The field contains public information known to both initiator and responder.	Optional
KDF_SUPPPRIVINFO	Specifies the SuppPrivInfo subfield of the OtherInfo field in the SP800-56A key derivation function. It contains private information known to both initiator and responder, such as a shared secret.	Optional

 

The call to the KDF is made as shown in the following pseudocode.

Copy

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 and Windows XP:  This value is not supported.

pParameterList [in, optional]

The address of a BCryptBufferDesc structure that contains the KDF parameters. This parameter is optional and can be NULL if it is not needed.

pbDerivedKey [out, optional]

The address of a buffer that receives the key. The cbDerivedKey parameter contains the size of this buffer. If this parameter is NULL, this function will place the required size, in bytes, in the ULONG pointed to by the pcbResult parameter.

cbDerivedKey [in]

The size, in bytes, of the pbDerivedKey buffer.

pcbResult [out]

A pointer to a ULONG that receives the number of bytes that were copied to the pbDerivedKey buffer. If the pbDerivedKey parameter is NULL, this function will place the required size, in bytes, in the ULONG pointed to by this parameter.

dwFlags [in]

A set of flags that modify the behavior of this function. This can be zero or the following value.

Value	Meaning
KDF_USE_SECRET_AS_HMAC_KEY_FLAG	The secret agreement value will also serve as the HMAC key. If this flag is specified, the KDF_HMAC_KEY parameter should not be included in the set of parameters in the pParameterList parameter. This flag is only used by the BCRYPT_KDF_HMAC key derivation function.

 

Return value

Returns a status code that indicates the success or failure of the function.

Possible return codes include, but are not limited to, the following.

Remarks

The BCryptBufferDesc structure in the pParameterList parameter can contain more than one of the KDF_SECRET_PREPEND and KDF_SECRET_APPEND parameters. If more than one of these parameters is specified, the parameter values are concatenated in the order in which they are contained in the array before the KDF is called. For example, assume the following parameter values are specified.

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

If the above parameter values are specified, the concatenated values to the actual KDF are as follows.

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

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

Depending on what processor modes a provider supports, BCryptDeriveKey can be called either from user mode or kernel mode. Kernel mode callers can execute either at PASSIVE_LEVEL IRQL or DISPATCH_LEVEL IRQL. If the current IRQL level is DISPATCH_LEVEL, the handle provided in the hSharedSecret parameter must be located in nonpaged (or locked) memory and must be derived from an algorithm handle returned by a provider that was opened by using the BCRYPT_PROV_DISPATCH flag.

To call this function in kernel mode, use Cng.lib, which is part of the Driver Development Kit (DDK). For more information, see WDK and Developer Tools.

Windows Server 2008 and Windows Vista:  To call this function in kernel mode, use Ksecdd.lib.

Requirements

See also

BCryptSecretAgreement