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 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 |
|---|---|
|
La fonction a réussi. |
|
Le paramètre hSharedSecret n’est pas valide. |
|
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
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour