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.

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.

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.

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.

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.

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

Voir aussi

NCryptBufferDesc