Funzione CryptSetKeyParam (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 CryptSetKeyParam personalizza vari aspetti delle operazioni di una chiave di sessione. I valori impostati da questa funzione non vengono salvati in modo permanente nella memoria e possono essere usati solo con in una singola sessione.

Il provider di crittografia microsoft base non consente l'impostazione dei valori per lo scambio di chiavi o le chiavi di firma; Tuttavia, i provider personalizzati possono definire valori che possono essere impostati per le relative chiavi.

Sintassi

BOOL CryptSetKeyParam(
  [in] HCRYPTKEY  hKey,
  [in] DWORD      dwParam,
  [in] const BYTE *pbData,
  [in] DWORD      dwFlags
);

Parametri

[in] hKey

Handle per la chiave per cui impostare i valori.

[in] dwParam

Le tabelle seguenti contengono valori predefiniti che è possibile usare.

Per tutti i tipi di chiave, questo parametro può contenere uno dei valori seguenti.

Valore	Significato
KP_ALGID	pbData punta a un ALG_IDappropriato. Questa operazione viene usata quando si scambiano chiavi di sessione con microsoft Base Digital Signature Standard (DSS), Diffie-Hellman provider di crittografia o CSP compatibili. Dopo che una chiave è concordata con la funzione CryptImportKey, la chiave di sessione viene abilitata per l'uso impostandone il tipo di algoritmo.
KP_CERTIFICATE	pbData è l'indirizzo di un buffer contenente il certificato X.509 codificato tramite regole di codifica distinte. La chiave pubblica nel certificato deve corrispondere alla firma o alla chiave di scambio corrispondente.
KP_PERMISSIONS	pbData punta a un valore DWORD che specifica zero o più flag di autorizzazione. Per una descrizione di questi flag, vedere CryptGetKeyParam.
KP_SALT	pbData punta a una matrice BYTE che specifica un nuovo valore salt da creare parte della chiave di sessione. Le dimensioni del valore salt variano a seconda del provider di servizi di configurazione in uso. Prima di impostare questo valore, determinare le dimensioni del valore salt chiamando la funzione CryptGetKeyParam. I valori salt vengono usati per rendere più univoche le chiavi di sessione, che rendono più difficili gli attacchi del dizionario. Il valore salt è zero per impostazione predefinita per Microsoft Base Cryptographic Provider.
KP_SALT_EX	pbData punta a una struttura CRYPT_INTEGER_BLOB che contiene il salt. Per altre informazioni, vedere Specifica di un valore salt.

Se un chiave DSS (Digital Signature Standard) viene specificata dal parametro hKey, il valore dwParam può essere impostato anche su uno dei valori seguenti.

Valore	Significato
KP_G	pbData punta al generatore G dal BLOB della chiave DSS. I dati sono sotto forma di struttura CRYPT_INTEGER_BLOB, in cui il membro pbData è il valore e il membro cbData è la lunghezza del valore. Il valore è previsto senza informazioni sull'intestazione e in modulo di little-endian.
KP_P	pbData punta al P modulo primo di un BLOB di chiave DSS. I dati sono sotto forma di struttura CRYPT_INTEGER_BLOB. Il membro pbData è il valore e il membro cbData è la lunghezza del valore. Il valore è previsto senza informazioni sull'intestazione e in modulo di little-endian.
KP_Q	pbData punta al primo Q di un BLOB di chiavi DSS. I dati sono sotto forma di struttura CRYPT_INTEGER_BLOB in cui il membro pbData è il valore e il membro cbData è la lunghezza del valore. Il valore è previsto senza informazioni sull'intestazione e in modulo di little-endian.
KP_X	Dopo aver impostato i valori P, Q e G, è possibile eseguire una chiamata che specifica il valore KP_X per dwParam e NULL per il parametro pbData può essere eseguito alla funzione CryptSetKeyParam. In questo modo vengono generati i valori X e Y.

Se un algoritmo Diffie-Hellman o chiave DSA (Digital Signature Algorithm) viene specificato da hKey, il valore dwParam può essere impostato su uno dei valori seguenti.

Valore	Significato
KP_CMS_DH_KEY_INFO	Imposta le informazioni per una chiave di Diffie-Hellman importata. Il parametro pbData è l'indirizzo di una struttura CMS_DH_KEY_INFO che contiene le informazioni sulla chiave da impostare.
KP_PUB_PARAMS	Imposta i parametri pubblici (P, Q, G e così via) di una chiave DSS o Diffie-Hellman. L'handle di chiave per questa chiave deve trovarsi nello stato PREGEN, generato con il flag CRYPT_PREGEN. Il parametro pbData deve essere un puntatore a una struttura DATA_BLOB in cui i dati in questa struttura sono un BLOB DHPUBKEY_VER3 o DSSPUBKEY_VER3. La funzione copia i parametri pubblici da questa struttura CRYPT_INTEGER_BLOB all'handle della chiave. Dopo aver effettuato questa chiamata, il valore del parametro KP_X deve essere usato con CryptSetKeyParam per creare la chiave privata effettiva. Il parametro KP_PUB_PARAMS viene usato come una chiamata anziché più chiamate con i valori dei parametri KP_P, KP_Q e KP_G.

Valore

Significato

KP_CMS_DH_KEY_INFO

Imposta le informazioni per una chiave di Diffie-Hellman importata. Il parametro pbData è l'indirizzo di una struttura CMS_DH_KEY_INFO che contiene le informazioni sulla chiave da impostare.

KP_PUB_PARAMS

Imposta i parametri pubblici (P, Q, G e così via) di una chiave DSS o Diffie-Hellman. L'handle di chiave per questa chiave deve trovarsi nello stato PREGEN, generato con il flag CRYPT_PREGEN. Il parametro pbData deve essere un puntatore a una struttura DATA_BLOB in cui i dati in questa struttura sono un BLOB DHPUBKEY_VER3 o DSSPUBKEY_VER3. La funzione copia i parametri pubblici da questa struttura CRYPT_INTEGER_BLOB all'handle della chiave. Dopo aver effettuato questa chiamata, il valore del parametro KP_X deve essere usato con CryptSetKeyParam per creare la chiave privata effettiva. Il parametro KP_PUB_PARAMS viene usato come una chiamata anziché più chiamate con i valori dei parametri KP_P, KP_Q e KP_G.

Se un chiave di crittografia a blocchi di sessione viene specificato dal parametro hKey , il valore dwParam può essere impostato anche su uno dei valori seguenti.

Valore	Significato
KP_EFFECTIVE_KEYLEN	Questo tipo di valore può essere usato solo con chiavi RC2 ed è stato aggiunto a causa dell'implementazione della funzione CryptSetKeyParam nel provider di crittografia avanzato Microsoft prima di Windows 2000. Nell'implementazione precedente, le chiavi RC2 nel provider avanzato erano di 128 bit, ma la lunghezza effettiva della chiave usata per espandere le chiavi nella tabella delle chiavi era solo di 40 bit. In questo modo, la forza dell'algoritmo è stata ridotta a 40 bit. Per mantenere la compatibilità con le versioni precedenti, l'implementazione precedente rimarrà invariata. Tuttavia, la lunghezza effettiva della chiave può essere impostata su maggiore di 40 bit usando KP_EFFECTIVE_KEYLEN nella chiamata CryptSetKeyParam. La lunghezza effettiva della chiave viene passata nel parametro pbData come puntatore a un valore DWORD con il valore effettivo della lunghezza della chiave. La lunghezza minima effettiva della chiave nel provider di crittografia di Base Microsoft è 1 e il massimo è 40. Nel provider di crittografia avanzato Microsoft, il valore minimo è uno e il massimo è 1.024. La lunghezza della chiave deve essere impostata prima di crittografare o decrittografare con la chiave.
KP_HIGHEST_VERSION	Imposta la versione TLS (Transport Layer Security) più elevata consentita. Questa proprietà si applica solo alle chiavi SSL e TLS. Il parametro pbData è l'indirizzo di una variabile DWORD che contiene il numero di versione TLS più alto supportato.
KP_IV	pbData punta a una matrice BYTE che specifica il vettore di inizializzazione. Questa matrice deve contenere elementi BlockLength/8. Ad esempio, se la lunghezza del blocco è di 64 bit, il vettore di inizializzazione è costituito da 8 byte. Il vettore di inizializzazione è impostato su zero per impostazione predefinita per il provider di crittografia di base Microsoft.
KP_KEYVAL	Impostare il valore della chiave per una chiave (DES) Data Encryption Standard. Il parametro pbData è l'indirizzo di un buffer contenente la chiave. Questo buffer deve avere la stessa lunghezza della chiave. Questa proprietà si applica solo alle chiavi DES.
KP_PADDING	Impostare la modalità di riempimento. Il parametro pbData è un puntatore a un valore DWORD che riceve un identificatore numerico che identifica il metodo di riempimento utilizzato daldi crittografia . Può trattarsi di uno dei valori seguenti. PKCS5_PADDING Specifica il metodo di riempimento PKCS 5 (sec 6.2). RANDOM_PADDING La spaziatura interna usa un numero casuale. Questo metodo di riempimento non è supportato dai CSP forniti da Microsoft. ZERO_PADDING La spaziatura interna usa zeri. Questo metodo di riempimento non è supportato dai CSP forniti da Microsoft.
KP_MODE	pbData punta a un valore DWORD che specifica la modalità di crittografia da utilizzare. Per un elenco delle modalità di crittografia definite, vedere CryptGetKeyParam. La modalità di crittografia è impostata su CRYPT_MODE_CBC per impostazione predefinita per il provider di crittografia di base Microsoft.
KP_MODE_BITS	pbData punta a un valore di DWORD che indica il numero di bit elaborati per ciclo quando viene usata la modalità di crittografia di feedback di output (OFB) o modalità di crittografia (TLS). Il numero di bit elaborati per ciclo è impostato su 8 per impostazione predefinita per il provider di crittografia di base Microsoft.

Se viene specificata una chiave RSA nel parametro hKey, il valore del parametro dwParam può essere il valore seguente.

Valore	Significato
KP_OAEP_PARAMS	Impostare i parametri OAEP (Optimal Asymmetric Encryption Padding) (PKCS #1 versione 2) per la chiave. Il parametro pbData è l'indirizzo di una struttura CRYPT_DATA_BLOB che contiene l'etichetta OAEP. Questa proprietà si applica solo alle chiavi RSA.

Si noti che i valori seguenti non vengono usati:

KP_ADMIN_PIN
KP_CMS_KEY_INFO
KP_INFO
KP_KEYEXCHANGE_PIN
KP_PRECOMP_MD5
KP_PRECOMP_SHA
KP_PREHASH
KP_PUB_EX_LEN
KP_PUB_EX_VAL
KP_RA
KP_RB
KP_ROUNDS
KP_RP
KP_SIGNATURE_PIN
KP_Y

[in] pbData

Puntatore a un buffer inizializzato con il valore da impostare prima di chiamare CryptSetKeyParam. Il formato di questi dati varia a seconda del valore di dwParam.

[in] dwFlags

Utilizzato solo quando dwParam è KP_ALGID. Il parametro dwFlags viene usato per passare i valori di flag per la chiave abilitata. Il parametro dwFlags può contenere valori come la dimensione della chiave e gli altri valori di flag consentiti durante la generazione dello stesso tipo di chiave con CryptGenKey. Per informazioni sui valori dei flag consentiti, vedere CryptGenKey.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero (TRUE).

Se la funzione ha esito negativo, il valore restituito è 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. Di seguito sono riportati alcuni possibili codici di errore.

Codice restituito	Descrizione
ERROR_BUSY	Il contesto CSP viene attualmente usato da un altro processo .
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_FLAGS	Il parametro dwFlags è diverso da zero o il buffer pbData contiene un valore non valido.
NTE_BAD_TYPE	Il parametro dwParam specifica un parametro sconosciuto.
NTE_BAD_UID	Impossibile trovare il contesto CSP specificato quando è stata creata la chiave hKey .
NTE_FAIL	La funzione non è riuscita in modo imprevisto.
NTE_FIXEDPARAMETER	Alcuni CSP hanno valori P, Q e G hardcoded. In questo caso, l'uso di KP_P, KP_Q e KP_G per il valore di dwParam causa questo errore.

Osservazioni

Se i parametri KP_Q, KP_P o KP_X vengono impostati su una chiave PREGEN Diffie-Hellman o DSS, le lunghezze della chiave devono essere compatibili con la lunghezza della chiave impostata utilizzando i 16 bit superiori del parametro dwFlags quando la chiave è stata creata usando CryptGenKey. Se non è stata impostata alcuna lunghezza della chiave in CryptGenKey, è stata usata la lunghezza predefinita della chiave. Verrà generato un errore se viene usata una lunghezza della chiave non predefinita per impostare P, Q o X.

Esempi

Per un esempio che usa questa funzione, vedere Programma C di esempio: Duplicare una chiave di sessione. Per altre informazioni sul codice che usa questa funzione, vedere Programma C di esempio: Impostazione e recupero dei parametri della chiave di sessione .

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