C language API functions and specifications

This section describes the API functions and specifications.

The C language API is currently provided in Windows and Linux versions.

Functional overview

The SDK can be used to obtain a time-stamp from a TSS with four basic steps:

Create an encoded request
Submit the request to the TSS
Decode the result
Verify the integrity of the time-stamp

To obtain a time-stamp from a TSS:

Using the TTI_SHA* functions, generate a digest of the data to be time-stamped.
Generate a nonce for the request. A nonce is a large random number that protects the request against replay attacks.
Populate a time-stamp request structure, TTI_TSQ_Ex, with the digest, nonce, and other relevant information.
Call TTI_EncodeTSQ_Ex to create an ASN.1 encoded version of the request.
Submit the encoded request to a TSS. The request will usually be submitted via a TCP/IP connection.
Unpack the response returned by the TSS by calling TTI_UnpackTSR. This will verify and remove the transport specific headers from the response.
Call TTI_GetTSR_Status to verify the response successfully produced a time-stamp token.
Call TTI_GetTSR_EncodedToken to get the time-stamp token from the response. This produces an encoded time-stamp token.

The encoded time-stamp token is a PKCS #7 SignedData object and the signature can be verified with any cryptographic toolkit that supports PKCS #7.

The TTI_VerifyTST_SignatureEx function can also be used to verify the time-stamp signature.
Verify the time-stamp token signature. Use TTI_VerifyTST_SignatureEx or a cryptographic toolkit that supports PKCS #7.
Call TTI_GetTST_TSTInfoEx to populate a TTI_TSTInfoEx structure with the contents of the time-stamp token.
Verify that:
- The value in the time-stamp token (TST) matches the values in the timestamp request (TSQ).
- The message imprint matches.
- The nonce matches.
- If the request included a specific policy identifier, this should match.
- The time contained in the time-stamp is reasonably close to the current system time (only perform this check if you can trust the system time to be relatively accurate).

Functions and specifications

The following sections document the API functions and their specifications.

API functions

The following sections explain the API specifications.

TTI_EncodeTSQ_Ex

Uses the information in a TTI_TSQ_Ex structure to create an encoded time-stamp request.

    int TTI_EncodeTSQ_Ex(
        const TTI_TSQ_Ex *    pTSQ,
        byte *                encodedReq,
        size_t *              encodedReqLen,
        TTI_TransportFormat   transportFormat  );

Parameters

pTSQ

[in] Points to a populated TTI_TSQ_Ex structure. The information in this structure is used to create the encoded time-stamp request. The TTI_TSQ_Ex structure supports nonce and serial numbers up to 40 bytes.

encodedReq

[out] Points to a buffer to receive the encoded time-stamp request.

encodedReqLen

[in/out] Points to a value specifying the size, in bytes, of the encodedReq buffer. When the function returns, this value contains the size, in bytes, of the encoded time-stamp request.

transportFormat

[in] A flag indicating which type of additional transport encoding should be included in the request.

Currently defined format types are:

TTI_RAW

Returns the encoded time-stamp request with no headers and no special encoding.

TTI_TCP

Returns the encoded time-stamp request prepended with a five-byte TCP header.

TTI_HTTP

Returns the time-stamp request encoded as an HTTP encoded request.

TTI_SMTP

Reserved for future use.

Return values

If this function succeeds, the return value is zero (TTI_SUCCESS).

If this function fails, the return value is a nonzero error code.

TTI_INVALID_PARAMETER

pTSQ and encodedReqLen must not be NULL.

transportFormat must be a valid TTI_TransportFormat value.

TTI_BUFFER_TOO_SMALL

The size indicated by encodedReqLen is too small. When the function returns, the required size is returned in the value pointed to by encodedReqLen.

TTI_TSR_ASN_ERROR

An unexpected ASN error occurred. To get the ASN error code, call TTI_GetLastAsnError.

TTI_NOT_SUPPORTED

TTI_SMTP is not supported at this time.

Remarks

This function creates an encoded time-stamp request that includes the information supplied in the TTI_TSQ_Ex structure. The request is formatted according to version one of the PKIX Time-Stamp protocol. This function will also encode the request for a particular transport mechanism. At this time, two transport format options are supported: TTI_RAW and TTI_TCP. TTI_RAW returns the encoded time-stamp request with no headers and no special encoding. TTI_TCP returns the request with a five-byte TCP header prepended. This header includes the size of the request and a flag byte set to zero (tsaMsg).

When this function is used with the transportFormat set to TTI_TCP, the resulting encoded time-stamp request may be submitted directly to a TSS via a TCP socket connected to port 318 of the server.

TTI_DecodeTSQ_Ex

Decodes an encoded time-stamp request and writes the information into a TTI_TSQ_Ex structure.

    int TTI_DecodeTSQ_Ex(
        TTI_TSQ_Ex *    pTSQ,
        const byte *    encodedReq,
        size_t          encodedReqLen  );

Parameters

pTSQ

[out] Points to a TTI_TSQ_Ex structure that receives information from the encoded time-stamp request. The TTI_TSQ_Ex structure supports nonce and serial numbers up to 40 bytes.

encodedReq

[in] Points to a buffer that contains an encoded time-stamp request.

encodedReqLen

[in] Specifies the size, in bytes, of the encoded time-stamp request.

Return values

If this function succeeds, the return value is zero (TTI_SUCCESS).

If this function fails, the return value is a nonzero error code.

TTI_INVALID_PARAMETER

pTSQ and encodedReqLen must not be NULL.

TTI_ASN_ERROR

Received unexpected results from an ASN function.

TTI_TSR_ASN_ERROR

An unexpected ASN error occurred. To get the ASN error code, call TTI_GetLastAsnError.

Remarks

This function can be used to decode a time-stamp request that was encoded with TTI_EncodeTSQ_Ex. It is potentially useful if the original TTI_TSQ_Ex structure that was used to create the encoded request is not available.

TTI_UnpackTSR

Converts a transport-specific response into a raw time-stamp response by removing transport-specific headers.

    int TTI_UnpackTSR(
        byte *              encodedResp,
        size_t *            encodedRespLen,
        int *               responseCode,
        TTI_TransportFormat transportFormat );

Parameters

encodedResp

[in/out] Points to a buffer that contains a transport-specific response. When the function returns, this buffer will contain a raw time-stamp response.

encodedRespLen

[in/out] Points to a value specifying the size, in bytes, of the transport-specific response. When the function returns, this value contains the size, in bytes, of the raw time-stamp response.

responseCode

[out] Points to an integer to receive the response code from a TTI_TCP response.

transportFormat

[in] The transport mechanism that produced this response.

Currently defined format types are:

TTI_RAW

Encoded time-stamp response with no headers and no special encoding.

TTI_TCP

Encoded time-stamp response prepended with a five-byte TCP header.

TTI_HTTP

Encoded time-stamp response with HTTP response headers.

TTI_SMTP

Reserved for future use.

Return values

If this function succeeds, the return value is zero (TTI_SUCCESS).

If this function fails, the return value is a nonzero error code.

TTI_INVALID_PARAMETER

encodedResp, encodedRespLen, and responseCode must not be NULL. transportFormat must be a valid TTI_TransportFormat value.

TTI_RESPONSE_SIZE_MISMATCH

The size from the TCP header did not match the actual size of the response. The expect size from the TCP header is returned in the value pointed to by encodedRespLen.

TTI_TSA_UNEXPECTED_RESPONSE

The response flag in the TCP header contained an unexpected value. The only expect value is 5 (finalMsgRep). The actual value is returned in the value pointed to by responseCode.

TTI_NOT_SUPPORTED

TTI_SMTP is not supported at this time.

Remarks

This function removes the header and special encoding that is added to a time-stamp response by the transport mechanism. The transport format options supported are:

TTI_RAW (only supported for completeness)
TTI_TCP.

If the format is TTI_RAW, this function simply returns TTI_SUCCESS without doing any processing because none is needed. If the format is TTI_TCP, this function will verify and remove the TCP header from the time-stamp response.

TTI_GetTSR_Status

Decodes a time-stamp response and writes the information into a TTI_PKIStatusInfo structure.

    int TTI_GetTSR_Status(
        TTI_PKIStatusInfo *   pPKIStatusInfo,
        const byte *          encodedResp,
        size_t                encodedRespLen  );

Parameters

pPKIStatusInfo

[out] Points to a TTI_PKIStatusInfo that receives information from the encoded time-stamp response.

encodedResp

[in] Points to a buffer that contains an encoded time-stamp response.

encodedRespLen

[in] Specifies the size, in bytes, of the encoded time-stamp response.

Return values

If this function succeeds, the return value is zero (TTI_SUCCESS).

If this function fails, the return value is a nonzero error code.

TTI_INVALID_PARAMETER

pPKIStatusInfo and encodedResp must not be NULL.

TTI_ASN_ERROR

Received unexpected results from an ASN function.

TTI_TSR_ASN_ERROR

An unexpected ASN error occurred. To get the ASN error code, call TTI_GetLastAsnError.

Remarks

This function retrieves the status information from a time-stamp response. This status information indicates whether a time-stamp token was issued in the response. If a timestamp token was not issued, the status information indicates the reason for the failure.

TTI_GetTSR_EncodedToken

Retrieves the encoded time-stamp token from an encoded time-stamp response.

    int TTI_GetTSR_EncodedToken(
        byte *          tokenBuf,
        size_t *        tokenBufLen,
        const byte *    encodedResp,
        size_t          encodedRespLen  );

Parameters

tokenBuf

[out] Points to a buffer that receives the encoded time-stamp token.

tokenBufLen

[in/out] Points to a value specifying the size, in bytes, of the tokenBufbuffer. When the function returns, this value contains the size, in bytes, of the encoded time-stamp token.

encodedResp

[in] Points to a buffer that contains an encoded time-stamp response.

encodedRespLen

[in] Specifies the size, in bytes, of the encoded time-stamp response.

Return values

If this function succeeds, the return value is zero (TTI_SUCCESS).

If this function fails, the return value is a nonzero error code.

TTI_INVALID_PARAMETER

encodedResp and tokenBufLen must not be NULL.

TTI_BUFFER_TOO_SMALL

The size indicated by tokenBufLen is too small. When the function returns, the required size is returned in the value pointed to by tokenBufLen.

TTI_ASN_ERROR

Received unexpected results from an ASN function.

TTI_TSR_ASN_ERROR

An unexpected ASN error occurred. To get the ASN error code, call TTI_GetLastAsnError.

TTI_INVALID_RESPONSE_STATUS

The time-stamp response status was not PKIS_granted or PKIS_grantedWithMods. This indicates that the timestamp response was a failure response, therefore there is no time-stamp token in the response.

TTI_NO_TOKEN_PRESENT

No token was present in the response. This is an unexpected situation and indicates corrupt data.

Remarks

A time-stamp response is what a TSS returns for a request. The response contains status information indicating what kind of response this is. If the status information indicates PKIS_granted or PKIS_grantedWithMods, the time-stamp response will also contain a time-stamp token. This function copies the time-stamp token into the supplied buffer. The time-stamp token is a Cryptographic Message Syntax SignedData object (see RFC 3369 [CMS2], RFC 3852 [CMS] and RFC 2315 [PKCS #7]). The time-stamp token represents the data that should be stored for future reference. This is the time-stamp.

TTI_GetTST_TSTInfoEx

Decodes an encoded time-stamp token and writes the encapsulated TSTInfo data into a TTI_TSTInfoEx structure.

    int TTI_GetTST_TSTInfoEx(
        TTI_TSTInfoEx *    pTSTInfo,
        const byte *       encodedToken,
        size_t             encodedTokenLen );

Parameters

pTSTInfo

[out] Points to a TTI_TSTInfoEx structure that receives information from the encoded time-stamp token. The TTI_TSTInfoEx structure supports nonce and serial numbers up to 40 bytes.

encodedToken

[in] Points to a buffer that contains an encoded time-stamp token.

encodedTokenLen

[in] Specifies the size, in bytes, of the encoded time-stamp token.

Return values

If this function succeeds, the return value is zero (TTI_SUCCESS).

If this function fails, the return value is a nonzero error code.

TTI_INVALID_PARAMETER

encodedResp and tokenBufLen must not be NULL.

TTI_ASN_ERROR

Received unexpected results from an ASN function.

TTI_TSR_ASN_ERROR

An unexpected ASN error occurred. To get the ASN error code, call TTI_GetLastAsnError.

Remarks

This is the core data of a time-stamp token. The TSTInfo is part of the signed data of the time-stamp token and therefore is protected against modification. This function reads and decodes this portion of the time-stamp token and writes the information into a TTI_TSTInfoEx structure.

TTI_GetTST_TSACertEx

Retrieves the encoded TSA certificate from an encoded time-stamp token.

    int TTI_GetTST_TSACertEx(
        byte *                 certBuf,
        size_t *               certBufLen,
        const byte *           encodedToken,
        size_t                 encodedTokenLen,
        TTI_VerificationModes  verifyModes,
        TTI_SigningCert_Kind * signingCertKind );

Parameters

certBuf

[out] Points to a buffer that receives the encoded TSA certificate.

certBufLen

[in/out] Points to a value specifying the size, in bytes, of the certBuf buffer. When the function returns, this value contains the size, in bytes, of the encoded TSA certificate.

encodedToken

[in] Points to a buffer that contains an encoded time-stamp token.

encodedTokenLen

[in] Specifies the size, in bytes, of the encoded time-stamp token.

verifyModes

[in] A bitmask identifying how to verify the signing certificate (see below).

signingCertKind

[out] On success, points to a value identifying how the signing certificate was verified (see below).

The supported values for verifyModes are:

TTI_VerifyMode_ESSCertID

Checks the first SHA-1 hash in the ESSCertID list.

TTI_VerifyMode_ESSCertIDv2

Checks the first SHA-2 hash in the ESSCertIDv2 list.

TTI_VerifyMode_ESSCertID | TTI_VerifyMode_ESSCertIDv2

Checks the first SHA-2 hash in the ESSCertIDv2 list. If no SHA-2 hashes are present, checks the first SHA-1 hash in the ESSCertID list.

The supported values for signingCertKind are:

TTI_Verified_SigningCert_ESSCertID

The signing certificate was verified using the SHA-1 hash in the ESSCertID list.

TTI_Verified_SigningCert_ESSCertIDv2

The signing certificate was verified using the SHA-2 hash in the ESSCertIDv2 list.

Return values

If this function succeeds, the return value is zero (TTI_SUCCESS).

If this function fails, the return value is a nonzero error code.

TTI_INVALID_PARAMETER

encodedToken and certBufLen must not be NULL, and verifyModes must be a supported combination of TTI_VerificationModes values.

TTI_BUFFER_TOO_SMALL

The size indicated by certBufLen is too small. When the function returns, the required size is returned in the value pointed to by certBufLen.

TTI_INVALID_TST

The content of the encodedToken buffer is not recognized as a valid encoded time-stamp token.

TTI_NO_TSACERT_PRESENT

The encoded time-stamp token did not contain the signing certificate. A time-stamp token will only contain the signing certificate if the time-stamp request specified that the certificate be included.

TTI_ESSCERTID_FAILED

The hash of the Time Attribute certificate did not match a value stored in the signed attributes of the time-stamp token.

Remarks

If the encoded time-stamp token contains the signing certificate, this function copies the encoded signing certificate into the supplied buffer. This function does not validate the signature on the time-stamp token. This function verifies the signing certificate based on the verifyModes bitmask described above. The ESSCertID provides cryptographic binding of the time-stamp token to a particular identity certificate, whereas the signature only binds the time-stamp token to the public key. Checking ESSCertIDv2 rather than ESSCertID will succeed only if the TSS is configured to include ESSCertIDv2 in the certificate as per RFC 5816.

TTI_GetTST_TimeAttributeCertEx

Retrieves the encoded Time Attribute Certificate from an encoded time-stamp token.

    int TTI_GetTST_TimeAttributeCertEx(
        byte *                 certBuf,
        size_t *               certBufLen,
        const byte *           encodedToken,
        size_t                 encodedTokenLen,
        TTI_VerificationModes  verifyModes,
        TTI_SigningCert_Kind * signingCertKind );

Parameters

certBuf

[out] Points to a buffer that receives the encoded Time Attribute Certificate.

certBufLen

[in/out] Points to a value specifying the size, in bytes, of the certBuf buffer. When the function returns, this value contains the size, in bytes, of the encoded Time Attribute Certificate.

encodedToken

[in] Points to a buffer that contains an encoded time-stamp token.

encodedTokenLen

[in] Specifies the size, in bytes, of the encoded time-stamp token.

verifyModes

[in] A bitmask identifying how to verify the Time Attribute Certificate (see below).

signingCertKind

[out] On success, points to a value identifying how the Time Attribute Certificate was verified (see below).

The supported values for verifyModes are:

TTI_VerifyMode_ESSCertID

Checks the SHA-1 hashes in the ESSCertID list.

TTI_VerifyMode_ESSCertIDv2

Checks the SHA-2 hashes in the ESSCertIDv2 list.

TTI_VerifyMode_ESSCertID | TTI_VerifyMode_ESSCertIDv2

Checks the SHA-2 hashes in the ESSCertIDv2 list. If no SHA-2 hashes are present, checks the SHA-1 hashes in the ESSCertID list.

The supported values for signingCertKind are:

TTI_Verified_SigningCert_None

The Time Attribute Certificate was not verified against any hash in either of the ESSCertID or ESSCertIDv2 lists.

TTI_Verified_SigningCert_ESSCertID

The Time Attribute Certificate was verified using the SHA-1 hash in the ESSCertID list.

TTI_Verified_SigningCert_ESSCertIDv2

The Time Attribute Certificate was verified using the SHA-2 hash in the ESSCertIDv2 list.

Return values

If this function succeeds, the return value is zero (TTI_SUCCESS).

If this function fails, the return value is a nonzero error code.

TTI_INVALID_PARAMETER

encodedToken and certBufLen must not be NULL, and verifyModes must be a supported combination of TTI_VerificationModes values.

TTI_BUFFER_TOO_SMALL

The size indicated by certBufLen is too small. When the function returns, the required size is returned in the value pointed to by certBufLen.

TTI_INVALID_TST

The content of the encodedToken buffer is not recognized as a valid encoded time-stamp token.

TTI_NO_TAC_PRESENT

The encoded time-stamp token did not contain the Time Attribute certificate. A time-stamp token will only contain the Time Attribute certificate if the time-stamp request specified that the certificate be included.

TTI_ESSCERTID_FAILED

The hash of the Time Attribute certificate did not match a value stored in the signed attributes of the time-stamp token.

Remarks

If the encoded time-stamp token contains the Time Attribute Certificate, this function copies the encoded TAC into the supplied buffer. This function verifies that the time-stamp token was issued under the Time Attribute Certificate before the function returns. This function verifies the Time Attribute Certificate based on the verifyModes bitmask described above. If the Time Attribute Certificate in the encoded time-stamp token is embedded within the set of SignerAttributes and not the certificate list, the TAC will not be verified using ESSCertID or ESSCertIDv2 hashes. This will be indicated by the value TTI_Verified_SigningCert_None being set in signingCertKind. This check is necessary because the certificate list in a time-stamp token is not protected by the signature. The cryptographic binding of a time-stamp to a Time Attribute Certificate is accomplished by including the appropriate hash of the Time Attribute Certificate in ESSCertID or ESSCertIDv2. Both ESSCertID and ESSCertIDv2 are protected by the signature of the time-stamp token. Checking ESSCertIDv2 rather than ESSCertID will succeed only if the TSS is configured to include ESSCertIDv2 in the certificate as per RFC 5816.

TTI_GetTAC_TimingMetricsEx

Decodes an encoded Time Attribute certificate and writes the encapsulated TimingMetrics attribute data into a TTI_TimingMetricsEx structure.

    int TTI_GetTAC_TimingMetricsEx(
        TTI_TimingMetricsEx *    pTimingMetrics,
        const byte *             certBuf,
        size_t                   certBufLen );

Parameters

pTimingMetrics

[out] Points to a TTI_TimingMetricsEx structure that receives information from the encoded Time Attribute certificate.

certBuf

[in] Points to a buffer that contains an encoded Time Attribute certificate.

certBufLen

[in] Specifies the size, in bytes, of the encoded Time Attribute certificate.

Return values

If this function succeeds, the return value is zero (TTI_SUCCESS).

If this function fails, the return value is a nonzero error code.

TTI_INVALID_PARAMETER

pTimingMetrics and certBuf must not be NULL.

TTI_ASN_ERROR

Received unexpected results from an ASN function.

TTI_TSR_ASN_ERROR

An unexpected ASN error occurred. To get the ASN error code, call TTI_GetLastAsnError.

TTI_GetTAC_TimingPolicy

Decodes an encoded Time Attribute certificate and writes the encapsulated TimingPolicy attribute data into a TTI_TimingPolicy structure.

    int TTI_GetTAC_TimingPolicy(
        TTI_TimingPolicy *    pTimingPolicy,
        const byte *          certBuf,
        size_t                certBufLen );

Parameters

pTimingPolicy

[out] Points to a TTI_TimingPolicy structure that receives information from the encoded Time Attribute certificate.

certBuf

[in] Points to a buffer that contains an encoded Time Attribute certificate.

certBufLen

[in] Specifies the size, in bytes, of the encoded Time Attribute certificate.

Return values

If this function succeeds, the return value is zero (TTI_SUCCESS).

If this function fails, the return value is a nonzero error code.

TTI_NO_TAC_TIMINGPOLICY_PRESENT

The Time Attribute Certificate does not contain Timing Policy information.

TTI_INVALID_PARAMETER

pTimingPolicy and certBuf must not be NULL.

TTI_ASN_ERROR

Received unexpected results from an ASN function.

TTI_TSR_ASN_ERROR

An unexpected ASN error occurred. To get the ASN error code, call TTI_GetLastAsnError.

TTI_CheckTAC_MatchesTSTEx

Verifies that the time-stamp token was issued under the Time Attribute certificate.

    int TTI_CheckTAC_MatchesTSTEx(
        const byte *           certBuf,
        size_t                 certBufLen,
        const byte *           encodedToken,
        size_t                 encodedTokenLen,
        TTI_VerificationModes  verifyModes,
        TTI_SigningCert_Kind * signingCertKind );

Parameters

certBuf

[in] Points to a buffer that contains an encoded Time Attribute certificate.

certBufLen

[in] Specifies the size, in bytes, of the encoded Time Attribute certificate.

encodedToken

[in] Points to a buffer that contains an encoded time-stamp token.

encodedTokenLen

[in] Specifies the size, in bytes, of the encoded time-stamp token.

verifyModes

[in] A bitmask identifying how to verify the Time Attribute Certificate (see below).

signingCertKind

[out] On success, points to a value identifying how the Time Attribute Certificate was verified (see below).

The supported values for verifyModes are:

TTI_VerifyMode_ESSCertID

Checks the SHA-1 hashes in the ESSCertID list.

TTI_VerifyMode_ESSCertIDv2

Checks the SHA-2 hashes in the ESSCertIDv2 list.

TTI_VerifyMode_ESSCertID | TTI_VerifyMode_ESSCertIDv2

Checks the SHA-2 hashes in the ESSCertIDv2 list. If no SHA-2 hashes are present, checks the SHA-1 hashes in the ESSCertID list.

The supported values for signingCertKind are:

TTI_Verified_SigningCert_None

The Time Attribute Certificate was not verified against any hash in either of the ESSCertID or ESSCertIDv2 lists.

TTI_Verified_SigningCert_ESSCertID

The Time Attribute Certificate was verified using the SHA-1 hash in the ESSCertID list.

TTI_Verified_SigningCert_ESSCertIDv2

The Time Attribute Certificate was verified using the SHA-2 hash in the ESSCertIDv2 list.

Return values

If this function succeeds, the return value is zero (TTI_SUCCESS).

If this function fails, the return value is a nonzero error code.

TTI_INVALID_PARAMETER

certBuf and encodedToken must not be NULL, and verifyModes must be a supported combination of TTI_VerificationModes values.

TTI_ASN_ERROR

Received unexpected results from an ASN function.

TTI_TSR_ASN_ERROR

An unexpected ASN error occurred. To get the ASN error code, call TTI_GetLastAsnError.

TTI_ESSCERTID_FAILED

The hash of the Time Attribute certificate did not match a value stored in the signed attributes of the time-stamp token.

Remarks

This function verifies that the time-stamp token was issued under the Time Attribute certificate. This function is especially useful when the time-stamp token does not contain a Time Attribute certificate and the user wants to verify that the time-stamp token was issued under a TAC that the user retrieved from a previous time-stamp or some other mechanism. This verification is done based on the verifyModes bitmask described above. If the Time Attribute Certificate in the encoded time-stamp token is embedded within the set of SignerAttributes and not the certificate list, the TAC will not be verified using ESSCertID or ESSCertIDv2 hashes. This will be indicated by the value TTI_Verified_SigningCert_None being set in signingCertKind. The cryptographic binding of a time-stamp to a Time Attribute certificate is accomplished by including the appropriate hash of the Time Attribute certificate in ESSCertID or ESSCertIDv2. Both ESSCertID and ESSCertIDv2 are protected by the signature of the time-stamp token. Checking ESSCertIDv2 rather than ESSCertID will succeed only if the TSS is configured to include ESSCertIDv2 in the certificate as per RFC 5816.

TTI_GetTAC_CertInfoEx

Decodes an encoded Time Attribute certificate and writes the encapsulated certificate data into a TTI_TAC_CertInfoEx structure.

    int TTI_GetTAC_CertInfoEx(
        TTI_TAC_CertInfoEx *    pTAC,
        const byte *            certBuf,
        size_t                  certBufLen );

Parameters

pTAC

[out] Points to a TTI_TAC_CertInfoEx structure that receives information from the encoded Time Attribute certificate. The TTI_TAC_CertInfoEx structure supports nonce and serial numbers up to 40 bytes.

certBuf

[in] Points to a buffer than contains an encoded Time Attribute certificate.

certBufLen

[in] Specifies the size, in bytes, of the encoded Time Attribute certificate.

Return values

If this function succeeds, the return value is zero (TTI_SUCCESS).

If this function fails, the return value is a nonzero error code.

TTI_INVALID_PARAMETER

pTimingMetrics and certBuf must not be NULL.

TTI_ASN_ERROR

Received unexpected results from an ASN function.

TTI_TSR_ASN_ERROR

An unexpected ASN error occurred. To get the ASN error code, call TTI_GetLastAsnError.

Signature validation function

The following section explains the signature validation function.

TTI_VerifyTST_SignatureEx

Verifies the signature on an encoded time-stamp token.

    int TTI_VerifyTST_SignatureEx(
        const byte *           encodedToken,
        size_t                 encodedTokenLen,
        const byte *           tsaCert,
        size_t                 tsaCertLen,
        TTI_VerificationModes  verifyModes,
        TTI_SigningCert_Kind * signingCertKind );

Parameters

encodedToken

[in] Points to a buffer that contains an encoded time-stamp token.

encodedTokenLen

[in] Specifies the size, in bytes, of encoded time-stamp token.

tsaCert

[in, optional] Points to a buffer that contains the TSA certificate that signed this token. If this parameter is NULL, this function attempts to verify the signature with a certificate included in the time-stamp token.

tsaCertLen

[in] Specifies the size, in bytes, of the encoded certificate.

verifyModes

[in] A bitmask identifying how to verify the signing certificate (see below).

signingCertKind

[out] On success, points to a value identifying how the signing certificate was verified (see below).

The supported values for verifyModes are:

TTI_VerifyMode_ESSCertID

Checks the first SHA-1 hash in the ESSCertID list.

TTI_VerifyMode_ESSCertIDv2

Checks the first SHA-2 hash in the ESSCertIDv2 list.

TTI_VerifyMode_ESSCertID | TTI_VerifyMode_ESSCertIDv2

Checks the first SHA-2 hash in the ESSCertIDv2 list. If no SHA-2 hashes are present, checks the first SHA-1 hash in the ESSCertID list.

The supported values for signingCertKind are:

TTI_Verified_SigningCert_ESSCertID

The signing certificate was verified using the SHA-1 hash in the ESSCertID list.

TTI_Verified_SigningCert_ESSCertIDv2

The signing certificate was verified using the SHA-2 hash in the ESSCertIDv2 list.

Return values

If this function succeeds, the return value is zero (TTI_SUCCESS).

If this function fails, the return value is a nonzero error code.

TTI_INVALID_PARAMETER

encodedToken is not allowed to be NULL and verifyModes must be a supported combination of TTI_VerificationModes values..

TTI_INVALID_TST

encodedToken did not contain a valid encoded time-stamp token.

TTI_INVALID_SIGNATURE

The time-stamp token signature was not valid.

TTI_NO_TSACERT_PRESENT

The encoded time-stamp token did not contain the signing certificate. A time-stamp token contains the signing certificate only if the time-stamp request required that the certificate be included.

TTI_ESSCERTID_FAILED

The hash of the Time Attribute certificate did not match a value stored in the signed attributes of the time-stamp token.

Remarks

This function is provided so that API users can validate the signature of a time-stamp token. However, if you have access to other PKI tools, we recommend you use those to validate the signature. Asking the API to validate its own signature is of limited value. In addition to verifying the signature on the time-stamp token, TTI_VerifyTST_Signature verifies the cryptographic binding of the time-stamp token to a particular identity certificate using either ESSCertID or ESSCertIDv2. The function achieves this using the verifyModes bitmask described above. Checking ESSCertIDv2 rather than ESSCertID will succeed only if the TSS is configured to include ESSCertIDv2 in the certificate as per RFC 5816.

Hash functions

The following sections document hash functions.

TTI_SHA1_Init

Creates a SHA-1 hash object and returns a handle that can be used to access the object.

    TTI_SHA1_HANDLE TTI_SHA1_Init();

Return values

If this function succeeds, the return value is zero (TTI_SUCCESS).

If this function fails, the return value is a nonzero error code.

Remarks

Use the TTI_SHA1_Update function to feed data to the hash object. After a successful call to this function, the returned handle must eventually be released with a call to TTI_SHA1_Final.

TTI_SHA1_Update

Used to feed data to a specified hash object. Before calling this function, the TTI_SHA1_Init function must be called to get a handle to a hash object.

    void TTI_SHA1_Update(
        TTI_SHA1_HANDLE hSHA,
        const void *    pData,
        size_t          cbData );

Parameters

hSHA

[in] Handle of the SHA-1 hash object.

pData

[in] Points to a buffer containing the data to be added to the SHA-1 hash object.

cbData

[in] Number of bytes of data to be added.

Remarks

This function may be called multiple times to compute the hash of long or discontiguous data streams.

TTI_SHA1_Final

Used to retrieve the value from a hash object and to release the hash object.

    void TTI_SHA1_Final(
        TTI_SHA1_HANDLE    hSHA,
        byte *             pbHash );

Parameters

hSHA

[in] Handle of the SHA-1 hash object.

pbHash

[out] Points to a buffer that receives the hash. The buffer must be at least 20 bytes in length.

Remarks

After this function is called, the TTI_SHA1_HANDLE that was passed in becomes invalid. It must not be used for future calls to TTI_SHA1_Update or TTI_SHA1_Final.

TTI_MD5_Init

Creates an MD5 hash object and returns a handle that can be used to access the object.

    TTI_MD5_HANDLE TTI_MD5_Init();

Return values

If this function succeeds, the return value is a nonzero handle. If this function fails, the return value is zero.

Remarks

Use the TTI_MD5_Update function to feed data to the hash object. After a successful call to this function, the returned handle must eventually be released with a call to TTI_MD5_Final.

TTI_MD5_Update

Used to feed data to a specified hash object. Before calling this function, the TTI_MD5_Init function must be called to get a handle to a hash object.

    void TTI_MD5_Update(
        TTI_MD5_HANDLE    hMD5,
        const void *      pData,
        size_t            cbData  );

Parameters

hMD5

[in] Handle of the MD5 hash object.

pData

[in] Points to a buffer containing the data to be added to the MD5 hash object.

cbData

[in] Number of bytes of data to be added.

Remarks

This function may be called multiple times to compute the hash of long or discontiguous data streams.

TTI_MD5_Final

Used to retrieve the value from a hash object and to release the hash object.

    void TTI_MD5_Final(
        TTI_MD5_HANDLE    hMD5,
        byte *            pbHash );

Parameters

hMD5

[in] Handle of the MD5 hash object.

pbHash

[out] Points to a buffer that receives the hash. The buffer must be at least 20 bytes in length.

Remarks

After this function is called, the TTI_MD5_HANDLE that was passed in becomes invalid. It must not be used for future calls to TTI_MD5_Update or TTI_MD5_Final.

TTI_SHA256_Init

Creates an SHA256 hash object and returns a handle that can be used to access the object.

    TTI_SHA256_HANDLE TTI_SHA256_Init();

Return values

If this function succeeds, the return value is a nonzero handle. If this function fails, the return value is zero.

Remarks

Use the TTI_SHA256_Update function to feed data to the hash object. After a successful call to this function, the returned handle must eventually be released with a call to TTI_SHA256_Final.

TTI_SHA256_Update

Used to feed data to a specified hash object. Before calling this function, the TTI_SHA256_Init function must be called to get a handle to a hash object.

    void TTI_SHA256_Update(
        TTI_SHA256_HANDLE    hSHA,
        const void *         pData,
        size_t               cbData  );

Parameters

hSHA

[in] Handle of the SHA hash object.

pData

[in] Points to a buffer containing the data to be added to the SHA hash object.

cbData

[in] Number of bytes of data to be added.

Remarks

This function may be called multiple times to compute the hash of long or discontiguous data streams.

TTI_SHA256_Final

Used to retrieve the value from a hash object and to release the hash object.

    void TTI_SHA256_Final(
        TTI_SHA256_HANDLE    hSHA,
        byte *               pbHash );

Parameters

hSHA

[in] Handle of the SHA hash object.

pbHash

[out] Points to a buffer that receives the hash. The buffer must be at least 20 bytes in length.

Remarks

After this function is called, the TTI_SHA256_HANDLE that was passed in becomes invalid. It must not be used for future calls to TTI_SHA256_Update or TTI_SHA256_Final.

TTI_SHA384_Init

Creates a SHA384 hash object and returns a handle that can be used to access the object.

    TTI_SHA384_HANDLE TTI_SHA384_Init();

Return values

If this function succeeds, the return value is a nonzero handle. If this function fails, the return value is zero.

Remarks

Use the TTI_SHA384_Update function to feed data to the hash object. After a successful call to this function, the returned handle must eventually be released with a call to TTI_SHA384_Final.

TTI_SHA384_Update

Used to feed data to a specified hash object. Before calling this function, the TTI_SHA384_Init function must be called to get a handle to a hash object.

    void TTI_SHA384_Update(
        TTI_SHA384_HANDLE    hSHA,
        const void *         pData,
        size_t               cbData  );

Parameters

hSHA

[in] Handle of the SHA hash object.

pData

[in] Points to a buffer containing the data to be added to the SHA384 hash object.

cbData

[in] Number of bytes of data to be added.

Remarks

This function may be called multiple times to compute the hash of long or discontiguous data streams.

TTI_SHA384_Final

Used to retrieve the value from a hash object and to release the hash object.

    void TTI_SHA384_Final(
        TTI_SHA384_HANDLE    hSHA,
        byte *               pbHash );

Parameters

hSHA

[in] Handle of the SHA hash object.

pbHash

[out] Points to a buffer that receives the hash. The buffer must be at least 20 bytes in length.

Remarks

After this function is called, the TTI_SHA384_HANDLE that was passed in becomes invalid. It must not be used for future calls to TTI_SHA384_Update or TTI_SHA384_Final.

TTI_SHA512_Init

Creates a SHA512 hash object and returns a handle that can be used to access the object.

     TTI_SHA512_HANDLE TTI_SHA512_Init();

Return values

If this function succeeds, the return value is a nonzero handle. If this function fails, the return value is zero.

Remarks

Use the TTI_SHA512_Update function to feed data to the hash object. After a successful call to this function, the returned handle must eventually be released with a call to TTI_SHA512_Final.

TTI_SHA512_Update

Used to feed data to a specified hash object. Before calling this function, the TTI_SHA512_Init function must be called to get a handle to a hash object.

    void TTI_SHA512_Update(
        TTI_SHA512_HANDLE    hSHA,
        const void *         pData,
        size_t               cbData  );

Parameters

hSHA

[in] Handle of the SHA hash object.

pData

[in] Points to a buffer containing the data to be added to the SHA512 hash object.

cbData

[in] Number of bytes of data to be added.

Remarks

This function may be called multiple times to compute the hash of long or discontiguous data streams.

TTI_SHA512_Final

Used to retrieve the value from a hash object and to release the hash object.

    void TTI_SHA512_Final(
        TTI_SHA512_HANDLE    hSHA,
        byte *               pbHash );

Parameters

hSHA

[in] Handle of the SHA hash object.

pbHash

[out] Points to a buffer that receives the hash. The buffer must be at least 20 bytes in length.

Remarks

After this function is called, the TTI_SHA512_HANDLE that was passed in becomes invalid. It must not be used for future calls to TTI_SHA512_Update or TTI_SHA512_Final.

Utility functions

The following sections document the utility functions available.

TTI_GetLastAsnError

Used to retrieve extended ASN error codes. This function should be called after an encoding or decoding function returns TTI_TSR_ASN_ERROR.

    int TTI_GetLastAsnError();

Return values

Returns the last ASN error code that occurred during an encoding or decoding function. This value is set before an encoding or decoding function returns TTI_TSR_ASN_ERROR.

Remarks

There are a large number of error codes that may be returned from this function. These errors usually occur only when an invalid or corrupted buffer is passed to a decode function. Since these errors are unexpected, this document does not contain a complete list of possible values. However, this function provides help with technical support in the case of unexpected errors.

TTI_TSTInfoToIDData

This function will modify the encapsulated content type in a time-stamp token, changing it from id-ct-TSTInfo to id-data.

    int TTI_TSTInfoToIDData(
        const byte *    encodedToken,
        size_t          encodedTokenLen,
        byte *          encodedObjectBuf,
        size_t *        encodedObjectBufLen  );

Parameters

encodedToken

[in] Points to a buffer that contains an encoded time-stamp token.

encodedTokenLen

[in] Specifies the size, in bytes, of the encoded time-stamp token.

encodedObjectBuf

[out] Points to a buffer to receive the modified encoded time-stamp token.

encodedObjectBufLen

[in/out] Points to a value specifying the size, in bytes, of the encodedObjectBuf buffer. When the function returns, this value contains the size, in bytes, of the modified encoded time-stamp token.

Return values

If this function succeeds, the return value is zero (TTI_SUCCESS).

If this function fails, the return value is a nonzero error code.

TTI_INVALID_PARAMETER

pbEncodedToken and pcbEncodedObjectLength must not be NULL.

TTI_BUFFER_TOO_SMALL

The size indicated by encodedObjectBufLen is too small. When the function returns, the required size is returned in the value pointed to by encodedObjectBufLen.

TTI_ASN_ERROR

Received unexpected results from an ASN function.

TTI_TSR_ASN_ERROR

An unexpected ASN error occurred. To get the ASN error code, call TTI_GetLastAsnError.

Remarks

The TSS issues time-stamp tokens that follow the requirements specified in RFC 3161. The encoded time-stamp tokens are CMS SignedData objects with an encapsulated content type of id-ct-TSTInfo.

However, testing has shown that several PKI tool sets cannot handle this embedded content type. Therefore, these tools cannot validate the signature on time-stamp tokens. This TTI_TSTInfoToIDData function provides a temporary solution for using one of these PKI tools. Modifying the encapsulated content type to id-data has no adverse affect on signature validation and allows a time-stamp token signature to be validated by popular tool sets. Now that RFC 3161 exists and the time-stamp protocol is no longer just an Internet Engineering Task Force (IETF) draft, we expect that the popular PKI tool sets will be updated to handle the id-ct-TSTInfo object identifier.

TTI_RemoveAttrCerts

Removes attribute certificates from a time-stamp token.

    int TTI_RemoveAttrCerts(
        const byte *    encodedToken,
        size_t          encodedTokenLen,
        byte *          encodedObjectBuf,
        size_t *        encodedObjectBufLen );

Parameters

encodedToken

[in] Points to a buffer that contains an encoded time-stamp token.

encodedTokenLen

[in] Specifies the size, in bytes, of the encoded time-stamp token.

encodedObjectBuf

[out] Points to a buffer to receive the modified encoded time-stamp token.

encodedObjectBufLen

Return values

If this function succeeds, the return value is zero (TTI_SUCCESS).

If this function fails, the return value is a nonzero error code.

TTI_INVALID_PARAMETER

pbEncodedToken and pcbEncodedObjectLength must not be NULL.

TTI_BUFFER_TOO_SMALL

The size indicated by encodedObjectBufLen is too small. When the function returns, the required size is returned in the value pointed to by encodedObjectBufLen.

TTI_ASN_ERROR

Received unexpected results from an ASN function.

TTI_TSR_ASN_ERROR

An unexpected ASN error occurred. To get the ASN error code, call TTI_GetLastAsnError.

Remarks

If the time-stamp token contains a certificate list, the certificate list will contain at least one attribute certificate, most likely the Time Attribute certificate. Many PKI tool sets cannot handle SignedData objects that contain attribute certificates. Therefore PKI tools cannot validate signatures on time-stamp tokens. The TTI_RemoveAttrCerts function provides a work-around for anyone using one of these PKI tools. Removing the attribute certificates has no adverse affect on signature validation and allows a time-stamp token signature to be validated by popular tool sets.