Funzione CryptGenKey (wincrypt.h)
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 |
---|---|
|
Specifica una chiave "Ephemeral" Diffie-Hellman. |
|
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 |
---|---|
|
Scambio di chiave |
|
Firma digitale |
[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 |
---|---|
|
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. |
|
Questo flag non viene usato. |
|
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. |
|
Questo flag non viene usato. |
|
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. |
|
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. |
|
Questo flag non viene usato. |
|
Questo flag non viene usato. |
|
Questo flag specifica che un valore salt non viene allocato per una chiave simmetrica a quaranta bit. Per altre informazioni, vedere Salt Value Functionality. |
|
Questo flag non viene usato. |
|
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. |
|
Questo flag non viene usato. |
|
Questo flag non viene usato. |
|
Questo flag non viene usato. |
|
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. |
|
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 |
---|---|
|
Uno dei parametri specifica un handle non valido. |
|
Uno dei parametri contiene un valore non valido. Si tratta più spesso di un puntatore che non è valido. |
|
Il parametro Algid specifica un algoritmo non supportato da questo provider di servizi di configurazione. |
|
Il parametro dwFlags contiene un valore non valido. |
|
Il parametro hProv non contiene un handle di contesto valido. |
|
La funzione non è riuscita in modo imprevisto. |
|
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 |
Vedi anche
Generazione di chiavi e funzioni di Exchange
Problemi di threading con i provider di servizi di crittografia
Commenti e suggerimenti
https://aka.ms/ContentUserFeedback.
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedereInvia e visualizza il feedback per