Condividi tramite


Funzione CryptGetKeyParam (wincrypt.h)

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 CryptGetKeyParam 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