recupera i dati che regolano le operazioni di una chiave. Se viene usato il provider di servizi di crittografia Microsoft, il materiale della chiave simmetrica di base non è recuperabile da questa o da altre funzioni.
Sintassi
BOOL CryptGetKeyParam(
[in] HCRYPTKEY hKey,
[in] DWORD dwParam,
[out] BYTE *pbData,
[in, out] DWORD *pdwDataLen,
[in] DWORD dwFlags
);
Parametri
[in] hKey
Handle della chiave sottoposta a query.
[in] dwParam
Specifica il tipo di query in corso di esecuzione.
Per tutti i tipi di chiave, questo parametro può contenere uno dei valori seguenti.
| Valore |
Significato |
-
KP_ALGID
|
Recuperare l'algoritmo di chiave. Il parametro pbData è un puntatore a un valore ALG_ID che riceve l'identificatore dell'algoritmo specificato al momento della creazione della chiave.
Quando si specifica AT_KEYEXCHANGE o AT_SIGNATURE per il parametro Algid della funzione CryptGenKey , gli identificatori dell'algoritmo usati per generare la chiave dipendono dal provider usato. Per altre informazioni, vedere ALG_ID.
|
-
KP_BLOCKLEN
|
Se una chiave di sessione viene specificata dal parametro hKey, recuperare la lunghezza del blocco della crittografia della chiave. Il parametro pbData è un puntatore a un valore DWORD che riceve la lunghezza del blocco, in bit. Per le crittografie di flusso , questo valore è sempre zero.
Se una coppia di chiavi pubblica/privata viene specificata da hKey, recuperare la granularità della crittografia della coppia di chiavi. Il parametro pbData è un puntatore a un valore DWORD che riceve la granularità della crittografia, in bit. Ad esempio, l'provider di crittografia microsoft base genera coppie di chiavi RSA a 512 bit, quindi viene restituito un valore pari a 512 per queste chiavi. Se l'algoritmo di chiave pubblica non supporta crittografia, il valore recuperato non è definito.
|
-
KP_CERTIFICATE
|
pbData è l'indirizzo di un buffer che riceve il certificato X.509 codificato tramite regole di codifica distinte (DER). La chiave pubblica nel certificato deve corrispondere alla firma o alla chiave di scambio corrispondente.
|
-
KP_GET_USE_COUNT
|
Questo valore non viene utilizzato.
|
-
KP_KEYLEN
|
Recuperare la lunghezza effettiva della chiave. Il parametro pbData è un puntatore a un valore DWORD che riceve la lunghezza della chiave, in bit.
KP_KEYLEN può essere usato per ottenere la lunghezza di qualsiasi tipo di chiave. Microsoft provider di servizi di crittografia (CSP) restituiscono una lunghezza di chiave di 64 bit per CALG_DES, 128 bit per CALG_3DES_112e 192 bit per CALG_3DES. Queste lunghezze sono diverse dalle lunghezze restituite durante l'enumerazione degli algoritmi con il valore dwParam del funzione CryptGetProvParam impostata su PP_ENUMALGS. La lunghezza restituita da questa chiamata è la dimensione effettiva della chiave, inclusi i bit di parità inclusi nella chiave.
I CSP Microsoft che supportano il CALG_CYLINK_MEKALG_ID restituiscono 64 bit per tale algoritmo.
CALG_CYLINK_MEK è una chiave a 40 bit, ma ha parità e bit di chiave zero per rendere la lunghezza della chiave 64 bit.
|
-
KP_SALT
|
Recuperare il valore salt della chiave. Il parametro pbData è un puntatore a una matrice BYTE che riceve il valore salt in forma little-endian. Le dimensioni del valore salt variano a seconda del provider di servizi di configurazione e dell'algoritmo usato. I valori salt non si applicano alle coppie di chiavi pubbliche/private .
|
-
KP_PERMISSIONS
|
Recuperare le autorizzazioni della chiave. Il parametro pbData è un puntatore a un valore DWORD che riceve i flag di autorizzazione per la chiave.
Sono attualmente definiti gli identificatori di autorizzazione seguenti. Le autorizzazioni della chiave possono essere pari a zero o a una combinazione di uno o più dei valori seguenti.
-
CRYPT_ARCHIVE
-
Consente l'esportazione durante la durata dell'handle della chiave. Questa autorizzazione può essere impostata solo se è già impostata nel campo delle autorizzazioni interne della chiave. I tentativi di cancellare questa autorizzazione vengono ignorati.
-
CRYPT_DECRYPT
-
Consenti decrittografia.
-
CRYPT_ENCRYPT
-
Consenti crittografia.
-
CRYPT_EXPORT
-
Consentire l'esportazione della chiave.
-
CRYPT_EXPORT_KEY
-
Consente di usare la chiave per l'esportazione delle chiavi.
-
CRYPT_IMPORT_KEY
-
Consente di usare la chiave per l'importazione delle chiavi.
-
CRYPT_MAC
-
Consentire codici di autenticazione dei messaggi (MACS) da usare con la chiave.
-
CRYPT_READ
-
Consente di leggere i valori.
-
CRYPT_WRITE
-
Consenti l'impostazione dei valori.
|
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_P
|
Recuperare il numero primo modulo P della chiave DSS. Il parametro pbData è un puntatore a un buffer che riceve il valore in formato little-endian. Il parametro pdwDataLen contiene le dimensioni del buffer, in byte.
|
-
KP_Q
|
Recuperare il numero primo modulo Q della chiave DSS. Il parametro pbData è un puntatore a un buffer che riceve il valore in formato little-endian. Il parametro pdwDataLen contiene le dimensioni del buffer, in byte.
|
-
KP_G
|
Recuperare il generatore G della chiave DSS. Il parametro pbData è un puntatore a un buffer che riceve il valore in formato little-endian. Il parametro pdwDataLen contiene le dimensioni del buffer, in byte.
|
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
|
Recuperare la lunghezza effettiva della chiave di una chiave RC2. Il parametro pbData è un puntatore a un valore DWORD che riceve la lunghezza effettiva della chiave.
|
-
KP_IV
|
Recuperare il vettore di inizializzazione della chiave. Il parametro pbData è un puntatore a una matrice BYTE che riceve il vettore di inizializzazione. La dimensione di questa matrice è la dimensione del blocco, espressa in byte. Ad esempio, se la lunghezza del blocco è di 64 bit, il vettore di inizializzazione è costituito da 8 byte.
|
-
KP_PADDING
|
Recuperare 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 numeri casuali. 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
|
Recuperare la modalità di crittografia . Il parametro pbData è un puntatore a un valore DWORD che riceve un identificatore della modalità di crittografia. Per altre informazioni sulle modalità di crittografia, vedere crittografia dei dati e decrittografia.
Sono attualmente definiti gli identificatori della modalità di crittografia seguenti.
-
CRYPT_MODE_CBC
-
La modalità di crittografia è concatenamento a blocchi crittografati.
-
CRYPT_MODE_CFB
-
La modalità di crittografia è feedback crittografato (TLS). I CSP Microsoft supportano attualmente solo commenti e suggerimenti a 8 bit in modalità feedback crittografato.
-
CRYPT_MODE_ECB
-
La modalità di crittografia è codice elettronico.
-
CRYPT_MODE_OFB
-
La modalità di crittografia è output feedback (OFB). I CSP Microsoft attualmente non supportano la modalità di feedback di output.
-
CRYPT_MODE_CTS
-
La modalità di crittografia è testo crittografato modalità di furto.
|
-
KP_MODE_BITS
|
Recuperare il numero di bit di cui eseguire il feedback. Il parametro pbData è un puntatore a un valore DWORD che riceve il numero di bit elaborati per ciclo quando vengono utilizzate le modalità di crittografia OFB o TLS.
|
Se un algoritmo Diffie-Hellman o chiave DSA (Digital Signature Algorithm) viene specificata da hKey, il valore dwParam può essere impostato anche sul valore seguente.
| Valore |
Significato |
-
KP_VERIFY_PARAMS
|
Verifica i parametri di un algoritmo Diffie-Hellman o di una chiave DSA. Il parametro pbData non viene usato e il valore a cui punta pdwDataLen riceve zero.
Questa funzione restituisce un valore diverso da zero se i parametri chiave sono validi o zero in caso contrario.
|
-
KP_KEYVAL
|
Questo valore non viene utilizzato.
Windows Vista, Windows Server 2003 e Windows XP: Recuperare il valore del contratto segreto da un algoritmo Diffie-Hellman importato chiave di tipo CALG_AGREEDKEY_ANY. Il parametro pbData è l'indirizzo di un buffer che riceve il valore del contratto segreto, in formato little-endian. Questo buffer deve avere la stessa lunghezza della chiave. Il parametro dwFlags deve essere impostato su 0xF42A19B6. Questa proprietà può essere recuperata solo da un thread in esecuzione nell'account di sistema locale. Questa proprietà è disponibile per l'uso nei sistemi operativi elencati in precedenza. Potrebbe essere modificato o non disponibile nelle versioni successive.
|
Se un certificato viene specificato da hKey, il valore dwParam può essere impostato anche sul valore seguente.
| Valore |
Significato |
-
KP_CERTIFICATE
|
Buffer che contiene il certificato X.509 con codifica DER. Il parametro pbData non viene usato e il valore a cui punta pdwDataLen riceve zero.
Questa funzione restituisce un valore diverso da zero se i parametri chiave sono validi o zero in caso contrario.
|
[out] pbData
Puntatore a un buffer che riceve i dati. Il formato di questi dati dipende dal valore di dwParam.
Se le dimensioni di questo buffer non sono note, è possibile recuperare le dimensioni necessarie in fase di esecuzione passando NULL per questo parametro e impostando il valore a cui punta pdwDataLen su zero. Questa funzione inserisce le dimensioni necessarie del buffer, in byte, nel valore a cui punta pdwDataLen. Per altre informazioni, vedere Recupero di dati di lunghezza sconosciuta.
[in, out] pdwDataLen
Puntatore a un valore DWORD che, in ingresso, contiene le dimensioni, in byte, del buffer a cui punta il parametro pbData. Quando la funzione viene restituita, il valore DWORD contiene il numero di byte archiviati nel buffer.
Nota Durante l'elaborazione dei dati restituiti nel buffer, le applicazioni devono usare le dimensioni effettive dei dati restituiti. Le dimensioni effettive possono essere leggermente inferiori rispetto alle dimensioni del buffer specificato nell'input. In caso di input, le dimensioni del buffer vengono talvolta specificate abbastanza grandi per garantire che i dati di output più grandi si adattino al buffer. Nell'output, la variabile a cui punta questo parametro viene aggiornata in modo da riflettere le dimensioni effettive dei dati copiati nel buffer.
[in] dwFlags
Questo parametro è riservato per uso futuro e deve essere impostato su zero.
Valore restituito
Se la funzione ha esito positivo, la funzione restituisce un valore diverso da zero.
Se la funzione ha esito negativo, restituisce zero. Per informazioni sugli errori estesi, chiamare GetLastError.
I codici di errore preceduti da "NTE" vengono generati dal provider di servizi di configurazione specifico usato. Alcuni possibili codici di errore includono quanto segue.
| 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.
|
-
ERROR_MORE_DATA
|
Se il buffer specificato dal parametro pbData non è sufficientemente grande da contenere i dati restituiti, la funzione imposta il codice ERROR_MORE_DATA e archivia le dimensioni del buffer necessarie, in byte, nella variabile a cui punta pdwDataLen.
|
-
NTE_BAD_FLAGS
|
Il parametro dwFlags è diverso da zero.
|
-
NTE_BAD_KEY o NTE_NO_KEY
|
La chiave specificata dal parametro hKey non è valida.
|
-
NTE_BAD_TYPE
|
Il parametro dwParam specifica un numero di valore sconosciuto.
|
-
NTE_BAD_UID
|
Impossibile trovare il contesto di CSP specificato al momento della creazione della chiave.
|
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 |
Vedere anche
CryptSetKeyParam
generazione di chiavi e funzioni di Exchange