CertFindSubjectInCTL function (wincrypt.h)
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(
[in] DWORD dwEncodingType,
[in] DWORD dwSubjectType,
[in] void *pvSubject,
[in] PCCTL_CONTEXT pCtlContext,
[in] DWORD dwFlags
);
Parameters
[in] 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.
[in] dwSubjectType
Specifies the type of subject to be searched for in the CTL. May be NULL for a default search.
| Value | Meaning |
|---|---|
|
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. |
|
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.
[in] pvSubject
Pointer used in conjunction with the dwSubjectType parameter.
[in] pCtlContext
A pointer to the CTL_CONTEXT structure being searched.
[in] 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 |
|---|---|
|
The subject was not found in the CTL. |
|
The dwSubjectType parameter was not either CTL_CERT_SUBJECT_TYPE or CTL_ANY_SUBJECT_TYPE. |
|
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
| Requirement | Value |
|---|---|
| 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 |