Deprecated functions

This appendix provides information about the deprecated API functions and specifications.

Although the deprecated functions and structures listed in this appendix are operational, they do not support the use of SHA-384 or SHA-512. The hash value size in these structures is limited to 40 bytes, which is not sufficient to support SHA-384 or SHA-512.

TTI_EncodeTSQ

This function has been replaced by TTI_EncodeTSQ_Ex. See TTI_EncodeTSQ_Ex for more information. Uses the information in a TTI_TSQ structure to create an encoded time-stamp request.

    int TTI_EncodeTSQ(
        const TTI_TSQ *        pTSQ,
        byte *                 encodedReq,
        size_t *               encodedReqLen,
        TTI_TransportFormat    transportFormat;

Parameters

pTSQ

[in] Points to a populated TTI_TSQ structure. The information in this structure is used to create the encoded time-stamp request.

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 are not supported at this time.

Remarks

This function creates an encoded time-stamp request that includes the information supplied in the TTI_TSQ 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

This function has been replaced by TTI_DecodeTSQ_Ex. See TTI_DecodeTSQ_Ex for more information. Decodes an encoded time-stamp request and writes the information into a TTI_TSQ structure.

    int TTI_DecodeTSQ(
        TTI_TSQ *       pTSQ,
        const byte *    encodedReq,
        size_t          encodedReqLen );

Parameters

pTSQ

[out] Points to a TTI_TSQ structure that receives information from the encoded time-stamp request.

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 encodedReq 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. It is potentially useful if the original TTI_TSQ structure that was used to create the encoded request is not available.

TTI_GetTST_TSTInfo

This function has been replaced by TTI_GetTST_TSTInfoEx. See TTI_GetTST_TSTInfoEx for more information. Decodes an encoded time-stamp token and writes the encapsulated TSTInfo data into a TTI_TSTInfo structure.

    int TTI_GetTST_TSTInfo(
        TTI_TSTInfo *    pTSTInfo,
        const byte *     encodedToken,
        size_t           encodedTokenLen );

Parameters

pTSTInfo

[out] Points to a TTI_TSTInfo structure that receives information from the encoded time-stamp token.

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_TSTInfo structure.

TTI_GetTAC_CertInfo

This function has been replaced by TTI_GetTAC_CertInfoEx. See TTI_GetTAC_CertInfoEx for more information. Decodes an encoded Time Attribute certificate and writes the encapsulated certificate data into a TTI_TAC_CertInfo structure.

    int TTI_GetTAC_CertInfo(
        TTI_TAC_CertInfo *    pTAC,
        const byte *          certBuf,
        size_t                certBufLen );

Parameters

pTAC

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

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.

TTI_GetTAC_TimingMetrics

This function has been replaced by TTI_GetTAC_TimingMetricsEx. See TTI_GetTAC_TimingMetricsEx for more information. Decodes an encoded Time Attribute certificate and writes the encapsulated TimingMetrics attribute data into a TTI_TimingMetrics structure.

    int TTI_GetTAC_TimingMetrics(
        TTI_TimingMetrics *    pTimingMetrics,
        const byte *           certBuf,
        size_t                 certBufLen );

Parameters

pTimingMetrics

[out] Points to a TTI_TimingMetrics 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_GetTST_TSACert

This function has been replaced by TTI_GetTST_TSACertEx. See TTI_GetTST_TSACertEx for more information. Retrieves the encoded TSA certificate from an encoded time-stamp token.

    int TTI_GetTST_TSACert(
        byte *        certBuf,
        size_t *      certBufLen,
        const byte *  encodedToken,
        size_t        encodedTokenLen );

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.

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.

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 signing 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. By default, this function verifies the signing certificate against the first SHA-2 hash in the ESSCertIDv2 list before the function returns. The ESSCertIDv2 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. If the TTI_VERIFY_ESSCERTIDV2 environment variable is set to 0, the function will instead carry out the comparable checks against the first SHA-1 hash in the ESSCertID list. Checking ESSCertIDv2 rather than ESSCertID will succeed only if the TSA is configured to include ESSCertIDv2 in the certificate as per RFC 5816.

TTI_GetTST_TimeAttributeCert

This function has been replaced by TTI_GetTST_TimeAttributeCertEx. See TTI_GetTST_TimeAttributeCertEx for more information. Retrieves the encoded Time Attribute certificate from an encoded time-stamp token.

    int TTI_GetTST_TimeAttributeCert(
        byte *          certBuf,
        size_t *        certBufLen,
        const byte *    encodedToken,
        size_t          encodedTokenLen );

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 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.

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.

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 timestamp token was issued under the Time Attribute certificate before the function returns. By default, this verification is done by checking the ESSCertIDv2 list of SHA-2 hashes for the SHA-2 hash of the Time Attribute certificate. 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 SHA-2 hash of the Time Attribute certificate in the ESSCertIDv2. The ESSCertIDv2 is protected by the signature of the time-stamp token. If the TTI_VERIFY_ESSCERTIDV2 environment variable is set to 0, the function will instead carry out the comparable operations using SHA-1, checking the ESSCertID list of SHA-1 hashes for the SHA-1 hash of the Time Attribute certificate. Checking ESSCertIDv2 rather than ESSCertID will succeed only if the TSA is configured to include ESSCertIDv2 in the certificate as per RFC 5816.

TTI_CheckTAC_MatchesTST

This function has been replaced by TTI_CheckTAC_MatchesTSTEx. See TTI_CheckTAC_MatchesTSTEx for more information. Verifies that the time-stamp token was issued under the Time Attribute certificate.

    int TTI_CheckTAC_MatchesTST(
        const byte *    certBuf,
        size_t          certBufLen,
        const byte *    encodedToken,
        size_t          encodedTokenLen );

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.

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.

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. By default, this verification is done by checking the ESSCertIDv2 list of SHA-2 hashes for the SHA-2 hash of the Time Attribute certificate. The cryptographic binding of a time-stamp to a Time Attribute certificate is accomplished by including the SHA-2 hash of the Time Attribute certificate in the ESSCertIDv2. The ESSCertIDv2 is protected by the signature on the time-stamp token. If the TTI_VERIFY_ESSCERTIDV2 environment variable is set to 0, the function will instead carry out the comparable checks against SHA-1 hashes in the ESSCertID list. Checking ESSCertIDv2 rather than ESSCertID will succeed only if the TSA is configured to include ESSCertIDv2 in the certificate as per RFC 5816.

TTI_VerifyTST_Signature

This function has been replaced by TTI_VerifyTST_SignatureEx. See TTI_VerifyTST_SignatureEx for more information. Verifies the signature on an encoded time-stamp token.

    int TTI_VerifyTST_Signature(
        const byte *    encodedToken,
        size_t          encodedTokenLen,
        const byte *    tsaCert,
        size_t          tsaCertLen );

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.

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.

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 signing 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. By default, the function achieves this by verifying the signing certificate against the first SHA-2 hash in the ESSCertIDv2 list before the function returns. If the TTI_VERIFY_ESSCERTIDV2 environment variable is set to 0, the function will instead carry out the comparable checks against the first SHA-1 hash in the ESSCertID list. Checking ESSCertIDv2 rather than ESSCertID will succeed only if the TSA is configured to include ESSCertIDv2 in the certificate as per RFC 5816.