Funzione BCryptGenerateKeyPair (bcrypt.h)

La funzione BCryptGenerateKeyPair crea una coppia di chiavi pubblica/privata vuota. Dopo aver creato una chiave usando questa funzione, è possibile usare la funzione BCryptSetProperty per impostarne le proprietà; Tuttavia, la chiave non può essere usata finché non viene chiamata la funzione BCryptFinalizeKeyPair .

Sintassi

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

Parametri

[in, out] hAlgorithm

Handle di un provider di algoritmi che supporta la firma, la crittografia asimmetrica o il contratto di chiave. Questo handle deve essere stato creato usando la funzione BCryptOpenAlgorithmProvider .

[out] phKey

Puntatore a un BCRYPT_KEY_HANDLE che riceve l'handle della chiave. Questo handle viene usato nelle funzioni successive che richiedono una chiave, ad esempio BCryptEncrypt. Questo handle deve essere rilasciato quando non è più necessario passandolo alla funzione BCryptDestroyKey.

[in] dwLength

Lunghezza, in bit, della chiave. I provider di algoritmi hanno restrizioni di dimensioni chiave diverse per ogni algoritmo asimmetrico standard.

Per gli identificatori di algoritmo post-quantistico, dwLength deve essere zero.

Identificatore dell'algoritmo	Significato
BCRYPT_DH_ALGORITHM	Le dimensioni della chiave devono essere maggiori o uguali a 512 bit, minori o uguali a 4096 bit e devono essere multiple di 64.
BCRYPT_DSA_ALGORITHM	Prima di Windows 8, la dimensione della chiave deve essere maggiore o uguale a 512 bit, minore o uguale a 1024 bit e deve essere un multiplo di 64. A partire da Windows 8, la dimensione della chiave deve essere maggiore o uguale a 512 bit, minore o uguale a 3072 bit e deve essere un multiplo di 64. L'elaborazione per le dimensioni delle chiavi minore o uguale a 1024 bit è conforme a FIPS 186-2. L'elaborazione per le dimensioni delle chiavi maggiore di 1024 e minore o uguale a 3072 è conforme a FIPS 186-3.
BCRYPT_ECDH_P256_ALGORITHM	Le dimensioni della chiave devono essere di 256 bit.
BCRYPT_ECDH_P384_ALGORITHM	Le dimensioni della chiave devono essere di 384 bit.
BCRYPT_ECDH_P521_ALGORITHM	Le dimensioni della chiave devono essere di 521 bit.
BCRYPT_ECDSA_P256_ALGORITHM	Le dimensioni della chiave devono essere di 256 bit.
BCRYPT_ECDSA_P384_ALGORITHM	Le dimensioni della chiave devono essere di 384 bit.
BCRYPT_ECDSA_P521_ALGORITHM	Le dimensioni della chiave devono essere di 521 bit.
BCRYPT_RSA_ALGORITHM	Le dimensioni della chiave devono essere maggiori o uguali a 512 bit, minori o uguali a 16384 bit e devono essere multiple di 64.

[in] dwFlags

Set di flag che modificano il comportamento di questa funzione. Non sono attualmente definiti flag, quindi questo parametro deve essere zero.

Usare BCRYPT_NO_KEY_VALIDATION per rifiutare esplicitamente eventuali auto test FIPS applicabili.

Valore restituito

Restituisce un codice di stato che indica l'esito positivo o negativo della funzione.

I codici restituiti possibili includono, a titolo esemplificativo, quanto segue:

Codice restituito	Descrizione
STATUS_SUCCESS	La funzione ha avuto esito positivo.
STATUS_INVALID_HANDLE	L'handle dell'algoritmo nel parametro hAlgorithm non è valido.
STATUS_INVALID_PARAMETER	Uno o più parametri non sono validi.
STATUS_NOT_SUPPORTED	Il provider specificato non supporta la crittografia della chiave asimmetrica.

Osservazioni

A seconda delle modalità del processore supportate da un provider, BCryptGenerateKeyPair può essere chiamato dalla modalità utente o dalla modalità kernel. I chiamanti in modalità kernel possono essere eseguiti in PASSIVE_LEVELirQL o DISPATCH_LEVEL IRQL. Se il livello IRQL corrente è DISPATCH_LEVEL, l'handle fornito nel parametro hAlgorithm deve essere stato aperto usando il flag BCRYPT_PROV_DISPATCH e qualsiasi puntatore passato alla funzione BCryptGenerateKeyPair deve fare riferimento alla memoria non di pagina (o bloccata).

Il chiamante deve liberare phKey con BCryptDestroyKey al termine dell'uso della chiave.

Se viene passato un handle di algoritmo XMS o LMSS, questa funzione restituirà STATUS_NOT_SUPPORTED perché la generazione di chiavi per algoritmi di firma basati su hash con stato non è consentita da FIPS.

Per chiamare questa funzione in modalità kernel, usare Cng.lib, che fa parte di Driver Development Kit (DDK). Windows Server 2008 e Windows Vista: Per chiamare questa funzione in modalità kernel, usare Ksecdd.lib.

Fabbisogno

Requisito	Valore
Client minimo supportato	Windows Vista [app desktop | App UWP]
Server minimo supportato	Windows Server 2008 [app desktop | App UWP]
Piattaforma di destinazione	Finestre
Intestazione	bcrypt.h
Biblioteca	Bcrypt.lib
DLL	Bcrypt.dll

Vedere anche

BCryptDestroyKey