Funzione CryptGetKeyParam (wincrypt.h)

Articolo
03/13/2024

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 CryptGetKeyParam recupera i dati che regolano le operazioni di una chiave. Se viene usato il provider di servizi di crittografia Microsoft , il materiale di chiave simmetrica di base non è recuperabile da questa o da qualsiasi altra funzione.

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 eseguita.

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

Valore	Significato
KP_ALGID	Recuperare l'algoritmo 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 AT_KEYEXCHANGE o AT_SIGNATURE viene specificato 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 viene specificata una chiave di sessione 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 crittografia di flusso, questo valore è sempre zero. Se una coppia di chiavi pubblica/privata è 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, il provider di crittografia microsoft base genera coppie chiave RSA a 512 bit, quindi viene restituito un valore pari a 512 per queste chiavi. Se l'algoritmo di chiave pubblica non supporta la crittografia, il valore recuperato non è definito.
KP_CERTIFICATE	pbData è l'indirizzo di un buffer che riceve 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_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. I provider di servizi di crittografia Microsoft restituiscono una lunghezza di chiave di 64 bit per CALG_DES, 128 bit per CALG_3DES_112 e 192 bit per CALG_3DES. Queste lunghezze sono diverse dalle lunghezze restituite quando si enumera gli algoritmi con il valore dwParam della funzione CryptGetProvParam impostato su PP_ENUMALGS. La lunghezza restituita da questa chiamata è la dimensione effettiva della chiave, inclusi i bit di parità inclusi nella chiave. I provider di servizi di configurazione Microsoft che supportano l'CALG_CYLINK_MEK ALG_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 CSP e dell'algoritmo usato. I valori salt non si applicano alle coppie di chiavi pubbliche/private.
KP_PERMISSIONS	Recuperare le autorizzazioni delle chiavi. Il parametro pbData è un puntatore a un valore DWORD che riceve i flag di autorizzazione per la chiave. Gli identificatori di autorizzazione seguenti sono attualmente definiti. Le autorizzazioni chiave possono essere zero o una combinazione di uno o più dei valori seguenti. CRYPT_ARCHIVE Consenti l'esportazione durante la durata dell'handle della chiave. Questa autorizzazione può essere impostata solo se è già impostata nel campo autorizzazioni interne della chiave. I tentativi di cancellare questa autorizzazione vengono ignorati. CRYPT_DECRYPT Consenti decrittografia. CRYPT_ENCRYPT Consenti crittografia. CRYPT_EXPORT Consenti l'esportazione della chiave. CRYPT_EXPORT_KEY Consentire l'uso della chiave per l'esportazione delle chiavi. CRYPT_IMPORT_KEY Consentire l'uso della chiave per l'importazione di chiavi. CRYPT_MAC Consenti l'uso dei codici di autenticazione dei messaggi (MACS) con la chiave. CRYPT_READ Consente di leggere i valori. CRYPT_WRITE Consente di impostare i valori.

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_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 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	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. Le dimensioni di questa matrice sono le dimensioni del blocco, 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 dalla 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 provider di servizi di configurazione forniti da Microsoft. ZERO_PADDING La spaziatura interna utilizza zeri. Questo metodo di riempimento non è supportato dai provider di servizi di configurazione 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. Gli identificatori della modalità di crittografia seguenti sono attualmente definiti. CRYPT_MODE_CBC La modalità di crittografia è il concatenamento a blocchi crittografati. CRYPT_MODE_CFB La modalità di crittografia è il feedback crittografato (TLS). I provider di servizi di configurazione Microsoft supportano attualmente solo commenti e suggerimenti a 8 bit in modalità di feedback crittografato. CRYPT_MODE_ECB La modalità di crittografia è un codebook elettronico. CRYPT_MODE_OFB La modalità di crittografia è Output Feedback (OFB). I provider di servizi di configurazione Microsoft attualmente non supportano la modalità feedback di output. CRYPT_MODE_CTS La modalità di crittografia è la modalità di furto del testo crittografato .
KP_MODE_BITS	Recuperare il numero di bit da inserire. 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 una 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 una chiave dell'algoritmo Diffie-Hellman importata 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. È possibile che in versioni successive sia stata modificata o non sia più disponibile.

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 una chiave dell'algoritmo Diffie-Hellman importata 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. È possibile che in versioni successive sia stata modificata o non sia più disponibile.

Se un certificato viene specificato da hKey, il valore dwParam può essere impostato anche sul valore seguente.

Valore	Significato
KP_CERTIFICATE	Buffer contenente 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. La forma 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, nella voce, 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 Quando si elaborano i dati restituiti nel buffer, le applicazioni devono usare le dimensioni effettive dei dati restituiti. Le dimensioni effettive possono essere leggermente inferiori alle dimensioni del buffer specificato nell'input. Nell'input, le dimensioni del buffer vengono talvolta specificate sufficientemente grandi per garantire che i dati di output più grandi possibili 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 CSP specifico usato. Di seguito sono riportati alcuni possibili codici di errore.

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 che 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 CSP specificato al momento della creazione della chiave.

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

CryptSetKeyParam

Generazione di chiavi e funzioni di Exchange