Edit

Share via

CryptGetTimeValidObject function (wincrypt.h)

  • Article

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
TIME_VALID_OID_GET_CTL
((LPCSTR)1)
 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.
TIME_VALID_OID_GET_CRL
 This value is reserved for future use.
TIME_VALID_OID_GET_CRL_FROM_CERT
((LPCSTR)3)
 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.
TIME_VALID_OID_GET_FRESHEST_CRL_FROM_CERT
((LPCSTR)4)
 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.
TIME_VALID_OID_GET_FRESHEST_CRL_FROM_CRL
((LPCSTR)5)
 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
CRYPT_ACCUMULATIVE_TIMEOUT
0x00000800
 Use the cumulative time-out registry setting of the client computer for revocation URL retrievals.
CRYPT_CACHE_ONLY_RETRIEVAL
0x00000002
 Retrieve the encoded bits from the client URL cache only. Do not use the wire to retrieve the URL.
CRYPT_CHECK_FRESHNESS_TIME_VALIDITY
0x00000400
 Check if the ThisUpdate property or extension of the current context is greater than or equal to the ftValidFor parameter.
CRYPT_DONT_CHECK_TIME_VALIDITY
0x00000200
 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.
CRYPT_DONT_VERIFY_SIGNATURE
0x00000100
 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.
CRYPT_KEEP_TIME_VALID
0x00000080
 This value is reserved for future use.
CRYPT_OCSP_ONLY_RETRIEVAL
0x01000000
 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.
CRYPT_WIRE_ONLY_RETRIEVAL
0x00000004
 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
CRYPT_E_NOT_FOUND
 The caller specified TIME_VALID_OID_GET_CRL for the pszTimeValidOid parameter. This OID is not supported.
CRYPT_E_NOT_IN_REVOCATION_DATABASE
 The caller set the CRYPT_OCSP_ONLY_RETRIEVAL flag and the context includes a non-OCSP URL.
E_INVALIDARG
 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.
E_OUTOFMEMORY
 The function could not allocate memory for an internal array operation.
ERROR_NOT_CONNECTED
 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
The TVO agent supports retrieval of TVO objects on-demand or by auto-update.

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