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 à 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 |
---|---|
|
Spécifie une clé Diffie-Hellman « éphémère ». |
|
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 |
---|---|
|
Échange de clés |
|
Signature numérique |
[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 |
---|---|
|
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. |
|
Cet indicateur n’est pas utilisé. |
|
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é. |
|
Cet indicateur n’est pas utilisé. |
|
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. |
|
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. |
|
Cet indicateur n’est pas utilisé. |
|
Cet indicateur n’est pas utilisé. |
|
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. |
|
Cet indicateur n’est pas utilisé. |
|
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. |
|
Cet indicateur n’est pas utilisé. |
|
Cet indicateur n’est pas utilisé. |
|
Cet indicateur n’est pas utilisé. |
|
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. |
|
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 |
---|---|
|
L’un des paramètres spécifie un handle qui n’est pas valide. |
|
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. |
|
Le paramètre Algid spécifie un algorithme que ce csp ne prend pas en charge. |
|
Le paramètre dwFlags contient une valeur qui n’est pas valide. |
|
Le paramètre hProv ne contient pas de handle de contexte valide. |
|
La fonction a échoué d’une manière inattendue. |
|
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 |
Voir aussi
Génération de clés et fonctions Exchange
Problèmes liés aux threads avec les fournisseurs de services de chiffrement
Commentaires
https://aka.ms/ContentUserFeedback.
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultezEnvoyer et afficher des commentaires pour