com.digistamp.tsp

Class CertHandler

Object

com.digistamp.tsp.CertHandler

public class CertHandler
extends Object

CertHandler is used as a singleton to hold the trusted "root" certificates from the TSA Service.

This is related to discovering trust using certificate chaining. In practice, the lowest level timestamp certificate is returned with each timestamp. Then, that certificate is checked using x.509 method of certificate-chaining to certificates you had trusted in advance by storing them on your computer. There are two options for where the certificates are stored on your system.

• Load certificates from directory 'com.digistamp.certificates' (details below) found in classpath and if not found then looks to current value of System Property "user.dir".
• In some deployment scenarios the certificates are stored in a JAR file. In this case this method will load the CA ROOT certificates by using predefined names. To use this method you will using this configuration property: mySpecialConfigs.put(Constants.ROOT_CERTS_BY_NAME, "true");

Details about comparing the two methods: when the file system is used then the toolkit can find the list of files in a particular directory and load that "dynamic" list. But, when loading from a jar we must use predefined certificate file names and we load only the ROOT certificates.

When using option of storing certificate in directory 'com.digistamp.certificates', common usage would be to have Root and Audit certificates and no Timestamp certificates in the directory structure. In this configuration, during verification processing the Timestamp certificate is retrieved from each timestamp and then that certificate is checked for correct chaining to the Root certificate that is stored in the directory structure.

The 'com.digistamp.certificates' directory has a prescribed structure:

• com.digistamp.certificates
  • Production
    • Root
    • Audit
    • Timestamp (contents optional)
  • Test
    • Root
    • Audit
    • Timestamp (contents optional)

Method Summary

Modifier and Type	Method and Description
static void	checkIssuer(org.bouncycastle.cert.X509CertificateHolder issuer, org.bouncycastle.cert.X509CertificateHolder child) did this certificate issue this child certificate? and check the signature and path.
static org.bouncycastle.cms.SignerInformationVerifier	createSIV(org.bouncycastle.cert.X509CertificateHolder issuerCertificate) Create a SignerInformationVerifier from a single target issuer certificate.
static org.bouncycastle.cert.X509CertificateHolder	findMatch(Collection<org.bouncycastle.cert.X509CertificateHolder> certs, org.bouncycastle.tsp.TimeStampToken aTimeStamp) Find an UNVERIFIED match by ESScertID.
static org.bouncycastle.cert.X509CertificateHolder	findMatch(org.bouncycastle.util.Store<org.bouncycastle.cert.X509CertificateHolder> aStore, org.bouncycastle.tsp.TimeStampToken aTimeStamp) Find an UNVERIFIED match by ESScertID.
static org.bouncycastle.cms.SignerInformationVerifier	findMatchingCertificate(org.bouncycastle.asn1.x500.X500Name targetCertificate, ArrayList<org.bouncycastle.cms.SignerInformationVerifier> issuerCertificateList) Find an UNVERIFIED match by X500Name between a target child certificate and its Issuer.
ArrayList<org.bouncycastle.cms.SignerInformationVerifier>	getAuditCertificates() Return all Audit Certificates associated with this CertHandler
static com.digistamp.tsp.CertID	getCertID(org.bouncycastle.asn1.cms.AttributeTable aAttributeTable)
static com.digistamp.tsp.CertID	getCertID(org.bouncycastle.tsp.TimeStampToken aTimeStamp)
static CertHandler	getInstance() Singleton accessor method
ArrayList<org.bouncycastle.cms.SignerInformationVerifier>	getRootCertificates() Return all Root Certificates associated with this CertHandler
ArrayList<org.bouncycastle.cms.SignerInformationVerifier>	getTimestampCertificates() Return all Timestamp Certificates associated with this CertHandler
static org.bouncycastle.cert.X509CertificateHolder	isGoodTimestamp(org.bouncycastle.tsp.TimeStampToken aTimeStampToken, CertHandler passedCertHandler) This function performs thorough checking of the object's timestamp response.
void	setTestUntrusted(boolean untrusted, boolean rootCertsByName) Decides, and reads, the appropriate set of certificates for Trusted Production usage, or Untrusted Test Usage.

Methods inherited from class Object

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

Method Detail

checkIssuer

public static void checkIssuer(org.bouncycastle.cert.X509CertificateHolder issuer,
                               org.bouncycastle.cert.X509CertificateHolder child)
                        throws org.bouncycastle.operator.OperatorCreationException,
                               org.bouncycastle.cert.CertException,
                               org.bouncycastle.tsp.TSPValidationException

did this certificate issue this child certificate? and check the signature and path.

Throws:

org.bouncycastle.operator.OperatorCreationException

org.bouncycastle.cert.CertException

org.bouncycastle.tsp.TSPValidationException

createSIV

public static org.bouncycastle.cms.SignerInformationVerifier createSIV(org.bouncycastle.cert.X509CertificateHolder issuerCertificate)
                                                                throws Exception

Create a SignerInformationVerifier from a single target issuer certificate. The resulting object is used for the thorough verification of 3161 timestamps.

Throws:

Exception

findMatch

public static org.bouncycastle.cert.X509CertificateHolder findMatch(Collection<org.bouncycastle.cert.X509CertificateHolder> certs,
                                                                    org.bouncycastle.tsp.TimeStampToken aTimeStamp)

Find an UNVERIFIED match by ESScertID. Returns null if no match was found. UNVERIFIED means that this performs NO cryptographic verification.

findMatch

public static org.bouncycastle.cert.X509CertificateHolder findMatch(org.bouncycastle.util.Store<org.bouncycastle.cert.X509CertificateHolder> aStore,
                                                                    org.bouncycastle.tsp.TimeStampToken aTimeStamp)

Find an UNVERIFIED match by ESScertID. Returns null if no match was found. UNVERIFIED means that this performs NO cryptographic verification.

findMatchingCertificate

public static org.bouncycastle.cms.SignerInformationVerifier findMatchingCertificate(org.bouncycastle.asn1.x500.X500Name targetCertificate,
                                                                                     ArrayList<org.bouncycastle.cms.SignerInformationVerifier> issuerCertificateList)

Find an UNVERIFIED match by X500Name between a target child certificate and its Issuer. Returns null if no match was found. UNVERIFIED means that this performs NO cryptographic verification.

getAuditCertificates

public ArrayList<org.bouncycastle.cms.SignerInformationVerifier> getAuditCertificates()

Return all Audit Certificates associated with this CertHandler

getCertID

public static com.digistamp.tsp.CertID getCertID(org.bouncycastle.asn1.cms.AttributeTable aAttributeTable)
                                          throws org.bouncycastle.tsp.TSPValidationException

Throws:

org.bouncycastle.tsp.TSPValidationException

getCertID

public static com.digistamp.tsp.CertID getCertID(org.bouncycastle.tsp.TimeStampToken aTimeStamp)
                                          throws org.bouncycastle.tsp.TSPValidationException

Throws:

org.bouncycastle.tsp.TSPValidationException

getInstance

public static CertHandler getInstance()
                               throws IOException

Singleton accessor method

Throws:

IOException

getRootCertificates

public ArrayList<org.bouncycastle.cms.SignerInformationVerifier> getRootCertificates()

Return all Root Certificates associated with this CertHandler

getTimestampCertificates

public ArrayList<org.bouncycastle.cms.SignerInformationVerifier> getTimestampCertificates()

Return all Timestamp Certificates associated with this CertHandler

isGoodTimestamp

public static org.bouncycastle.cert.X509CertificateHolder isGoodTimestamp(org.bouncycastle.tsp.TimeStampToken aTimeStampToken,
                                                                          CertHandler passedCertHandler)
                                                                   throws org.bouncycastle.tsp.TSPValidationException

This function performs thorough checking of the object's timestamp response. Throws an exception if not successful. Checks include:

Confirm that the timestamp is valid against trusted timestamp certificates known by CertHandler. If you did not configure CertHandler to have trusted 'timestamp' certificates then certificates attached to the timestamp are searched. Confirm that the timestamp certificate is valid against an audit/intermediate certificate Confirm that the audit certificate is valid against a previously known and trusted root certificate

Throws:

org.bouncycastle.tsp.TSPValidationException

setTestUntrusted

public void setTestUntrusted(boolean untrusted,
                             boolean rootCertsByName)
                      throws IOException

Decides, and reads, the appropriate set of certificates for Trusted Production usage, or Untrusted Test Usage. Normally you would not call this method, instead setting the properties in the configuration by using:
mySpecialConfigs.put(Constants.PKI_UNTRUSTED,"true");
mySpecialConfigs.put(Constants.ROOT_CERTS_BY_NAME, "true");
TSAservice.setConfiguration(mySpecialConfigs); The default configuration is to retrieve product quality time stamps, not TEST. If you wish to use the untrusted "Test" set of certificates then you would call this with the first parameter as "true". There are two ways to find the ROOT certificates that are used to verify timestamps. This is better described in this class introduction.

Throws:

IOException