Funzione CryptDeriveKey (wincrypt.h)

Articolo
03/03/2024

Importante Questa API è deprecata. Il software nuovo ed esistente deve iniziare a usare le API cryptography next generation. Microsoft potrebbe rimuovere questa API nelle versioni future.

La funzione CryptDeriveKey genera chiavi di sessione crittografiche derivate da un valore di dati di base. Questa funzione garantisce che quando vengono usati lo stesso provider di servizi di crittografia (CSP) e gli stessi 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 sono derivate dai 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 HCRYPTPROV di un CSP 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 di 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 Algoritmi del provider avanzato.

[in] hBaseData

Handle per un oggetto hash che è stato inserito nei 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 RC4 a 128 bit, il valore 0x00800000 viene combinato con qualsiasi altro valore predefinito dwFlags con un'operazione OR bit per bit. A causa della modifica delle restrizioni del controllo di esportazione, il CSP predefinito e la lunghezza della chiave predefinita possono cambiare tra le versioni del sistema operativo. È importante che la crittografia e 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.

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

Valore	Significato
CRYPT_CREATE_SALT	In genere, quando una chiave di sessione viene eseguita da un valore hash , esistono diversi bit rimasti. 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), il valore salt deve essere ottenuto e mantenuto anche con il BLOB della chiave.
CRYPT_EXPORTABLE	Se questo flag è impostato, la chiave di sessione può essere trasferita dal CSP 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 ha creato è in grado di usarla. Questo flag non si applica alle 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 Salt Value Functionality.
CRYPT_UPDATE_KEY	Alcuni provider di servizi di configurazione 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 generata e dal CSP specifico in uso. I provider di servizi di crittografia Microsoft ignorano questo flag.
CRYPT_SERVER 1024 (0x400)	Questo flag viene usato solo con i provider 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 non riesce, restituisce zero (FALSE). 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_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.

Commenti

Quando le chiavi vengono generate per crittografie a blocchi simmetrici, per impostazione predefinita la chiave 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 .

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

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

Lasciare che n sia la lunghezza della chiave derivata richiesta, espressa in byte. La chiave derivata è il primo n byte del valore hash dopo il completamento del calcolo hash 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. Consentire k di essere la lunghezza del valore hash rappresentato dal parametro di input hBaseData. Impostare i primi k byte del buffer sul risultato di un'operazione XOR dei primi 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 i primi k byte del buffer sul risultato di un'operazione XOR dei primi k byte del buffer con il valore hash rappresentato dal parametro di input hBaseData.
Eseguire l'hashing del risultato del passaggio 1 usando lo stesso algoritmo hash usato per calcolare il valore hash rappresentato dal parametro hBaseData .
Eseguire l'hashing 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 i primi 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 è il provider di servizi di crittografia Diffie-Hellman avanzato microsoft. Ognuno di questi provider di servizi di configurazione 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 per algoritmo e provider.

Provider	Algoritmi	Lunghezza minima chiave	Lunghezza 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

Esempio

Per un esempio che usa questa funzione, vedere Esempio di programma C: derivazione di una chiave di sessione da una password.

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