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

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.

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

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.

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

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

Vedere anche

CryptAcquireContext

CryptDestroyKey

CryptExportKey

CryptGetKeyParam

CryptImportKey

CryptSetKeyParam

generazione di chiavi e funzioni di Exchange

problemi di threading con i provider di servizi di crittografia