BCryptDeriveKey, fonction (bcrypt.h)
La fonction BCryptDeriveKey dérive une clé d’une valeur de contrat secret.
Pour la dérivation de clé à partir d’un secret donné, consultez BCryptKeyDerivation.
Syntaxe
NTSTATUS BCryptDeriveKey(
[in] BCRYPT_SECRET_HANDLE hSharedSecret,
[in] LPCWSTR pwszKDF,
[in, optional] BCryptBufferDesc *pParameterList,
[out, optional] PUCHAR pbDerivedKey,
[in] ULONG cbDerivedKey,
[out] ULONG *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 BCryptSecretAgreement .
[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 |
| KDF_TLS_PRF_PROTOCOL |
Valeur DWORD qui spécifie la version du protocole TLS dont l’algorithme PRF doit être utilisé.
Les valeurs autorisées sont :
Windows Server 2008 et Windows Vista : TLS1_1_PROTOCOL_VERSION, les TLS1_2_PROTOCOL_VERSION et les DTLS1_0_PROTOCOL_VERSION ne sont pas pris en charge. Windows Server 2008 R2, Windows 7, Windows Server 2008 et Windows Vista : DTLS1_0_PROTOCOL_VERSION n’est pas pris en charge. |
Facultatif |
| KDF_HASH_ALGORITHM | ID d’algorithme CNG du hachage à utiliser avec le HMAC dans le PRF, pour la version du protocole TLS 1.2. Les choix valides sont SHA-256 et SHA-384. S’il n’est pas spécifié, SHA-256 est utilisé. | Facultatif |
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.
BCRYPT_KDF_RAW_SECRET (L"TRUNCATE »)
Retourne la représentation little-endian du secret brut sans aucune modification.
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.
Windows 8, 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 BCryptBufferDesc 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 l’ULONG vers lequel pointe le paramètre pcbResult .
[in] cbDerivedKey
Taille, en octets, de la mémoire tampon pbDerivedKey .
[out] pcbResult
Pointeur vers un ULONG qui reçoit le nombre d’octets qui ont été 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 l’ULONG 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. |
|
Une erreur interne s’est produite. |
|
Le handle dans 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
Si le paramètre pwszKDF est défini sur BCRYPT_KDF_RAW_SECRET, le secret retourné (contrairement aux autres valeurs pwszKDF ) est encodé au format little endian. Il est important de prendre note de cela lors de l’utilisation du secret brut dans d’autres fonctions CNG, car la plupart d’entre elles acceptent des entrées encodées big-endian.
Selon les modes de processeur pris en charge par un fournisseur, BCryptDeriveKey peut être appelé à partir du mode utilisateur ou du mode noyau. Les appelants en mode noyau peuvent s’exécuter à PASSIVE_LEVELIRQL ou DISPATCH_LEVEL IRQL. Si le niveau IRQL actuel est DISPATCH_LEVEL, le handle fourni dans le paramètre hSharedSecret doit se trouver dans une mémoire non paginée (ou verrouillée) et doit être dérivé d’un handle d’algorithme retourné par un fournisseur ouvert à l’aide de l’indicateur BCRYPT_PROV_DISPATCH .
Pour appeler cette fonction en mode noyau, utilisez Cng.lib, qui fait partie du Kit de développement de pilotes (DDK). Windows Server 2008 et Windows Vista : Pour appeler cette fonction en mode noyau, utilisez Ksecdd.lib.
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 | bcrypt.h |
| Bibliothèque | Bcrypt.lib |
| DLL | Bcrypt.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