Funzione CryptGenKey (wincrypt.h)

Articolo
03/03/2024

Importante Questa API è deprecata. Il software nuovo e esistente deve iniziare a usare le API di nuova generazione di crittografia. Microsoft può rimuovere questa API nelle versioni future.

La funzione CryptGenKey genera una chiave di sessione crittografica casuale o una coppia di chiavi pubblica/privata. Un handle per la coppia chiave o chiave viene restituito in phKey. Questo handle può quindi essere usato in base alle esigenze con qualsiasi funzione CryptoAPI che richiede un handle 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 più avanti l'algoritmo 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 a un provider di servizi di crittografia 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 CSP usato.

Per ALG_ID valori da usare con il provider di crittografia di base Microsoft, vedere Algoritmi provider di base.

Per ALG_ID valori da usare con il provider di crittografia avanzata Microsoft o il provider di crittografia avanzata Microsoft, vedere Algoritmi provider avanzati.

Per un Diffie-Hellman CSP, usare uno dei valori seguenti.

Valore	Significato
CALG_DH_EPHEM	Specifica una chiave "Ephemeral" Diffie-Hellman.
CALG_DH_SF	Specifica una chiave di Diffie-Hellman "Store and Forward".

Oltre a generare chiavi di sessione per algoritmi simmetrici, questa funzione può anche generare coppie di chiavi pubbliche/private. Ogni client CryptoAPI in genere possiede 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 chiave
AT_SIGNATURE	Firma digitale

Nota Quando vengono specificate specifiche 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 l'identificatore dell'algoritmo 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, la chiave di firma RSA e le chiavi di scambio delle chiavi RSA possono essere impostate quando viene generata la chiave. Le dimensioni della chiave, che rappresentano la lunghezza del modulo di chiave in bit, vengono impostate con i 16 bit superiori di questo parametro. Pertanto, se viene generata una chiave di firma RSA a 2.048 bit, il valore 0x08000000 viene combinato con qualsiasi altro valore predefinito dwFlags con un'operazione BIT-OR . 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 di controllo di esportazione, il CSP predefinito e la lunghezza della chiave predefinita possono cambiare tra le versioni del sistema operativo. È importante che sia la crittografia che la decrittografia usino lo stesso CSP 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 RSA Microsoft. La firma DSS predefinita Diffie-Hellman provider di servizi crittografici è il provider di servizi DSS avanzato microsoft Diffie-Hellman provider di crittografia. Ognuno di questi provider di servizi di configurazione 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 zero, viene generata la dimensione della chiave predefinita. Se viene specificata una chiave maggiore del valore massimo o inferiore al minimo, la chiamata ha esito negativo con il codice ERROR_INVALID_PARAMETER.

La tabella seguente elenca 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 e ExchangeKeys	384	512	16.384
Provider sicuri e avanzati RSA Firme 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 Exchange	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 Exchange	512	512	1\.024
Provider avanzati DSS/DH Chiavi di firma	512	1\.024	1\.024
Provider avanzati DSS/DH Chiavi di Exchange	512	1\.024	4\.096

Per le lunghezze delle chiavi di sessione, vedere CryptDeriveKey.

Per altre informazioni sulle chiavi generate con 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 finché 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 usato.
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), il valore salt deve essere ottenuto e mantenuto anche con il BLOB della chiave.
CRYPT_DATA_KEY	Questo flag non viene usato.
CRYPT_EXPORTABLE	Se questo flag è impostato, la chiave può essere trasferita fuori 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, ciò 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, ciò significa che la chiave privata non può essere trasportata o sottoposta a backup. Questo flag si applica solo ai BLOB della chiave sessione e alla chiave privata. Non si applica alle chiavi pubbliche, che sono sempre esportabili.
CRYPT_FORCE_KEY_PROTECTION_HIGH	Questo flag specifica la protezione avanzata della chiave. Quando questo flag viene 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, viene generato lo stesso 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 imposterà 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 usato.
CRYPT_INITIATOR	Questo flag non viene usato.
CRYPT_NO_SALT	Questo flag specifica che un valore salt non viene allocato per una chiave simmetrica a quaranta bit. Per altre informazioni, vedere Salt Value Functionality.
CRYPT_ONLINE	Questo flag non viene usato.
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 coinvolgono 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 usato.
CRYPT_SF	Questo flag non viene usato.
CRYPT_SGCKEY	Questo flag non viene usato.
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 CSP in uso. 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 viene impostato su NTE_SILENT_CONTEXT.
CRYPT_VOLATILE	Questo flag non viene usato.

[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 CSP specifico usato. Nella tabella seguente sono elencati alcuni codici di errore possibili.

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 che 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.

Commenti

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

Per scegliere una lunghezza di 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 di 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.

Esempio

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 Esempio di programma C: crittografia di un file. Per un altro esempio che usa questa funzione, vedere Esempio di programma C: 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);
}

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	wincrypt.h
Libreria	Advapi32.lib
DLL	Advapi32.dll