Fonction CryptDeriveKey (wincrypt.h)

Article
08/27/2023

Important Cette API est déconseillée. Les logiciels nouveaux et existants doivent commencer à utiliser les API de nouvelle génération de chiffrement. Microsoft peut supprimer cette API dans les versions ultérieures.

La fonction CryptDeriveKey génère des clés de session de chiffrement dérivées d’une valeur de données de base. Cette fonction garantit que lorsque le même fournisseur de services de chiffrement (CSP) et les mêmes algorithmes sont utilisés, les clés générées à partir des mêmes données de base sont identiques. Les données de base peuvent être un mot de passe ou toute autre donnée utilisateur.

Cette fonction est identique à CryptGenKey, sauf que les clés de session générées sont dérivées des données de base au lieu d’être aléatoires. CryptDeriveKey ne peut être utilisé que pour générer des clés de session. Il ne peut pas générer de paires de clés publiques/privées.

Un handle à la clé de session est retourné dans le paramètre phKey . Ce handle peut être utilisé avec n’importe quelle fonction CryptoAPI qui nécessite un handle de clé.

Syntaxe

BOOL CryptDeriveKey(
  [in]      HCRYPTPROV hProv,
  [in]      ALG_ID     Algid,
  [in]      HCRYPTHASH hBaseData,
  [in]      DWORD      dwFlags,
  [in, out] HCRYPTKEY  *phKey
);

Paramètres

[in] hProv

Handle HCRYPTPROV d’un fournisseur de solutions cloud créé par un appel à CryptAcquireContext.

[in] Algid

Une structure ALG_ID qui identifie l’algorithme de chiffrement symétrique pour lequel la clé doit être générée. Les algorithmes disponibles seront probablement différents pour chaque fournisseur de solutions cloud. Pour plus d’informations sur l’identificateur d’algorithme utilisé par les différents fournisseurs pour les spécifications clés AT_KEYEXCHANGE et AT_SIGNATURE, consultez ALG_ID.

Pour plus d’informations sur ALG_ID valeurs à utiliser avec le fournisseur de chiffrement de base Microsoft, consultez Algorithmes de fournisseur de base. Pour plus d’informations sur ALG_ID valeurs à utiliser avec le fournisseur de chiffrement Microsoft Strong ou le fournisseur de chiffrement microsoft amélioré, consultez Algorithmes de fournisseur amélioré.

[in] hBaseData

Handle d’un objet de hachage qui a été alimenté par les données de base exactes.

Pour obtenir ce handle, une application doit d’abord créer un objet de hachage avec CryptCreateHash , puis ajouter les données de base à l’objet de hachage avec CryptHashData. Ce processus est décrit en détail dans Hachages et signatures numériques.

[in] dwFlags

Spécifie le type de clé générée.

Les tailles d’une clé de session peuvent être définies lorsque la clé est générée. La taille de clé, qui représente la longueur du module de clé en bits, est définie avec les 16 bits supérieurs de ce paramètre. Ainsi, si une clé de session RC4 128 bits doit être générée, la valeur 0x00800000 est combinée à toute autre valeur prédéfinie dwFlags avec une opération or au niveau du bit. En raison de la modification des restrictions de contrôle d’exportation, la longueur du csp par défaut et la longueur de la clé par défaut peuvent changer d’une version du système d’exploitation à l’autre. Il est important que le chiffrement et le déchiffrement utilisent le même csp et que la longueur de la clé soit définie explicitement à l’aide du paramètre dwFlags pour garantir l’interopérabilité sur différentes plateformes de système d’exploitation.

Les 16 bits inférieurs de ce paramètre peuvent être zéro ou vous pouvez spécifier un ou plusieurs des indicateurs suivants en utilisant l’opérateur OR au niveau du bit pour les combiner.

Valeur	Signification
CRYPT_CREATE_SALT	En règle générale, lorsqu’une clé de session est fabriquée à partir d’une valeur de hachage , il existe un certain nombre de bits restants. Par exemple, si la valeur de hachage est de 128 bits et que la clé de session est de 40 bits, il reste 88 bits. Si cet indicateur est défini, une valeur salt est attribuée à la clé en fonction des bits de valeur de hachage inutilisés. Vous pouvez récupérer cette valeur salt à l’aide de la fonction CryptGetKeyParam avec le paramètre dwParam défini sur KP_SALT. Si cet indicateur n’est pas défini, la clé reçoit une valeur de sel de zéro. Lorsque des clés avec des valeurs de sel différentes de zéro sont exportées (à l’aide de CryptExportKey), la valeur salt doit également être obtenue et conservée avec l’objet BLOB de clé.
CRYPT_EXPORTABLE	Si cet indicateur est défini, la clé de session peut être transférée hors du csp vers un objet BLOB de clé via la fonction CryptExportKey . Étant donné que les clés doivent généralement être exportables, cet indicateur doit généralement être défini. Si cet indicateur n’est pas défini, la clé de session n’est pas exportable. Cela signifie que la clé n’est disponible que dans la session active et que seule l’application qui l’a créée peut l’utiliser. Cet indicateur ne s’applique pas aux paires de clés publiques/privées.
CRYPT_NO_SALT	Cet indicateur spécifie qu’une valeur sans sel est allouée pour une clé symétrique de 40 bits. Pour plus d’informations, consultez Salt Value Functionality.
CRYPT_UPDATE_KEY	Certains fournisseurs de solutions cloud utilisent des clés de session dérivées de plusieurs valeurs de hachage. Dans ce cas, CryptDeriveKey doit être appelé plusieurs fois. Si cet indicateur est défini, une nouvelle clé de session n’est pas générée. Au lieu de cela, la clé spécifiée par phKey est modifiée. Le comportement précis de cet indicateur dépend du type de clé généré et du fournisseur de solutions cloud en cours d’utilisation. Les fournisseurs de services de chiffrement Microsoft ignorent cet indicateur.
CRYPT_SERVER 1024 (0x400)	Cet indicateur est utilisé uniquement avec les fournisseurs Schannel . Si cet indicateur est défini, la clé à générer est une clé d’écriture de serveur ; sinon, il s’agit d’une clé d’écriture cliente.

[in, out] phKey

Pointeur vers une variable HCRYPTKEY pour recevoir l’adresse du handle de la clé nouvellement générée. Une fois la clé terminée, relâchez le handle en appelant la fonction CryptDestroyKey .

Valeur retournée

Si la fonction réussit, la fonction retourne une valeur différente de zéro (TRUE).

Si la fonction échoue, elle retourne zéro (FALSE). Pour obtenir des informations d’erreur étendues, appelez GetLastError.

Les codes d’erreur préfacés par « NTE » sont générés par le fournisseur de solutions cloud en cours d’utilisation. Certains codes d’erreur possibles sont répertoriés dans le tableau suivant.

Code de retour	Description
ERROR_INVALID_HANDLE	L’un des paramètres spécifie un handle qui n’est pas valide.
ERROR_INVALID_PARAMETER	L’un des paramètres contient une valeur qui n’est pas valide. Il s’agit le plus souvent d’un pointeur qui n’est pas valide.
NTE_BAD_ALGID	Le paramètre Algid spécifie un algorithme que ce csp ne prend pas en charge.
NTE_BAD_FLAGS	Le paramètre dwFlags contient une valeur qui n’est pas valide.
NTE_BAD_HASH	Le paramètre hBaseData ne contient pas de handle valide pour un objet de hachage.
NTE_BAD_HASH_STATE	Une tentative d’ajout de données à un objet de hachage déjà marqué « terminé » a été effectuée.
NTE_BAD_UID	Le paramètre hProv ne contient pas de handle de contexte valide.
NTE_FAIL	La fonction a échoué d’une manière inattendue.
NTE_SILENT_CONTEXT	Le fournisseur n’a pas pu effectuer l’action, car le contexte a été acquis en mode silencieux.

Remarques

Lorsque des clés sont générées pour les chiffrements de blocs symétriques, la clé est configurée par défaut en mode de chaînage de blocs de chiffrement (CBC) avec un vecteur d’initialisation de zéro. Ce mode de chiffrement fournit une bonne méthode par défaut pour le chiffrement en bloc des données. Pour modifier ces paramètres, utilisez la fonction CryptSetKeyParam .

La fonction CryptDeriveKey termine le hachage. Une fois que CryptDeriveKey a été appelé, plus aucune donnée ne peut être ajoutée au hachage. Les appels supplémentaires à CryptHashData ou CryptHashSessionKey échouent. Une fois l’application terminée avec le hachage, CryptDestroyHash doit être appelé pour détruire l’objet de hachage.

Pour choisir une longueur de clé appropriée, les méthodes suivantes sont recommandées.

Pour énumérer les algorithmes pris en charge par le fournisseur de solutions cloud et pour obtenir les longueurs de clés maximales et minimales pour chaque algorithme, appelez CryptGetProvParam avec PP_ENUMALGS_EX.
Utilisez les longueurs minimale et maximale pour choisir une longueur de clé appropriée. Il n’est pas toujours recommandé de choisir la longueur maximale, car cela peut entraîner des problèmes de performances.
Une fois la longueur de clé souhaitée choisie, utilisez les 16 bits supérieurs du paramètre dwFlags pour spécifier la longueur de la clé.

Soit n la longueur de clé dérivée requise, en octets. La clé dérivée est les n premiers octets de la valeur de hachage après que le calcul de hachage a été effectué par CryptDeriveKey. Si le hachage n’est pas membre de la famille SHA-2 et que la clé requise est pour 3DES ou AES, la clé est dérivée comme suit :

Formez une mémoire tampon de 64 octets en répétant la constante 0x36 64 fois. Soit k la longueur de la valeur de hachage représentée par le paramètre d’entrée hBaseData. Définissez les premiers k octets de la mémoire tampon sur le résultat d’une opération XOR des premiers k octets de la mémoire tampon avec la valeur de hachage représentée par le paramètre d’entrée hBaseData.
Formez une mémoire tampon de 64 octets en répétant la constante 0x5C 64 fois. Définissez les premiers k octets de la mémoire tampon sur le résultat d’une opération XOR des premiers k octets de la mémoire tampon avec la valeur de hachage représentée par le paramètre d’entrée hBaseData.
Hachez le résultat de l’étape 1 en utilisant le même algorithme de hachage que celui utilisé pour calculer la valeur de hachage représentée par le paramètre hBaseData .
Hachez le résultat de l’étape 2 en utilisant le même algorithme de hachage que celui utilisé pour calculer la valeur de hachage représentée par le paramètre hBaseData .
Concaténer le résultat de l’étape 3 avec le résultat de l’étape 4.
Utilisez les n premiers n octets du résultat de l’étape 5 comme clé dérivée.

Le fournisseur de services de chiffrement complet RSA par défaut est le fournisseur de chiffrement fort RSA Microsoft. Le fournisseur de services de chiffrement Diffie-Hellman signature DSS par défaut est le fournisseur de services de chiffrement DSS Diffie-Hellman amélioré par Microsoft. Chacun de ces fournisseurs de services cloud a une longueur de clé symétrique par défaut de 128 bits pour RC2 et RC4.

Le tableau suivant répertorie les longueurs de clé minimales, par défaut et maximales pour la clé de session par algorithme et par fournisseur.

Fournisseur	Algorithmes	Longueur de clé minimale	Longueur de clé par défaut	Longueur maximale de clé
MS Base	RC4 et RC2	40	40	56
MS Base	DES	56	56	56
MS Enhanced	RC4 et RC2	40	128	128
MS Enhanced	DES	56	56	56
MS Enhanced	3DES 112	112	112	112
MS Enhanced	3DES	168	168	168
MS Strong	RC4 et RC2	40	128	128
MS Strong	DES	56	56	56
MS Strong	3DES 112	112	112	112
MS Strong	3DES	168	168	168
DSS/DH Base	RC4 et RC2	40	40	56
DSS/DH Base	Cylink MEK	40	40	40
DSS/DH Base	DES	56	56	56
DSS/DH Enh	RC4 et RC2	40	128	128
DSS/DH Enh	Cylink MEK	40	40	40
DSS/DH Enh	DES	56	56	56
DSS/DH Enh	3DES 112	112	112	112
DSS/DH Enh	3DES	168	168	168

Exemples

Pour obtenir un exemple qui utilise cette fonction, consultez Exemple de programme C : Dérivation d’une clé de session à partir d’un mot de passe.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	wincrypt.h
Bibliothèque	Advapi32.lib
DLL	Advapi32.dll