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.
| Valeur | Signification |
|---|---|
|
Spécifie une clé Diffie-Hellman « éphémère ». |
|
Spécifie une clé Diffie-Hellman « Stocker et transférer ». |
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.
| Valeur | Signification |
|---|---|
|
Échange de clés |
|
Signature numérique |
[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.
| 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 Clés de signature et d’échange |
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 |
Sans objet | Sans objet | Sans objet |
|
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 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.
| 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 la création pour l’archivage ou la 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, la clé est affectée automatiquement à une valeur de sel de aléatoire. Vous pouvez récupérer cette valeur de sel à l’aide de la fonction CryptGetKeyParam 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érente de zéro sont exportées (via |
|
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 dans un objet blob de clés à 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 sera en mesure de 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 à la clé de session et objets blob de clé privée. Elle ne s’applique pas aux clés publiques, qui sont toujours exportables. |
|
Cet indicateur spécifie une protection forte par clé. Lorsque cet indicateur est défini, l’utilisateur est invité à entrer un mot de passe pour la clé lors de la création de la clé. 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 services cloud tiers définissent leur propre comportement pour une protection forte par clé. 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 forte des clés 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 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’aucune valeur de sel n' est allouée pour une clé symétrique quarante bits. Pour plus d’informations, consultez fonctionnalité Salt Value. |
|
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 services 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 csp utilisé. Si le contexte du fournisseur a été ouvert avec l’indicateur de CRYPT_SILENT défini, l’utilisation de cet indicateur provoque un échec et la dernière erreur est définie sur NTE_SILENT_CONTEXT. |
|
Cet indicateur n’est pas utilisé. |
[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.
| Retourner le code | 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 fournisseur de solutions Cloud ne prend pas en charge. |
|
Le paramètre dwFlags contient une valeur non valide. |
|
Le paramètre hProv ne contient pas de handle de contexte valide. |
|
La fonction a échoué de 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 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
| 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 |
Voir aussi
de génération de clés et de fonctions Exchange
problèmes de threading avec les fournisseurs de services de chiffrement