Funzione CertFindCTLInStore (wincrypt.h)

Articolo
08/27/2023

La funzione CertFindCTLInStore trova il contesto CTL (Certificate Trust List) primo o successivo che corrisponde ai criteri di ricerca stabiliti dal dwFindType e dal relativo pvFindPara associato. Questa funzione può essere usata in un ciclo per trovare tutti i contesti CTL in un archivio certificati che corrispondono ai criteri di ricerca specificati.

Sintassi

PCCTL_CONTEXT CertFindCTLInStore(
  [in] HCERTSTORE    hCertStore,
  [in] DWORD         dwMsgAndCertEncodingType,
  [in] DWORD         dwFindFlags,
  [in] DWORD         dwFindType,
  [in] const void    *pvFindPara,
  [in] PCCTL_CONTEXT pPrevCtlContext
);

Parametri

[in] hCertStore

Handle dell'archivio certificati da cercare.

[in] dwMsgAndCertEncodingType

Specifica il tipo di codifica utilizzata nel CTL. È sempre accettabile specificare sia il certificato che i tipi di codifica dei messaggi combinandoli con un'operazione OR bit per bit, come illustrato nell'esempio seguente:

X509_ASN_ENCODING | PKCS_7_ASN_ENCODING I tipi di codifica attualmente definiti sono:

X509_ASN_ENCODING
PKCS_7_ASN_ENCODING

Questo parametro viene usato solo quando il parametro dwFindType è impostato su CTL_FIND_USAGE.

[in] dwFindFlags

Può essere impostato quando dwFindType è impostato su CTL_FIND_USAGE. Per informazioni dettagliate, vedere i commenti in CTL_FIND_USAGE, come illustrato di seguito.

[in] dwFindType

Specifica il tipo di ricerca eseguita. Il tipo di ricerca determina il tipo di dati, il contenuto e l'uso di pvFindPara. Questo parametro può avere uno dei valori seguenti.

Valore	Significato
CTL_FIND_ANY	Tipo di dati pvFindPara: NULL. Qualsiasi CTL è una corrispondenza.
CTL_FIND_SHA1_HASH	Tipo di dati pvFindPara: CRYPT_HASH_BLOB. Viene trovato un elenco CTL con un hash corrispondente all'hash nella struttura CRYPT_HASH_BLOB .
CTL_FIND_MD5_HASH	Tipo di dati pvFindPara: CRYPT_HASH_BLOB. Viene trovato un elenco CTL con un hash corrispondente all'hash nella struttura CRYPT_HASH_BLOB .
CTL_FIND_USAGE	Tipo di dati pvFindPara: CTL_FIND_USAGE_PARA. Qualsiasi CTL viene trovato con un identificatore di utilizzo, un identificatore di elenco o un firmatario corrispondente all'identificatore di utilizzo, all'identificatore di elenco o al firmatario nella struttura CTL_FIND_USAGE_PARA . Se il membro cUsageIdentifier è di dimensioni SubjectUsage , qualsiasi CTL è una corrispondenza. Se il membro cbData del membro ListIdentifier è zero, qualsiasi identificatore di elenco è una corrispondenza. Se il membro cbData di ListIdentifier è CTL_FIND_NO_LIST_ID_CBDATA, solo un CTL senza un identificatore di elenco è una corrispondenza. Se il membro pSigner nella struttura CTL_FIND_USAGE_PARA è NULL, viene utilizzata una corrispondenza qualsiasi firmatario CTL e vengono usati solo i membri Issuer e SerialNumber nella struttura pSignerCERT_INFO . Se pSigner è CTL_FIND_NO_SIGNER_PTR, solo un CTL senza un firmatario è una corrispondenza.
CTL_FIND_SAME_USAGE_FLAG	Tipo di dati pvFindPara: CTL_FIND_USAGE_PARA. Vengono confrontate solo le CCL con gli stessi identificatori di utilizzo. Le licenze CRL con identificatori di utilizzo aggiuntivi non corrispondono. Ad esempio, se solo "1.2.3" viene specificato nella struttura CTL_FIND_USAGE_PARA , per una corrispondenza, il CTL deve contenere solo "1.2.3" e nessun identificatore di utilizzo aggiuntivo.
CTL_FIND_EXISTING	Tipo di dati pvFindPara: PCCTL_CONTEXT. Cerca il CRL successivo che corrisponde esattamente al CTL_CONTEXT.
CTL_FIND_SUBJECT	Tipo di dati pvFindPara: CTL_FIND_SUBJECT_PARA. Viene trovato un elenco CTL con l'oggetto specificato. CertFindSubjectInCTL può essere chiamato per ottenere un puntatore alla voce dell'oggetto nel CTL. Il membro pUsagePara in CTL_FIND_SUBJECT_PARA può essere impostato facoltativamente per abilitare la corrispondenza descritta in precedenza in CTL_FIND_USAGE.

[in] pvFindPara

Puntatore al valore di ricerca associato al parametro dwFindType .

[in] pPrevCtlContext

Puntatore all'ultima CTL_CONTEXT restituita da questa funzione. Deve essere NULL per ottenere il primo CTL nell'archivio. I CRL successivi vengono recuperati impostando pPrevCtlContext sul puntatore al CTL_CONTEXT restituito da una chiamata di funzione precedente. Tutti i certificati che non soddisfano i criteri di ricerca o eliminati in precedenza da CertDeleteCTLFromStore vengono ignorati. Questa funzione libera la CTL_CONTEXT a cui fa riferimento i valori non NULL di questo parametro.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è un puntatore a un contesto CTL di sola lettura.

Per informazioni sugli errori estesi, chiamare GetLastError. Di seguito sono riportati alcuni possibili codici di errore.

Codice restituito	Descrizione
CRYPT_E_NOT_FOUND	Nessun CTL trovato nell'archivio, nessun CTL è stato trovato corrispondente ai criteri di ricerca oppure la funzione ha raggiunto la fine dell'elenco dello store.
E_INVALIDARG	L'handle nel parametro hCertStore non corrisponde a quello nel contesto CTL a cui punta il parametro pPrevCtlContext oppure un valore non valido specificato nel parametro dwFindType .

Commenti

Un puntatore restituito viene liberato quando viene passato come pPrevCtlContext in una chiamata successiva alla funzione. In caso contrario, il puntatore deve essere liberato chiamando CertFreeCTLContext. Un pPrevCtlContext non NULL passato alla funzione viene sempre liberato con una chiamata a CertFreeCTLContext, anche se la funzione genera un errore.

CertDuplicateCTLContext può essere chiamato per creare un duplicato del contesto restituito. Il contesto CTL restituito può essere aggiunto a un archivio certificati diverso usando CertAddCTLContextToStore oppure è possibile aggiungere un collegamento a tale contesto CTL a un archivio non dell'insieme usando CertAddCTLLinkToStore. Se non viene trovato un elenco CTL corrispondente ai criteri di ricerca, viene restituito NULL .

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