Funzione CertGetCTLContextProperty (wincrypt.h)

Articolo
08/27/2023

La funzione CertGetCTLContextProperty recupera una proprietà estesa di un contesto CTL ( Certificate Trust List ).

Sintassi

BOOL CertGetCTLContextProperty(
  [in]      PCCTL_CONTEXT pCtlContext,
  [in]      DWORD         dwPropId,
  [out]     void          *pvData,
  [in, out] DWORD         *pcbData
);

Parametri

[in] pCtlContext

Puntatore alla struttura CTL_CONTEXT .

[in] dwPropId

Identifica la proprietà da recuperare. Gli identificatori attualmente definiti e il tipo di dati da restituire in pvData sono elencati nella tabella seguente.

Valore	Significato
CERT_ACCESS_STATE_PROP_ID	Tipo di dati per pvData: puntatore a un DWORD Restituisce un valore DWORD che indica se le operazioni di scrittura nel certificato sono persistenti. Il valore DWORD non viene impostato se il certificato si trova in un archivio di memoria o in un archivio basato sul Registro di sistema aperto come di sola lettura.
CERT_ARCHIVED_PROP_ID	Tipo di dati per pvData: NULL Indica che il certificato viene ignorato durante le enumerazioni. Un certificato con questo set di proprietà viene trovato con operazioni di ricerca esplicite, ad esempio quelle usate per trovare un certificato con un hash specifico o un numero di serie. Nessun dato in pvData è associato a questa proprietà.
CERT_AUTO_ENROLL_PROP_ID	Tipo di dati per pvData: puntatore a una matrice BYTE Restituisce una stringa Unicode con terminazione Null che denomina il tipo di certificato per il quale il certificato è stato registrato automaticamente.
CERT_CTL_USAGE_PROP_ID	Tipo di dati per pvData: puntatore a una matrice BYTE Restituisce una matrice di byte contenente una struttura di CTL_USAGE con codifica ASN.1 (Abstract Syntax Notation One).
CERT_DESCRIPTION_PROP_ID	Tipo di dati per pvData: puntatore a una matrice BYTE Restituisce la proprietà visualizzata dall'interfaccia utente del certificato. Questa proprietà consente all'utente di descrivere l'uso del certificato.
CERT_ENHKEY_USAGE_PROP_ID	Tipo di dati per pvData: puntatore a una matrice BYTE Restituisce una matrice di byte contenente una struttura con codifica ASN.1 CERT_ENHKEY_USAGE .
CERT_FRIENDLY_NAME_PROP_ID	Tipo di dati per pvData: puntatore a una matrice BYTE Restituisce una stringa di caratteri Unicode con terminazione Null che contiene il nome visualizzato per il CTL.
CERT_HASH_PROP_ID	Tipo di dati per pvData: puntatore a una matrice BYTE Restituisce l'hash SHA1. Se l'hash non esiste, viene calcolato usando CryptHashCertificate.
CERT_KEY_CONTEXT_PROP_ID	Tipo di dati per pvData: puntatore a un CERT_KEY_CONTEXT Restituisce una struttura CERT_KEY_CONTEXT .
CERT_KEY_IDENTIFIER_PROP_ID	Tipo di dati per pvData: puntatore a una matrice BYTE Se non esiste, cerca l'estensione szOID_SUBJECT_KEY_IDENTIFIER. In caso di errore, viene eseguito un hash SHA1 sul membro SubjectPublicKeyInfo del certificato per produrre i valori dell'identificatore.
CERT_KEY_PROV_HANDLE_PROP_ID	Tipo di dati per pvData: puntatore a un HCRYPTPROV Restituisce l'handle del provider ottenuto dal CERT_KEY_CONTEXT_PROP_ID.
CERT_KEY_PROV_INFO_PROP_ID	Tipo di dati per pvData: puntatore a una struttura CRYPT_KEY_PROV_INFO Restituisce un puntatore a un CRYPT_KEY_PROV_INFO.
CERT_KEY_SPEC_PROP_ID	Tipo di dati per pvData: puntatore a un DWORD Restituisce un valore DWORD che specifica la chiave privata ottenuta da CERT_KEY_CONTEXT_PROP_ID proprietà, se presente. In caso contrario, se CERT_KEY_PROV_INFO_PROP_ID esiste, è l'origine di dwKeySpec.
CERT_MD5_HASH_PROP_ID	Tipo di dati per pvData: puntatore a una matrice BYTE Restituisce l'hash MD5. Se l'hash non esiste, viene calcolato usando CryptHashCertificate.
CERT_NEXT_UPDATE_LOCATION_PROP_ID	Tipo di dati per pvData: puntatore a una matrice BYTE Restituisce la struttura CERT_ALT_NAME_INFO con codifica ASN.1. CERT_NEXT_UPDATE_LOCATION_PROP_ID è attualmente usato solo con elenchi di scopi consentiti.
CERT_PVK_FILE_PROP_ID	Tipo di dati per pvData: puntatore a una matrice BYTE Restituisce una stringa unicode con terminazione Null con caratteri wide che specifica il nome file contenente la chiave privata associata alla chiave pubblica del certificato.
CERT_SHA1_HASH_PROP_ID	Tipo di dati per pvData: puntatore a una matrice BYTE Restituisce l'hash SHA1. Se l'hash non esiste, viene calcolato usando CryptHashCertificate.
CERT_SIGNATURE_HASH_PROP_ID	Tipo di dati per pvData: puntatore a una matrice BYTE Restituisce l'hash della firma. Se l'hash non esiste, viene calcolato con CryptHashToBeSigned. La lunghezza dell'hash è di 20 byte per SHA e 16 per MD5.

Per tutti gli altri identificatori di proprietà, pvData punta a una matrice di byte e non a un CRYPT_DATA_BLOB come indicato dal parametro pvData in CertSetCertificateContextProperty.

Per altre informazioni su ogni identificatore di proprietà, vedere la documentazione sul parametro dwPropId in CertSetCertificateContextProperty. CERT_SHA1_HASH_PROP_ID e CERT_NEXT_UPDATE_LOCATION_PROP_ID sono le proprietà predefinite di maggiore interesse.

[out] pvData

Puntatore a un buffer per ricevere i dati come determinato da dwPropId. Le strutture a cui puntano i membri di una struttura restituita vengono restituite anche in base alla struttura di base. Pertanto, le dimensioni contenute in pcbData spesso superano le dimensioni della struttura di base.

Questo parametro può essere NULL per impostare le dimensioni delle informazioni a scopo di allocazione della memoria. Per altre informazioni, vedere Recupero di dati di lunghezza sconosciuta.

[in, out] pcbData

Puntatore a un valore DWORD che specifica le dimensioni, in byte, del buffer a cui punta il parametro pvData . Quando la funzione viene restituita, il valore DWORD contiene il numero di byte 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 alle dimensioni del buffer specificato nell'input. In caso di input, le dimensioni del buffer vengono in genere 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.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è TRUE.

Se la funzione ha esito negativo, il valore restituito è FALSE.

Gli errori della funzione chiamata , CryptHashCertificate, possono essere propagati a questa funzione. Per informazioni sugli errori estesi, chiamare GetLastError.

Di seguito sono riportati alcuni possibili codici di errore.

Codice restituito	Descrizione
CRYPT_E_NOT_FOUND	CTL non ha la proprietà specificata.
ERROR_MORE_DATA	Se il buffer specificato dal parametro pvData non è sufficiente per contenere i dati restituiti, la funzione imposta il codice ERROR_MORE_DATA e archivia le dimensioni del buffer necessarie, in byte, nella variabile puntata da pcbData.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	wincrypt.h
Libreria	Crypt32.lib
DLL	Crypt32.dll

Vedi anche

CertEnumCTLContextProperties

CertGetCertificateContextProperty

CertSetCTLContextProperty

CryptHashCertificate

Funzioni delle proprietà estese

Condividi tramite