Partager via

BCryptDeriveKey, fonction (bcrypt.h)

  • Article

La fonction BCryptDeriveKey dérive une clé d’une valeur de contrat secret.

Pour obtenir 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 spécifié d’octets 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 l' 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 de 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é.

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

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é Hash-Based code d’authentification des messages (HMAC).

Si le paramètre cbDerivedKey est inférieur à la taille de la clé dérivée, cette fonction copie uniquement le nombre spécifié d’octets 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 l' 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 de 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é.

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

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é (PRF) de sécurité de couche de transport (TLS) . La taille de la clé dérivée est toujours de 48 octets. Par conséquent, le paramètre cbDerivedKey doit être 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 de PRF. La valeur initiale doit être de 64 octets de long. Obligatoire
KDF_TLS_PRF_PROTOCOL Valeur DWORD qui spécifie la version du protocole TLS dont l’algorithme PRF doit être utilisé.

Les valeurs valides sont les suivantes :

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 et Windows Vista : TLS1_1_PROTOCOL_VERSION, TLS1_2_PROTOCOL_VERSION et 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.

 Optionnel
KDF_HASH_ALGORITHM ID d’algorithme CNG de 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é. Optionnel
 

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. Optionnel
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é. Optionnel
 

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 petite-endienne 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 spécifié d’octets 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 l' 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 est NULL, cette fonction place la taille requise, en octets, dans le ULONG pointé par le paramètre .

[in] cbDerivedKey

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

[out] pcbResult

Pointeur vers un ULONG qui reçoit le nombre d’octets copiés dans la mémoire tampon pbDerivedKey. Si le paramètre pbDerivedKey est NULL, cette fonction place la taille requise, en octets, dans la ULONG pointée 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 de l’accord 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 dans le paramètre pParameterList. Cet indicateur est utilisé uniquement par la fonction de dérivation de clé BCRYPT_KDF_HMAC.

Valeur de retour

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

Les codes de retour possibles incluent, mais ne sont pas limités à, les éléments suivants.

Retourner le code Description
STATUS_SUCCESS
 La fonction a réussi.
STATUS_INTERNAL_ERROR
 Une erreur interne s’est produite.
STATUS_INVALID_HANDLE
 Le handle dans le paramètre hSharedSecret n’est pas valide.
STATUS_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 de la fonction KDF. Par exemple, supposons que les valeurs de paramètre suivantes sont 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 à la fonction KDF réelle 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 toutes les autres fonctions CNG, car la plupart d’entre eux prennent des entrées encodées big-endian.

Selon les modes de processeur pris en charge par un fournisseur, BCryptDeriveKey peut être appelé en mode utilisateur ou en mode noyau. Les appelants en mode noyau peuvent s’exécuter à PASSIVE_LEVEL IRQL ou DISPATCH_LEVEL IRQL. Si le niveau IRQL actuel est DISPATCH_LEVEL, le handle fourni dans le paramètre hSharedSecret doit se trouver dans la mémoire nonpage (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.

Exigences

Exigence Valeur
client minimum pris en charge Windows Vista [applications de bureau | Applications UWP]
serveur minimum pris en charge Windows Server 2008 [applications de bureau | Applications UWP]
plateforme cible Windows
d’en-tête bcrypt.h
bibliothèque Bcrypt.lib
DLL Bcrypt.dll

Voir aussi

BCryptSecretAgreement