NCryptDeriveKey function (ncrypt.h)
The NCryptDeriveKey function derives a key from a secret agreement value. This function is intended to be used as part of a secret agreement procedure using persisted secret agreement keys. To derive key material by using a persisted secret instead, use the NCryptKeyDerivation function.
Syntax
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
);
Parameters
[in] hSharedSecret
The secret agreement handle to create the key from. This handle is obtained from the NCryptSecretAgreement function.
[in] pwszKDF
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.
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.
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 |
The call to the KDF is made as shown in the following pseudocode.
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.
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.
[in, optional] pParameterList
The address of a NCryptBufferDesc structure that contains the KDF parameters. This parameter is optional and can be NULL if it is not needed.
[out, optional] pbDerivedKey
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 DWORD pointed to by the pcbResult parameter.
[in] cbDerivedKey
The size, in bytes, of the pbDerivedKey buffer.
[out] pcbResult
A pointer to a DWORD 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 DWORD pointed to by this parameter.
[in] dwFlags
A set of flags that modify the behavior of this function. This can be zero or the following value.
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.
| Return code | Description |
|---|---|
|
The function was successful. |
|
The hSharedSecret parameter is not valid. |
|
One or more parameters are not valid. |
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
A service must not call this function from its StartService Function. If a service calls this function from its StartService function, a deadlock can occur, and the service may stop responding.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista [desktop apps | UWP apps] |
| Minimum supported server | Windows Server 2008 [desktop apps | UWP apps] |
| Target Platform | Windows |
| Header | ncrypt.h |
| Library | Ncrypt.lib |
| DLL | Ncrypt.dll |
See also
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for