iaik.tsp
Class TimeStampReq

java.lang.Object
  iaik.tsp.TimeStampReq

public class TimeStampReq
extends java.lang.Object

This class implements the TSP ASN.1 type TimeStampReq as it is specified in RFC 3161.

 TimeStampReq ::= SEQUENCE {
     version          INTEGER { v1(1) },
     messageImprint   MessageImprint,
                        --a hash algorithm OID and the hash value of the data to be
                        --time stamped
     reqPolicy        TSAPolicyID    OPTIONAL,
     nonce            INTEGER        OPTIONAL,
     certReq          BOOLEAN        DEFAULT FALSE,
     extensions       [0] IMPLICIT Extensions OPTIONAL
 }
 

This class handles the ASN.1 structure and the DER encoding and decoding of this structure.

The version field (currently v1) describes the version of the TimeStamp request.

The messageImprint field SHALL contain the hash of the datum to be time stamped. The hash is represented as an OCTET STRING. Its length MUST match the length of the hash value for that algorithm (e.g. 20 bytes for SHA-1 or 16 bytes for MD5). The hash algorithm indicated in the hashAlgorithm field MUST be a known hash algorithm (one-way and collision resistant).

The reqPolicy field, if included, indicates the policy under which the TimeStampToken SHOULD be provided.

The nonce, if included, allows to verify the timeliness of the response when no local clock is available. The nonce is a large unique number which is generated by the client (e.g. a 64 bit integer). In such a case the same nonce value shall be included in the response, otherwise the response shall be rejected.

If the certReq field is present and set to true, the TSA's public key certificate that is referenced by the ESSCertID attribute in the response MUST be provided by the TSA in the certificates field from the SignedData structure in that response. That field may also contain other certificates.

If the certReq field is missing, or if the certReq field is present and set to false then the certificates field from the SignedData structure MUST not be present in the response.

The extensions field is a generic way to add additional information to the request in the future. Extensions are defined in RFC 2459. If an extension, whether it is marked critical or not critical, is used by a requester but is not recognized by a time stamping server, the server SHALL not issue a token and SHALL return a failure (unacceptedExtension).

Example code for creating a TimeStampReq:

 
 //Create a new TimeStampReq
 TimeStampReq request = new TimeStampReq();

 //Calculate the hash of a given message
 byte[] hashed_message = null;
 try {
   hashed_message = MessageImprint.calculateHash("Data to be hashed", AlgorithmID.sha1);
 } catch (NoSuchAlgorithmException e) {
   e.printStackTrace();
   return;
 }
 
 //Create a new imprint with the hash and the hash algorithm
 MessageImprint imprint = new MessageImprint(AlgorithmID.sha1, hashed_message);
 
 //set the imprint
 request.setMessageImprint(imprint);
 
 //request the TSA to include its certificate chain into the response
 request.setCertReq(true);
 
 //set the nonce if needful (optional)
 //The nonce is a large random number with a high probability that the client
 //generates it only once (e.g., a 64 bit integer).
 request.setNonce(new BigInteger("1234567890"));
 
 //set the policy under which the token should be created (optional)
 request.setTSAPolicyID(new ObjectID("0.8.15"));
 
 byte[] req = request.getEncoded();
 
 //now the request is ready to be send
 

Field Summary

static int

PROTOCOL_VERSION The current protocol version = 1

Constructor Summary

TimeStampReq()
Constructs an empty TimeStampReq object.

TimeStampReq(ASN1Object component)
This constructor tries to reconstruct a TimeStampReq object from the given ASN.1 structure.

TimeStampReq(byte[] timeStampReq)
This constructor generates a TimeStampReq object from an encoded ASN.1 object.

TimeStampReq(MessageImprint message_imprint)
To construct a new TimeStampReq object a MessageImprint object must be provided.

Method Summary

boolean	getCertReq() Returns if a certificate is requested or not.
byte[]	getEncoded() This method DER encodes the ASN.1 TimeStampReq object.
X509Extensions	getExtensions() Returns the X509Extensions object.
MessageImprint	getMessageImprint() Returns the MessageImprint object.
java.math.BigInteger	getNonce() Returns the nonce number.
ObjectID	getTSAPolicyID() Returns the PolicyInformation object.
int	getVersion() Returns the TSP version.
void	setCertReq(boolean cert_req) This method sets or resets a certificate request.
void	setExtensions(X509Extensions extensions) This method sets a new X509Extensions object.
void	setMessageImprint(MessageImprint message_imprint) This method sets a new MessageImprint object.
void	setNonce(java.math.BigInteger nonce) This method sets a new nonce number.
void	setTSAPolicyID(ObjectID req_policy) This method sets a new PolicyInformation object.
ASN1Object	toASN1Object() Returns the ASN.1 structure of the TimeStampReq object.
java.lang.String	toString() This method returns a string representation of this object.

Methods inherited from class java.lang.Object

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

Field Detail

PROTOCOL_VERSION

public static final int PROTOCOL_VERSION

The current protocol version = 1

See Also:

Constant Field Values

Constructor Detail

TimeStampReq

public TimeStampReq()

Constructs an empty TimeStampReq object.

TimeStampReq

public TimeStampReq(MessageImprint message_imprint)
             throws java.lang.NullPointerException

To construct a new TimeStampReq object a MessageImprint object must be provided.

Parameters:

message_imprint - The hashed message and its algorithm identifier.

Throws:

java.lang.NullPointerException - Thrown if the given argument is null.

TimeStampReq

public TimeStampReq(ASN1Object component)
             throws CodingException

This constructor tries to reconstruct a TimeStampReq object from the given ASN.1 structure.

Parameters:

component - The ASN.1 structure.

Throws:

CodingException - Thrown if the given ASN.1 Object is not a TimeStampReq.

TimeStampReq

public TimeStampReq(byte[] timeStampReq)
             throws CodingException

This constructor generates a TimeStampReq object from an encoded ASN.1 object.

Parameters:

timeStampReq - The encoded ASN.1 object.

Throws:

CodingException - If the given ASN.1 Object is not a TimeStampReq.

Method Detail

getEncoded

public byte[] getEncoded()

This method DER encodes the ASN.1 TimeStampReq object.

Returns:

DER encoded TimeStampReq object.

toASN1Object

public ASN1Object toASN1Object()

Returns the ASN.1 structure of the TimeStampReq object.

Returns:

ASN1Object of the TimeStampReq object.

setMessageImprint

public void setMessageImprint(MessageImprint message_imprint)
                       throws java.lang.NullPointerException

This method sets a new MessageImprint object.

Parameters:

message_imprint - The MessageImprint object.

Throws:

java.lang.NullPointerException - Thrown if the given argument is null.

getMessageImprint

public MessageImprint getMessageImprint()

Returns the MessageImprint object.

Returns:

The MessageImprint object.

setTSAPolicyID

public void setTSAPolicyID(ObjectID req_policy)
                    throws java.lang.NullPointerException

This method sets a new PolicyInformation object.

Parameters:

req_policy - The policy information as ObjectID under which this time stamp request is presented.

Throws:

java.lang.NullPointerException - Thrown if the given argument is null.

getTSAPolicyID

public ObjectID getTSAPolicyID()

Returns the PolicyInformation object.

Returns:

The PolicyInformation object.

setNonce

public void setNonce(java.math.BigInteger nonce)
              throws java.lang.NullPointerException

This method sets a new nonce number.

Parameters:

nonce - The new number which is nearly unique.

Throws:

java.lang.NullPointerException - Thrown if the given argument is null.

getNonce

public java.math.BigInteger getNonce()

Returns the nonce number.

Returns:

The nonce number.

setCertReq

public void setCertReq(boolean cert_req)

This method sets or resets a certificate request. If it is set the TSA must return a certificate.

Parameters:

cert_req - An boolean which indicates if an certificate is requested.

getCertReq

public boolean getCertReq()

Returns if a certificate is requested or not.

Returns:

True if a certificate is requested otherwise false.

setExtensions

public void setExtensions(X509Extensions extensions)
                   throws java.lang.NullPointerException

This method sets a new X509Extensions object.

Parameters:

extensions - The X509Extensions object which specifies the extensions for this request.

Throws:

java.lang.NullPointerException - Thrown if the given argument is null.

getExtensions

public X509Extensions getExtensions()

Returns the X509Extensions object.

Returns:

The X509Extensions object.

getVersion

public int getVersion()

Returns the TSP version.

Returns:

An integer which specifies the TSP version.

toString

public java.lang.String toString()

This method returns a string representation of this object.

Overrides:

toString in class java.lang.Object

Returns:

a string which represents the TimeStampReq object.