Funzione CryptGetProvParam (wincrypt.h)
Sintassi
BOOL CryptGetProvParam(
[in] HCRYPTPROV hProv,
[in] DWORD dwParam,
[out] BYTE *pbData,
[in, out] DWORD *pdwDataLen,
[in] DWORD dwFlags
);
Parametri
[in] hProv
Handle della destinazione CSP della query. Questo handle deve essere stato creato usando la funzione CryptAcquireContext .
[in] dwParam
Natura della query. Le query seguenti sono definite.
| Valore | Significato |
|---|---|
|
Restituisce il numero di identificazione personale dell'amministratore nel parametro pbData come LPSTR. |
|
Questa costante non viene usata. |
|
Questa costante non viene usata. |
|
Restituisce la catena di certificati associata all'handle hProv . La catena di certificati restituita è X509_ASN_ENCODING codificata. |
|
Nome del contenitore della chiave corrente come stringa CHAR con terminazione Null. Questa stringa corrisponde esattamente a quella passata nel parametro pszContainer della funzione CryptAcquireContext per specificare il contenitore chiave da usare. Il parametro pszContainer può essere letto per determinare il nome del contenitore di chiavi predefinito. |
|
Non implementato dai provider di servizi di configurazione Microsoft. Questo comportamento può essere implementato da altri provider di servizi di configurazione.
Windows XP: Questo parametro non è supportato. |
|
Struttura PROV_ENUMALGS contenente informazioni su un algoritmo supportato dal CSP sottoposto a query.
La prima volta che questo valore viene letto, il parametro dwFlags deve contenere il flag di CRYPT_FIRST . In questo modo questa funzione consente di recuperare il primo elemento nell'enumerazione. Gli elementi successivi possono quindi essere recuperati impostando il flag di CRYPT_NEXT nel parametro dwFlags . Quando questa funzione ha esito negativo con il codice di errore ERROR_NO_MORE_ITEMS , è stata raggiunta la fine dell'enumerazione. Questa funzione non è thread safe e tutti gli algoritmi disponibili potrebbero non essere enumerati se questa funzione viene usata in un contesto multithreaded. |
|
Struttura PROV_ENUMALGS_EX che contiene informazioni su un algoritmo supportato dalla query CSP. La struttura restituita contiene altre informazioni sull'algoritmo rispetto alla struttura restituita per PP_ENUMALGS.
La prima volta che questo valore viene letto, il parametro dwFlags deve contenere il flag di CRYPT_FIRST . In questo modo questa funzione consente di recuperare il primo elemento nell'enumerazione. Gli elementi successivi possono quindi essere recuperati impostando il flag di CRYPT_NEXT nel parametro dwFlags . Quando questa funzione ha esito negativo con il codice di errore ERROR_NO_MORE_ITEMS , è stata raggiunta la fine dell'enumerazione. Questa funzione non è thread safe e tutti gli algoritmi disponibili potrebbero non essere enumerati se questa funzione viene usata in un contesto multithreaded. |
|
Nome di uno dei contenitori chiave gestiti dal CSP sotto forma di stringa CHAR con terminazione null.
La prima volta che questo valore viene letto, il parametro dwFlags deve contenere il flag di CRYPT_FIRST . In questo modo questa funzione consente di recuperare il primo elemento nell'enumerazione. Gli elementi successivi possono quindi essere recuperati impostando il flag di CRYPT_NEXT nel parametro dwFlags . Quando questa funzione ha esito negativo con il codice di errore ERROR_NO_MORE_ITEMS , è stata raggiunta la fine dell'enumerazione. Per enumerare i contenitori di chiavi associati a un computer, chiamare prima CryptAcquireContext usando il flag CRYPT_MACHINE_KEYSET e quindi usare l'handle restituito da CryptAcquireContext come parametro hProv nella chiamata a CryptGetProvParam. Questa funzione non è thread safe e tutti gli algoritmi disponibili potrebbero non essere enumerati se questa funzione viene usata in un contesto multithreaded. |
|
Questa costante non viene usata. |
|
Indica che il CSP corrente supporta il membro dwProtocols della struttura PROV_ENUMALGS_EX . Se questa funzione ha esito positivo, il CSP supporta il membro dwProtocols della struttura PROV_ENUMALGS_EX . Se questa funzione ha esito negativo con un codice di errore NTE_BAD_TYPE , il CSP non supporta il membro dwProtocols . |
|
Questa costante non viene usata. |
|
Valore DWORD che indica come viene implementato il CSP. Per una tabella dei valori possibili, vedere Osservazioni. |
|
Questa query non viene usata. |
|
Specifica che il PIN di scambio delle chiavi è contenuto in pbData. Il PIN viene rappresentato come stringa ASCII con terminazione Null. |
|
Recupera il descrittore di sicurezza per il contenitore di archiviazione delle chiavi. Il parametro pbData è l'indirizzo di una struttura SECURITY_DESCRIPTOR che riceve il descrittore di sicurezza per il contenitore di archiviazione delle chiavi. Il descrittore di sicurezza viene restituito in formato auto-relativo. |
|
Determina se il parametro hProv è un set di chiavi computer. Il parametro pbData deve essere un DWORD; la DWORD verrà impostata sul flag CRYPT_MACHINE_KEYSET se tale flag è stato passato alla funzione CryptAcquireContext . |
|
Restituisce informazioni sui valori dell'identificatore di chiave supportati dal CSP. I valori dell'identificatore di chiave vengono aggiunti a un OR logico e restituiti nel parametro pbData della chiamata come DWORD. Ad esempio, il provider di crittografia microsoft base versione 1.0 restituisce un valore DWORD di AT_SIGNATURE | AT_KEYEXCHANGE. |
|
Restituisce un valore DWORD di CRYPT_SEC_DESCR. |
|
Numero di bit per la lunghezza di incremento di AT_KEYEXCHANGE. Queste informazioni vengono usate con informazioni restituite nel valore di PP_ENUMALGS_EX. Con le informazioni restituite quando si usano PP_ENUMALGS_EX e PP_KEYX_KEYSIZE_INC, è possibile determinare le lunghezze di chiave valide per AT_KEYEXCHANGE. Queste lunghezze di chiave possono quindi essere usate con CryptGenKey. Ad esempio, se un CSP enumera CALG_RSA_KEYX (AT_KEYEXCHANGE ) con una lunghezza minima di 512 bit e un massimo di 1024 bit e restituisce la lunghezza di incremento come 64 bit, le lunghezze di chiave valide sono 512, 576, 640,... 1024. |
|
Nome del CSP sotto forma di stringa CHAR con terminazione null. Questa stringa è identica a quella passata nel parametro pszProvider della funzione CryptAcquireContext per specificare che viene usato il CSP corrente. |
|
Valore DWORD che indica il tipo di provider del CSP. |
|
Ottiene l'archivio certificati radice per la smart card. Questo archivio certificati contiene tutti i certificati radice archiviati nella smart card.
Il parametro pbData è l'indirizzo di una variabile HCERTSTORE che riceve l'handle dell'archivio certificati. Quando questo handle non è più necessario, il chiamante deve chiuderlo usando la funzione CertCloseStore . Windows Server 2003 e Windows XP: Questo parametro non è supportato. |
|
Dimensioni, in bit, della chiave di sessione. |
|
Usato con crittografia con gated del server. |
|
Numero di bit per la lunghezza di incremento di AT_SIGNATURE. Queste informazioni vengono usate con informazioni restituite nel valore di PP_ENUMALGS_EX. Con le informazioni restituite quando si usano PP_ENUMALGS_EX e PP_SIG_KEYSIZE_INC, è possibile determinare le lunghezze di chiave valide per AT_SIGNATURE. Queste lunghezze di chiave possono quindi essere usate con CryptGenKey.
Ad esempio, se un CSP enumera CALG_RSA_SIGN (AT_SIGNATURE ) con una lunghezza minima di 512 bit e un massimo di 1024 bit e restituisce la lunghezza di incremento come 64 bit, le lunghezze di chiave valide sono 512, 576, 640,... 1024. |
|
Specifica che il PIN della firma della chiave è contenuto in pbData. Il PIN viene rappresentato come stringa ASCII con terminazione Null. |
|
Ottiene l'identificatore della smart card. Il parametro pbData è l'indirizzo di una struttura GUID che riceve l'identificatore della smart card.
Windows Server 2003 e Windows XP: Questo parametro non è supportato. |
|
Ottiene il nome del lettore smart card. Il parametro pbData è l'indirizzo di una matrice di caratteri ANSI che riceve una stringa ANSI con terminazione null contenente il nome del lettore smart card. Le dimensioni di questo buffer, contenute nella variabile a cui fa riferimento il parametro pdwDataLen , devono includere il terminatore NULL .
Windows Server 2003 e Windows XP: Questo parametro non è supportato. |
|
Dimensioni della chiave simmetrica. |
|
Questa query non viene usata. |
|
Nome del contenitore univoco del contenitore di chiavi corrente sotto forma di stringa CHAR con terminazione null. Per molti provider di servizi di rete, questo nome è lo stesso nome restituito quando viene usato il valore PP_CONTAINER. La funzione CryptAcquireContext deve funzionare con questo nome del contenitore. |
|
Indica se è supportato un generatore di numeri casuali hardware (RNG). Quando viene specificato PP_USE_HARDWARE_RNG , la funzione ha esito positivo e restituisce TRUE se è supportato un RNG hardware. La funzione ha esito negativo e restituisce FALSE se un RNG hardware non è supportato. Se è supportato un RNG, PP_USE_HARDWARE_RNG può essere impostato in CryptSetProvParam per indicare che il CSP deve usare esclusivamente il RNG hardware per questo contesto del provider. Quando viene usato PP_USE_HARDWARE_RNG , il parametro pbData deve essere NULL e dwFlags deve essere zero.
Nessuno dei provider di servizi di rete Microsoft attualmente supporta l'uso di un RNG hardware. |
|
Ottiene l'archivio certificati utente per la smart card. Questo archivio certificati contiene tutti i certificati utente archiviati nella smart card. I certificati in questo archivio vengono codificati usando PKCS_7_ASN_ENCODING o X509_ASN_ENCODING codifica e devono contenere la proprietà CERT_KEY_PROV_INFO_PROP_ID .
Il parametro pbData è l'indirizzo di una variabile HCERTSTORE che riceve l'handle di un archivio certificati in memoria. Quando questo handle non è più necessario, il chiamante deve chiuderlo usando la funzione CertCloseStore . Windows Server 2003 e Windows XP: Questo parametro non è supportato. |
|
Numero di versione del CSP. Il byte meno significativo contiene il numero di versione secondario e il successivo byte più significativo del numero di versione principale. La versione 2.0 è rappresentata come 0x00000200. Per mantenere la compatibilità con le versioni precedenti del provider di crittografia microsoft e del provider di crittografia avanzata Microsoft, i nomi dei provider mantengono la designazione "v1.0" nelle versioni successive. |
[out] pbData
Puntatore a un buffer per ricevere i dati. La forma di questi dati varia a seconda del valore di dwParam. Quando dwParam è impostato su PP_USE_HARDWARE_RNG, pbData deve essere impostato su NULL.
Questo parametro può essere NULL per impostare le dimensioni di queste informazioni per scopi di allocazione della memoria. Per altre informazioni, vedere Recupero dei dati di lunghezza sconosciuta.
[in, out] pdwDataLen
Puntatore a un valore DWORD che specifica le dimensioni, in byte, del buffer a cui punta il parametro pbData . Quando la funzione restituisce, il valore DWORD contiene il numero di byte archiviati o da archiviare nel buffer.
Se PP_ENUMALGS o PP_ENUMALGS_EX è impostato, il parametro pdwDataLen funziona in modo diverso. Se pbData è NULL o il valore puntato da pdwDataLen è troppo piccolo, il valore restituito in questo parametro è la dimensione dell'elemento più grande nell'elenco di enumerazione anziché la dimensione dell'elemento attualmente in lettura.
Se PP_ENUMCONTAINERS è impostato, la prima chiamata alla funzione restituisce le dimensioni del contenitore chiave massimo consentito dal provider corrente. Questo comportamento è diverso da altri possibili comportamenti, ad esempio la restituzione della lunghezza del contenitore esistente più lungo o la lunghezza del contenitore corrente. Le chiamate di enumerazione successive non modificheranno il parametro dwLen . Per ogni contenitore enumerato, il chiamante può determinare la lunghezza della stringa con terminazione Null a livello di codice, se necessario. Se uno dei valori di enumerazione viene letto e il parametro pbData è NULL, è necessario specificare il flag CRYPT_FIRST affinché le informazioni sulle dimensioni vengano recuperate correttamente.
[in] dwFlags
Se dwParam è PP_KEYSET_SEC_DESCR, il descrittore di sicurezza nel contenitore di chiavi in cui vengono archiviate le chiavi viene recuperato. In questo caso, dwFlags viene usato per passare i flag di bit SECURITY_INFORMATION che indicano le informazioni di sicurezza richieste, come definito in Platform SDK. SECURITY_INFORMATION flag di bit possono essere combinati con un'operazione OR bit per bit.
I valori seguenti vengono definiti per l'uso con PP_KEYSET_SEC_DESCR.
I valori seguenti vengono definiti per l'uso con PP_ENUMALGS, PP_ENUMALGS_EX e PP_ENUMCONTAINERS.
| Valore | Significato |
|---|---|
|
Recuperare il primo elemento nell'enumerazione . Ciò ha lo stesso effetto della reimpostazione dell'enumeratore. |
|
Recuperare l'elemento successivo nell'enumerazione . Quando non sono presenti altri elementi da recuperare, questa funzione avrà esito negativo e imposterà l'ultimo errore su ERROR_NO_MORE_ITEMS. |
|
Recuperare i certificati abilitati per la crittografia server-gated (SGC). I certificati abilitati per SGC non sono più supportati. |
|
Questo flag non viene usato. |
|
Questo flag non viene usato. |
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 dall'NTE vengono generati dal CSP specifico usato. Di seguito sono riportati alcuni possibili codici di errore.
| Codice restituito | Descrizione |
|---|---|
|
Uno dei parametri specifica un handle non valido. |
|
Uno dei parametri contiene un valore non valido. Si tratta più spesso di un puntatore che non è valido. |
|
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. |
|
È stata raggiunta la fine dell'elenco di enumerazione. Nessun dato valido è stato inserito nel buffer pbData . Questo codice di errore viene restituito solo quando dwParam è uguale a PP_ENUMALGS o PP_ENUMCONTAINERS. |
|
Il parametro dwFlags specifica un flag non valido. |
|
Il parametro dwParam specifica un numero di valore sconosciuto. |
|
Il contesto CSP specificato da hProv non è valido. |
Commenti
Questa funzione non deve essere usata in un thread di un programma multithreading.
I valori seguenti vengono restituiti in pbData se dwParam è PP_IMPTYPE.
| Valore | Significato |
|---|---|
| CRYPT_IMPL_HARDWARE 0x01 |
L'implementazione è in hardware. |
| CRYPT_IMPL_SOFTWARE 0x02 |
L'implementazione è nel software. |
| CRYPT_IMPL_MIXED 0x03 |
L'implementazione prevede sia hardware che software. |
| CRYPT_IMPL_UNKNOWN 0x04 |
Il tipo di implementazione è sconosciuto. |
| CRYPT_IMPL_REMOVABLE 0x08 |
L'implementazione è in supporti rimovibili. |
Il parametro dwFlags viene usato per passare i flag di bit SECURITY_INFORMATION che indicano le informazioni di sicurezza richieste. Il puntatore al descrittore di sicurezza viene restituito nel parametro pbData e la lunghezza del descrittore di sicurezza viene restituita nel parametro pdwDataLen . La sicurezza key-container viene gestita con SetFileSecurity e GetFileSecurity.
È possibile determinare la classe di un algoritmo enumerato con dwParam impostato su PP_ENUMALGS o PP_ENUMALGS_EX. Questa operazione può essere eseguita per visualizzare un elenco di algoritmi di crittografia supportati e ignorare il resto. La macro GET_ALG_CLASS(x) accetta un identificatore di algoritmo come argomento e restituisce un codice che indica la classe generale di tale algoritmo. I valori restituiti possibili includono:
- ALG_CLASS_DATA_ENCRYPT
- ALG_CLASS_HASH
- ALG_CLASS_KEY_EXCHANGE
- ALG_CLASS_SIGNATURE
Nella tabella seguente sono elencati gli algoritmi supportati dal provider di crittografia di base Microsoft insieme alla classe di ogni algoritmo.
| Nome | Identificatore | Classe |
|---|---|---|
| "MD2" | CALG_MD2 | ALG_CLASS_HASH |
| "MD5" | CALG_MD5 | ALG_CLASS_HASH |
| "SHA" | CALG_SHA | ALG_CLASS_HASH |
| "MAC" | CALG_MAC | ALG_CLASS_HASH |
| "RSA_SIGN" | CALG_RSA_SIGN | ALG_CLASS_SIGNATURE |
| "RSA_KEYX" | CALG_RSA_KEYX | ALG_CLASS_KEY_EXCHANGE |
| "RC2" | CALG_RC2 | ALG_CLASS_DATA_ENCRYPT |
| "RC4" | CALG_RC4 | ALG_CLASS_DATA_ENCRYPT |
Le applicazioni non devono usare un algoritmo con un identificatore di algoritmo non riconosciuto. L'uso di un algoritmo di crittografia sconosciuto può produrre risultati imprevedibili.
Esempio
Nell'esempio seguente viene illustrato come trovare il nome del CSP associato a un handle del provider di servizi di crittografia e il nome del contenitore di chiavi associato all'handle. Per il contesto completo per questo esempio, vedere Esempio di programma C: Uso di CryptAcquireContext.
Per un altro esempio che usa questa funzione, vedere Esempio di programma C: enumerazione di provider CSP e tipi di provider.
//-----------------------------------------------------------------
// Declare and initialize variables.
HCRYPTPROV hCryptProv;
BYTE pbData[1000]; // 1000 will hold the longest
// key container name.
DWORD cbData;
//-------------------------------------------------------------------
// An HCRYPTPROV must be acquired before using code like that in
// "Example C Program Using CryptAcquireContext."
//-------------------------------------------------------------------
// Read the name of the default CSP.
cbData = 1000;
if(CryptGetProvParam(
hCryptProv,
PP_NAME,
pbData,
&cbData,
0))
{
printf("CryptGetProvParam succeeded.\n");
printf("Provider name: %s\n", pbData);
}
else
{
printf("Error reading CSP name. \n");
exit(1);
}
//--------------------------------------------------------------------
// Read the name of the default key container.
cbData = 1000;
if(CryptGetProvParam(
hCryptProv,
PP_CONTAINER,
pbData,
&cbData,
0))
{
printf("CryptGetProvParam succeeded. \n");
printf("Key Container name: %s\n", pbData);
}
else
{
printf("Error reading key container name. \n");
exit(1);
}
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 |