Funzione CryptDeriveKey (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 di CryptDeriveKey genera chiavi di sessione crittografiche derivate da un valore di dati di base. Questa funzione garantisce che quando vengono usati gli stessi provider di servizi di crittografia (CSP) e algoritmi, le chiavi generate dagli stessi dati di base sono identiche. I dati di base possono essere una password o qualsiasi altro dato utente.

Questa funzione è uguale a CryptGenKey, ad eccezione del fatto che le chiavi di sessione generate derivano da dati di base anziché essere casuali. CryptDeriveKey può essere usato solo per generare chiavi di sessione. Non può generare coppie di chiavi pubbliche/private.

Un handle per la chiave di sessione viene restituito nel parametro phKey . Questo handle può essere usato con qualsiasi funzione CryptoAPI che richiede un handle di chiave.

Sintassi

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

Parametri

[in] hProv

Handle di HCRYPTPROV di un provider di servizi di configurazione creato da una chiamata a CryptAcquireContext.

[in] Algid

Struttura ALG_ID che identifica l'algoritmo di crittografia simmetrica per cui deve essere generata la chiave. Gli algoritmi disponibili saranno probabilmente diversi per ogni provider di servizi di configurazione. Per altre informazioni sull'identificatore dell'algoritmo usato dai diversi provider per le specifiche chiave AT_KEYEXCHANGE e AT_SIGNATURE, vedere ALG_ID.

Per altre informazioni sui valori di ALG_ID da usare con il provider di crittografia di base Microsoft, vedere algoritmi del provider di base. Per altre informazioni sui valori di ALG_ID da usare con il provider di crittografia avanzata Microsoft o il provider di crittografia avanzata Microsoft, vedere Enhanced Provider Algorithms.

[in] hBaseData

Handle per un oggetto hash che è stato fornito ai dati di base esatti.

Per ottenere questo handle, un'applicazione deve prima creare un oggetto hash con CryptCreateHash e quindi aggiungere i dati di base all'oggetto hash con CryptHashData. Questo processo è descritto in dettaglio in hash e firme digitali.

[in] dwFlags

Specifica il tipo di chiave generata.

Le dimensioni di una chiave di sessione 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 sessione a 128 bit RC4, il valore 0x00800000 viene combinato con qualsiasi altro dwFlags valore predefinito con un'operazione diOR bit per 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.

I 16 bit inferiori di questo parametro possono essere zero oppure è possibile specificare uno o più dei flag seguenti usando l'operatore ORor bit per bit per combinarli.

Valore	Significato
CRYPT_CREATE_SALT	In genere, quando viene creata una chiave di sessione da un valore hash, sono presenti diversi bit rimanenti. Ad esempio, se il valore hash è a 128 bit e la chiave di sessione è a 40 bit, verranno lasciati 88 bit. Se questo flag è impostato, alla chiave viene assegnato un valore salt in base ai bit del valore hash inutilizzato. È 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 (usando CryptExportKey), è necessario ottenere e conservare anche il valore salt con la chiave BLOB.
CRYPT_EXPORTABLE	Se questo flag è impostato, la chiave di sessione può essere trasferita dal provider di servizi di configurazione in un BLOB di chiavi tramite la funzione CryptExportKey . Poiché le chiavi in genere devono essere esportabili, questo flag deve essere in genere impostato. Se questo flag non è impostato, la chiave della sessione non è esportabile. Ciò significa che la chiave è disponibile solo all'interno della sessione corrente e solo l'applicazione che l'ha creata è in grado di usarla. Questo flag non si applica a coppie di chiavi pubbliche/private.
CRYPT_NO_SALT	Questo flag specifica che non viene allocato alcun valore salt per una chiave simmetrica a 40 bit. Per altre informazioni, vedere funzionalità valore salt.
CRYPT_UPDATE_KEY	Alcuni CSP usano chiavi di sessione derivate da più valori hash. In questo caso, CryptDeriveKey deve essere chiamato più volte. Se questo flag è impostato, non viene generata una nuova chiave di sessione. Viene invece modificata la chiave specificata da phKey. Il comportamento preciso di questo flag dipende dal tipo di chiave da generare e dal particolare CSP in uso. I provider di servizi di crittografia Microsoft ignorano questo flag.
CRYPT_SERVER 1024 (0x400)	Questo flag viene usato solo con provider di Schannel . Se questo flag è impostato, la chiave da generare è una chiave di scrittura server; in caso contrario, si tratta di una chiave di scrittura client.

[in, out] phKey

Puntatore a una variabile HCRYPTKEY per ricevere l'indirizzo dell'handle della chiave appena generata. Al termine dell'uso della chiave, rilasciare l'handle chiamando la funzione CryptDestroyKey .

Valore restituito

Se la funzione ha esito positivo, la funzione restituisce un valore diverso da zero (TRUE).

Se la funzione ha esito negativo, restituisce zero (FALSE). 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_HASH	Il parametro hBaseData non contiene un handle valido per un oggetto hash .
NTE_BAD_HASH_STATE	È stato effettuato un tentativo di aggiungere dati a un oggetto hash già contrassegnato come "completato".
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

Quando vengono generate chiavi 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.

La funzione CryptDeriveKey completa l'hash. Dopo aver chiamato CryptDeriveKey, non è possibile aggiungere altri dati all'hash. Chiamate aggiuntive a CryptHashData o CryptHashSessionKey esito negativo. Al termine dell'applicazione con l'hash, è necessario chiamare CryptDestroyHash per eliminare definitivamente l'oggetto hash.

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

Per enumerare gli algoritmi supportati dal provider di servizi di configurazione e per ottenere la lunghezza massima e minima della chiave per ogni algoritmo, 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.

Lasciare n essere la lunghezza della chiave derivata richiesta, in byte. La chiave derivata è la prima n byte del valore hash dopo che il calcolo hash è stato completato da CryptDeriveKey. Se l'hash non è un membro della famiglia SHA-2 e la chiave richiesta è per 3DES o AES, la chiave viene derivata come segue:

Formare un buffer a 64 byte ripetendo la costante 0x36 64 volte. Lasciare k essere la lunghezza del valore hash rappresentato dal parametro di input hBaseData. Impostare il primo k byte del buffer sul risultato di un'operazione di XOR del primo k byte del buffer con il valore hash rappresentato dal parametro di input hBaseData.
Formare un buffer a 64 byte ripetendo la costante 0x5C 64 volte. Impostare il primo k byte del buffer sul risultato di un'operazione di XOR del primo k byte del buffer con il valore hash rappresentato dal parametro di input hBaseData.
Eseguire l'hash del risultato del passaggio 1 usando lo stesso algoritmo hash usato per calcolare il valore hash rappresentato dal parametro hBaseData.
Eseguire l'hash del risultato del passaggio 2 usando lo stesso algoritmo hash usato per calcolare il valore hash rappresentato dal parametro hBaseData.
Concatenare il risultato del passaggio 3 con il risultato del passaggio 4.
Usare il primo n byte del risultato del passaggio 5 come chiave derivata.

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.

Nella tabella seguente sono elencate le lunghezze minime, predefinite e massime della chiave per la chiave di sessione in base all'algoritmo e al provider.

Provider	Algoritmi	Lunghezza minima chiave	Lunghezza della chiave predefinita	Lunghezza massima della chiave
MS Base	RC4 e RC2	40	40	56
MS Base	DES	56	56	56
MS Enhanced	RC4 e RC2	40	128	128
MS Enhanced	DES	56	56	56
MS Enhanced	3DES 112	112	112	112
MS Enhanced	3DES	168	168	168
MS Strong	RC4 e RC2	40	128	128
MS Strong	DES	56	56	56
MS Strong	3DES 112	112	112	112
MS Strong	3DES	168	168	168
DSS/DH Base	RC4 e RC2	40	40	56
DSS/DH Base	Cylink MEK	40	40	40
DSS/DH Base	DES	56	56	56
DSS/DH Enh	RC4 e RC2	40	128	128
DSS/DH Enh	Cylink MEK	40	40	40
DSS/DH Enh	DES	56	56	56
DSS/DH Enh	3DES 112	112	112	112
DSS/DH Enh	3DES	168	168	168

Esempi

Per un esempio che usa questa funzione, vedere Programma C di esempio: Derivazione di una chiave di sessione da una password.

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