CertFindSubjectInCTL function

The CertFindSubjectInCTL function attempts to find the specified subject in a certificate trust list (CTL). A subject can be identified either by the certificate's whole context or by any unique identifier of the certificate's subject such as the SHA1 hash of the certificate's issuer and serial number.

Syntax

PCTL_ENTRY CertFindSubjectInCTL(
  DWORD         dwEncodingType,
  DWORD         dwSubjectType,
  void          *pvSubject,
  PCCTL_CONTEXT pCtlContext,
  DWORD         dwFlags
);

Parameters

dwEncodingType

Specifies the encoding type used. Currently, only X509_ASN_ENCODING and PKCS_7_ASN_ENCODING are being used; however, additional encoding types may be added in the future. For either current encoding type, use:

X509_ASN_ENCODING | PKCS_7_ASN_ENCODING.

dwSubjectType

Specifies the type of subject to be searched for in the CTL. May be NULL for a default search.

Value Meaning
CTL_CERT_SUBJECT_TYPE
pvSubject data type: Pointer to a CERT_CONTEXT structure.

The CTL's SubjectAlgorithm is examined to determine the representation of the subject's identity. Initially, only SHA1 and MD5 hashes are supported as values for SubjectAlgorithm. The appropriate hash property is obtained from the CERT_CONTEXT structure.

CTL_ANY_SUBJECT_TYPE
pvSubject data type: Pointer to a CTL_ANY_SUBJECT_INFO structure.

The SubjectAlgorithm member of this structure must match the algorithm type of the CTL, and the SubjectIdentifier member must match one of the CTL entries.

 

The certificate's hash or the SubjectIdentifier member of the CTL_ANY_SUBJECT_INFO structure is used as the key in searching the subject entries. A binary memory comparison is done between the key and the entry's SubjectIdentifier.

If dwSubjectType is set to either preceding value, dwEncodingType is not used.

pvSubject

Pointer used in conjunction with the dwSubjectType parameter.

pCtlContext

A pointer to the CTL_CONTEXT structure being searched.

dwFlags

Reserved for future use and must be zero.

Return Value

If the function succeeds, the return value is the entry, if it is found.

If the function fails, the return value is NULL. For extended error information, call GetLastError. Some possible error codes follow.

Return code Description
CRYPT_E_NOT_FOUND
The subject was not found in the CTL.
E_INVALIDARG
The dwSubjectType parameter was not either CTL_CERT_SUBJECT_TYPE or CTL_ANY_SUBJECT_TYPE.
NTE_BAD_ALGID
The CTL's SubjectAlgorithm member did not map to either SHA1 or MD5.

Remarks

The certificate's hash or the SubjectIdentifier member of the CTL_ANY_SUBJECT_INFO structure is used as the key in searching the subject entries. A binary memory comparison is done between the key and the entry's SubjectIdentifier.

Requirements

   
Minimum supported client Windows XP [desktop apps | UWP apps]
Minimum supported server Windows Server 2003 [desktop apps | UWP apps]
Target Platform Windows
Header wincrypt.h
Library Crypt32.lib
DLL Crypt32.dll

See Also

CERT_CONTEXT

CTL_ANY_SUBJECT_INFO

CTL_CONTEXT

CertFindCTLInStore

Certificate and Certificate Store Maintenance Functions