Condividi tramite


Funzione CryptGetProvParam (wincrypt.h)

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 CryptGetProvParam recupera i parametri che regolano le operazioni di un provider di servizi di crittografia (CSP).

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
PP_ADMIN_PIN
31 (0x1F)
Restituisce il numero di identificazione personale dell'amministratore nel parametro pbData come LPSTR.
PP_APPLI_CERT
18 (0x12)
Questa costante non viene usata.
PP_CHANGE_PASSWORD
7 (0x7)
Questa costante non viene usata.
PP_CERTCHAIN
9 (0x9)
Restituisce la catena di certificati associata all'handle hProv . La catena di certificati restituita è X509_ASN_ENCODING codificata.
PP_CONTAINER
6 (0x6)
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.
PP_CRYPT_COUNT_KEY_USE
41 (0x29)
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.

PP_ENUMALGS
1 (0x1)
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.

PP_ENUMALGS_EX
22 (0x16)
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.

PP_ENUMCONTAINERS
2 (0x2)
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.

PP_ENUMELECTROOTS
26 (0x1A)
Questa costante non viene usata.
PP_ENUMEX_SIGNING_PROT
40 (0x28)
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 .
PP_ENUMMANDROOTS
25 (0x19)
Questa costante non viene usata.
PP_IMPTYPE
3 (0x3)
Valore DWORD che indica come viene implementato il CSP. Per una tabella dei valori possibili, vedere Osservazioni.
PP_KEY_TYPE_SUBTYPE
10 (0xA)
Questa query non viene usata.
PP_KEYEXCHANGE_PIN
32 (0x20)
Specifica che il PIN di scambio delle chiavi è contenuto in pbData. Il PIN viene rappresentato come stringa ASCII con terminazione Null.
PP_KEYSET_SEC_DESCR
8 (0x8)
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.
PP_KEYSET_TYPE
27 (0x1B)
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 .
PP_KEYSPEC
39 (0x27)
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.
PP_KEYSTORAGE
17 (0x11)
Restituisce un valore DWORD di CRYPT_SEC_DESCR.
PP_KEYX_KEYSIZE_INC
35 (0x23)
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.
PP_NAME
4 (0x4)
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.
PP_PROVTYPE
16 (0x10)
Valore DWORD che indica il tipo di provider del CSP.
PP_ROOT_CERTSTORE
46 (0x2E)
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.

PP_SESSION_KEYSIZE
20 (0x14)
Dimensioni, in bit, della chiave di sessione.
PP_SGC_INFO
37 (0x25)
Usato con crittografia con gated del server.
PP_SIG_KEYSIZE_INC
34 (0x22)
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.

PP_SIGNATURE_PIN
33 (0x21)
Specifica che il PIN della firma della chiave è contenuto in pbData. Il PIN viene rappresentato come stringa ASCII con terminazione Null.
PP_SMARTCARD_GUID
45 (0x2D)
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.

PP_SMARTCARD_READER
43 (0x2B)
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.

PP_SYM_KEYSIZE
19 (0x13)
Dimensioni della chiave simmetrica.
PP_UI_PROMPT
21 (0x15)
Questa query non viene usata.
PP_UNIQUE_CONTAINER
36 (0x24)
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.
PP_USE_HARDWARE_RNG
38 (0x26)
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.

PP_USER_CERTSTORE
42 (0x2A)
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.

PP_VERSION
5 (0x5)
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.

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 rispetto alle dimensioni del buffer specificato nell'input. In base all'input, le dimensioni del buffer vengono in genere specificate abbastanza grandi per garantire che i dati di output più grandi siano adatti al buffer. Nell'output la variabile a cui punta questo parametro viene aggiornata per riflettere le dimensioni effettive dei dati copiati 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.

Valore Significato
OWNER_SECURITY_INFORMATION
Viene fatto riferimento all'identificatore proprietario dell'oggetto.
GROUP_SECURITY_INFORMATION
Viene fatto riferimento all'identificatore di gruppo primario dell'oggetto.
DACL_SECURITY_INFORMATION
Viene fatto riferimento all'ACL discrezionale dell'oggetto.
SACL_SECURITY_INFORMATION
Viene fatto riferimento all'ACL di sistema dell'oggetto.
 

I valori seguenti vengono definiti per l'uso con PP_ENUMALGS, PP_ENUMALGS_EX e PP_ENUMCONTAINERS.

Valore Significato
CRYPT_FIRST
1 (0x1)
Recuperare il primo elemento nell'enumerazione . Ciò ha lo stesso effetto della reimpostazione dell'enumeratore.
CRYPT_NEXT
2 (0x2)
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.
CRYPT_SGC_ENUM
4 (0x4)
Recuperare i certificati abilitati per la crittografia server-gated (SGC). I certificati abilitati per SGC non sono più supportati.
CRYPT_SGC
Questo flag non viene usato.
CRYPT_FASTSGC
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
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.
ERROR_NO_MORE_ITEMS
È 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.
NTE_BAD_FLAGS
Il parametro dwFlags specifica un flag non valido.
NTE_BAD_TYPE
Il parametro dwParam specifica un numero di valore sconosciuto.
NTE_BAD_UID
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

Vedi anche

Descrittori di sicurezza assoluti e Self-Relative

Cryptacquirecontext

CryptCreateHash

CryptDeriveKey

CryptGenKey

CryptGetKeyParam

CryptSetProvParam

Funzioni del provider di servizi