Fonction CryptGenKey (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 CryptGenKey génère une clé de session de chiffrement aléatoire ou une paire de clés publique/privée. Un handle à la clé ou à la paire de clés est retourné dans phKey. Ce handle peut ensuite être utilisé en fonction des besoins avec n’importe quelle fonction CryptoAPI qui nécessite un handle de clé.

L’application appelante doit spécifier l’algorithme lors de l’appel de cette fonction. Étant donné que ce type d’algorithme est conservé avec la clé, l’application n’a pas besoin de spécifier l’algorithme ultérieurement lorsque les opérations de chiffrement réelles sont effectuées.

Syntaxe

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

Paramètres

[in] hProv

Handle à un fournisseur de services de chiffrement (CSP) créé par un appel à CryptAcquireContext.

[in] Algid

Valeur ALG_ID qui identifie l’algorithme pour lequel la clé doit être générée. Les valeurs de ce paramètre varient en fonction du fournisseur de solutions cloud utilisé.

Pour ALG_ID valeurs à utiliser avec le fournisseur de chiffrement de base Microsoft, consultez Algorithmes du fournisseur de base.

Pour 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é.

Pour un Diffie-Hellman CSP, utilisez l’une des valeurs suivantes.

Valeur	Signification
CALG_DH_EPHEM	Spécifie une clé Diffie-Hellman « éphémère ».
CALG_DH_SF	Spécifie une clé de Diffie-Hellman « Stocker et transférer ».

En plus de générer des clés de session pour les algorithmes symétriques, cette fonction peut également générer des paires de clés publiques/privées. Chaque client CryptoAPI possède généralement deux paires de clés publiques/privées. Pour générer l’une de ces paires de clés, définissez le paramètre Algid sur l’une des valeurs suivantes.

Valeur	Signification
AT_KEYEXCHANGE	Échange de clés
AT_SIGNATURE	Signature numérique

Note Lorsque les spécifications de clé AT_KEYEXCHANGE et AT_SIGNATURE sont spécifiées, les identificateurs d’algorithme utilisés pour générer la clé dépendent du fournisseur utilisé. Par conséquent, pour ces spécifications de clé, les valeurs retournées par CryptGetKeyParam (lorsque le paramètre KP_ALGID est spécifié) dépendent du fournisseur utilisé. Pour déterminer l’identificateur d’algorithme utilisé par les différents fournisseurs pour les spécifications clés AT_KEYEXCHANGE et AT_SIGNATURE, consultez ALG_ID.

[in] dwFlags

Spécifie le type de clé générée. Les tailles d’une clé de session, d’une clé de signature RSA et de clés d’échange de clés RSA 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. Par conséquent, si une clé de signature RSA 2 048 bits doit être générée, la valeur 0x08000000 est combinée à toute autre valeur prédéfinie dwFlags avec une opération OR au niveau du bit. Les 16 bits supérieurs de 0x08000000 sont 0x0800 ou décimaux 2 048. La valeur RSA1024BIT_KEY peut être utilisée pour spécifier une clé RSA 1024 bits.

En raison de la modification des restrictions de contrôle d’exportation, la longueur du fournisseur de solutions cloud 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.

En particulier, le fournisseur de services de chiffrement COMPLET RSA par défaut est le fournisseur de chiffrement Fort RSA Microsoft. La signature DSS par défaut Diffie-Hellman fournisseur de services de chiffrement est le fournisseur de chiffrement DSS Diffie-Hellman amélioré Microsoft. Chacun de ces fournisseurs de solutions cloud a une longueur de clé symétrique par défaut de 128 bits pour RC2 et RC4 et une longueur de clé par défaut de 1 024 bits pour les algorithmes à clé publique.

Si les 16 bits supérieurs sont zéro, la taille de clé par défaut est générée. Si une clé supérieure au maximum ou inférieure au minimum est spécifiée, l’appel échoue avec le code ERROR_INVALID_PARAMETER.

Le tableau suivant répertorie les longueurs de signature et d’échange minimales, par défaut et maximales à compter de Windows XP.

Type de clé et fournisseur	Longueur minimale	Longueur par défaut	Longueur maximale
Fournisseur de base RSA Signature et ExchangeKeys	384	512	16 384
Fournisseurs RSA forts et améliorés Signature et clés Exchange	384	1 024	16 384
Fournisseurs de base DSS Clés de signature	512	1 024	1 024
Fournisseurs de base DSS Clés Exchange	Non applicable	Non applicable	Non applicable
Fournisseurs de base DSS/DH Clés de signature	512	1 024	1 024
Fournisseurs de base DSS/DH Clés Exchange	512	512	1 024
Fournisseurs améliorés DSS/DH Clés de signature	512	1 024	1 024
Fournisseurs améliorés DSS/DH Clés Exchange	512	1 024	4 096

Pour connaître la longueur des clés de session, consultez CryptDeriveKey.

Pour plus d’informations sur les clés générées à l’aide de fournisseurs Microsoft, consultez Fournisseurs de services de chiffrement Microsoft.

Les 16 bits inférieurs de ce paramètre peuvent être zéro ou une combinaison d’une ou plusieurs des valeurs suivantes.

Valeur	Signification
CRYPT_ARCHIVABLE	Si cet indicateur est défini, la clé peut être exportée jusqu’à ce que son handle soit fermé par un appel à CryptDestroyKey. Cela permet d’exporter les clés nouvellement générées lors de leur création à des fins d’archivage ou de récupération de clé. Une fois le handle fermé, la clé n’est plus exportable.
CRYPT_CREATE_IV	Cet indicateur n’est pas utilisé.
CRYPT_CREATE_SALT	Si cet indicateur est défini, une valeur de sel aléatoire est affectée automatiquement à la clé. 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 salt différentes de zéro sont exportées (via CryptExportKey), la valeur salt doit également être obtenue et conservée avec l’objet BLOB de clé.
CRYPT_DATA_KEY	Cet indicateur n’est pas utilisé.
CRYPT_EXPORTABLE	Si cet indicateur est défini, la clé peut être transférée hors du fournisseur de solutions Cloud vers un objet BLOB de clé à l’aide de la fonction CryptExportKey . Étant donné que les clés de session doivent généralement être exportables, cet indicateur doit généralement être défini lors de leur création. Si cet indicateur n’est pas défini, la clé n’est pas exportable. Pour une clé de session, cela signifie que la clé est disponible uniquement dans la session active et que seule l’application qui l’a créée pourra l’utiliser. Pour une paire de clés publique/privée, cela signifie que la clé privée ne peut pas être transportée ou sauvegardée. Cet indicateur s’applique uniquement aux objets BLOB de clé de session et de clé privée. Elle ne s’applique pas aux clés publiques, qui sont toujours exportables.
CRYPT_FORCE_KEY_PROTECTION_HIGH	Cet indicateur spécifie une protection de clé forte. Lorsque cet indicateur est défini, l’utilisateur est invité à entrer un mot de passe pour la clé lors de sa création. L’utilisateur est invité à entrer le mot de passe chaque fois que cette clé est utilisée. Cet indicateur est utilisé uniquement par les fournisseurs de services cloud fournis par Microsoft. Les fournisseurs de solutions cloud tiers définissent leur propre comportement pour une protection forte des clés. La spécification de cet indicateur entraîne le même résultat que l’appel de cette fonction avec l’indicateur CRYPT_USER_PROTECTED lorsque la protection par clé forte est spécifiée dans le registre système. Si cet indicateur est spécifié et que le handle du fournisseur dans le paramètre hProv a été créé à l’aide de l’indicateur CRYPT_VERIFYCONTEXT ou CRYPT_SILENT , cette fonction définit la dernière erreur sur NTE_SILENT_CONTEXT et retourne zéro. Windows Server 2003 et Windows XP : Cet indicateur n’est pas pris en charge.
CRYPT_KEK	Cet indicateur n’est pas utilisé.
CRYPT_INITIATOR	Cet indicateur n’est pas utilisé.
CRYPT_NO_SALT	Cet indicateur spécifie qu’une valeur sans sel est allouée pour une clé symétrique de quarante bits. Pour plus d’informations, consultez Salt Value Functionality.
CRYPT_ONLINE	Cet indicateur n’est pas utilisé.
CRYPT_PREGEN	Cet indicateur spécifie une génération initiale de clé Diffie-Hellman ou DSS. Cet indicateur est utile uniquement avec les fournisseurs de solutions cloud Diffie-Hellman et DSS. Lorsqu’elle est utilisée, une longueur de clé par défaut est utilisée, sauf si une longueur de clé est spécifiée dans les 16 bits supérieurs du paramètre dwFlags . Si les paramètres qui impliquent des longueurs de clé sont définis sur une clé PREGEN Diffie-Hellman ou DSS à l’aide de CryptSetKeyParam, les longueurs de clé doivent être compatibles avec la longueur de clé définie ici.
CRYPT_RECIPIENT	Cet indicateur n’est pas utilisé.
CRYPT_SF	Cet indicateur n’est pas utilisé.
CRYPT_SGCKEY	Cet indicateur n’est pas utilisé.
CRYPT_USER_PROTECTED	Si cet indicateur est défini, l’utilisateur est averti par le biais d’une boîte de dialogue ou d’une autre méthode lorsque certaines actions tentent d’utiliser cette clé. Le comportement précis est spécifié par le fournisseur csp utilisé. Si le contexte du fournisseur a été ouvert avec l’indicateur CRYPT_SILENT défini, l’utilisation de cet indicateur entraîne un échec et la dernière erreur est définie sur NTE_SILENT_CONTEXT.
CRYPT_VOLATILE	Cet indicateur n’est pas utilisé.

[out] phKey

Adresse vers laquelle la fonction copie le handle de la clé nouvellement générée. Lorsque vous avez terminé d’utiliser la clé, supprimez le handle de la clé en appelant la fonction CryptDestroyKey .

Valeur retournée

Retourne une valeur différente de zéro en cas de réussite ou de zéro dans le cas contraire.

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 particulier utilisé. 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_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

Si des clés sont générées pour les chiffrements par blocs symétriques, la clé, par défaut, est configurée en mode de chaînage de blocs de chiffrement (CBC) avec un vecteur d’initialisation égal à 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 .

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

Énumérez les algorithmes pris en charge par le fournisseur de solutions Cloud et obtenez les longueurs de clé maximales et minimales pour chaque algorithme. Pour ce faire, 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é.

Exemples

L’exemple suivant montre la création d’une clé de session aléatoire. Pour obtenir un exemple qui inclut le contexte complet de cet exemple, consultez Exemple de programme C : chiffrement d’un fichier. Pour obtenir un autre exemple qui utilise cette fonction, consultez Exemple de programme C : Déchiffrement d’un fichier.

//-------------------------------------------------------------------
//  Declare the handle to the key.
HCRYPTKEY hKey; 
//-------------------------------------------------------------------
//  This example assumes that a cryptographic context 
//  has been acquired, and that it is stored in hCryptProv.
//---------------------------------------------------------------
//  Create a random session key. 

 if(CryptGenKey(
          hCryptProv, 
          ENCRYPT_ALGORITHM, 
          KEYLENGTH | CRYPT_EXPORTABLE, 
          &hKey))
 {
         printf("A session key has been created.\n");
 } 
 else
 {
          printf("Error during CryptGenKey.\n"); 
          exit(1);
 }
//-------------------------------------------------------------------
//  The key created can be exported into a key BLOB that can be
//  written to a file.
//  ...
//  When you have finished using the key, free the resource.
if (!CryptDestroyKey(hKey))
{
          printf("Error during CryptDestroyKey.\n"); 
          exit(1);
}

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