CertFindSubjectInCTL

The CertFindSubjectInCTL function attempts to find the specified subject in the CTL. A subject can be identified by either its certificate context or any unique identifier such as its SHA1 hash.

#include <wincrypt.h>
PCTL_ENTRY WINAPI CertFindSubjectInCTL(
  DWORD dwEncodingType,       // in
  DWORD dwSubjectType,        // in
  void *pvSubject,            // in
  PCCTL_CONTEXT pCtlContext,  // in
  DWORD dwFlags               // in
);

Parameters

dwEncodingType

The type of encoding used. Note that either a certificate or message encoding type is required. If the low-order word containing the certificate encoding type is nonzero, then it is used. Otherwise, the high-order word containing the message encoding type is used. If both are specified, the certificate encoding type in the low-order word is used.

Currently defined encoding types are shown in the following table:

Encoding type Value

CRYPT_ASN_ENCODING 0x00000001

X509_ASN_ENCODING 0x00000001

PKCS_7_ASN_ENCODING 0x00010000

dwSubjectType

Encoding type	Value
CRYPT_ASN_ENCODING	0x00000001
X509_ASN_ENCODING	0x00000001
PKCS_7_ASN_ENCODING	0x00010000

For CTL_CERT_SUBJECT_TYPE, pvSubject points to a CERT_CONTEXT. The CTL's SubjectAlgorithm is examined to determine the representation of the subject's identity. Initially, only SHA1 or MD5 hash will be supported. The appropriate hash property is obtained from the CERT_CONTEXT.

For CTL_ANY_SUBJECT_TYPE, pvSubject points to the CTL_ANY_SUBJECT_INFO structure which contains the SubjectAlgorithm to be matched in the CTL and the SubjectIdentifer to be matched in one of the CTL entries.

The dwEncodingType isn't used for either of the above values for dwSubjectType.

pvSubject

Depends on the dwSubjectType . See dwSubjectType for details.

pCtlContext

A pointer to the CTL_CONTEXT that is being searched.

dwFlags

The flag values. dwFlags currently does not have any defined flags and must be set to zero for future compatibility.

Return Values

Returns the entry, if it is found. If it is not found, it returns NULL.

Call GetLastError to see the reason for any failures. This function has the following error codes.

Error code	Description
CRYPT_E_NOT_FOUND	Subject not found in CTL.
E-INVALIDARG	The dwSubjectType wasn't either CTL_CERT_SUBJECT_TYPE or CTL_ANY_SUBJECT_TYPE.
NTE_BAD_ALGID	The CTL's SubjectAlgorithm member didn't map to either SHA1 or MD5.

Remarks

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

Example

// EXAMPLE CODE FOR USING CertFindSubjectInCTL. Finds
// the subject in the CTL. The subject can be identified
// by its certificate context or unique identifier.
// Assume a pointer to the CERT_ANY_SUBJECT_INFO and a
// pointer to the CTL_CONTEXT is already known.

// Set up the variables.
DWORD dwEncodingType = X509_ASN_ENCODING;   // Type of encoding
DWORD dwSubjectType = CTL_ANY_SUBJECT_TYPE; // Subject type
CTL_ANY_SUBJECT_INFO *pvSubject;            // Initialized elsewhere
PCCTL_CONTEXT pCtlContext;                  // Initialized elsewhere
DWORD dwFlags = 0;                          // Flag value
PCTL_ENTRY pResult;                         // Pointer to the returned
                                            // subject

pResult = CertFindSubjectInCTL(
            dwEncodingType, // in - dwEncoding Type isn't used for
                            //   for this dwSubjectType 
            dwSubjectType,  // in - CTL_ANY_SUBJECT_TYPE
            pvSubject,      // in - points to CTL_ANY_SUBJECT_INFO
            pCtlContext,    // in - points to CTL_CONTEXT to be
                            //   searched
            dwFlags);       // in - dwFlags set to 0

if (!pResult) {             // NULL- no entry found
  cout<< "no entry found "<< endl
      << "error code = "<< GetLastError ()<< endl;
}
else {
  cout<< "entry is "<< &pResult<< endl;
}

QuickInfo