Fonction CryptGenKey (wincrypt.h)

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 vers 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 csp utilisé.

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

Pour ALG_ID valeurs à utiliser avec le fournisseur de chiffrement Microsoft Strong ou le fournisseur de chiffrement Microsoft Enhanced, consultez algorithmes de fournisseur améliorés.

Pour un fournisseur de solutions cloud Diffie-Hellman, utilisez l’une des valeurs suivantes.

En plus de générer des clés de session pour 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.

[in] dwFlags

Spécifie le type de clé généré. Les tailles d’une clé de session, d’une clé de signature RSA et d’une clé RSA clés d’échange 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 signature RSA 2 048 bits doit être générée, la valeur 0x08000000 est combinée à toute autre dwFlags valeur prédéfinie avec une opération orOR. Les 16 bits supérieurs de 0x08000000 sont 0x0800, ou 2 048 décimaux. 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, 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.

En particulier, le fournisseur de services de chiffrement complet RSA 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 et une longueur de clé par défaut de 1 024 bits pour les algorithmes de clé publique.

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

Le tableau suivant répertorie les longueurs minimales, par défaut et maximales de signature et de clé d’échange commençant par Windows XP.

Pour connaître les longueurs de clé 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.

[out] phKey

Adresse à 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 de retour

Retourne une valeur différente de zéro si elle réussit ou zéro sinon.

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.

Remarques

Si 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 .

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 des longueurs de clés maximales et minimales pour chaque algorithme. Pour ce faire, 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é.

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);
}

Exigences

Voir aussi

CryptAcquireContext

CryptDestroyKey

CryptExportKey

CryptGetKeyParam

CryptImportKey

CryptSetKeyParam

de génération de clés et de fonctions Exchange

problèmes de threading avec les fournisseurs de services de chiffrement