Funzione CryptSetKeyParam (wincrypt.h)

Articolo
08/27/2023

Importante Questa API è deprecata. Il software nuovo e esistente deve iniziare a usare le API di nuova generazione di crittografia. Microsoft può 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 mantenuti in memoria e possono essere usati solo 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 chiavi.

Sintassi

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

Parametri

[in] hKey

Handle alla chiave per cui devono essere impostati i valori.

[in] dwParam

Le tabelle seguenti contengono valori predefiniti che possono essere usati.

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

Valore	Significato
KP_ALGID	pbData punta a un ALG_ID appropriato. Questa operazione viene usata quando si scambiano chiavi di sessione con Microsoft Base Digital Signature Standard (DSS), Diffie-Hellman Provider di crittografia o provider compatibile. Dopo aver concordato una chiave con la funzione CryptImportKey , la chiave di sessione è abilitata per l'uso impostando il tipo di algoritmo.
KP_CERTIFICATE	pbData è l'indirizzo di un buffer che contiene il certificato X.509 codificato tramite Distinguished Encoding Rules (DER). 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 rendere parte della chiave di sessione. Le dimensioni del valore salt variano a seconda dell'uso del CSP. 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 rende 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 contenente il sale. Per altre informazioni, vedere Specifica di un valore salt.

Se viene specificata una chiave DSS (Digital Signature Standard ) 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 una struttura CRYPT_INTEGER_BLOB , in cui il membro pbData è il valore e il membro cbData è la lunghezza del valore. Il valore è previsto senza informazioni di intestazione e in formato little-endian .
KP_P	pbData punta al P primo modulo di un BLOB di chiave DSS. I dati sono sotto forma di una struttura CRYPT_INTEGER_BLOB . Il membro pbData è il valore e il membro cbData è la lunghezza del valore. Il valore è previsto senza informazioni di intestazione e in formato little-endian .
KP_Q	pbData punta al primo Q di un BLOB di chiave DSS. I dati sono sotto forma di una struttura CRYPT_INTEGER_BLOB in cui il membro pbData è il valore e il membro cbData è la lunghezza del valore. Il valore è previsto senza informazioni di intestazione e in formato 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 alla funzione CryptSetKeyParam . Ciò causa la generazione dei valori X e Y.

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

Valore	Significato
KP_CMS_DH_KEY_INFO	Imposta le informazioni per una chiave Diffie-Hellman importata. Il parametro pbData è l'indirizzo di una struttura CMS_DH_KEY_INFO che contiene le informazioni chiave da impostare.
KP_PUB_PARAMS	Imposta i parametri pubblici (P, Q, G e così via) di una chiave DSS o di Diffie-Hellman. L'handle della chiave per questa chiave deve trovarsi nello stato PREGEN, generato con il flag di CRYPT_PREGEN. Il parametro pbData deve essere un puntatore a una struttura DATA_BLOB in cui i dati di 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 eseguito 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 Diffie-Hellman importata. Il parametro pbData è l'indirizzo di una struttura CMS_DH_KEY_INFO che contiene le informazioni chiave da impostare.

KP_PUB_PARAMS

Imposta i parametri pubblici (P, Q, G e così via) di una chiave DSS o di Diffie-Hellman. L'handle della chiave per questa chiave deve trovarsi nello stato PREGEN, generato con il flag di CRYPT_PREGEN. Il parametro pbData deve essere un puntatore a una struttura DATA_BLOB in cui i dati di 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 eseguito 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 viene specificata una chiave di sessione di crittografia a blocchi 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 avanzata Microsoft prima di Windows 2000. Nell'implementazione precedente, le chiavi RC2 nel provider avanzato erano 128 bit in forza, ma la lunghezza della chiave effettiva usata per espandere le chiavi nella tabella delle chiavi era solo 40 bit. Ciò riduce la forza dell'algoritmo a 40 bit. Per mantenere la compatibilità con le versioni precedenti, l'implementazione precedente rimarrà così come è. Tuttavia, la lunghezza effettiva della chiave può essere impostata su maggiore di 40 bit usando KP_EFFECTIVE_KEYLEN nella chiamata CryptSetKeyParam . La lunghezza della chiave effettiva viene passata al parametro pbData come puntatore a un valore DWORD con il valore di lunghezza della chiave effettiva. La lunghezza minima effettiva della chiave nel provider di crittografia di base Microsoft è una e il massimo è 40. Nel provider di crittografia avanzata 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 DATA Encryption Standard (DES). Il parametro pbData è l'indirizzo di un buffer che contiene la chiave. Questo buffer deve essere 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 usato dalla crittografia. Questo può essere 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 provider di servizi di configurazione forniti da Microsoft. ZERO_PADDING La spaziatura interna usa zero. Questo metodo di riempimento non è supportato dai provider di servizi di configurazione forniti da Microsoft.
KP_MODE	pbData punta a un valore DWORD che specifica la modalità di crittografia da usare. 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 DWORD che indica il numero di bit elaborati per ciclo quando viene usata la modalità di crittografia FEEDBACK di output (OFB) o Feedback 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 contenente 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. La forma di questi dati varia a seconda del valore di dwParam.

[in] dwFlags

Usato solo quando dwParam è KP_ALGID. Il parametro dwFlags viene usato per passare i valori del flag per la chiave abilitata. Il parametro dwFlags può contenere valori come le dimensioni della chiave e gli altri valori di flag consentiti durante la generazione dello stesso tipo di chiave con CryptGenKey. Per informazioni sui valori di 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 sull'errore estese, chiamare GetLastError.

I codici di errore preceduti da "NTE" vengono generati dal particolare CSP usato. Alcuni codici di errore possibili seguono.

Codice restituito	Descrizione
ERROR_BUSY	Il contesto CSP è 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. Questo è più spesso un puntatore che 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 provider di servizi di configurazione dispongono di valori P, Q e G hardcoded. Se si tratta del caso, l'uso di KP_P, KP_Q e KP_G per il valore dwParam causa questo errore.

Commenti

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

Esempio

Per un esempio che usa questa funzione, vedere Esempio di programma C: duplicare una chiave di sessione. Per altri codici che usano questa funzione, vedere Esempio di programma C: impostazione e recupero dei parametri chiave sessione .

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