NCryptKeyDerivation, fonction (ncrypt.h)

La fonction NCryptKeyDerivation crée une clé à partir d’une autre clé à l’aide de la fonction de dérivation de clé spécifiée. La fonction retourne la clé dans un tableau d’octets.

Syntaxe

SECURITY_STATUS NCryptKeyDerivation(
  [in]  NCRYPT_KEY_HANDLE hKey,
  [in]  NCryptBufferDesc  *pParameterList,
  [out] PUCHAR            pbDerivedKey,
  [in]  DWORD             cbDerivedKey,
  [out] DWORD             *pcbResult,
  [in]  ULONG             dwFlags
);

Paramètres

[in] hKey

Handle de la clé de fonction de dérivation de clé (KDF).

[in] pParameterList

Adresse d’une structure NCryptBufferDesc qui contient les paramètres KDF. Les paramètres peuvent être spécifiques à une fonction KDF ou générique. Le tableau suivant présente les paramètres obligatoires et facultatifs pour les KDF spécifiques implémentés par le fournisseur de stockage de clés logicielles Microsoft.

KDF Paramètre Obligatoire
SP800-108 HMAC en mode compteur KDF_LABEL Oui
KDF_CONTEXT oui
KDF_HASH_ALGORITHM oui
SP800-56A KDF_ALGORITHMID oui
KDF_PARTYUINFO oui
KDF_PARTYVINFO oui
KDF_HASH_ALGORITHM oui
KDF_SUPPPUBINFO non
KDF_SUPPPRIVINFO non
PBKDF2 KDF_HASH_ALGORITHM oui
KDF_SALT Oui
KDF_ITERATION_COUNT non
CAPI_KDF KDF_HASH_ALGORITHM Oui
 

Le paramètre générique suivant peut être utilisé :

  • KDF_GENERIC_PARAMETER
Les paramètres génériques sont mappés aux paramètres spécifiques de KDF de la manière suivante :

SP800-108 HMAC en mode compteur :

  • KDF_GENERIC_PARAMETER = KDF_LABEL||0x00||KDF_CONTEXT

SP800-56A

  • KDF_GENERIC_PARAMETER = KDF_ALGORITHMID || KDF_PARTYUINFO || KDF_PARTYVINFO {|| KDF_SUPPPUBINFO } {|| KDF_SUPPPRIVINFO }

PBKDF2

  • KDF_GENERIC_PARAMETER = KDF_SALT
  • KDF_ITERATION_COUNT : la valeur par défaut est 10000

CAPI_KDF

  • KDF_GENERIC_PARAMETER = Non utilisé

[out] pbDerivedKey

Adresse d’une mémoire tampon qui reçoit la clé. Le paramètre cbDerivedKey contient la taille, en octets, de la mémoire tampon de clé.

[in] cbDerivedKey

Taille, en octets, de la mémoire tampon vers laquelle pointe le paramètre pbDerivedKey .

[out] pcbResult

Pointeur vers un DWORD qui reçoit le nombre d’octets copiés dans la mémoire tampon vers laquelle pointe le paramètre pbDerivedKey .

[in] dwFlags

Indicateurs qui modifient le comportement de la fonction. La valeur suivante peut être utilisée avec le fournisseur de stockage de clés logicielles Microsoft.

Valeur Signification
BCRYPT_CAPI_AES_FLAG
Spécifie que l’algorithme cible est AES et que la clé doit donc être doublement développée. Cet indicateur n’est valide qu’avec l’algorithme CAPI_KDF.
NCRYPT_SILENT_FLAG
Demande que le fournisseur de services clés (KSP) n’affiche aucune interface utilisateur. Si le fournisseur doit afficher l’interface utilisateur pour fonctionner, l’appel échoue et le KSP doit définir le code d’erreur NTE_SILENT_CONTEXT comme dernière erreur.

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
ERROR_SUCCESS
La fonction a réussi.
NTE_INVALID_HANDLE
Les handles hProvider ou hKey ne sont pas valides.
NTE_INVALID_PARAMETER
Les paramètres pwszDerivedKeyAlg et pParameterList ne peuvent pas être NULL.
NTE_NO_MEMORY
La mémoire était insuffisante pour créer la clé.
NTE_NOT_SUPPORTED
Cette fonction n’est pas prise en charge par le fournisseur de stockage de clés.

Remarques

Vous pouvez utiliser les identificateurs d’algorithme suivants dans la fonction NCryptCreatePersistedKey avant d’appeler NCryptKeyDerivation :

  • BCRYPT_CAPI_KDF_ALGORITHM
  • BCRYPT_SP800108_CTR_HMAC_ALGORITHM
  • BCRYPT_SP80056A_CONCAT_ALGORITHM
  • BCRYPT_PBKDF2_ALGORITHM

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows 8 [applications de bureau | Applications UWP]
Serveur minimal pris en charge Windows Server 2012 [applications de bureau | Applications UWP]
Plateforme cible Windows
En-tête ncrypt.h
Bibliothèque Ncrypt.lib
DLL Ncrypt.dll

Voir aussi

BCryptKeyDerivation

NCryptDeriveKey