Edit

CryptRetrieveTimeStamp function (wincrypt.h)

  • Article

The CryptRetrieveTimeStamp function encodes a time stamp request and retrieves the time stamp token from a location specified by a URL to a Time Stamping Authority (TSA).

Syntax

BOOL CryptRetrieveTimeStamp(
  [in]            LPCWSTR                    wszUrl,
                  DWORD                      dwRetrievalFlags,
                  DWORD                      dwTimeout,
  [in]            LPCSTR                     pszHashId,
  [in, optional]  const CRYPT_TIMESTAMP_PARA *pPara,
  [in]            const BYTE                 *pbData,
                  DWORD                      cbData,
  [out]           PCRYPT_TIMESTAMP_CONTEXT   *ppTsContext,
  [out, optional] PCCERT_CONTEXT             *ppTsSigner,
  [out, optional] HCERTSTORE                 *phStore
);

Parameters

[in] wszUrl

A pointer to a null-terminated wide character string that contains the URL of the TSA to which to send the request.

dwRetrievalFlags

A set of flags that specify how the time stamp is retrieved.

Value Meaning
TIMESTAMP_DONT_HASH_DATA
0x00000001
 Inhibit hash calculation on the array of bytes pointed to by the pbData parameter.
TIMESTAMP_VERIFY_CONTEXT_SIGNATURE
0x00000020
 Enforce signature validation on the retrieved time stamp.
Note  The TIMESTAMP_VERIFY_CONTEXT_SIGNATURE flag is valid only if the fRequestCerts member of the CRYPT_TIMESTAMP_PARA pointed to by the pPara parameter is set to TRUE.
 
TIMESTAMP_NO_AUTH_RETRIEVAL
0x00020000
Set this flag to inhibit automatic authentication handling.

dwTimeout

A DWORD value that specifies the maximum number of milliseconds to wait for retrieval. If this parameter is set to zero, this function does not time out.

[in] pszHashId

A pointer to a null-terminated character string that contains the hash algorithm object identifier (OID).

[in, optional] pPara

A pointer to a CRYPT_TIMESTAMP_PARA structure that contains additional parameters for the request.

[in] pbData

A pointer to an array of bytes to be time stamped.

cbData

The size, in bytes, of the array pointed to by the pbData parameter.

[out] ppTsContext

A pointer to a PCRYPT_TIMESTAMP_CONTEXT structure. When you have finished using the context, you must free it by calling the CryptMemFree function.

[out, optional] ppTsSigner

A pointer to a PCERT_CONTEXT that receives the certificate of the signer. When you have finished using this structure, you must free it by passing this pointer to the CertFreeCertificateContext function.

Set this parameter to NULL if the TSA signer's certificate is not needed.

[out, optional] phStore

The handle of a certificate store initialized with certificates from the time stamp response. This store can be used for validating the signer certificate of the time stamp response.

This parameter can be NULL if the TSA supporting certificates are not needed. When you have finished using this handle, release it by passing it to the CertCloseStore function.

Return value

If the function is unable to retrieve, decode, and validate the time stamp context, it returns FALSE. For extended error information, call the GetLastError function.

Requirements

Requirement Value
Minimum supported client Windows 7 [desktop apps | UWP apps]
Minimum supported server Windows Server 2008 R2 [desktop apps | UWP apps]
Target Platform Windows
Header wincrypt.h
DLL Crypt32.dll

See also

CryptVerifyTimeStampSignature