CryptGetTimeValidObject

[This is preliminary documentation and subject to change.]

The CryptGetTimeValidObject function gets the object whose validity period covers the specified time values.

The object (CTL, CRL, or certificate) is returned via the ppvObject parameter.

#include <wincrypt.h>
BOOL WINAPI CryptGetTimeValidObject(
  LPCSTR pszTimeValidOid,          // in
  LPVOID pvPara,                   // in
  PCCERT_CONTEXT pIssuer,          // in
  LPFILETIME pftValidFor,          // in/optional
  DWORD dwFlags,                   // in
  DWORD dwTimeout,                 // in
  LPVOID* ppvObject,               // out/optional
  PCRYPT_CREDENTIALS pCredentials, // in/optional
  LPVOID pvReserved                // in/optional
);
 

Parameters

pszTimeValidOid

Pointer to the object identifier defining the pvPara context type. If the HIWORD of the pszTimeValidOid parameter is zero, the LOWORD specifies the integer identifier for the type of the given structure. Otherwise, this parameter is a long pointer to a null-terminated string.

OIDs extend the functionality of the CryptoAPI. See OID Overview for additional information.

The following table lists currently supported OIDs:

OID	Meaning
TIME_VALID_OID_ GET_CTL	Gets the next time valid CTL.
TIME_VALID_OID_ GET_CRL	Gets the next time valid CRL.
TIME_VALID_OID_ GET_CRL_FROM_CERT	Gets the next time valid CRL from the certificate.

pvPara

If the pvPara is not correct for the pszTimeValidOid, program behavior is unspecified.

If the pszTimeValidOid is TIME_VALID_OID_GET_CTL;

pvPara is a PCCTL_CONTEXT. The pointer is to the current CTL.

If the pszTimeValidOid is TIME_VALID_OID_GET_CRL;

pvPara is a PCCRL_CONTEXT. The pointer is to the current CRL.

If the pszTimeValidOid is TIME_VALID_OID_GET_CRL_FROM_CERT;

pvPara is a PCCCERT_CONTEXT. The pointer is to the certificate.

pIssuer

Pointer to an issuer context.

pftValidFor

Pointer to a valid time for the object to be verified. If set to NULL the current time is used.

dwFlags

Flag values. This parameter is reserved for future use and should always be set to zero.

dwTimeout

Specifies the maximum number of milliseconds to wait for retrieval. If a value of zero is specified, this function will not time-out. This value is used in synchronous retrieval only.

ppvObject

Address of pointer variable of the returned object. The return type can be one of the supported types, shown in pszTimeValidOid. The valid times of the object are stored in the FILETIME structure of the CTL_INFO, CRL_INFO, or CERT_INFO pointed to by ppvObject. The context will be freed by calling CertFreeCTLContext, CertFreeCRLContext, or CertFreeCertificateContext.

pCredentials

Pointer to the Credentials structure when accessing the URL. The only type of credentials currently supported are username and password credentials. pCredentials is used only when the object is being retrieved from the wire. Do not use pCredentials when using cache only retrieval (set pCredentials to NULL). If the URL scheme is file, pCredentials is not used.

pvReserved

This parameter is reserved for future use and must be NULL.

Return Values

If the function succeeds, the return value is TRUE. If it does not succeed, the return value is FALSE. To retrieve extended error information, use the GetLastError function.

Remarks

TimeValidDllGetObject has the same signature as CryptGetTimeValidObject. The developer can implement a TimeValidDllGetObject with the signature of CryptGetTimeValidObject and install it for the OID.

Example

// EXAMPLE CODE FOR USING CryptGetTimeValidObject().
// Assume that pointers to a CRL context (pvPara) and the
// certificate issuer (pIssuer) are already known.

// Set up the variables.
LPCSTR pszTimeValidOid;   // Pointer to a time Valid OID
PCCRL_CONTEXT pvPara;     // Pointer to a PCCRL_CONTEXT to get the
                          //   time valid object- a PCCRL_CONTEXT
                          //   because the OID is a CRL.
PCCERT_CONTEXT pIssuer;   // Pointer to a certificate's issuer
LPFILETIME pftValidFor;   // Pointer to the FILETIME structure
DWORD dwFlags;            // Flag values- future use- set to 0
DWORD dwTimeout;          // Time out value (set to 0)-
                          //   Not used in Windows NT 5.0 Beta
PCCRL_CONTEXT* ppvObject;        // Pointer to address of the object
PCRYPT_CREDENTIALS pCredentials;
                          // Pointer to the Credentials structure
LPVOID pvReserved;        // Reserved for future use- set to NULL
BOOL fResult;             // Return value- True if function successful
                          //   False if function fails

// call to CryptGetTimeValidObject to get the
//   ThisUpdate and NextUpdate time.
fResult= CryptGetTimeValidObject(
           TIME_VALID_OID_GET_CRL,
                           // in- pszTimeValidOid
           (LPVOID)pvPara, // in- Initialized elsewhere
           pIssuer,        // in- Initialized elsewhere
           NULL,           // in/optional- pftValidFor set to NULL,
                           //   use current time.
           0,              // in- dwFlags- set to 0
           0,              // in- timeout value- set to 0
           (LPVOID*)ppvObject,
                           // out/optional-
           NULL,           // in/optional-pCredentials set to NULL,
                           //   using cache only
           NULL);          // in/optional- Reserved- set to NULL

if (fResult){              // returned value is TRUE
                           //   CryptGetTimeValidObject is successful
  cout<< "Call to CryptGetTimeValidObject successful"<< endl
      << "Pointer to the address (ppvObject) = "<< ppvObject<< endl
      << "ThisUpdate = "<< (*ppvObject)->
            pCrlInfo->ThisUpdate.dwLowDateTime<< endl
      << "NextUpdate = "<< (*ppvObject)->
            pCrlInfo->NextUpdate.dwLowDateTime<< endl<< endl;
 }
else {                     // returned value is FALSE
  cout<< "Call to CryptGetTimeValidObject failed"<< endl
      << "error code = "<< GetLastError<< endl;
}
// free memory
CertFreeCRLContext (*ppvObject);

QuickInfo

  Windows NT: Requires version 5.0 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in wincrypt.h.
  Import Library: Use cryptnet.lib.

See Also

CryptFlushTimeValidObject