Funzione CryptDeriveKey (wincrypt.h)
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 |
---|---|
|
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. |
|
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. |
|
Questo flag specifica che non viene allocato alcun valore salt per una chiave simmetrica a 40 bit. Per altre informazioni, vedere Salt Value Functionality. |
|
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. |
|
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 |
---|---|
|
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 hBaseData non contiene un handle valido per un oggetto hash. |
|
È stato effettuato un tentativo di aggiungere dati a un oggetto hash già contrassegnato come "completato". |
|
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
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.
- 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.
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 |
Vedi anche
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