NCryptDeriveKey, fonction (ncrypt.h)

La fonction NCryptDeriveKey dérive une clé d’une valeur d’accord secret. Cette fonction est destinée à être utilisée dans le cadre d’une procédure d’accord secret utilisant des clés d’accord secret persistantes. Pour dériver le matériel de clé à l’aide d’un secret persistant à la place, utilisez la fonction NCryptKeyDerivation .

Syntaxe

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

Paramètres

[in] hSharedSecret

Handle de contrat secret à partir duquel créer la clé. Ce handle est obtenu à partir de la fonction NCryptSecretAgreement .

[in] pwszKDF

Pointeur vers une chaîne Unicode terminée par null qui identifie la fonction de dérivation de clé (KDF) à utiliser pour dériver la clé. Il peut s’agir de l’une des chaînes suivantes.

BCRYPT_KDF_HASH (L"HASH »)

Utilisez la fonction de dérivation de clé de hachage.

Si le paramètre cbDerivedKey est inférieur à la taille de la clé dérivée, cette fonction copie uniquement le nombre d’octets spécifié dans la mémoire tampon pbDerivedKey . Si le paramètre cbDerivedKey est supérieur à la taille de la clé dérivée, cette fonction copie la clé dans la mémoire tampon pbDerivedKey et définit la variable pointée par le pcbResult sur le nombre réel d’octets copiés.

Les paramètres identifiés par le paramètre pParameterList peuvent ou doivent contenir les paramètres suivants, comme indiqué par la colonne Obligatoire ou facultative.

Paramètre Description Obligatoire ou facultatif
KDF_HASH_ALGORITHM Chaîne Unicode terminée par null qui identifie l’algorithme de hachage à utiliser. Il peut s’agir de l’un des identificateurs d’algorithme de hachage standard des identificateurs d’algorithme CNG ou de l’identificateur d’un autre algorithme de hachage inscrit.

Si ce paramètre n’est pas spécifié, l’algorithme de hachage SHA1 est utilisé.

Facultatif
KDF_SECRET_PREPEND Valeur à ajouter au début de l’entrée de message à la fonction de hachage. Pour plus d'informations, consultez la section Notes. Facultatif
KDF_SECRET_APPEND Valeur à ajouter à la fin de l’entrée de message à la fonction de hachage. Pour plus d'informations, consultez la section Notes. Facultatif
 

L’appel à la fonction KDF est effectué comme indiqué dans le pseudocode suivant.

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

Utilisez la fonction de dérivation de clé HMAC ( Hash-Based Message Authentication Code ).

Si le paramètre cbDerivedKey est inférieur à la taille de la clé dérivée, cette fonction copie uniquement le nombre d’octets spécifié dans la mémoire tampon pbDerivedKey . Si le paramètre cbDerivedKey est supérieur à la taille de la clé dérivée, cette fonction copie la clé dans la mémoire tampon pbDerivedKey et définit la variable pointée par le pcbResult sur le nombre réel d’octets copiés.

Les paramètres identifiés par le paramètre pParameterList peuvent ou doivent contenir les paramètres suivants, comme indiqué par la colonne Obligatoire ou facultative.

Paramètre Description Obligatoire ou facultatif
KDF_HASH_ALGORITHM Chaîne Unicode terminée par null qui identifie l’algorithme de hachage à utiliser. Il peut s’agir de l’un des identificateurs d’algorithme de hachage standard des identificateurs d’algorithme CNG ou de l’identificateur d’un autre algorithme de hachage inscrit.

Si ce paramètre n’est pas spécifié, l’algorithme de hachage SHA1 est utilisé.

Facultatif
KDF_HMAC_KEY Clé à utiliser pour la fonction pseudo-aléatoire (PRF). Facultatif
KDF_SECRET_PREPEND Valeur à ajouter au début de l’entrée de message à la fonction de hachage. Pour plus d'informations, consultez la section Notes. Facultatif
KDF_SECRET_APPEND Valeur à ajouter à la fin de l’entrée de message à la fonction de hachage. Pour plus d'informations, consultez la section Notes. Facultatif
 

L’appel à la fonction KDF est effectué comme indiqué dans le pseudocode suivant.

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

Utilisez la fonction de dérivation de clé de fonction pseudo-aléatoire (PRF) tls (Transport Layer Security). La taille de la clé dérivée étant toujours de 48 octets, le paramètre cbDerivedKey doit être de 48.

Les paramètres identifiés par le paramètre pParameterList peuvent ou doivent contenir les paramètres suivants, comme indiqué par la colonne Obligatoire ou facultative.

Paramètre Description Obligatoire ou facultatif
KDF_TLS_PRF_LABEL Chaîne ANSI qui contient l’étiquette PRF. Obligatoire
KDF_TLS_PRF_SEED Valeur initiale PRF. La valeur initiale doit être de 64 octets. Obligatoire
 

L’appel à la fonction KDF est effectué comme indiqué dans le pseudocode suivant.

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

BCRYPT_KDF_SP80056A_CONCAT (L"SP800_56A_CONCAT »)

Utilisez la fonction de dérivation de clé SP800-56A.

Les paramètres identifiés par le paramètre pParameterList peuvent ou doivent contenir les paramètres suivants, comme indiqué par la colonne Obligatoire ou facultative. Toutes les valeurs de paramètre sont traitées comme des tableaux d’octets opaques.

Paramètre Description Obligatoire ou facultatif
KDF_ALGORITHMID Spécifie le sous-champ AlgorithmID du champ OtherInfo dans la fonction de dérivation de clé SP800-56A. Indique l’objectif prévu de la clé dérivée. Obligatoire
KDF_PARTYUINFO Spécifie le sous-champ PartyUInfo du champ OtherInfo dans la fonction de dérivation de clé SP800-56A. Le champ contient des informations publiques fournies par l’initiateur. Obligatoire
KDF_PARTYVINFO Spécifie le sous-champ PartyVInfo du champ OtherInfo dans la fonction de dérivation de clé SP800-56A. Le champ contient des informations publiques fournies par le répondeur. Obligatoire
KDF_SUPPPUBINFO Spécifie le sous-champ SuppPubInfo du champ OtherInfo dans la fonction de dérivation de clé SP800-56A. Le champ contient des informations publiques connues de l’initiateur et du répondeur. Facultatif
KDF_SUPPPRIVINFO Spécifie le sous-champ SuppPrivInfo du champ OtherInfo dans la fonction de dérivation de clé SP800-56A. Il contient des informations privées connues de l’initiateur et du répondeur, telles qu’un secret partagé. Facultatif
 

L’appel à la fonction KDF est effectué comme indiqué dans le pseudocode suivant.

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 et Windows XP : Cette valeur n’est pas prise en charge.

[in, optional] pParameterList

Adresse d’une structure NCryptBufferDesc qui contient les paramètres KDF. Ce paramètre est facultatif et peut être NULL s’il n’est pas nécessaire.

[out, optional] pbDerivedKey

Adresse d’une mémoire tampon qui reçoit la clé. Le paramètre cbDerivedKey contient la taille de cette mémoire tampon. Si ce paramètre a la valeur NULL, cette fonction place la taille requise, en octets, dans le DWORD pointé par le paramètre pcbResult .

[in] cbDerivedKey

Taille, en octets, de la mémoire tampon pbDerivedKey .

[out] pcbResult

Pointeur vers un DWORD qui reçoit le nombre d’octets copiés dans la mémoire tampon pbDerivedKey . Si le paramètre pbDerivedKey a la valeur NULL, cette fonction place la taille requise, en octets, dans le DWORD pointé par ce paramètre.

[in] dwFlags

Ensemble d’indicateurs qui modifient le comportement de cette fonction. Il peut s’agir de zéro ou de la valeur suivante.

Valeur Signification
KDF_USE_SECRET_AS_HMAC_KEY_FLAG
La valeur du contrat secret servira également de clé HMAC. Si cet indicateur est spécifié, le paramètre KDF_HMAC_KEY ne doit pas être inclus dans l’ensemble de paramètres du paramètre pParameterList . Cet indicateur est utilisé uniquement par la fonction de dérivation de clé BCRYPT_KDF_HMAC .

Valeur retournée

Retourne un code status qui indique la réussite ou l’échec de la fonction.

Les codes de retour possibles incluent, sans s’y limiter, les éléments suivants.

Code de retour Description
ERROR_SUCCESS
La fonction a réussi.
NTE_INVALID_HANDLE
Le paramètre hSharedSecret n’est pas valide.
NTE_INVALID_PARAMETER
Un ou plusieurs paramètres ne sont pas valides.

Remarques

La structure BCryptBufferDesc dans le paramètre pParameterList peut contenir plusieurs paramètres KDF_SECRET_PREPEND et KDF_SECRET_APPEND . Si plusieurs de ces paramètres sont spécifiés, les valeurs de paramètre sont concaténées dans l’ordre dans lequel elles sont contenues dans le tableau avant l’appel du KDF. Par exemple, supposons que les valeurs de paramètre suivantes soient spécifiées.

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

Si les valeurs de paramètre ci-dessus sont spécifiées, les valeurs concaténées du KDF réel sont les suivantes.

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

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

Un service ne doit pas appeler cette fonction à partir de sa fonction StartService. Si un service appelle cette fonction à partir de sa fonction StartService, un interblocage peut se produire et le service peut cesser de répondre.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows Vista [applications de bureau | applications UWP]
Serveur minimal pris en charge Windows Server 2008 [applications de bureau | applications UWP]
Plateforme cible Windows
En-tête ncrypt.h
Bibliothèque Ncrypt.lib
DLL Ncrypt.dll

Voir aussi

NCryptBufferDesc