NCryptKeyDerivation, fonction (ncrypt.h)

Article
03/04/2024

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

Partager via