CryptGetTimeValidObject function (wincrypt.h)
The CryptGetTimeValidObject function retrieves a CRL, an OCSP response, or CTL object that is valid within a given context and time.
Syntax
BOOL CryptGetTimeValidObject(
[in] LPCSTR pszTimeValidOid,
[in] LPVOID pvPara,
[in] PCCERT_CONTEXT pIssuer,
[in, optional] LPFILETIME pftValidFor,
[in] DWORD dwFlags,
[in] DWORD dwTimeout,
[out, optional] LPVOID *ppvObject,
[in, optional] PCRYPT_CREDENTIALS pCredentials,
[in, out, optional] PCRYPT_GET_TIME_VALID_OBJECT_EXTRA_INFO pExtraInfo
);
Parameters
[in] pszTimeValidOid
A pointer to an object identifier (OID) that identifies the object being requested. If the HIWORD of the pszTimeValidOid parameter is zero, the LOWORD specifies the integer identifier for the type of the specified structure.
This parameter can be one of the following values. For information about how these values affect the pvPara parameter, see the heading "For the pvPara parameter" in the Meaning column.
| Value | Meaning |
|---|---|
|
Provides a certificate trust list (CTL) based on a URL obtained from the NextUpdateLocation property or extension of the current CTL context.
For the pvPara parameter: A pointer to a PCCTL_CONTEXT that represents the current certificate trust list. |
|
This value is reserved for future use. |
|
Provides a CRL based on information obtained from the CRL distribution points extension of the current certificate context.
For the pvPara parameter: A pointer to a PCCERT_CONTEXT that represents the subject certificate. |
|
Provides a delta CRL based on information obtained from the freshest CRL extension of the current certificate context.
For the pvPara parameter: A pointer to a PCCERT_CONTEXT that represents the subject certificate. |
|
Provides a delta CRL based on information obtained from the freshest CRL extension of the current CRL context.
For the pvPara parameter: A pointer to a PCCERT_CRL_CONTEXT_PAIR that represents the subject certificate and its base CRL. |
[in] pvPara
A structure determined by the value of pszTimeValidOid. For details, see the description for the pszTimeValidOid parameter.
[in] pIssuer
A pointer to a CERT_CONTEXT containing the issuer's certificate.
[in, optional] pftValidFor
A pointer to an optional FILETIME structure version of the current system time or a freshness time from the current context.
[in] dwFlags
A value that determines various retrieval factors such as time-out, source, and validity checks.
The following table lists possible values for the dwFlags parameter.
| Value | Meaning |
|---|---|
|
Use the cumulative time-out registry setting of the client computer for revocation URL retrievals. |
|
Retrieve the encoded bits from the client URL cache only. Do not use the wire to retrieve the URL. |
|
Check if the ThisUpdate property or extension of the current context is greater than or equal to the ftValidFor parameter. |
|
Do not perform time validity check. Use this to retrieve a more recent base CRL over the wire or to bypass time validity check during a cache retrieval. When this flag is set, pftValidFor can be NULL. |
|
Do not perform signature verification. Use this when verification of the retrieved object will be performed outside of this function or to force a replacement of a retrieved cache entry with a new cache entry for the object. |
|
This value is reserved for future use. |
|
Retrieves the time valid object from an OCSP responder service only based on Authority Information Access URLs in the current context. The CertVerifyRevocation function sets this flag when it is called with the dwFlags parameter set to CERT_VERIFY_REV_SERVER_OCSP_FLAG. |
|
Retrieves the encoded bits from the wire only. Does not use the URL cache. |
[in] dwTimeout
A value, in milliseconds, that specifies when to terminate an URL retrieval attempt that has not returned a result.
[out, optional] ppvObject
A pointer to an address for the returned object. The return type can be one of the supported types shown in the pszObjectOid parameter of the CryptRetrieveObjectByUrl function.
[in, optional] pCredentials
A pointer to an optional CRYPT_CREDENTIALS structure used to access the URL. The only type of credentials currently supported are user name and password credentials.
[in, out, optional] pExtraInfo
A pointer to an optional CRYPT_GET_TIME_VALID_OBJECT_EXTRA_INFO structure that contains extra information about the cache entry for an object.
Return value
If the function succeeds, the function returns TRUE.
If the function fails, it returns FALSE. For extended error information, call GetLastError.
Some possible error codes follow.
| Return code | Description |
|---|---|
|
The caller specified TIME_VALID_OID_GET_CRL for the pszTimeValidOid parameter. This OID is not supported. |
|
The caller set the CRYPT_OCSP_ONLY_RETRIEVAL flag and the context includes a non-OCSP URL. |
|
The function failed to retrieve a CRL from a certificate context or retrieve a CTL, and it failed to copy any URLs from a cache entry. |
|
The function could not allocate memory for an internal array operation. |
|
The caller did not set the CRYPT_CACHE_ONLY_RETRIEVAL flag and is not connected to the Internet. |
Remarks
The Cryptnet dynamic link library implements a time valid object (TVO) cache that is used to support the CryptGetTimeValidObject function. The cache is used by a process-global TVO agent where each cache entry consists of the following information.
- Origin Identifier
- Context OID
- Context
- Retrieval URL
- Expire Time
- Offline URL Time Information
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista [desktop apps only] |
| Minimum supported server | Windows Server 2008 [desktop apps only] |
| Target Platform | Windows |
| Header | wincrypt.h |
| Library | Cryptnet.lib |
| DLL | Cryptnet.dll |
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