CertVerifyCTLUsage function (wincrypt.h)
The CertVerifyCTLUsage function verifies that a subject is trusted for a specified usage by finding a signed and time-valid certificate trust list (CTL) with the usage identifiers that contain the subject. A certificate's subject can be identified by either its certificate context or any unique identifier such as the SHA1 hash of the subject's certificate.
Syntax
BOOL CertVerifyCTLUsage(
[in] DWORD dwEncodingType,
[in] DWORD dwSubjectType,
[in] void *pvSubject,
[in] PCTL_USAGE pSubjectUsage,
[in] DWORD dwFlags,
[in, optional] PCTL_VERIFY_USAGE_PARA pVerifyUsagePara,
[in, out] PCTL_VERIFY_USAGE_STATUS pVerifyUsageStatus
);
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 can be added in the future. For either current encoding type, use
X509_ASN_ENCODING | PKCS_7_ASN_ENCODING.
[in] dwSubjectType
If the dwSubjectType parameter is set to CTL_CERT_SUBJECT_TYPE, pvSubject points to a CERT_CONTEXT structure. The structure's SubjectAlgorithm member 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.
If the dwSubjectType parameter is set to CTL_ANY_SUBJECT_TYPE, pvSubject points to the 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.
If dwSubjectType is set to either preceding value, dwEncodingType is not used.
[in] pvSubject
Value used in conjunction with the dwSubjectType parameter.
[in] pSubjectUsage
A pointer to a CTL_USAGE structure used to specify the intended usage of the subject.
[in] dwFlags
If the CERT_VERIFY_INHIBIT_CTL_UPDATE_FLAG is not set, a CTL whose time is no longer valid in one of the stores specified by rghCtlStore in CTL_VERIFY_USAGE_PARA can be replaced. When replaced, the CERT_VERIFY_UPDATED_CTL_FLAG is set in the dwFlags member of pVerifyUsageStatus. If this flag is set, an update will not be made, even if a time-valid, updated CTL is received for a CTL that is in the store and whose time is no longer valid.
If the CERT_VERIFY_TRUSTED_SIGNERS_FLAG is set, 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. For more information, see Remarks.
If CERT_VERIFY_NO_TIME_CHECK_FLAG is set, the CTLs are not checked for time validity. Otherwise, they are.
If CERT_VERIFY_ALLOW_MORE_USAGE_FLAG is set, the CTL can contain usage identifiers in addition to those specified by pSubjectUsage. Otherwise, the found CTL will contain no additional usage identifiers.
[in, optional] pVerifyUsagePara
A pointer to a CTL_VERIFY_USAGE_PARA structure that specifies the stores to be searched to find the CTL and the stores that contain acceptable CTL signers. Setting the ListIdentifier member further limits the search.
[in, out] pVerifyUsageStatus
A pointer to a CTL_VERIFY_USAGE_STATUS structure. The cbSize member of the structure must to be set to the size, in bytes, of the structure, and all other fields must be set to zero before CertVerifyCTLUsage is called. For more information, see CTL_VERIFY_USAGE_STATUS.
Return value
If the subject is trusted for the specified usage, TRUE is returned. Otherwise, FALSE is returned. GetLastError can return one of the following error codes.
| Value | Description |
|---|---|
|
No DLL or exported function was found to verify subject usage. |
|
The called function was not able to do a usage check on the subject. |
|
The server was offline; therefore, the called function could not complete the usage check. |
|
The subject was not found in a CTL. |
|
No trusted signer was found to verify the signature of the message or trust list. |
The dwError member of the CTL_VERIFY_USAGE_PARA pointed to by pVerifyUsageStatus is set to the same error code.
Remarks
CertVerifyCTLUsage is a dispatcher to functions that can be installed by using an object identifier (OID). First, it tries to find an OID function that matches the first usage object identifier in the CLT_USAGE structure pointed to by pSubjectUsage. If this fails, it uses the default CertDllVerifyCTLUsage functions.
The CertDllVerifyCTLUsage function in Cryptnet.dll can be installed by using an OID; it has the following properties:
- If CTL stores are specified by rghCtlStore in pVerifyUsagePara, 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, only the signer stores specified by rghSignerStore in pVerifyUsagePara are searched to find the certificate that corresponds to the signer's issuer and serial number. Otherwise, the CTL message's store, the signer stores specified by rghSignerStore in pVerifyUsagePara, the Trust system store, CA system store, ROOT, and Software Publisher Certificate (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 signature of the CTL.
- If the CTL has a set NextUpdate member and CERT_VERIFY_NO_TIME_CHECK is not set, it is verified for time validity.
- If the CTL obtained from the store has a time that is not valid, an attempt is made to get a time-valid version. The CertDllVerifyCTLUsage function uses the NextUpdateLocation property or the NextUpdateLocation extension of the CTL, or it searches the signer's information for a NextUpdateLocation attribute.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP [desktop apps only] |
| Minimum supported server | Windows Server 2003 [desktop apps only] |
| Target Platform | Windows |
| Header | wincrypt.h |
| Library | Crypt32.lib |
| DLL | Crypt32.dll |
See also
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for