Fonction CryptDeriveKey (wincrypt.h)

Article
07/16/2024

important cette API est déconseillée. Les logiciels nouveaux et existants doivent commencer à utiliser 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 de chiffrement dérivées d’une valeur de données de base. Cette fonction garantit que lorsque les mêmes fournisseur de services de chiffrement (CSP) et les 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 paires de clés publiques/privées.

Un handle vers 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

Un handle HCRYPTPROV créé par un appel à CryptAcquireContext.

[in] Algid

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 Fort Microsoft ou le fournisseur de chiffrement Microsoft Amélioré, consultez algorithmes de fournisseur améliorés.

[in] hBaseData

Handle vers un objet de hachage qui a été alimenté 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é.

Les tailles d’une clé de session peuvent être définies lorsque la clé est générée. La taille de clé, représentant la longueur du module de clé en bits, est définie avec les 16 bits supérieurs de ce paramètre. Par conséquent, si une clé de session RC4 128 bits doit être générée, la valeur 0x00800000 est combinée avec toute autre valeur dwFlags valeur prédéfinie avec une opération OR au niveau du bit. En raison de la modification des restrictions de contrôle d’exportation, le fournisseur csp par défaut et la longueur de clé par défaut peuvent changer entre les versions du système d’exploitation. Il est important que le chiffrement et le déchiffrement utilisent le même fournisseur csp et que la longueur de la clé soit explicitement définie à 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 nuls ou vous pouvez spécifier un ou plusieurs des indicateurs suivants à l’aide de l’opérateur orou de bits pour les combiner.

Valeur	Signification
CRYPT_CREATE_SALT	En règle générale, lorsqu’une clé de session est effectuée à partir d’un valeur de hachage, il existe plusieurs bits de reste. Par exemple, si la valeur de hachage est de 128 bits et que la clé de session est de 40 bits, il y aura 88 bits restants. Si cet indicateur est défini, la clé est affectée à une valeur de sel en fonction des bits de valeur de hachage inutilisés. Vous pouvez récupérer cette valeur de sel à 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 les clés avec des valeurs de sel différent de zéro sont exportées (à l’aide de CryptExportKey), la valeur de sel doit également être obtenue et conservée avec leblob de clé .
CRYPT_EXPORTABLE	Si cet indicateur est défini, la clé de session peut être transférée hors du fournisseur de solutions Cloud dans un objet BLOB de clés 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é est disponible uniquement au sein de la session active et que seule l’application créée est en mesure de l’utiliser. Cet indicateur ne s’applique pas aux paires de clés publiques/privées.
CRYPT_NO_SALT	Cet indicateur spécifie qu’aucune valeur de sel n’est allouée pour une clé symétrique 40 bits. Pour plus d’informations, consultez fonctionnalité Salt Value.
CRYPT_UPDATE_KEY	Certains fournisseurs de services cloud utilisent des clés de session dérivées de plusieurs valeurs de hachage. Lorsque c’est le cas, CryptDeriveKey doit être appelée 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 particulier utilisé. Les fournisseurs de services de chiffrement Microsoft ignorent cet indicateur.
CRYPT_SERVER 1024 (0x400)	Cet indicateur est utilisé uniquement avec fournisseurs de 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 client.

[in, out] phKey

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

Valeur de retour

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écédé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.

Retourner le code	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 fournisseur de solutions Cloud ne prend pas en charge.
NTE_BAD_FLAGS	Le paramètre dwFlags contient une valeur non 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 a été effectuée pour ajouter des données à un objet de hachage qui est déjà marqué « terminé ».
NTE_BAD_UID	Le paramètre hProv ne contient pas de handle de contexte valide.
NTE_FAIL	La fonction a échoué de 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 chiffrements de blocs symétriques , la clé par défaut est configurée en mode 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 lede hachage . Une fois CryptDeriveKey a été appelée, aucune autre donnée ne peut être ajoutée au hachage. Des appels supplémentaires à CryptHashData ou CryptHashSessionKey échouent. Une fois l’application terminée avec le hachage, CryptDestroyHash doit être appelée 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 obtenir des longueurs de clé maximales et minimales pour chaque algorithme, appelez CryptGetProvParam avec PP_ENUMALGS_EX.
Utilisez les longueurs minimales et maximales pour choisir une longueur de clé appropriée. Il n’est pas toujours conseillé 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é.

Laissez n être la longueur de clé dérivée requise, en octets. La clé dérivée est la première n octets de la valeur de hachage une fois le calcul de hachage terminé par CryptDeriveKey. Si le hachage n’est pas membre de la famille SHA-2 et que la clé requise concerne 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. Laissez k être la longueur de la valeur de hachage représentée par le paramètre d’entrée hBaseData. Définissez le premier k octets de la mémoire tampon sur le résultat d’une opération XOR du premier 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 le premier k octets de la mémoire tampon sur le résultat d’une opération XOR du premier k octets de la mémoire tampon avec la valeur de hachage représentée par le paramètre d’entrée hBaseData.
Hachage du résultat de l’étape 1 à l’aide du même algorithme de hachage que celui utilisé pour calculer la valeur de hachage représentée par le paramètre hBaseData.
Hachage du 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 la première n octets du résultat de l’étape 5 comme clé dérivée.

Le fournisseur de services de chiffrement RSA complet par défaut est le fournisseur microsoft RSA Strong Cryptographic Provider. La signature DSS par défaut Diffie-Hellman fournisseur de services de chiffrement est le fournisseur de services de chiffrement Microsoft Enhanced DSS Diffie-Hellman. Chacune de ces fournisseurs de services cloud a une longueur de clé symétrique 128 bits par défaut 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 fournisseur.

Fournisseur	Algorithmes	Longueur minimale de la clé	Longueur de clé par défaut	Longueur maximale de la clé
MS Base	RC4 et RC2	40	40	56
MS Base	DES	56	56	56
MS Amélioré	RC4 et RC2	40	128	128
MS Amélioré	DES	56	56	56
MS Amélioré	3DES 112	112	112	112
MS Amélioré	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.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows XP [applications de bureau uniquement]
serveur minimum pris en charge	Windows Server 2003 [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	wincrypt.h
bibliothèque	Advapi32.lib
DLL	Advapi32.dll