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 aTTI_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
|
[in] Points to a populated |
|
[out] Points to a buffer to receive the encoded time-stamp request. |
|
[in/out] Points to a value specifying the size, in bytes, of the |
|
[in] A flag indicating which type of additional transport encoding should be included in the request. |
Currently defined format types are:
|
Returns the encoded time-stamp request with no headers and no special encoding. |
|
Returns the encoded time-stamp request prepended with a five-byte TCP header. |
|
Returns the time-stamp request encoded as an HTTP encoded request. |
|
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.
|
|
|
The size indicated by |
|
An unexpected ASN error occurred.
To get the ASN error code, call |
|
|
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
|
[out] Points to a |
|
[in] Points to a buffer that contains an encoded time-stamp request. |
|
[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.
|
|
|
Received unexpected results from an ASN function. |
|
An unexpected ASN error occurred.
To get the ASN error code, call |
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
|
[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. |
|
[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. |
|
[out] Points to an integer to receive the response code from a |
|
[in] The transport mechanism that produced this response. |
Currently defined format types are:
|
Encoded time-stamp response with no headers and no special encoding. |
|
Encoded time-stamp response prepended with a five-byte TCP header. |
|
Encoded time-stamp response with HTTP response headers. |
|
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.
|
|
|
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 |
|
The response flag in the TCP header contained an unexpected value.
The only expect value is 5 ( |
|
|
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
|
[out] Points to a |
|
[in] Points to a buffer that contains an encoded time-stamp response. |
|
[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.
|
|
|
Received unexpected results from an ASN function. |
|
An unexpected ASN error occurred.
To get the ASN error code, call |
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
|
[out] Points to a buffer that receives the encoded time-stamp token. |
|
[in/out] Points to a value specifying the size, in bytes, of the |
|
[in] Points to a buffer that contains an encoded time-stamp response. |
|
[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.
|
|
|
The size indicated by |
|
Received unexpected results from an ASN function. |
|
An unexpected ASN error occurred.
To get the ASN error code, call |
|
The time-stamp response status was not |
|
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
|
[out] Points to a |
|
[in] Points to a buffer that contains an encoded time-stamp token. |
|
[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.
|
|
|
Received unexpected results from an ASN function. |
|
An unexpected ASN error occurred.
To get the ASN error code, call |
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
|
[out] Points to a buffer that receives the encoded TSA certificate. |
|
[in/out] Points to a value specifying the size, in bytes, of the |
|
[in] Points to a buffer that contains an encoded time-stamp token. |
|
[in] Specifies the size, in bytes, of the encoded time-stamp token. |
|
[in] A bitmask identifying how to verify the signing certificate (see below). |
|
[out] On success, points to a value identifying how the signing certificate was verified (see below). |
The supported values for verifyModes
are:
|
Checks the first SHA-1 hash in the ESSCertID list. |
|
Checks the first SHA-2 hash in the ESSCertIDv2 list. |
|
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:
|
The signing certificate was verified using the SHA-1 hash in the ESSCertID list. |
|
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.
|
|
|
The size indicated by |
|
The content of the |
|
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. |
|
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
|
[out] Points to a buffer that receives the encoded Time Attribute Certificate. |
|
[in/out] Points to a value specifying the size, in bytes, of the |
|
[in] Points to a buffer that contains an encoded time-stamp token. |
|
[in] Specifies the size, in bytes, of the encoded time-stamp token. |
|
[in] A bitmask identifying how to verify the Time Attribute Certificate (see below). |
|
[out] On success, points to a value identifying how the Time Attribute Certificate was verified (see below). |
The supported values for verifyModes
are:
|
Checks the SHA-1 hashes in the ESSCertID list. |
|
Checks the SHA-2 hashes in the ESSCertIDv2 list. |
|
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:
|
The Time Attribute Certificate was not verified against any hash in either of the ESSCertID or ESSCertIDv2 lists. |
|
The Time Attribute Certificate was verified using the SHA-1 hash in the ESSCertID list. |
|
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.
|
|
|
The size indicated by |
|
The content of the |
|
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. |
|
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
|
[out] Points to a |
|
[in] Points to a buffer that contains an encoded Time Attribute certificate. |
|
[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.
|
|
|
Received unexpected results from an ASN function. |
|
An unexpected ASN error occurred.
To get the ASN error code, call |
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
|
[out] Points to a |
|
[in] Points to a buffer that contains an encoded Time Attribute certificate. |
|
[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.
|
The Time Attribute Certificate does not contain Timing Policy information. |
|
|
|
Received unexpected results from an ASN function. |
|
An unexpected ASN error occurred.
To get the ASN error code, call |
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
|
[in] Points to a buffer that contains an encoded Time Attribute certificate. |
|
[in] Specifies the size, in bytes, of the encoded Time Attribute certificate. |
|
[in] Points to a buffer that contains an encoded time-stamp token. |
|
[in] Specifies the size, in bytes, of the encoded time-stamp token. |
|
[in] A bitmask identifying how to verify the Time Attribute Certificate (see below). |
|
[out] On success, points to a value identifying how the Time Attribute Certificate was verified (see below). |
The supported values for verifyModes
are:
|
Checks the SHA-1 hashes in the ESSCertID list. |
|
Checks the SHA-2 hashes in the ESSCertIDv2 list. |
|
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:
|
The Time Attribute Certificate was not verified against any hash in either of the ESSCertID or ESSCertIDv2 lists. |
|
The Time Attribute Certificate was verified using the SHA-1 hash in the ESSCertID list. |
|
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.
|
|
|
Received unexpected results from an ASN function. |
|
An unexpected ASN error occurred.
To get the ASN error code, call |
|
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
|
[out] Points to a |
|
[in] Points to a buffer than contains an encoded Time Attribute certificate. |
|
[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.
|
|
|
Received unexpected results from an ASN function. |
|
An unexpected ASN error occurred.
To get the ASN error code, call |
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
|
[in] Points to a buffer that contains an encoded time-stamp token. |
|
[in] Specifies the size, in bytes, of encoded time-stamp token. |
|
[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. |
|
[in] Specifies the size, in bytes, of the encoded certificate. |
|
[in] A bitmask identifying how to verify the signing certificate (see below). |
|
[out] On success, points to a value identifying how the signing certificate was verified (see below). |
The supported values for verifyModes
are:
|
Checks the first SHA-1 hash in the ESSCertID list. |
|
Checks the first SHA-2 hash in the ESSCertIDv2 list. |
|
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:
|
The signing certificate was verified using the SHA-1 hash in the ESSCertID list. |
|
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.
|
|
|
|
|
The time-stamp token signature was not valid. |
|
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. |
|
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
|
[in] Handle of the SHA-1 hash object. |
|
[in] Points to a buffer containing the data to be added to the SHA-1 hash object. |
|
[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
|
[in] Handle of the SHA-1 hash object. |
|
[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
|
[in] Handle of the MD5 hash object. |
|
[in] Points to a buffer containing the data to be added to the MD5 hash object. |
|
[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
|
[in] Handle of the MD5 hash object. |
|
[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
|
[in] Handle of the SHA hash object. |
|
[in] Points to a buffer containing the data to be added to the SHA hash object. |
|
[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
|
[in] Handle of the SHA hash object. |
|
[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
|
[in] Handle of the SHA hash object. |
|
[in] Points to a buffer containing the data to be added to the SHA384 hash object. |
|
[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
|
[in] Handle of the SHA hash object. |
|
[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
|
[in] Handle of the SHA hash object. |
|
[in] Points to a buffer containing the data to be added to the SHA512 hash object. |
|
[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 );
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
|
[in] Points to a buffer that contains an encoded time-stamp token. |
|
[in] Specifies the size, in bytes, of the encoded time-stamp token. |
|
[out] Points to a buffer to receive the modified encoded time-stamp token. |
|
[in/out] Points to a value specifying the size, in bytes, of the |
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.
|
|
|
The size indicated by |
|
Received unexpected results from an ASN function. |
|
An unexpected ASN error occurred.
To get the ASN error code, call |
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
|
[in] Points to a buffer that contains an encoded time-stamp token. |
|
[in] Specifies the size, in bytes, of the encoded time-stamp token. |
|
[out] Points to a buffer to receive the modified encoded time-stamp token. |
|
[in/out] Points to a value specifying the size, in bytes, of the |
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.
|
|
|
The size indicated by |
|
Received unexpected results from an ASN function. |
|
An unexpected ASN error occurred.
To get the ASN error code, call |
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.