CertVerifyCTLUsage

The CertVerifyCTLUsage function verifies that a subject is trusted for a specified usage by finding a signed and time valid CTL with the usage identifiers that contains the subject. A subject can be identified by either its certificate context or any identifier such as its SHA1 hash.

#include <wincrypt.h>
BOOL WINAPI CertVerifyCTLUsage(
  DWORD dwEncodingType,                        // in
  DWORD dwSubjectType,                         // in
  void* pvSubject,                             // in
  PCTL_USAGE pSubjectUsage,                    // in
  DWORD dwFlags,                               // in
  PCTL_VERIFY_USAGE_PARA pVerifyUsagePara,     // in, optional
  PCTL_VERIFY_USAGE_STATUS pVerifyUsageStatus  // in/out
);

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

See dwSubjectType in CertFindSubjectInCTL for definition.

pvSubject

See pvSubject in CertFindSubjectInCTL for definition.

pSubjectUsage

A pointer to a CTL_USAGE structure. It is used to specify the intended usage of the subject.

dwFlags

If the CERT_VERIFY_INHIBIT_CTL_UPDATE_FLAG isn't set, then a time invalid CTL in one of the stores specified by rghCtlStore in CTL_VERIFY_USAGE_PARA may be replaced. When replaced, the CERT_VERIFY_UPDATED_CTL_FLAG is set in pVerifyUsageStatus->dwFlags. If this flag is set, then even if a time valid updated CTL is received for a CTL that is currently time invalid in the store, an update will not be made.

If the CERT_VERIFY_TRUSTED_SIGNERS_FLAG is set, then, only the signer stores specified by rghSignerStore in CTL_VERIFY_USAGE_PARA are searched to find the signer. Otherwise, the signer stores provide additional sources to find the signer's certificate. See the Remarks for further details.

If CERT_VERIFY_NO_TIME_CHECK_FLAG is set, then, the CTLs aren't checked for time validity. Otherwise, they are.

If CERT_VERIFY_ALLOW_MORE_USAGE_FLAG is set, then, the CTL may contain additional usage identifiers than specified by pSubjectUsage. Otherwise, the found CTL will contain the same usage identifiers and no additional ones.

pVerifyUsagePara

With pVerifyUsagePara, the caller can specify the stores to be searched to find the CTL. The caller can also specify the stores containing acceptable CTL signers. By setting the ListIdentifier, the caller can also be limited to a particular signer CTL list.

pVerifyUsageStatus

Only the cbSize member of the CTL_VERIFY_USAGE_STATUS needs to be set for this parameter when CertVerifyCTLUsage is called. However, all unused fields must be zeroed. See CTL_VERIFY_USAGE_STATUS for additional details.

Return Values

If the subject is trusted for the specified usage, then, TRUE is returned. Otherwise, FALSE is returned with dwError set to one of the following:

CRYPT_E_NO_VERIFY_USAGE_DLL

CRYPT_E_NO_VERIFY_USAGE_CHECK

CRYPT_E_VERIFY_USAGE_OFFLINE

CRYPT_E_NOT_IN_CTL

CRYPT_E_NO_TRUSTED_SIGNER

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

Error code	Description
CRYPT_E_NO_VERIFY_ USAGE_DLL	No Dll or exported function was found to verify subject usage.
CRYPT_E_NO_VERIFY_ USAGE_CHECK	The called function wasn't able to do a usage check on the subject.
CRYPT_E_VERIFY_ USAGE_OFFLINE	Since the server was offline, the called function wasn't able to complete the usage check.
CRYPT_E_NOT_IN_CTL	The subject wasn't found in a Certificate Trust List (CTL).
CRYPT_E_NO_TRUSTED_ SIGNER	No trusted signer was found to verify the signature of the message or trust list.

Remarks

CertVerifyCTLUsage will be implemented as a dispatcher to OID installable functions. First, it will try to find an OID function matching the first usage object identifier in the pSubjectUsage sequence. Next, it will dispatch to the default CertDllVerifyCTLUsage functions.

Microsoft has implemented an OID installable CertDllVerifyCTLUsage function residing in the cryptnet.dll with the following properties:

If CTL stores are specified by rghCtlStore in pVerifyUsagePara, then, only those stores are searched to find a CTL. Otherwise, the "Trust" system store is searched to find a CTL.
If CERT_VERIFY_TRUSTED_SIGNERS_FLAG is set, then, only the signer stores specified by rghSignerStore in pVerifyUsagePara are searched to find the certificate corresponding to the signer's issuer and serial number. Otherwise, the CTL message's store, signer stores specified by rghSignerStore in pVerifyUsagePara, "Trust" system store, "CA" system store, "ROOT" and "SPC" system stores are searched to find the signer's certificate. In either case, the public key in the found certificate is used to verify the CTL's signature.
If the CTL has a NextUpdate and CERT_VERIFY_NO_TIME_CHECK isn't set, then it's verified for time validity.
If the CTL obtained from the store is time invalid, then, an attempt is made to get a time valid version. Uses either the CTL's NextUpdateLocation property or CTL's NextUpdateLocation extension or searches the signer's information for a NextUpdateLocation attribute.

Example

// EXAMPLE CODE FOR USING CertVerifyCTLUsage().
// Verifies that a subject is trusted.
// Assume that the application has pointers to
// CERT_CONTEXT (pvSubject), PCTL_USAGE (pSubjectUsage),
// PCTL_VERIFY_USAGE_PARA (pVerifyUsagePara), and
// PCTL_VERIFY_USAGE_STATUS (pVerifyUsageStatus).

// Set up the variables.
DWORD dwEncodingType = X509_ASN_ENCODING;
                         // Type of encoding
DWORD dwSubjectType = CTL_CERT_SUBJECT_TYPE;
                         // CERT_CONTEXT or CTL_ANY_SUBJECT_INFO
CERT_CONTEXT* pvSubject; // Initialized elsewhere
PCTL_USAGE pSubjectUsage;// Initialized elsewhere
DWORD dwFlags = 0;       // The flag values
PCTL_VERIFY_USAGE_PARA pVerifyUsagePara;
                         // Initialized elsewhere
PCTL_VERIFY_USAGE_STATUS pVerifyUsageStatus;
                         // Initialized elsewhere
BOOL fResult;            // Return True if subject is trusted
                         //   FALSE otherwise
fResult= CertVerifyCTLUsage(
           dwEncodingType,     // in - CRYPT_ASN_ENCODING
           dwSubjectType,      // in
           pvSubject,          // in
           pSubjectUsage,      // in - Specify the store to be
                               //   searched
           dwFlags,            // in - Set to 0
           pVerifyUsagePara,   // in - optional
           pVerifyUsageStatus);// in/out

if (!fResult) {                // FALSE
 cout<< "Subject is not trusted"<< endl
     << "dwError = "<< pVerifyUsageStatus->dwError<< endl
     << "error code = "<< GetLastError ()<< endl;
}
else {                         // TRUE
 cout<< "Subject is trusted"<< endl;
}

QuickInfo