NCryptDeriveKey, fonction (ncrypt.h)

La fonction NCryptDeriveKey dérive une clé d’un NCRYPT_SECRET_HANDLE. Cette fonction est destinée à être utilisée dans le cadre d’une procédure de contrat secret utilisant des clés de contrat secret persistantes.

Pour dériver le matériau 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 secret à partir duquel créer la clé. Ce handle est actuellement 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 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 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 . 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.

Cela est également appelé SP800-56C rev2 KDF en une étape (section 4.1) à l’aide d’une fonction de hachage approuvée qui a une force correspondant à l’algorithme utilisé pour générer le handle secret.

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.

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 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 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 est NULL, cette fonction place la taille requise, en octets, dans le DWORD pointé par le paramètre cciResult .

[in] cbDerivedKey

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

[out] pcbResult

Pointeur vers un DWORD 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 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 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 NCryptBufferDesc 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.

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.

Spécifications

Voir aussi

NCryptBufferDesc

NCryptSecretAgreement