iaik.tsp
Class TimeStampToken

java.lang.Object
  iaik.cms.ContentInfo
      iaik.tsp.TimeStampToken

public class TimeStampToken
extends ContentInfo

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

 TimeStampToken ::= ContentInfo
     -- contentType is id-signedData as defined in [CMS]
     -- content is SignedData as defined in([CMS])
     -- eContentType within SignedData is id-ct-TSTInfo
     -- eContent within SignedData is TSTInfo
 

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

This class is a ContentInfo class. It additionally registers the TSTInfo structure to the factory class.

Field Summary

static int	ISSUER_AND_SERIALNUMBER The CMS certificate identifier type IssuerAndSerialNumber.
static int	SUBJECT_KEY_IDENTIFIER The CMS certificate identifier type SubjectKeyIdentifier.

Constructor Summary

TimeStampToken(ASN1Object obj)
Creates a TimeStampToken from the given ASN.1 Object.

TimeStampToken(byte[] tsaToken)
Creates a TimeStampToken from an encoded ASN.1 Object.

TimeStampToken(TSTInfo tstInfo)
Creates a TimeStampToken object.

Method Summary

void	addSha1ESSCertID(boolean addSha1CertID) Whether to also include a SHA-1 based ESSCertID if an ESSCertIDv2 is used with another hash algorithm according to RFC 5816.
protected void	checkKeyUsage(X509Certificate tsaCert) This method checks the ExtendedKeyUsage and KeyUsage extensions of the TSA responder certificate.
ESSCertID	getCertID() Returns the certificate identifier of the signer certificate, or null if not present.
ESSCertIDv2	getCertIDv2() Returns the ESSCertIDv2 certificate identifier of an SigningCertificateV2 attribute, or null if not present.
java.security.cert.X509Certificate[]	getCertificates() Returns the included X509 certificates or null.
AlgorithmID	getHashAlgorithm() Returns the used AlgorithmID for creating the hash.
ESSIssuerSerial	getIssuerSerial() Returns the ESSIssuerSerial.
ESSIssuerSerial	getIssuerSerialv2() Returns the ESSIssuerSerial of an SigningCertificateV2/ESSCertIDv2 attribute, if present.
SignedData	getSignedData() Returns the SignedData form the TimeStampToken, or null if the TimeStampToken is not signed.
SignerInfo	getSignerInfo() Returns the SignerInfo if present.
java.security.cert.X509Certificate	getSigningCertificate() Returns the TSACertificate or null if not present.
TSTInfo	getTSTInfo() Returns the TSTInfo object.
boolean	isSigningCertificate(java.security.cert.X509Certificate cert) Checks whether the supplied certificate actually is the certificate of the signer.
void	setCertificates(java.security.cert.X509Certificate[] certs) Sets the CertificateChain for signing.
static void	setCheckKeyUsage(boolean checkKeyUsage) Decides whether to check the ExtendedKeyUsage and KeyUsage extensions of the TSA responder certificate when verifying the signature of the time stamp token.
void	setHashAlgorithm(AlgorithmID algorithmId) Sets the hash algorithm used for creating the hash.
void	setPrivateKey(java.security.PrivateKey privateKey) Sets the PrivateKey for signing.
void	setSigningCertificate(java.security.cert.X509Certificate tsaCertificate) Sets the certificate for signing.
void	signTimeStampToken() This method signs the TimeStampToken.
void	signTimeStampToken(java.lang.String provider) This method signs the TimeStampToken.
void	signTimeStampToken(java.lang.String provider, AlgorithmID signatureAlgorithm) This method signs the TimeStampToken.
void	signTimeStampToken(java.lang.String provider, AlgorithmID signatureAlgorithm, int certificateIdentifier) This method signs the TimeStampToken.
void	signTimeStampToken(java.lang.String provider, AlgorithmID signatureAlgorithm, int certificateIdentifier, Attribute[] signedAttributes, Attribute[] unsignedAttributes) This method signs the TimeStampToken.
java.lang.String	toString() This method returns a string representation of this object.
void	verifyTimeStampToken() This method verifies the signature of the TimeStampToken This method throws a CertificateNotFoundException if the certificate of the signing TSA is not included in this TimeStampToken.
void	verifyTimeStampToken(java.security.cert.X509Certificate certificate) This method verifies the signature of the TimeStampToken.

Methods inherited from class iaik.cms.ContentInfo

create, create, decode, getContent, getContentInputStream, getContentType, getEncoded, keepEncodedContent, register, setContent, toASN1Object, toByteArray, toString, writeTo

Methods inherited from class java.lang.Object

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

Field Detail

ISSUER_AND_SERIALNUMBER

public static final int ISSUER_AND_SERIALNUMBER

The CMS certificate identifier type IssuerAndSerialNumber.

See Also:

Constant Field Values

SUBJECT_KEY_IDENTIFIER

public static final int SUBJECT_KEY_IDENTIFIER

The CMS certificate identifier type SubjectKeyIdentifier.

See Also:

Constant Field Values

Constructor Detail

TimeStampToken

public TimeStampToken(TSTInfo tstInfo)

Creates a TimeStampToken object.

Parameters:

tstInfo - The TSTInfo element.

TimeStampToken

public TimeStampToken(ASN1Object obj)
               throws CMSParsingException,
                      CodingException

Creates a TimeStampToken from the given ASN.1 Object.

Parameters:

obj - The TimeStampToken as ASN.1 Object.

Throws:

CMSParsingException - Thrown if an invalid DER-encoded CMS object is parsed or unsupported DER features are found in the CMS object.

CodingException - Thrown if an ASN.1 coding exception occurs.

TimeStampToken

public TimeStampToken(byte[] tsaToken)
               throws CMSParsingException,
                      CodingException

Creates a TimeStampToken from an encoded ASN.1 Object.

Parameters:

tsaToken - The encoded TimeStampToken.

Throws:

CMSParsingException - Thrown if an invalid DER-encoded CMS object is parsed or unsupported DER features are found in the CMS object.

CodingException - Thrown if an ASN.1 coding exception occurs.

Method Detail

setCheckKeyUsage

public static void setCheckKeyUsage(boolean checkKeyUsage)

Decides whether to check the ExtendedKeyUsage and KeyUsage extensions of the TSA responder certificate when verifying the signature of the time stamp token.

Parameters:

checkKeyUsage - whether to check the ExtendedKeyUsage and KeyUsage extensions

getTSTInfo

public TSTInfo getTSTInfo()

Returns the TSTInfo object.

Returns:

TSTInfo The TSTInfo object.

setSigningCertificate

public void setSigningCertificate(java.security.cert.X509Certificate tsaCertificate)
                           throws java.lang.NullPointerException

Sets the certificate for signing.

Parameters:

tsaCertificate - The signing certificate.

Throws:

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

getSigningCertificate

public java.security.cert.X509Certificate getSigningCertificate()

Returns the TSACertificate or null if not present.

Returns:

The certificate.

isSigningCertificate

public boolean isSigningCertificate(java.security.cert.X509Certificate cert)
                             throws java.security.cert.CertificateException

Checks whether the supplied certificate actually is the certificate of the signer.

This method first checks if the given certificate is actually identified by IssuerAndSerialNumber or SubjectKeyIdentifier. If this check is successful, this method then looks if the SigningCertificate and/or the SigningCertificateV2 are present and identify the given certificate as cert of the signer. If both SigningCertificate attributes are present this method accepts the given certificate as signer certificate only if it is identified by both SigningCertificate attributes.

Parameters:

cert - the certificate to be checked of being the one of the signer

Returns:

true if the supplied certificate is the signer certificate, false if not

Throws:

java.security.cert.CertificateException - if the check cannot be completed because an error occurs when parsing the certificate or the SigningCertificate or SigningCertificateV2 attribute or a hash algorithm (required for calculating the cert hash) is not supported by the installed cryptographic providers

setPrivateKey

public void setPrivateKey(java.security.PrivateKey privateKey)
                   throws java.lang.NullPointerException

Sets the PrivateKey for signing.

Parameters:

privateKey - The private key.

Throws:

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

setHashAlgorithm

public void setHashAlgorithm(AlgorithmID algorithmId)
                      throws java.lang.NullPointerException

Sets the hash algorithm used for creating the hash. If not set SHA1 will be used as default.

Parameters:

algorithmId - The AlgorithmID.

Throws:

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

addSha1ESSCertID

public void addSha1ESSCertID(boolean addSha1CertID)

Whether to also include a SHA-1 based ESSCertID if an ESSCertIDv2 is used with another hash algorithm according to RFC 5816.
RFC 5816 updates RFC 3161 to allow the use of other hash algoithms than SHA-1 for calculating the cert id of the TSA certificate. RFC 3161 uses the SigningCertificate attribute (RFC 2634) to identify the certificate of the response signing TSA with an ESSCertID that calculates a SHA-1 hash of the certificate. RFC 5816 updates RFC 3161 to allow to use the SigningCertificateV2 attribute (RFC 5035) with an ESSCertIDv2 that uses another hash algorithm than SHA-1 to calculate a hash of the signer certificate.
The usage of SigningCertificate/ESSCertID is still permitted according the following rules:

• When SHA-1 is used for calculating the cert hash, the SigningCertificate/ESSCertID attribute must be used
• When another hash algorithm than SHA-1 is used, the SigningCertificateV2/ESSCertIDv2 attribute must be used
• For backwards compatibility both SigningCertificate/ESSCertID and SigningCertificateV2/ESSCertIDv2 may be used in a single response to allow requestors that only support SHA-1 to correctly interpret SigningCertificate/ESSCertID, but ignore SigningCertificateV2/ESSCertIDv2

This implementation uses SigningCertificate/ESSCertID if SHA-1 has been set as hash algorithm for this TimeStampToken, but uses SigningCertificateV2/ESSCertIDv2 if another hash algorithm than SHA-1 has been set. In this case, if you want to include SigningCertificate/ESSCertID, too, call this addSha1ESSCertID method, e.g.:

 TimeStampToken token = ...;
 ...
 token.setHashAlgorithm(AlgorithmID.sha256);
 token.addSha1ESSCertID(true);
 

Parameters:

addSha1CertID - whether to add a SHA-1 SigningCertificate/ESSCertID attribute to a SigningCertificateV2/ESSCertIDv2 attribute that uses another hash algorithm than SHA-1 (default: false if another hash algorithm than SHA-1 has been set, only a SigningCertificateV2/ESSCertIDv2 attribute is used)

getHashAlgorithm

public AlgorithmID getHashAlgorithm()

Returns the used AlgorithmID for creating the hash.

Returns:

The AlgorithmID.

getSignedData

public SignedData getSignedData()

Returns the SignedData form the TimeStampToken, or null if the TimeStampToken is not signed.

Returns:

the SignedData form the TimeStampToken, or null if the TimeStampToken is not signed.

getCertID

public ESSCertID getCertID()
                    throws CodingException

Returns the certificate identifier of the signer certificate, or null if not present.

If this TimeStampToken contains a SigningCertificate attribute, this methid returns the ESSCertID of the SigningCertificate attribute.
If this TimeStampToken does not contain a SigningCertificate attribute, but contains a SigningCertificateV2 attribute this method returns the ESSCertIDv2 of the SigningCertificateV2 attribute.
If both SigningCertificate attribute and SigningCertificateV2 attributes are included, this method returns the ESSCertID of the SigningCertificate attribute. In this case you can call method getCertIDv2() if you want to get the ESSCertIDv2 of the SigningCertificateV2 attribute.

If you want to get all included cert ids (of signer and authorization certificates), get the SignerInfo of this TimeStampToken and query its SigningCertificate and SigningCertificateV2 attributes.

Returns:

The certificate identifier, or null if not present.

Throws:

CodingException - Thrown if the a coding error occurs.

getCertIDv2

public ESSCertIDv2 getCertIDv2()
                        throws CodingException

Returns the ESSCertIDv2 certificate identifier of an SigningCertificateV2 attribute, or null if not present.

If you want to get all included ESSCertIDv2 ids (of signer and authorization certificates), get the SignerInfo of this TimeStampToken and query its SigningCertificateV2 attribute.

Returns:

the ESSCertIDv2 certificate identifier of an SigningCertificateV2 attribute, or null if not present.

Throws:

CodingException - Thrown if the a coding error occurs.

getIssuerSerial

public ESSIssuerSerial getIssuerSerial()
                                throws CodingException

Returns the ESSIssuerSerial.

If this TimeStampToken contains a SigningCertificate attribute, the ESSIssuerSerial is taken from the ESSCertID of the SigningCertificate attribute.
If this TimeStampToken does not contain a SigningCertificate attribute, but contains a SigningCertificateV2 attribute the ESSIssuerSerial is taken from the ESSCertIDv2 of the SigningCertificateV2 attribute.
If both SigningCertificate attribute and SigningCertificateV2 attributes are included, this method returns the ESSIssuerSerial from the ESSCertID of the SigningCertificate attribute. In this case you can call method getIssuerSerialv2() if you want to get the ESSIssuerSerial from the ESSCertIDv2 of the SigningCertificateV2 attribute.

If you want to get all included ESSIssuerSerial objects (of signer and authorization certificates), get the SignerInfo of this TimeStampToken and query its SigningCertificate and SigningCertificateV2 attributes.

Returns:

The ESSIssuerSerial object.

Throws:

CodingException - Thrown if the a coding error occurs.

getIssuerSerialv2

public ESSIssuerSerial getIssuerSerialv2()
                                  throws CodingException

Returns the ESSIssuerSerial of an SigningCertificateV2/ESSCertIDv2 attribute, if present.

If you want to get all included ESSCertIDv2 ESSIssuerSerial objects (of signer and authorization certificates), get the SignerInfo of this TimeStampToken and query its SigningCertificateV2 attribute.

Returns:

The ESSIssuerSerial object of the SigningCertificateV2/ESSCertIDv2 attribute, or null if no SigningCertificateV2/ESSCertIDv2 is included.

Throws:

CodingException - Thrown if the a coding error occurs.

getSignerInfo

public SignerInfo getSignerInfo()

Returns the SignerInfo if present.

Returns:

The SignerInfo.

setCertificates

public void setCertificates(java.security.cert.X509Certificate[] certs)
                     throws java.lang.NullPointerException

Sets the CertificateChain for signing.

Parameters:

certs - The CertificateChain.

Throws:

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

getCertificates

public java.security.cert.X509Certificate[] getCertificates()

Returns the included X509 certificates or null.

Returns:

The included X509 certificates or null.

signTimeStampToken

public void signTimeStampToken(java.lang.String provider,
                               AlgorithmID signatureAlgorithm,
                               int certificateIdentifier)
                        throws TspSigningException

This method signs the TimeStampToken.
The following signed attributes are added to the SignerInfo of the TSA:

• ContentType (tstInfo)
• MessageDigest
• SigningCertificate and/or SigningCertificateV2

This method uses SigningCertificate/ESSCertID attribute if SHA-1 has been set as hash algorithm for this TimeStampToken, but uses the SigningCertificateV2/ESSCertIDv2 if another hash algorithm than SHA-1 has been set. In this case, if you want to include SigningCertificate/ESSCertID, too, call method addSha1ESSCertID, e.g.:

 TimeStampToken token = ...;
 ...
 token.setHashAlgorithm(AlgorithmID.sha256);
 token.addSha1ESSCertID(true);
 

Parameters:

provider - The provider to be used for signing. If null the first provider who supports the specified algorithm will be used.

signatureAlgorithm - The algorithm to be used for signature calculation. If null PKCS#1 rsaEncryption will be used.

certificateIdentifier - Information about the signer's certificate. Either IssuerAndSerialNumber = 0 or SubjectKeyID = 1.

Throws:

TspSigningException - Thrown if any error occurs during the signing process.

signTimeStampToken

public void signTimeStampToken(java.lang.String provider,
                               AlgorithmID signatureAlgorithm,
                               int certificateIdentifier,
                               Attribute[] signedAttributes,
                               Attribute[] unsignedAttributes)
                        throws TspSigningException

This method signs the TimeStampToken.

When using this method to sign the TimeStampToken any signed and unsigned attributes that shall be included into the SignerInfo must have been already calculated by the application. This method does not add any attributes by itself, except for the MessageDigest attribute which is added if signedAttributes are supplied and do not contain the MessageDigest attribute yet.
If no attributes are given no attributes are added. Note that a time stamp requester may not accept a TimeStampToken that does not contain a SigningCertificate or SigningCertificateV2 attribute.
If you not want take care about attribute handling just use method signTimeStampToken which automatically adds the ContentType, SigningCertificate and/or SigningCertificateV2 attributes.

Parameters:

provider - The provider to be used for signing. If null the first provider who supports the specified algorithm will be used.

signatureAlgorithm - The algorithm to be used for signature calculation. If null PKCS#1 rsaEncryption will be used.

certificateIdentifier - Information about the signer's certificate. Either IssuerAndSerialNumber = 0 or SubjectKeyID = 1.

Throws:

TspSigningException - Thrown if any error occurs during the signing process.

signTimeStampToken

public void signTimeStampToken(java.lang.String provider,
                               AlgorithmID signatureAlgorithm)
                        throws TspSigningException

This method signs the TimeStampToken.

Parameters:

provider - The provider to be used for signing. If null the first provider who supports the specified algorithm will be used.

signatureAlgorithm - The algorithm to be used for signature calculation. If null PKCS#1 rsaEncryption will be used.

Throws:

TspSigningException - Thrown if any error occurs during the signing process.

signTimeStampToken

public void signTimeStampToken(java.lang.String provider)
                        throws TspSigningException

This method signs the TimeStampToken. ISSUER_AND_SERIALNUMBER as CertificateIdentifier will be used.

Parameters:

provider - The provider to be used for signing. If null the first provider who supports rsaEncryption will be used.

Throws:

TspSigningException - Thrown if any error occurs during the signing process.

signTimeStampToken

public void signTimeStampToken()
                        throws TspSigningException

This method signs the TimeStampToken. rsaEncryption with the first provider who supports this algorithm and ISSUER_AND_SERIALNUMBER as CertificateIdentifier will be used.

Throws:

TspSigningException - Thrown if any error occurs during the signing process.

verifyTimeStampToken

public void verifyTimeStampToken(java.security.cert.X509Certificate certificate)
                          throws TspVerificationException

This method verifies the signature of the TimeStampToken.

This method uses the given certificate to verify that the signature has been correctly calculated with the corresponding private key. This method does not perform any certificate path validation. However, it checks if the certificate contains a critical ExtendedKeyUsagae extension with key purpose id timeStamping as required by RFC 3161 and if the KeyUsage extension -- if present -- is eligible for signing.
This method does not check if the certificate of the signing TSA is identified by the SigningCertificate attribute of this TimeStampToken. You may call method isSigningCertificate to check for right signing certificate identification:

 TimeStampToken token = ...;
 ...
 //get the signing certificate from the token (or -- if not included -- from some cert data base)
 X509Certificate cert = token.getSigningCertificate();
 // check SigningCertificate/SigningCertificateV2 attribute
 if (token.getCertID() == null) {
   throw new Exception("No SigningCertificate attribute included!");  
 } 
 if (!token.isSigningCertificate(cert)) {
   throw new Exception("Certificate " + cert.getSubjectDN() + " is not signing certificate!");
 }
 // verify signature
 token.verifyTimeStampToken(cert); 
 

Parameters:

certificate - The certificate for verifying the signature.

Throws:

TspVerificationException - Thrown if the signature of the time stamp token is invalid, or the TSA certificate could not be parsed or the TSA certificate does not contain a critical ExtendedKeyUsage extension with timeStamping key purpose id

verifyTimeStampToken

public void verifyTimeStampToken()
                          throws CertificateNotFoundException,
                                 TspVerificationException

This method verifies the signature of the TimeStampToken This method throws a CertificateNotFoundException if the certificate of the signing TSA is not included in this TimeStampToken.

This method does not perform any certificate path validation. However, it checks if the certificate contains a critical ExtendedKeyUsagae extension with key purpose id timeStamping as required by RFC 3161.
This method does not check if the certificate of the signing TSA is identified by the SigningCertificate attribute of this TimeStampToken. You may call method isSigningCertificate to check for right signing certificate identification:

 TimeStampToken token = ...;
 ...
 //get the signing certificate from the token (or -- if not included -- from some cert data base)
 X509Certificate cert = token.getSigningCertificate();
 // check SigningCertificate/SigningCertificateV2 attribute 
 if (token.getCertID() == null) {
   throw new Exception("No SigningCertificate attribute included!");  
 } 
 if (!token.isSigningCertificate(cert)) {
   throw new Exception("Certificate " + cert.getSubjectDN() + " is not signing certificate!");
 }
 // verify signature
 token.verifyTimeStampToken(); 
 

Throws:

CertificateNotFoundException - if the signer certificate is not included

TspVerificationException - Thrown if the signature of the time stamp token is invalid, or the TSA certificate could not be parsed or the TSA certificate does not contain a critical ExtendedKeyUsage extension with timeStamping key purpose id

toString

public java.lang.String toString()

This method returns a string representation of this object.

Overrides:

toString in class ContentInfo

Returns:

A String representing the TimeStampResp object.

checkKeyUsage

protected void checkKeyUsage(X509Certificate tsaCert)
                      throws TspVerificationException

This method checks the ExtendedKeyUsage and KeyUsage extensions of the TSA responder certificate.

This method checks if the given TSA responder certificate contains a critical ExtendedKeyUsagae extension with key purpose id timeStamping as required by RFC 3161. If the certificate contains a KeyUsage extension this method also checks if the KeyUsage extension makes the certificate eligible for signing, i.e. if the digitalSignature or nonRepudiation key usage bits are set.

This method is called by method verifyTimeStampToken to check the (extended) key usage compliance of the TSA certificate. This check can be disabled by calling method setCheckKeyUsage(false) or by overriding this checkKeyUsage method.

Parameters:

tsaCert - The certificate of the TSA responder

Throws:

TspVerificationException - If key usage check is enabled and (the TSA certificate does not contain a critical ExtendedKeyUsage extension with timeStamping key purpose id, or the certificate does contain a non-signing eligible KeyUsage extension, or KeyUsage or ExtendedKeyUsage extension are present but cannot be parsed)