com.entrust.toolkit.timestamp

Class TimeStampVerifier

java.lang.Object

com.entrust.toolkit.timestamp.TimeStampVerifier

public class TimeStampVerifier
extends java.lang.Object

This class provides a verification mechanism for time-stamps that are represented as TimeStampToken structures as defined in RFC 3161, the Time-Stamp Procotocl (TSP) specification.

It allows a TimeStampToken structure to be verified, which ensures that it has not been tampered and that TimeStamp Authority that issued the certificate was trusted at the time of issuance (valid). It can also determine whether or not a time-stamp applies to a particular piece of data. Together these two features can determine whether a piece of data existed before a particular time.

Since:

7.0

See Also:

RFC 3161

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	DEFAULT_ENFORCE_TSA_EXTENDED_KEY_USAGE_CRITICALITY Indicates be default whether the Extended Key-Usage extension of the TimeStamp Authority will be forced to be CRITICAL.

Constructor Summary

Constructors

Constructor and Description
TimeStampVerifier(CertVerifier certVerifier) Creates a new TimeStampVerifier object that will use the indicated certificate verification mechanism.

Method Summary

Methods

Modifier and Type	Method and Description
void	enforceTSAExtendedKeyUsageCriticality(boolean enforce) Allows configuration of the enforcement of the RFC3161 requirement that the TimeStamp Authority (TSA) certificate contain a CRITICAL extended key-usage extension.
void	setTsaCert(X509Certificate tsaCert) Sets the TimeStamp Authority certificate.
X509Certificate	verify(byte[] data, TimeStampToken timeStampToken) Verifies that the time-stamp token is valid.
X509Certificate	verify(java.io.InputStream data, TimeStampToken timeStampToken) Verifies that the time-stamp token is valid.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_ENFORCE_TSA_EXTENDED_KEY_USAGE_CRITICALITY

public static final boolean DEFAULT_ENFORCE_TSA_EXTENDED_KEY_USAGE_CRITICALITY

Indicates be default whether the Extended Key-Usage extension of the TimeStamp Authority will be forced to be CRITICAL.

See Also:

Constant Field Values

Constructor Detail

TimeStampVerifier

public TimeStampVerifier(CertVerifier certVerifier)

Creates a new TimeStampVerifier object that will use the indicated certificate verification mechanism.

Parameters:

certVerifier - the certificate verification mechanism

Throws:

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

Method Detail

setTsaCert

public void setTsaCert(X509Certificate tsaCert)

Sets the TimeStamp Authority certificate.

This certificate will be used to during the verification of the time-stamp token.

Parameters:

tsaCert - the TimeStamp Authority certificate

enforceTSAExtendedKeyUsageCriticality

public void enforceTSAExtendedKeyUsageCriticality(boolean enforce)

Allows configuration of the enforcement of the RFC3161 requirement that the TimeStamp Authority (TSA) certificate contain a CRITICAL extended key-usage extension.

According to RFC3161, the TimeStamp Authority must contain an extended key-usage extension that is CRITICAL. However, since there are TSAs already in existence that do not meet this requirement, this APIs enforcement of this requirement to be configurable.

Parameters:

enforce - indicates whether the Extended Key-Usage extension of the TimeStamp Authority will be forced to be CRITICAL.

verify

public X509Certificate verify(byte[] data,
                     TimeStampToken timeStampToken)
                       throws TimeStampException,
                              java.lang.IllegalArgumentException

Verifies that the time-stamp token is valid.

First, it verifies that that time-stamp token actually applies to the data indicated. Then, it verifies the signature on the time-stamp token, ensuring that it has not been tampered. Finally, it ensures that the TimeStamp Authority(TSA) certificate is valid and trusted.

The TSA certificate that is included in the time-stamp token, if it exists, is used to verify the signature. If the time-stamp token does not contain a TSA certificate, the TSA certificate is searched for by examining the certificates contained in the certificate verifier, and if found, used to verify the signature. If the TSA certificate could not be found in the certificate verifier, the TSA certificate that was set when this time-stamp verifier was created is used to verify the signature. If a TSA certificate does not exist in the time-stamp token, or in the certificate verifier, or in the time-stamp verifier, the verification will always fail.

For the TSA certificate to be valid, it must contain the extended key-usage extension with the 'timeStamping' key-purpose identifier. Also, according to RFC3161, this extension must be CRITICAL. However, since there are TSAs already in existence that do not meet this requirement, enforcement of this requirement is configurable through the enforceTSACriticalExtendedKeyUsage(boolean) API.

Parameters:

data - the data that the time-stamp was created over

timeStampToken - the time-stamp token

Returns:

the TimeStamp Authority certificate that signed the time-stamp token

Throws:

TimeStampException - thrown if the time-stamp token does not apply to the data or the time-stamp validation/verification fails

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

verify

public X509Certificate verify(java.io.InputStream data,
                     TimeStampToken timeStampToken)
                       throws TimeStampException,
                              java.lang.IllegalArgumentException

Verifies that the time-stamp token is valid.

First, it verifies that that time-stamp token actually applies to the data indicated. Then, it verifies the signature on the time-stamp token, ensuring that it has not been tampered. Finally, it ensures that the TimeStamp Authority(TSA) certificate is valid and trusted.

The TSA certificate that is included in the time-stamp token, if it exists, is used to verify the signature. If the time-stamp token does not contain a TSA certificate, the TSA certificate is searched for by examining the certificates contained in the certificate verifier, and if found, used to verify the signature. If the TSA certificate could not be found in the certificate verifier, the TSA certificate that was set when this time-stamp verifier was created is used to verify the signature. If a TSA certificate does not exist in the time-stamp token, or in the certificate verifier, or in the time-stamp verifier, the verification will always fail.

For the TSA certificate to be valid, it must contain the extended key-usage extension with the 'timeStamping' key-purpose identifier. Also, according to RFC3161, this extension must be CRITICAL. However, since there are TSAs already in existaece that do not meet this requirement, enforcement of this requirement is configurable through the enforceTSACriticalExtendedKeyUsage(boolean) API.

Parameters:

data - an input stream containing the data that the time-stamp was created over

timeStampToken - the time-stamp token

Returns:

the TimeStamp Authority certificate that signed the time-stamp token

Throws:

TimeStampException - thrown if the time-stamp token does not apply to the data or the time-stamp validation/verification fails

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