BCryptDeriveKey, fonction (bcrypt.h)

La fonction BCryptDeriveKey dérive une clé d’un BCRYPT_SECRET_HANDLE. Cette opération est généralement effectuée dans le cadre d’une procédure d’accord secret.

Pour obtenir la dérivation de clé à partir d’un secret directement fourni par l’appelant, 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 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 . Il s’agit généralement d’une mauvaise pratique, car elle peut réduire considérablement la force de sécurité de la clé résultante.

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 ppcResult 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.

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

KDF-Output = Hash(
    KDF-Prepend + 
    hSharedSecret + 
    KDF-Append)

BCRYPT_KDF_HMAC (L"HMAC »)

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

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 . Il s’agit généralement d’une mauvaise pratique, car elle peut réduire considérablement la force de sécurité de la clé résultante.

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 ppcResult 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.

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

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é pseudo-aléatoire (PRF) de la fonction de dérivation de la 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.

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. Il s’agit également de SP800-56C rev2 à une étape KDF.

La fonction KDF accepte une fonction de hachage approuvée comme paramètre, mais cette API choisit la fonction de hachage en interne, correspondant à la force de sécurité de l’algorithme de hachage à l’algorithme utilisé pour générer le handle secret. (par exemple, ECDH P-256 utilise SHA256, ECDH P-384 utilise SHA384)

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.

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. L’utilisation de cette option est généralement incorrecte, mais peut être nécessaire si vous devez interagir avec un KDF non pris en charge.

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 . Il s’agit généralement d’une mauvaise pratique, car elle peut réduire considérablement la force de sécurité de la clé résultante.

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 ppcResult 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.

BCRYPT_KDF_HKDF (L"HKDF »)

Utilisez la fonction HKDF (Extract-and-Expand KDF) basée sur HMAC à partir de RFC 5869.

Dans HKDF, une distinction est faite entre la dérivation d’une clé de l’une ou l’autre :

1. La sortie d’une fonction d’accord secret, qui n’est pas aléatoire uniformément et est considérée comme du matériel de clé d’entrée (IKM). Presque tous les utilisateurs de BCryptDeriveKey auront un handle secret de ce formulaire.
2. Valeur secrète uniformément aléatoire.

La première étape consiste à « extraire » une clé pseudo-random (PRK) du handle secret.

Cette étape est effectuée en appelant BCryptSetProperty sur un handle secret avec BCRYPT_HKDF_HASH_ALGORITHM pour définir l’algorithme de hachage à utiliser dans les calculs HMAC dans HKDF. Ceci est suivi d’un deuxième appel à BCryptSetProperty avec l’un des deux :

1. Si le handle de secret représente IKM, utilisez BCRYPT_HKDF_SALT_AND_FINALIZE pour fournir la valeur de sel facultative et extraire le PRK à partir de l’IKM et finaliser le handle secret.
2. Sinon, utilisez BCRYPT_HKDF_PRK_AND_FINALIZE pour transformer directement la valeur secrète en PRK HKDF et finaliser le handle secret.

La deuxième étape consiste à « Développer » le PRK dans une clé dérivée de sortie.

Cette étape est effectuée en appelant BCryptDeriveKey sur un handle de secret finalisé.

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.

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

KDF-Output = HKDF-Expand(
    hSharedSecret.PRK,
    info,
    cbDerivedKey)

Windows 10 : La prise en charge de HKDF commence.

[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 l’ULONG pointé par le paramètre cciResult .

[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 est 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 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 :

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 abValue0[] = {0x01};
BYTE abValue1[] = {0x04, 0x05};
BYTE abValue2[] = {0x10, 0x11, 0x12};
BYTE abValue3[] = {0x20, 0x21, 0x22, 0x23};

Parameter[0].type = KDF_SECRET_APPEND
Parameter[0].value = abValue0;
Parameter[0].length = sizeof (abValue0);
Parameter[1].type = KDF_SECRET_PREPEND
Parameter[1].value = abValue1;
Parameter[1].length = sizeof (abValue1);
Parameter[2].type = KDF_SECRET_APPEND
Parameter[2].value = abValue2;
Parameter[2].length = sizeof (abValue2);
Parameter[3].type = KDF_SECRET_PREPEND
Parameter[3].value = abValue3;
Parameter[3].length = sizeof (abValue3);

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.

Lorsque vous utilisez un fournisseur d’algorithmes pris en charge, BCryptDeriveKey peut être appelé en mode utilisateur ou en 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 la mémoire non paginé (ou verrouillée) et doit être dérivé d’un handle d’algorithme retourné par un fournisseur qui a été 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

Voir aussi

BCryptBufferDesc

BCryptSecretAgreement