Funzione CertGetCertificateContextProperty (wincrypt.h)
La funzione CertGetCertificateContextProperty
Sintassi
BOOL CertGetCertificateContextProperty(
[in] PCCERT_CONTEXT pCertContext,
[in] DWORD dwPropId,
[out] void *pvData,
[in, out] DWORD *pcbData
);
Parametri
[in] pCertContext
Puntatore alla struttura CERT_CONTEXT del certificato che contiene la proprietà da recuperare.
[in] dwPropId
Proprietà da recuperare. Gli identificatori attualmente definiti e il tipo di dati da restituire in pvData sono elencati nella tabella seguente.
CERT_ACCESS_STATE_PROP_ID
Tipo di dati di
Restituisce un valore DWORD
CERT_AIA_URL_RETRIEVED_PROP_ID
Questo identificatore è riservato.
CERT_ARCHIVED_KEY_HASH_PROP_ID
Tipo di dati di
Restituisce una chiave crittografata salvata in precedenza hash per il contesto del certificato.
CERT_ARCHIVED_PROP_ID
Tipo di dati di pvData: NULL. Se la funzione di
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_AUTHORITY_INFO_ACCESS_PROP_ID
Questo identificatore è riservato.
CERT_AUTO_ENROLL_PROP_ID
Tipo di dati di
Restituisce una stringa Unicode con terminazione Null che denomina il tipo di certificato per cui il certificato è stato registrato automaticamente.
CERT_AUTO_ENROLL_RETRY_PROP_ID
Questo identificatore è riservato.
CERT_BACKED_UP_PROP_ID
Questo identificatore è riservato.
CERT_CA_DISABLE_CRL_PROP_ID
Tipo di dati di
Disabilita recupero dell'elenco di revoche di certificati (CRL) per i certificati usati dall'autorità di certificazione (CA). Se il certificato DELLA CA contiene questa proprietà, deve includere anche la proprietà CERT_CA_OCSP_AUTHORITY_INFO_ACCESS_PROP_ID.
CERT_CA_OCSP_AUTHORITY_INFO_ACCESS_PROP_ID
Tipo di dati di
Contiene l'elenco degli URL (OCSP) del protocollo di stato dei certificati online
CERT_CROSS_CERT_DIST_POINTS_PROP_ID
Tipo di dati di
Posizione dei certificati incrociati. Attualmente, questo identificatore è applicabile solo ai certificati e non ai CRL o elenchi di attendibilità dei certificati (CRL).
La matrice BYTE
CERT_CTL_USAGE_PROP_ID
Tipo di dati di
Restituisce una matrice di byte che contengono una struttura con codifica ASN.1 CTL_USAGE.
CERT_DATE_STAMP_PROP_ID
Tipo di dati di
Ora in cui il certificato è stato aggiunto all'archivio.
CERT_DESCRIPTION_PROP_ID
Tipo di dati di
Restituisce la proprietà visualizzata dall'interfaccia utente del certificato. Questa proprietà consente all'utente di descrivere l'uso del certificato.
CERT_EFS_PROP_ID
Questo identificatore è riservato.
CERT_ENHKEY_USAGE_PROP_ID
Tipo di dati di
Restituisce una matrice di byte che contengono una struttura con codifica ASN.1 CERT_ENHKEY_USAGE. Questa struttura contiene una matrice di identificatori di oggetto avanzati identificatori di oggetto (OID), ognuno dei quali specifica un uso valido del certificato.
CERT_ENROLLMENT_PROP_ID
Tipo di dati di
Informazioni di registrazione della richiesta in sospeso che contiene RequestID, CADNSName, CAName e DisplayName. Il formato dei dati è definito nel modo seguente:
| Byte | Contenuto |
|---|---|
| Primi 4 byte | ID richiesta in sospeso |
| 4 byte successivi | Dimensioni CADNSName, in caratteri, incluso il carattere Null di terminazione, seguito dalla stringa CADNSName con carattere null di terminazione |
| 4 byte successivi | Dimensione CAName, in caratteri, incluso il carattere Null di terminazione, seguito dalla stringa CAName con carattere null di terminazione |
| 4 byte successivi | Dimensioni DisplayName, in caratteri, incluso il carattere Null di terminazione, seguito dalla stringa DisplayName con carattere null di terminazione |
CERT_EXTENDED_ERROR_INFO_PROP_ID
Tipo di dati di
Restituisce una stringa di caratteri Unicode con terminazione Null che contiene informazioni estese sull'errore per il contesto del certificato.
CERT_FORTEZZA_DATA_PROP_ID
Questo identificatore è riservato.
CERT_FRIENDLY_NAME_PROP_ID
Tipo di dati di
Restituisce una stringa di caratteri Unicode con terminazione Null contenente il nome visualizzato per il certificato.
CERT_HASH_PROP_ID
Tipo di dati di
Restituisce l'hash SHA1. Se l'hash non esiste, viene calcolato usando la funzione CryptHashCertificate.
CERT_HCRYPTPROV_OR_NCRYPT_KEY_HANDLE_PROP_ID
Tipo di dati di pvData: puntatore a un tipo di dati HCRYPTPROV_OR_NCRYPT_KEY_HANDLE.
Restituisce l' HCRYPTPROV
CERT_HCRYPTPROV_TRANSFER_PROP_ID
Restituisce l'handle di chiave DELL'API di crittografia (CAPI) associato al certificato. Il chiamante è responsabile della liberazione dell'handle. Non verrà liberata quando il contesto viene liberato. Il valore della proprietà viene rimosso dopo la restituzione. Se si chiama questa proprietà in un contesto con una chiave CNG, viene restituito CRYPT_E_NOT_FOUND.
CERT_IE30_RESERVED_PROP_ID
Questo identificatore è riservato.
CERT_ISSUER_PUBLIC_KEY_MD5_HASH_PROP_ID
Tipo di dati di
Hash MD5 della chiave pubblica associata alla chiave privata usata per firmare questo certificato.
CERT_ISSUER_SERIAL_NUMBER_MD5_HASH_PROP_ID
Tipo di dati di
Hash MD5 del nome dell'autorità emittente e del numero di serie del certificato.
CERT_KEY_CONTEXT_PROP_ID
Tipo di dati di pvData: puntatore a una struttura di CERT_KEY_CONTEXT.
Restituisce una struttura CERT_KEY_CONTEXT.
CERT_KEY_IDENTIFIER_PROP_ID
Tipo di dati di
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 di pvData: puntatore a un valore HCRYPTPROV.
Restituisce l'handle del provider ottenuto da CERT_KEY_CONTEXT_PROP_ID.
CERT_KEY_PROV_INFO_PROP_ID
Tipo di dati di pvData: puntatore a una struttura di CRYPT_KEY_PROV_INFO.
Restituisce un puntatore a una struttura CRYPT_KEY_PROV_INFO.
CERT_KEY_SPEC_PROP_ID
Tipo di dati di
Restituisce un valore DWORD che specifica la chiave privata ottenuta da CERT_KEY_CONTEXT_PROP_ID se esistente. In caso contrario, se CERT_KEY_PROV_INFO_PROP_ID esiste, è l'origine del dwKeySpec.
CERT_MD5_HASH_PROP_ID
Tipo di dati di
Restituisce l'hash MD5. Se l'hash non esiste, viene calcolato usando la funzione CryptHashCertificate.
CERT_NCRYPT_KEY_HANDLE_PROP_ID
Tipo di dati di pvData: puntatore a un tipo di dati NCRYPT_KEY_HANDLE.
Restituisce un CERT_NCRYPT_KEY_SPEC scelta, se applicabile.
CERT_NCRYPT_KEY_HANDLE_TRANSFER_PROP_ID
Restituisce l'handle di chiave CNG associato al certificato. Il chiamante è responsabile della liberazione dell'handle. Non verrà liberata quando il contesto viene liberato. Il valore della proprietà viene rimosso dopo la restituzione. Se si chiama questa proprietà in un contesto con una chiave CAPI legacy, viene restituito CRYPT_E_NOT_FOUND.
CERT_NEW_KEY_PROP_ID
Questo identificatore è riservato.
CERT_NEXT_UPDATE_LOCATION_PROP_ID
Tipo di dati di
Restituisce la struttura con codifica ASN.1 CERT_ALT_NAME_INFO.
CERT_NEXT_UPDATE_LOCATION_PROP_ID è attualmente usato solo con elenchi di scopi consentiti.
CERT_NO_AUTO_EXPIRE_CHECK_PROP_ID
Questo identificatore è riservato.
CERT_OCSP_CACHE_PREFIX_PROP_ID
Questo identificatore è riservato.
CERT_OCSP_RESPONSE_PROP_ID
Tipo di dati di
Restituisce una risposta OCSP codificata per questo certificato.
CERT_PUB_KEY_CNG_ALG_BIT_LENGTH_PROP_ID
Tipo di dati di pvData: puntatore a una stringa Unicode con terminazione Null.
Restituisce una stringa L"<PUBKEY><BITLENGTH>" che rappresenta l'algoritmo di chiave pubblica e la lunghezza del bit del certificato. Sono supportati gli algoritmi di <PUBKEY> seguenti:
- L"RSA" (BCRYPT_RSA_ALGORITHM)
- L"DSA" (BCRYPT_DSA_ALGORITHM)
- L"ECDSA" (SSL_ECDSA_ALGORITHM)
Windows 8 e Windows Server 2012: inizia Supporto per questa proprietà.
CERT_PUBKEY_ALG_PARA_PROP_ID
Tipo di dati di
Per le chiavi pubbliche che supportano l'ereditarietà dei parametri dell'algoritmo, restituisce i parametri dell'algoritmo PublicKey con codifica ASN.1. Per
CERT_PUBKEY_HASH_RESERVED_PROP_ID
Questo identificatore è riservato.
CERT_PVK_FILE_PROP_ID
Tipo di dati di
Restituisce una stringa di caratteri wide Unicode con terminazione Null contenente il nome file contenente la chiave privata associata alla chiave pubblica del certificato.
CERT_RENEWAL_PROP_ID
Tipo di dati di
Restituisce l'hash del certificato rinnovato.
CERT_REQUEST_ORIGINATOR_PROP_ID
Tipo di dati di
Restituisce una stringa Unicode con terminazione Null contenente il nome del computer DNS per l'origine della richiesta di contesto del certificato.
CERT_ROOT_PROGRAM_CERT_POLICIES_PROP_ID
Tipo di dati di
Restituisce un puntatore a una struttura di CERT_POLICIES_INFO codificata che contiene i criteri dell'applicazione del certificato radice per il contesto. Questa proprietà può essere decodificata usando la funzione
CERT_ROOT_PROGRAM_NAME_CONSTRAINTS_PROP_ID
Questo identificatore è riservato.
CERT_SHA1_HASH_PROP_ID
Tipo di dati di
Restituisce l'hash SHA1. Se l'hash non esiste, viene calcolato usando la funzione CryptHashCertificate.
CERT_SHA1_SHA256_HASH_PROP_ID
Tipo di dati di
Restituisce una combinazione dell'hash SHA1 e dell'hash SHA256. Se l'hash non esiste, viene calcolato usando la funzione CryptHashCertificate.
CERT_SHA256_HASH_PROP_ID
Tipo di dati di
Restituisce l'hash SHA256. Se l'hash non esiste, viene calcolato usando la funzione CryptHashCertificate.
CERT_SIGN_HASH_CNG_ALG_PROP_ID
Tipo di dati di pvData: puntatore a una stringa Unicode con terminazione Null.
Restituisce la stringa L"<SIGNATURE>/<HASH>" che rappresenta la firma del certificato. Il valore <SIGNATURE> identifica l'algoritmo di chiave pubblica CNG. Sono supportati gli algoritmi seguenti:
- L"RSA" (BCRYPT_RSA_ALGORITHM)
- L"DSA" (BCRYPT_DSA_ALGORITHM)
- L"ECDSA" (SSL_ECDSA_ALGORITHM)
Il valore <HASH> identifica l'algoritmo hash CNG. Sono supportati gli algoritmi seguenti:
- L"MD5" (BCRYPT_MD5_ALGORITHM)
- L"SHA1" (BCRYPT_SHA1_ALGORITHM)
- L"SHA256" (BCRYPT_SHA256_ALGORITHM)
- L"SHA384" (BCRYPT_SHA384_ALGORITHM)
- L"SHA512" (BCRYPT_SHA512_ALGORITHM)
Di seguito sono riportati esempi comuni:
- L"RSA/SHA1"
- L"RSA/SHA256"
- L"ECDSA/SHA256"
Windows 7 e Windows Server 2008 R2: inizia il supporto per questa proprietà.
CERT_SIGNATURE_HASH_PROP_ID
Tipo di dati di
Restituisce l'hash della firma. Se l'hash non esiste, viene calcolato usando la funzione CryptHashToBeSigned. La lunghezza dell'hash è di 20 byte per SHA e 16 per MD5.
CERT_SMART_CARD_DATA_PROP_ID
Tipo di dati di
Restituisce un puntatore ai dati codificati delle smart card. Prima di chiamare CertGetCertificateContextProperty, è possibile usare questa costante per recuperare un certificato di smart card usando il CertFindCertificateInStore funzione con il parametro pvFindPara impostato su CERT_SMART_CARD_DATA_PROP_ID e il parametro dwFindType impostato su CERT_FIND_PROPERTY.
CERT_SMART_CARD_ROOT_INFO_PROP_ID
Tipo di dati di
Restituisce un puntatore a una struttura CRYPT_SMART_CARD_ROOT_INFO codificata.
CERT_SOURCE_LOCATION_PROP_ID
Questo identificatore è riservato.
CERT_SOURCE_URL_PROP_ID
Questo identificatore è riservato.
CERT_SUBJECT_DISABLE_CRL_PROP_ID
Questo identificatore è riservato.
CERT_SUBJECT_INFO_ACCESS_PROP_ID
Tipo di dati di
Restituisce l'estensione di accesso alle informazioni sull'oggetto del contesto del certificato come struttura di CERT_SUBJECT_INFO_ACCESS codificata.
CERT_SUBJECT_NAME_MD5_HASH_PROP_ID
Tipo di dati di
Restituisce un hash MD5 del nome soggetto codificato del contesto del certificato.
CERT_SUBJECT_OCSP_AUTHORITY_INFO_ACCESS_PROP_ID
Questo identificatore è riservato.
CERT_SUBJECT_PUB_KEY_BIT_LENGTH_PROP_ID
Tipo di dati di
Restituisce la lunghezza, espressa in bit, della chiave pubblica nel certificato.
Windows 8 e Windows Server 2012: inizia Supporto per questa proprietà.
CERT_SUBJECT_PUBLIC_KEY_MD5_HASH_PROP_ID
Tipo di dati di
Restituisce l'hash MD5 della chiave pubblica del certificato.
Per tutti gli identificatori di proprietà definiti dall'utente,
Per altre informazioni su ogni identificatore di proprietà, vedere la documentazione sul parametro dwPropId in CertSetCertificateContextProperty.
[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 dopo la 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
Per ottenere le dimensioni necessarie di un buffer in fase di esecuzione, passare NULL per il parametro pvData e impostare il valore a cui punta questo parametro su zero. Se il parametro
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 caso di input, le dimensioni del buffer vengono in genere specificate in modo sufficientemente grande 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.
Valore restituito
Se la funzione ha esito positivo, la funzione restituisce TRUE.
Se la funzione non riesce, restituisce FALSE. Per informazioni sugli errori estesi, chiamare GetLastError.
Di seguito sono riportati alcuni possibili codici di errore:
| Codice restituito | Descrizione |
|---|---|
| CRYPT_E_NOT_FOUND | Il certificato non dispone della 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 a cui punta pcbData. |
Gli errori della funzione chiamata CryptHashCertificate possono essere propagati a questa funzione.
Osservazioni
Le proprietà non vengono archiviate all'interno di un certificato. In genere, vengono associati a un certificato dopo la ricezione della risposta del certificato e quindi salvati con il certificato nell'archivio. Per motivi di sicurezza, è consigliabile convalidare i valori delle proprietà prima di salvarli e salvare solo le proprietà informative, ad esempio il valore CERT_FRIENDLY_NAME_PROP_ID negli archivi utente. Tutti gli altri tipi di proprietà devono essere salvati negli archivi computer locali.
Il codice può usare una macro per valutare la classe di hash per un contesto di certificato. Per altre informazioni, vedere CertSetCertificateContextProperty.
Esempi
Per esempi che usano questa funzione, vedere Programma C di esempio: Recupero e impostazione delle proprietà del certificato e Esempio di programma C: Presentazione dei certificati in un archivio.
Fabbisogno
| Requisito | Valore |
|---|---|
| client minimo supportato | Windows XP [app desktop | App UWP] |
| server minimo supportato | Windows Server 2003 [app desktop | App UWP] |
| piattaforma di destinazione | Finestre |
| intestazione |
wincrypt.h |
| libreria |
Crypt32.lib |
| dll | Crypt32.dll |