Funzione CryptGenKey (wincrypt.h)

Articolo
07/16/2024

Importante Questa API è deprecata. Il software nuovo ed esistente deve iniziare a usare API Di nuova generazione di crittografia. Microsoft potrebbe rimuovere questa API nelle versioni future.

La funzione CryptGenKey genera un chiave di sessione di crittografia casuale o una coppia di chiavi pubblica/privata . Un handle per la coppia di chiavi o chiave viene restituito in phKey. Questo handle può quindi essere usato in base alle esigenze con qualsiasi funzione CryptoAPI che richiede un handle di chiave.

L'applicazione chiamante deve specificare l'algoritmo quando si chiama questa funzione. Poiché questo tipo di algoritmo viene mantenuto in bundle con la chiave, l'applicazione non deve specificare l'algoritmo in un secondo momento quando vengono eseguite le operazioni di crittografia effettive.

Sintassi

BOOL CryptGenKey(
  [in]  HCRYPTPROV hProv,
  [in]  ALG_ID     Algid,
  [in]  DWORD      dwFlags,
  [out] HCRYPTKEY  *phKey
);

Parametri

[in] hProv

Handle per un provider di servizi di crittografia (CSP) creato da una chiamata a CryptAcquireContext.

[in] Algid

Valore ALG_ID che identifica l'algoritmo per il quale deve essere generata la chiave. I valori per questo parametro variano a seconda del provider di servizi di configurazione usato.

Per ALG_ID valori da usare con il provider di crittografia di base Microsoft, vedere Base Provider Algorithms.

Per ALG_ID valori da usare con il provider di crittografia avanzata Microsoft o il provider di crittografia avanzata Microsoft, vedere algoritmi del provider avanzato.

Per un provider di servizi di configurazione Diffie-Hellman, usare uno dei valori seguenti.

Valore	Significato
CALG_DH_EPHEM	Specifica una chiave Diffie-Hellman "Effimero".
CALG_DH_SF	Specifica una chiave di Diffie-Hellman "Archivia e inoltra".

Oltre a generare chiavi di sessione per algoritmi simmetrici, questa funzione può anche generare coppie di chiavi pubbliche/private. Ogni client CryptoAPI ha in genere due coppie di chiavi pubbliche/private. Per generare una di queste coppie di chiavi, impostare il parametro Algid su uno dei valori seguenti.

Valore	Significato
AT_KEYEXCHANGE	Scambio di chiavi
AT_SIGNATURE	Firma digitale

Nota Quando vengono specificate specifiche di chiave AT_KEYEXCHANGE e AT_SIGNATURE, gli identificatori dell'algoritmo usati per generare la chiave dipendono dal provider usato. Di conseguenza, per queste specifiche chiave, i valori restituiti da CryptGetKeyParam (quando viene specificato il parametro KP_ALGID) dipendono dal provider usato. Per determinare quale identificatore di algoritmo viene usato dai diversi provider per le specifiche chiave AT_KEYEXCHANGE e AT_SIGNATURE, vedere ALG_ID.

[in] dwFlags

Specifica il tipo di chiave generata. Le dimensioni di una chiave di sessione, della chiave di firma RSA e della chiave RSA chiavi di scambio possono essere impostate quando viene generata la chiave. La dimensione della chiave, che rappresenta la lunghezza del modulo di chiave in bit, viene impostata con i 16 bit superiori di questo parametro. Pertanto, se deve essere generata una chiave di firma RSA a 2.048 bit, il valore 0x08000000 viene combinato con qualsiasi altro dwFlags valore predefinito con un'operazione diOR bit per bit. I 16 bit superiori di 0x08000000 sono 0x0800 o decimali 2.048. Il valore RSA1024BIT_KEY può essere usato per specificare una chiave RSA a 1024 bit.

A causa della modifica delle restrizioni del controllo di esportazione, il provider di servizi di configurazione predefinito e la lunghezza predefinita della chiave possono cambiare tra le versioni del sistema operativo. È importante che sia la crittografia che la decrittografia usino lo stesso provider di servizi di configurazione e che la lunghezza della chiave venga impostata in modo esplicito usando il parametro dwFlags per garantire l'interoperabilità su piattaforme del sistema operativo diverse.

In particolare, il provider di servizi di crittografia completo RSA predefinito è il provider di crittografia avanzata Microsoft RSA. La firma DSS predefinita Diffie-Hellman provider di servizi di crittografia è microsoft Enhanced DSS Diffie-Hellman Cryptographic Provider. Ognuno di questi CSP ha una lunghezza di chiave simmetrica a 128 bit predefinita per RC2 e RC4 e una lunghezza di chiave predefinita a 1.024 bit per gli algoritmi di chiave pubblica.

Se i 16 bit superiori sono pari a zero, vengono generate le dimensioni predefinite della chiave. Se viene specificata una chiave maggiore del valore massimo o minore del valore minimo, la chiamata ha esito negativo con il codice ERROR_INVALID_PARAMETER.

Nella tabella seguente sono elencate le lunghezze minime, predefinite e massime della firma e della chiave di scambio a partire da Windows XP.

Tipo di chiave e provider	Lunghezza minima	Lunghezza predefinita	Lunghezza massima
RSA Base Provider Firma ed ExchangeKeys	384	512	16,384
Provider avanzati e avanzati RSA Firma e chiavi di scambio	384	1,024	16,384
Provider di base DSS Chiavi di firma	512	1,024	1,024
Provider di base DSS Chiavi di Scambio	Non applicabile	Non applicabile	Non applicabile
Provider di base DSS/DH Chiavi di firma	512	1,024	1,024
Provider di base DSS/DH Chiavi di Scambio	512	512	1,024
Provider avanzati DSS/DH Chiavi di firma	512	1,024	1,024
Provider avanzati DSS/DH Chiavi di Scambio	512	1,024	4,096

Per le lunghezze delle chiavi di sessione, vedere CryptDeriveKey.

Per altre informazioni sulle chiavi generate tramite provider Microsoft, vedere Provider di servizi di crittografia Microsoft.

I 16 bit inferiori di questo parametro possono essere zero o una combinazione di uno o più dei valori seguenti.

Valore	Significato
CRYPT_ARCHIVABLE	Se questo flag è impostato, la chiave può essere esportata fino a quando il relativo handle non viene chiuso da una chiamata a CryptDestroyKey. Ciò consente di esportare le chiavi appena generate al momento della creazione per l'archiviazione o il ripristino delle chiavi. Dopo la chiusura dell'handle, la chiave non è più esportabile.
CRYPT_CREATE_IV	Questo flag non viene utilizzato.
CRYPT_CREATE_SALT	Se questo flag è impostato, alla chiave viene assegnato automaticamente un valore salt casuale. È possibile recuperare questo valore salt usando la funzione CryptGetKeyParam con il parametro dwParam impostato su KP_SALT. Se questo flag non è impostato, alla chiave viene assegnato un valore salt pari a zero. Quando le chiavi con valori salt diversi da zero vengono esportate (tramite CryptExportKey), è necessario ottenere e conservare anche il valore salt con il BLOB della chiave.
CRYPT_DATA_KEY	Questo flag non viene utilizzato.
CRYPT_EXPORTABLE	Se questo flag è impostato, la chiave può essere trasferita dal provider di servizi di configurazione in un BLOB di chiavi usando la funzione CryptExportKey. Poiché le chiavi di sessione in genere devono essere esportabili, questo flag deve in genere essere impostato al momento della creazione. Se questo flag non è impostato, la chiave non è esportabile. Per una chiave di sessione, significa che la chiave è disponibile solo all'interno della sessione corrente e solo l'applicazione che l'ha creata sarà in grado di usarla. Per una coppia di chiavi pubblica/privata , significa che la chiave privata non può essere trasportata o sottoposta a backup. Questo flag si applica solo alla chiave di sessione e BLOB a chiave privata. Non si applica alle chiavi pubbliche, che sono sempre esportabili.
CRYPT_FORCE_KEY_PROTECTION_HIGH	Questo flag specifica la protezione con chiave avanzata. Quando questo flag è impostato, all'utente viene richiesto di immettere una password per la chiave al momento della creazione della chiave. All'utente verrà richiesto di immettere la password ogni volta che viene usata questa chiave. Questo flag viene usato solo dai provider di servizi di configurazione forniti da Microsoft. I provider di servizi di configurazione di terze parti definiranno il proprio comportamento per la protezione avanzata delle chiavi. Se si specifica questo flag, il risultato della chiamata a questa funzione con il flag CRYPT_USER_PROTECTED quando viene specificata la protezione con chiave avanzata nel Registro di sistema. Se questo flag viene specificato e l'handle del provider nel parametro hProv è stato creato usando il flag CRYPT_VERIFYCONTEXT o CRYPT_SILENT, questa funzione imposta l'ultimo errore su NTE_SILENT_CONTEXT e restituirà zero. Windows Server 2003 e Windows XP: Questo flag non è supportato.
CRYPT_KEK	Questo flag non viene utilizzato.
CRYPT_INITIATOR	Questo flag non viene utilizzato.
CRYPT_NO_SALT	Questo flag specifica che non viene allocato alcun valore salt per una chiave simmetrica a quaranta bit. Per altre informazioni, vedere funzionalità valore salt.
CRYPT_ONLINE	Questo flag non viene utilizzato.
CRYPT_PREGEN	Questo flag specifica un Diffie-Hellman iniziale o una generazione di chiavi DSS. Questo flag è utile solo con provider di servizi di configurazione di Diffie-Hellman e DSS. Se utilizzata, verrà usata una lunghezza di chiave predefinita, a meno che non venga specificata una lunghezza della chiave nei 16 bit superiori del parametro dwFlags. Se i parametri che prevedono lunghezze di chiave vengono impostati su una chiave PREGEN Diffie-Hellman o DSS usando CryptSetKeyParam, le lunghezze della chiave devono essere compatibili con la lunghezza della chiave impostata qui.
CRYPT_RECIPIENT	Questo flag non viene utilizzato.
CRYPT_SF	Questo flag non viene utilizzato.
CRYPT_SGCKEY	Questo flag non viene utilizzato.
CRYPT_USER_PROTECTED	Se questo flag è impostato, l'utente riceve una notifica tramite una finestra di dialogo o un altro metodo quando determinate azioni tentano di usare questa chiave. Il comportamento preciso viene specificato dal provider di servizi di configurazione usato. Se il contesto del provider è stato aperto con il flag CRYPT_SILENT impostato, l'uso di questo flag causa un errore e l'ultimo errore è impostato su NTE_SILENT_CONTEXT.
CRYPT_VOLATILE	Questo flag non viene utilizzato.

[out] phKey

Indirizzo in cui la funzione copia l'handle della chiave appena generata. Al termine dell'uso della chiave, eliminare l'handle alla chiave chiamando la funzione CryptDestroyKey .

Valore restituito

Restituisce un valore diverso da zero se ha esito positivo o zero in caso contrario.

Per informazioni sugli errori estesi, chiamare GetLastError.

I codici di errore preceduti da "NTE" vengono generati dal provider di servizi di configurazione specifico usato. Nella tabella seguente sono elencati alcuni possibili codici di errore.

Codice restituito	Descrizione
ERROR_INVALID_HANDLE	Uno dei parametri specifica un handle non valido.
ERROR_INVALID_PARAMETER	Uno dei parametri contiene un valore non valido. Si tratta più spesso di un puntatore non valido.
NTE_BAD_ALGID	Il parametro Algid specifica un algoritmo non supportato da questo provider di servizi di configurazione.
NTE_BAD_FLAGS	Il parametro dwFlags contiene un valore non valido.
NTE_BAD_UID	Il parametro hProv non contiene un handle di contesto valido.
NTE_FAIL	La funzione non è riuscita in modo imprevisto.
NTE_SILENT_CONTEXT	Il provider non è riuscito a eseguire l'azione perché il contesto è stato acquisito come invisibile all'utente.

Osservazioni

Se le chiavi vengono generate per crittografia a blocchi simmetrica , la chiave, per impostazione predefinita, viene configurata in modalità di concatenamento a blocchi di crittografia (CBC) con un vettore di inizializzazione pari a zero. Questa modalità di crittografia fornisce un metodo predefinito valido per la crittografia bulk dei dati. Per modificare questi parametri, usare la funzione CryptSetKeyParam.

Per scegliere una lunghezza della chiave appropriata, sono consigliati i metodi seguenti:

Enumerare gli algoritmi supportati dal provider di servizi di configurazione e ottenere la lunghezza massima e minima della chiave per ogni algoritmo. A tale scopo, chiamare CryptGetProvParam con PP_ENUMALGS_EX.
Usare le lunghezze minime e massime per scegliere una lunghezza della chiave appropriata. Non è sempre consigliabile scegliere la lunghezza massima perché ciò può causare problemi di prestazioni.
Dopo aver scelto la lunghezza della chiave desiderata, usare i 16 bit superiori del parametro dwFlags per specificare la lunghezza della chiave.

Esempi

Nell'esempio seguente viene illustrata la creazione di una chiave di sessione casuale. Per un esempio che include il contesto completo per questo esempio, vedere Programma C di esempio: Crittografia di un file. Per un altro esempio che usa questa funzione, vedere Programma C di esempio: Decrittografia di un file.

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

Fabbisogno

Requisito	Valore
client minimo supportato	Windows XP [solo app desktop]
server minimo supportato	Windows Server 2003 [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	wincrypt.h
libreria	Advapi32.lib
dll	Advapi32.dll