BCryptGenerateKeyPair, fonction (bcrypt.h)

La fonction BCryptGenerateKeyPair crée une paire de clés publique/privée vide. Après avoir créé une clé à l’aide de cette fonction, vous pouvez utiliser la fonction BCryptSetProperty pour définir ses propriétés ; Toutefois, la clé ne peut pas être utilisée tant que la fonction BCryptFinalizeKeyPair n’est pas appelée.

Syntaxe

NTSTATUS BCryptGenerateKeyPair(
  [in, out] BCRYPT_ALG_HANDLE hAlgorithm,
  [out]     BCRYPT_KEY_HANDLE *phKey,
  [in]      ULONG             dwLength,
  [in]      ULONG             dwFlags
);

Paramètres

[in, out] hAlgorithm

Gérer un fournisseur d’algorithmes qui prend en charge la signature, le chiffrement asymétrique ou le contrat de clé. Ce handle doit avoir été créé à l’aide de la fonction BCryptOpenAlgorithmProvider .

[out] phKey

Pointeur vers un BCRYPT_KEY_HANDLE qui reçoit le handle de la clé. Ce handle est utilisé dans les fonctions suivantes qui nécessitent une clé, telle que BCryptEncrypt. Ce handle doit être libéré lorsqu’il n’est plus nécessaire en le transmettant à la fonction BCryptDestroyKey .

[in] dwLength

Longueur, en bits, de la clé. Les fournisseurs d’algorithmes ont des restrictions de taille de clé différentes pour chaque algorithme asymétrique standard.

Pour les identificateurs d’algorithme post-quantique, le dwLength doit être égal à zéro.

Identificateur d’algorithme	Signification
BCRYPT_DH_ALGORITHM	La taille de clé doit être supérieure ou égale à 512 bits, inférieure ou égale à 4 096 bits, et doit être un multiple de 64.
BCRYPT_DSA_ALGORITHM	Avant Windows 8, la taille de clé doit être supérieure ou égale à 512 bits, inférieure ou égale à 1 024 bits et doit être un multiple de 64. À compter de Windows 8, la taille de clé doit être supérieure ou égale à 512 bits, inférieure ou égale à 3072 bits, et doit être un multiple de 64. Le traitement des tailles de clé inférieures ou égales à 1024 bits respecte FIPS 186-2. Le traitement des tailles de clé supérieures à 1024 et inférieures ou égales à 3072 adhère à FIPS 186-3.
BCRYPT_ECDH_P256_ALGORITHM	La taille de la clé doit être de 256 bits.
BCRYPT_ECDH_P384_ALGORITHM	La taille de la clé doit être de 384 bits.
BCRYPT_ECDH_P521_ALGORITHM	La taille de la clé doit être de 521 bits.
BCRYPT_ECDSA_P256_ALGORITHM	La taille de la clé doit être de 256 bits.
BCRYPT_ECDSA_P384_ALGORITHM	La taille de la clé doit être de 384 bits.
BCRYPT_ECDSA_P521_ALGORITHM	La taille de la clé doit être de 521 bits.
BCRYPT_RSA_ALGORITHM	La taille de clé doit être supérieure ou égale à 512 bits, inférieure ou égale à 16384 bits, et doit être un multiple de 64.

[in] dwFlags

Ensemble d’indicateurs qui modifient le comportement de cette fonction. Aucun indicateur n’est actuellement défini. Ce paramètre doit donc être égal à zéro.

Utilisez BCRYPT_NO_KEY_VALIDATION pour refuser les tests auto-tests FIPS applicables.

Valeur de retour

Retourne un code d’état qui indique la réussite ou l’échec de la fonction.

Les codes de retour possibles incluent, mais ne sont pas limités, les éléments suivants :

Retourner le code	Descriptif
STATUS_SUCCESS	La fonction a réussi.
STATUS_INVALID_HANDLE	Le handle d’algorithme dans le paramètre hAlgorithm n’est pas valide.
STATUS_INVALID_PARAMETER	Un ou plusieurs paramètres ne sont pas valides.
STATUS_NOT_SUPPORTED	Le fournisseur spécifié ne prend pas en charge le chiffrement de clé asymétrique.

Remarques

Selon les modes processeur pris en charge par un fournisseur, BCryptGenerateKeyPair peut être appelé en mode utilisateur ou en mode noyau. Les appelants en mode noyau peuvent s’exécuter à PASSIVE_LEVELIRQL ou DISPATCH_LEVEL IRQL. Si le niveau IRQL actuel est DISPATCH_LEVEL, le handle fourni dans le paramètre hAlgorithm doit avoir été ouvert à l’aide de l’indicateur BCRYPT_PROV_DISPATCH , et tous les pointeurs passés à la fonction BCryptGenerateKeyPair doivent faire référence à la mémoire nonpage (ou verrouillée).

L’appelant doit libérer phKey avec BCryptDestroyKey lorsque la clé est utilisée.

Si un handle d’algorithme XMS ou LMSS est transmis, cette fonction retourne STATUS_NOT_SUPPORTED , car la génération de clés pour les algorithmes de signature basés sur un hachage avec état n’est pas autorisée par FIPS.

Pour appeler cette fonction en mode noyau, utilisez Cng.lib, qui fait partie du Kit de développement de pilotes (DDK). Windows Server 2008 et Windows Vista : Pour appeler cette fonction en mode noyau, utilisez Ksecdd.lib.

Exigences

Exigence	Valeur
Client minimum requis	Windows Vista [applications de bureau | Applications UWP]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau | Applications UWP]
plateforme cible	Fenêtres
En-tête	bcrypt.h
Bibliothèque	Bcrypt.lib
DLL	Bcrypt.dll

Voir aussi

BCryptDestroyKey