Condividi tramite

Funzione CertGetCertificateContextProperty (wincrypt.h)

  • Articolo

La funzione CertGetCertificateContextProperty recupera le informazioni contenute in una proprietà estesa di un contesto di certificato .

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 pvData: puntatore a un valore DWORD .

Restituisce un valore DWORD che indica se le operazioni di scrittura nel certificato sono persistenti. Il valore DWORD non è 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_AIA_URL_RETRIEVED_PROP_ID

Questo identificatore è riservato.

CERT_ARCHIVED_KEY_HASH_PROP_ID

Tipo di dati di pvData: puntatore a una matrice di valori BYTE . La dimensione di questa matrice viene specificata nel parametro pcbData.

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 CertGetCertificateContextProperty restituisce true, l'ID proprietà specificato esiste per il CERT_CONTEXT.

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 pvData: puntatore a una matrice di valori BYTE . La dimensione di questa matrice viene specificata nel parametro pcbData.

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 pvData: puntatore a una matrice di valori BYTE . La dimensione di questa matrice viene specificata nel parametro pcbData.

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 pvData: puntatore a una matrice di valori BYTE . La dimensione di questa matrice viene specificata nel parametro pcbData.

Contiene l'elenco degli URL (OCSP) del protocollo di stato dei certificati online da usare per i certificati rilasciati dal certificato della CA. Il contenuto della matrice è costituito dai byte con codifica ASN.1 (AsN.1) di una struttura X509_AUTHORITY_INFO_ACCESS in cui pszAccessMethod è impostato su szOID_PKIX_OCSP.

CERT_CROSS_CERT_DIST_POINTS_PROP_ID

Tipo di dati di pvData: puntatore a una matrice di valori BYTE . La dimensione di questa matrice viene specificata nel parametro pcbData.

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 contiene una struttura con codifica ASN.1 CROSS_CERT_DIST_POINTS_INFO decodificata usando la funzione CryptDecodeObject con un valore X509_CROSS_CERT_DIST_POINTS per il parametro lpszStuctType.

CERT_CTL_USAGE_PROP_ID

Tipo di dati di pvData: puntatore a una matrice di valori BYTE . La dimensione di questa matrice viene specificata nel parametro pcbData.

Restituisce una matrice di byte che contengono una struttura con codifica ASN.1 CTL_USAGE.

CERT_DATE_STAMP_PROP_ID

Tipo di dati di pvData: puntatore a una struttura FILETIME .

Ora in cui il certificato è stato aggiunto all'archivio.

CERT_DESCRIPTION_PROP_ID

Tipo di dati di pvData: puntatore a una matrice di valori BYTE . La dimensione di questa matrice viene specificata nel parametro pcbData.

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 pvData: puntatore a una matrice di valori BYTE . La dimensione di questa matrice viene specificata nel parametro pcbData.

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 pvData: puntatore a una matrice di valori BYTE . La dimensione di questa matrice viene specificata nel parametro pcbData.

Informazioni di registrazione della richiesta in sospeso che contiene RequestID, CADNSName, CAName e DisplayName. Il formato dei dati è definito come segue.

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 pvData: puntatore a una matrice di valori BYTE . La dimensione di questa matrice viene specificata nel parametro pcbData.

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 pvData: puntatore a una matrice di valori BYTE . La dimensione di questa matrice viene specificata nel parametro pcbData.

Restituisce una stringa di caratteri Unicode con terminazione Null contenente il nome visualizzato per il certificato.

CERT_HASH_PROP_ID

Tipo di dati di pvData: puntatore a una matrice di valori BYTE . La dimensione di questa matrice viene specificata nel parametro pcbData.

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 o NCRYPT_KEY_HANDLE scelta.

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 pvData: puntatore a una matrice di valori BYTE . La dimensione di questa matrice viene specificata nel parametro pcbData.

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 pvData: puntatore a una matrice di valori BYTE . La dimensione di questa matrice viene specificata nel parametro pcbData.

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 pvData: puntatore a una matrice di valori BYTE . La dimensione di questa matrice viene specificata nel parametro pcbData.

Se inesistente, 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 pvData: puntatore a un valore DWORD .

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 pvData: puntatore a una matrice di valori BYTE . La dimensione di questa matrice viene specificata nel parametro pcbData.

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 pvData: puntatore a una matrice di valori BYTE . La dimensione di questa matrice viene specificata nel parametro pcbData.

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 pvData: puntatore a una matrice di valori BYTE . La dimensione di questa matrice viene specificata nel parametro pcbData.

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 un valore 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 pvData: puntatore a una matrice di valori BYTE . La dimensione di questa matrice viene specificata nel parametro pcbData.

Per le chiavi pubbliche che supportano l'ereditarietà dei parametri dell'algoritmo, restituisce i parametri dell'algoritmo PublicKey con codifica ASN.1. Per Digital Signature Standard (DSS), restituisce i parametri codificati usando la funzione CryptEncodeObject . Questa proprietà viene utilizzata solo se è definita CMS_PKCS7.

CERT_PUBKEY_HASH_RESERVED_PROP_ID

Questo identificatore è riservato.

CERT_PVK_FILE_PROP_ID

Tipo di dati di pvData: puntatore a una matrice di valori BYTE . La dimensione di questa matrice viene specificata nel parametro pcbData.

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 pvData: puntatore a una matrice di valori BYTE . La dimensione di questa matrice viene specificata nel parametro pcbData.

Restituisce l'hash del certificato rinnovato.

CERT_REQUEST_ORIGINATOR_PROP_ID

Tipo di dati di pvData: puntatore a una matrice di valori BYTE . La dimensione di questa matrice viene specificata nel parametro pcbData.

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 pvData: puntatore a una matrice di valori BYTE . La dimensione di questa matrice viene specificata nel parametro pcbData.

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 CryptDecodeObject con il parametro lpszStructType impostato su X509_CERT_POLICIES e il parametro dwCertEncodingType impostato su una combinazione di X509_ASN_ENCODING ORPKCS_7_ASN_ENCODINGbit per bit.

CERT_ROOT_PROGRAM_NAME_CONSTRAINTS_PROP_ID

Questo identificatore è riservato.

CERT_SHA1_HASH_PROP_ID

Tipo di dati di pvData: puntatore a una matrice di valori BYTE . La dimensione di questa matrice viene specificata nel parametro pcbData.

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 pvData: puntatore a una matrice di valori BYTE . La dimensione di questa matrice è di 52 byte, 20 byte per l'hash SHA1 e 32 byte per l'hash SHA256.

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 pvData: puntatore a una matrice di valori BYTE . La dimensione di questa matrice viene specificata nel parametro pcbData.

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 pvData: puntatore a una matrice di valori BYTE . La dimensione di questa matrice viene specificata nel parametro pcbData.

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 pvData: puntatore a una matrice di valori BYTE . La dimensione di questa matrice viene specificata nel parametro pcbData.

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 pvData: puntatore a una matrice di valori BYTE . La dimensione di questa matrice viene specificata nel parametro pcbData.

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 pvData: puntatore a una matrice di valori BYTE . La dimensione di questa matrice viene specificata nel parametro pcbData.

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 pvData: puntatore a una matrice di valori BYTE . La dimensione di questa matrice viene specificata nel parametro pcbData.

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 pvData: puntatore a un valore DWORD .

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 pvData: puntatore a una matrice di valori BYTE . La dimensione di questa matrice viene specificata nel parametro pcbData.

Restituisce l'hash MD5 della chiave pubblica del certificato.

Per tutti gli identificatori di proprietà definiti dall'utente, pvData punta a una matrice di valori BYTE .

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

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 pvData non è NULL e la dimensione specificata in pcbData è inferiore al numero di byte necessari per contenere i dati, la funzione ha esito negativo, GetLastError restituisce ERROR_MORE_DATAe la dimensione richiesta viene inserita nella variabile a cui punta il parametro pcbData.

Nota Durante l'elaborazione dei 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

Vedere anche

CERT_KEY_CONTEXT

CertCreateCertificateContext

CertSetCertificateContextProperty

CryptHashCertificate

CryptHashToBeSigned

funzioni delle proprietà estese