Funzione CertSelectCertificateChains (wincrypt.h)

  • Articolo

La funzione CertSelectCertificateChains recupera le catene di certificati in base ai criteri di selezione specificati.

Sintassi

BOOL CertSelectCertificateChains(
  [in, optional] LPCGUID                  pSelectionContext,
  [in]           DWORD                    dwFlags,
  [in, optional] PCCERT_SELECT_CHAIN_PARA pChainParameters,
  [in]           DWORD                    cCriteria,
  [in, optional] PCCERT_SELECT_CRITERIA   rgpCriteria,
  [in]           HCERTSTORE               hStore,
  [out]          PDWORD                   pcSelection,
  [out]          PCCERT_CHAIN_CONTEXT     **pprgpSelection
);

Parametri

[in, optional] pSelectionContext

Puntatore al GUID dello scenario di selezione del certificato da usare per questa chiamata.

[in] dwFlags

Flag per controllare il processo di selezione del certificato. Questo parametro può essere una combinazione di zero o più flag seguenti:

Valore Significato
CERT_SELECT_ALLOW_EXPIRED
 Selezionare certificati scaduti che soddisfano i criteri di selezione. Per impostazione predefinita, i certificati scaduti vengono rifiutati dalla selezione.
CERT_SELECT_TRUSTED_ROOT
 Selezionare i certificati in cui il bit di errore nello stato di attendibilità della catena di certificati non è impostato su CERT_TRUST_IS_UNTRUSTED_ROOT, CERT_TRUST_IS_PARTIAL_CHAIN o CERT_TRUST_IS_NOT_TIME_VALID.

Inoltre, i certificati con uno degli errori di vincolo non validi seguenti non sono selezionati:

  • CERT_TRUST_INVALID_POLICY_CONSTRAINTS
  • CERT_TRUST_INVALID_BASIC_CONSTRAINTS
  • CERT_TRUST_INVALID_NAME_CONSTRAINTS
CERT_SELECT_DISALLOW_SELFSIGNED
 Selezionare i certificati non autofirmati e autofirmati.
CERT_SELECT_HAS_PRIVATE_KEY
 Selezionare i certificati con valore impostato per la proprietà CERT_KEY_PROV_INFO_PROP_ID del certificato.
CERT_SELECT_HAS_KEY_FOR_SIGNATURE
 Selezionare i certificati in cui è impostato il valore del membro dwKeySpec della proprietà CERT_KEY_PROV_INFO_PROP_ID su AT_SIGNATURE.

Se questa funzione viene chiamata come parte di un'applicazione abilitata per CNG e il membro dwKeySpec della proprietà CERT_KEY_PROV_INFO_PROP_ID è impostato su -1, selezionare i certificati in cui il valore della proprietà NCRYPT_KEY_USAGE_PROPERTY della chiave privata associata ha il NCRYPT_ALLOW_SIGNING_FLAG impostato.
CERT_SELECT_HAS_KEY_FOR_KEY_EXCHANGE
 Selezionare i certificati in cui è impostato il valore del membro dwKeySpec della proprietà CERT_KEY_PROV_INFO_PROP_ID su AT_KEYEXCHANGE.

Se questa funzione viene chiamata come parte di un'applicazione abilitata per CNG e il membro dwKeySpec della proprietà CERT_KEY_PROV_INFO_PROP_ID è impostato su -1, selezionare i certificati in cui è impostato NCRYPT_ALLOW_DECRYPT_FLAG o NCRYPT_ALLOW_KEY_AGREEMENT_FLAG .
CERT_SELECT_HARDWARE_ONLY
 Selezionare i certificati in cui il valore della proprietà PP_IMPTYPE del provider di chiavi private associato è impostato su CRYPT_IMPL_HARDWARE o CRYPT_IMPL_REMOVABLE. Per i provider CNG, NCRYPT_IMPL_TYPE_PROPERTY valore della proprietà DEVE avere il set di NCRYPT_IMPL_HARDWARE_FLAG o NCRYPT_IMPL_REMOVABLE_FLAG bit.

Se questa funzione viene chiamata come parte di un'applicazione abilitata per CNG, selezionare i certificati in cui la proprietà NCRYPT_IMPL_TYPE_PROPERTY è impostata su NCRYPT_IMPL_HARDWARE_FLAG o NCRYPT_IMPL_REMOVABLE_FLAG.
CERT_SELECT_ALLOW_DUPLICATES
 Consenti la selezione dei certificati in cui il nome Alt soggetto e soggetto contengono le stesse informazioni e il valore dell'estensione del modello di certificato è equivalente. Per impostazione predefinita, quando i certificati corrispondono a questi criteri, viene selezionato solo il certificato più recente.

[in, optional] pChainParameters

Puntatore a una struttura CERT_SELECT_CHAIN_PARA per specificare i parametri per la compilazione della catena. Se NULL, verranno usati i parametri predefiniti.

Il membro pChainPara della struttura CERT_SELECT_CHAIN_PARA punta a una struttura CERT_CHAIN_PARA che può essere usata per abilitare la firma complessa.

[in] cCriteria

Numero di elementi nella matrice a cui punta la matrice rgpCriteria .

[in, optional] rgpCriteria

Puntatore a una matrice di strutture CERT_SELECT_CRITERIA che definiscono i criteri di selezione. Se questo parametro è impostato su NULL, il valore del parametro cCriteria deve essere zero.

[in] hStore

Handle in un archivio da cui selezionare i certificati.

[out] pcSelection

Puntatore a un valore DWORD per ricevere il numero di elementi nella matrice a cui punta il parametro pprgpSelection .

[out] pprgpSelection

Puntatore a un puntatore a una posizione per ricevere una matrice di CERT_CHAIN_CONTEXT struttura. La funzione CertSelectCertificateChains restituisce solo catene di certificati che corrispondono a tutti i criteri di selezione. Le voci nella matrice sono ordinate in base alla qualità, ad esempio la catena con la massima qualità è la prima voce.

L'archiviazione per la matrice viene allocata dalla funzione CertSelectCertificateChains . Per liberare la memoria allocata, è prima necessario rilasciare ogni singolo contesto della catena nella matrice chiamando la funzione CertFreeCertificateChain . È quindi necessario liberare la memoria chiamando la funzione CertFreeCertificateChainList .

Valore restituito

Se la funzione ha esito positivo, la funzione restituisce TRUE.

Se la funzione ha esito negativo, restituisce zero (FALSE). Per informazioni sull'errore estese, chiamare la funzione GetLastError .

Nota Se la selezione non restituisce risultati, la funzione CertSelectCertificateChains restituisce TRUE, ma il valore puntato al parametro pcSelection è impostato su zero.
 

Commenti

I criteri di selezione possono essere specificati tramite il parametro dwFlags , tramite il parametro rgpCriteria o tramite entrambi i parametri. Se non vengono specificati criteri di selezione, la funzione ha esito positivo e restituisce catene di certificati per tutti i certificati nell'archivio specificato dal parametro hStore .

Le catene di certificati selezionate sono ordinate in base alla logica di preferenza seguente:

  • Preferisce i certificati che sono certificati smart card sui certificati che non sono basati su smart card.
  • Preferisce i certificati con un periodo di validità più lungo (la data di scadenza è successiva).
  • Se più certificati hanno la stessa data di scadenza, preferire i certificati rilasciati più di recente.
  • Se c'è un tie, preferisce catene più brevi.
Alcuni criteri di selezione richiedono che una catena di certificati venga compilata prima di poter selezionare i criteri da usare. Se i certificati intermedi necessari per compilare la catena non sono disponibili in locale, viene eseguito un recupero di rete per i certificati emittente. Questo recupero di rete viene eseguito se il flag di CERT_SELECT_TRUSTED_ROOT è impostato o per i criteri seguenti:
  • CERT_SELECT_BY_ISSUER_NAME
  • CERT_SELECT_BY_ISSUER_ATTR
  • CERT_SELECT_BY_POLICY_OID
Eseguire le azioni seguenti per abilitare il controllo delle firme complesse:

Quando si abilita il controllo delle firme complesse, verrà ignorata qualsiasi catena di certificati che restituisce un errore di CERT_TRUST_IS_NOT_SIGNATURE_VALID nel campo dwErrorStatusdella struttura CERT_TRUST_STATUS. Il parametro pprgpSelection punta a una struttura CERT_CHAIN_CONTEXT che, a sua volta, punta alla struttura CERT_TRUST_STATUS . Il valore CERT_TRUST_HAS_WEAK_SIGNATURE è impostato anche per una firma debole.

Requisiti

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

Vedi anche

CertGetCertificateContextProperty

CertSetCertificateContextProperty