com.entrust.toolkit.timestamp

Class TimeStampClient

java.lang.Object

com.entrust.toolkit.timestamp.TimeStampClient

public class TimeStampClient
extends java.lang.Object

The class represents the client side of the Time-Stamp protocol as defined in RFC 3161.

In order to request a time-stamp from the TimeStamp Authority (TSA), a certificate validation mechanism and a time-stamp transport are needed. The time-stamp transport is required to allow communication with the TSA, and the certificate validation mechanism is required to verify/validated information received from the TSA.

In order for the validation of the TSA certificate to be successful, the TSA certificate must be trusted. This means that the certificate verification mechanism must be able to trust the TSA certificate. If the certificate verification mechanism does not already have a trust relationship with the TSA, trust can be established manually, by adding the TSA certificate as a trusted certificate using the CertificateVerifier API getCertificateStore().addTrustedCertificate(X509Certificate).

Since:

7.0

See Also:

RFC 3161

Field Summary

Fields

Modifier and Type	Field and Description
static AlgorithmID	DEFAULT_HASH_ALGORITHM The default hash algorithm used in the time-stamp request.
static java.lang.Boolean	DEFAULT_REQUEST_TSA_CERT Indicates whether by default, the Time Stamp Authority must return their certificate in the time-stamp response.

Constructor Summary

Constructors

Constructor and Description
TimeStampClient(TimeStampTransport timeStampTransport, TimeStampVerifier timeStampVerifier) Creates a new TimeStampClient.

Method Summary

Modifier and Type	Method and Description
AlgorithmID	getHashAlgorithm() Returns the algorithm identifier of hash algorithm that is being used when requesting a time-stamp.
java.lang.Boolean	getRequestTSACert() Returns an indicator for whether the Time Stamp Authority (TSA) must return their certificate in the time-stamp response.
ObjectID	getTSAPolicyId() Returns an identifier for the Time Stamp Authority policy under which the requested time-stamp token SHOULD be provided.
TimeStampToken	requestTimeStampToken(byte[] data) Requests a time-stamp for the data contained in a byte array.
TimeStampToken	requestTimeStampToken(java.io.InputStream data) Requests a time-stamp for the data contained in an input stream.
void	setHashAlgorithm(AlgorithmID hashAlgorithm) Sets the algorithm identifier of hash algorithm that is being used when requesting a time-stamp.
void	setRequestTSACert(java.lang.Boolean requestTsaCert) Set an indicator for whether the TimeStamp Authority (TSA) must return their certificate in the time-stamp response.
void	setTSAPolicyId(ObjectID tsaPolicyId) Set an identifier for the TimeStamp Authority(TSA) policy under which the requested time-stamp token SHOULD be provided.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_HASH_ALGORITHM

public static final AlgorithmID DEFAULT_HASH_ALGORITHM

The default hash algorithm used in the time-stamp request.

DEFAULT_REQUEST_TSA_CERT

public static final java.lang.Boolean DEFAULT_REQUEST_TSA_CERT

Indicates whether by default, the Time Stamp Authority must return their certificate in the time-stamp response.

Constructor Detail

TimeStampClient

public TimeStampClient(TimeStampTransport timeStampTransport,
                       TimeStampVerifier timeStampVerifier)

Creates a new TimeStampClient.

Parameters:

timeStampTransport - the connection for communication with the TimeStamp Authority

timeStampVerifier - the time-stamp verification mechanism; used to verify the time-stamp token received from the Time Stamp Authority

Throws:

java.lang.IllegalArgumentException - thrown if any of the parameters are null

java.lang.SecurityException - thrown if cryptographic algorithms provided by the 'Entrust' provider could not be found

Method Detail

getHashAlgorithm

public AlgorithmID getHashAlgorithm()

Returns the algorithm identifier of hash algorithm that is being used when requesting a time-stamp.

The hash algorithm is used to create a digest of the data for which the time-stamp is being requested. The time-stamp token returned by the Time Stamp Authority will indicate that this hash algorithm has been used to create the time-stamp.

Returns:

the algorithm identifier of the requested hash algorithm

getRequestTSACert

public java.lang.Boolean getRequestTSACert()

Returns an indicator for whether the Time Stamp Authority (TSA) must return their certificate in the time-stamp response.

When set to true the TSA's certificate that was used to create the requested time-stamp token MUST be provided in the response. This guarantees that the response can be verified. Otherwise, the Time Stamp Authority's certificate MUST be manually set in the TimeStampVerifier or already exists as a trusted certificate in CertVerifier it contains.

Returns:

the request Time Stamp Authority certificate indicator

getTSAPolicyId

public ObjectID getTSAPolicyId()

Returns an identifier for the Time Stamp Authority policy under which the requested time-stamp token SHOULD be provided.

Returns:

the Time Stamp Authority policy identifier

setHashAlgorithm

public void setHashAlgorithm(AlgorithmID hashAlgorithm)

Sets the algorithm identifier of hash algorithm that is being used when requesting a time-stamp.

The hash algorithm is used to create a digest of the data for which the time-stamp is being requested. The time-stamp token returned by the Time Stamp Authority will indicate that this hash algorithm has been used to create the time-stamp.

This hash algorithm will be used for all subsequent time-stamp requests. If the algorithm identifier provided is null the has algorithm will revert back to its default value DEFAULT_HASH_ALGORITHM.

Parameters:

hashAlgorithm - the algorithm identifier of the requested hash algorithm (OPTIONAL)

setRequestTSACert

public void setRequestTSACert(java.lang.Boolean requestTsaCert)

Set an indicator for whether the TimeStamp Authority (TSA) must return their certificate in the time-stamp response.

When set to true the TSA's certificate that was used to create the requested time-stamp token MUST be provided in the response. This guarantees that the response can be verified. Otherwise, the TSA's certificate MUST be manually set in the TimeStampVerifier or already exists as a trusted certificate in CertVerifier it contains.

This indicator will be included in all subsequent time-stamp requests. When set to null the indicator will no longer be included in any subsequent time-stamp requests.

Parameters:

requestTsaCert - the request Time Stamp Authority certificate indicator (OPTIONAL)

setTSAPolicyId

public void setTSAPolicyId(ObjectID tsaPolicyId)

Set an identifier for the TimeStamp Authority(TSA) policy under which the requested time-stamp token SHOULD be provided.

This TSA policy identifier will be included in all subsequent time-stamp requests. When set to null the TSA policy identifier will no longer be included in any subsequent time-stamp requests.

Parameters:

tsaPolicyId - the TimeStamp Authority policy identifier (OPTIONAL)

requestTimeStampToken

public TimeStampToken requestTimeStampToken(byte[] data)
                                     throws TimeStampException

Requests a time-stamp for the data contained in a byte array.

This sends/receives a time-stamp request/response using the time-stamp transport. It first ensures that the response received is valid, by checking that the data contained in the TimeStampResp is what was requested. Then, it verifies the signature protection on the response, and validates the signer certificate (TSA certificate).

In order for the validation of the TSA certificate to be successful, the TSA certificate must be trusted. This means that the certificate verification mechanism must be able to trust the TSA certificate. If the certificate verification mechanism does not already have a trust relationship with the TSA, trust can be established manually, by adding the TSA certificate as a trusted certificate using the CertificateVerifier API getCertificateStore().addTrustedCertificate(X509Certificate.

Parameters:

data - the data to be time-stamped

Returns:

the time-stamp token

Throws:

TimeStampException - thrown if an error occurs while requesting/receiving the time-stamp, or there is a problem with the response received

java.lang.IllegalArgumentException - thrown if the parameter is null

requestTimeStampToken

public TimeStampToken requestTimeStampToken(java.io.InputStream data)
                                     throws TimeStampException

Requests a time-stamp for the data contained in an input stream.

This sends/receives a time-stamp request/response using the time-stamp transport. It first ensures that the response received is valid, by checking that the data contained in the TimeStampResp is what was requested. Then, it verifies the signature protection on the response, and validates the signer certificate (TSA certificate).

In order for the validation of the TSA certificate to be successful, the TSA certificate must be trusted. This means that the certificate verification mechanism must be able to trust the TSA certificate. If the certificate verification mechanism does not already have a trust relationship with the TSA, trust can be established manually, by adding the TSA certificate as a trusted certificate using the CertificateVerifier API getCertificateStore().addTrustedCertificate(X509Certificate.

Parameters:

data - contains the data to be time-stamped

Returns:

the time-stamp token

Throws:

TimeStampException - thrown if an error occurs while requesting/receiving the time-stamp, or there is a problem with the response received

java.lang.IllegalArgumentException - thrown if the parameter is null