Funzione CertFindCTLInStore (wincrypt.h)

Articolo
07/16/2024

La funzione CertFindCTLInStore trova il primo o il successivo elenco di attendibilità certificati (CTL) contesto che corrisponde ai criteri di ricerca stabiliti dal dwFindType e dal relativo pvFindPara. 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 in cui eseguire la ricerca.

[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 di 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 segue.

[in] dwFindType

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

Valore	Significato
CTL_FIND_ANY	Tipo di dati di pvFindPara: NULL. Qualsiasi CTL è una corrispondenza.
CTL_FIND_SHA1_HASH	Tipo di dati di pvFindPara: CRYPT_HASH_BLOB. Viene trovato un CTL con un hash corrispondente all'hash nella struttura CRYPT_HASH_BLOB.
CTL_FIND_MD5_HASH	Tipo di dati di pvFindPara: CRYPT_HASH_BLOB. Viene trovato un CTL con un hash corrispondente all'hash nella struttura CRYPT_HASH_BLOB.
CTL_FIND_USAGE	Tipo di dati di pvFindPara: CTL_FIND_USAGE_PARA. Viene rilevato un CTL 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 corrisponde. Se il membro cbData di membro ListIdentifier è zero, qualsiasi identificatore di elenco corrisponde. 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, qualsiasi firmatario CTL è una corrispondenza e vengono utilizzati 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 di pvFindPara: CTL_FIND_USAGE_PARA. Vengono confrontate solo le CRL con gli stessi identificatori di utilizzo. Le licenze CTL con identificatori di utilizzo aggiuntivi non corrispondono. Ad esempio, se nella struttura di CTL_FIND_USAGE_PARA viene specificato solo "1.2.3", per una corrispondenza, il CTL deve contenere solo "1.2.3" e nessun identificatore di utilizzo aggiuntivo.
CTL_FIND_EXISTING	Tipo di dati di pvFindPara: PCCTL_CONTEXT. Cerca il CRL successivo che corrisponde esattamente al CTL_CONTEXT.
CTL_FIND_SUBJECT	Tipo di dati di pvFindPara: CTL_FIND_SUBJECT_PARA. Viene trovato un CTL con l'oggetto specificato. è possibile chiamare CertFindSubjectInCTL 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'ultimo CTL_CONTEXT restituito da questa funzione. Deve essere NULL per ottenere il primo CTL nell'archivio. Le CRL successive vengono recuperate 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 che sono stati eliminati in precedenza da CertDeleteCTLFromStore vengono ignorati. Questa funzione libera i CTL_CONTEXT a cui fa riferimento nonvalori NULL di questo parametro.

Valore restituito

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

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 è uguale a quello nel contesto CTL a cui fa riferimento il parametro pPrevCtlContext oppure un valore non valido specificato nel parametro dwFindType.

Osservazioni

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. UnNULLpPrevCtlContext passato alla funzione viene sempre liberato con una chiamata a CertFreeCTLContext, anche se la funzione genera un errore.

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

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