DigiStamp SecureTime API Java Toolkit README FILE
(C) Copyright 2000-2011. DigiStamp, Inc.
www.digistamp.com

Thank you for your interest in the SecureTime toolkit. This document contains information on how to use the supplied Java Library. Documentation on the software components of the toolkit is in the HTML document that is delivered with the software. The attached sample programs will help you quickly retrieve your first time stamp.

The toolkit is delivered in a zip file that contains the documentation and sample programs. Unzip the DigiStampJToolkit.zip into a directory that you create, for example, name it "digistamp".

You will need to establish an account with DigiStamp to request time stamps from the servers. Account set-up is at the www.digistamp.com web site.

Introduction

The toolkit library allows adding time stamping capability to your existing application. The toolkit performs the functions:

• File hash generation
• Creating a time stamp request
• Communicating the time stamp request to the DigiStamp server via the Internet (you configure the rules for automatic failover to time stamp Internet sites)
• Decoding the time stamp response
• Outputting a CMS record structure that contains the time stamp
• Verifying the time stamp authenticity

API Documentation

The SecureTime API documentation describes the classes and their public interface. See the:

License Terms

Delivered with the software is a file DigistampLicense.html. Please review the license carefully. You must accept this license or delete your copies of the software. If you have questions or concerns about the license please contact DigiStamp before proceeding with use of the toolkit.

The demo for signing and timestamp a PDF file requireds the iText libraries. Included in this distribution is a copy of iText - by Bruno Lowagie, Adolf Baeyensstraat 121, 9040 Gent, BELGIUM
- distributed under MOZILLA PUBLIC LICENSE Version 1.1, see file: MPL-1.1.txt
- The source code and original works are available at: http://www.lowagie.com/iText
- The changes made to the iText library are described in file: “PDF-Digital-signature-with-timestamp Jul 25, 2007.html”
- The version of the iText library included here is 2.0.4

Support Requests, Bug Reports, and Requests for Enhancements

Internet Email: support@digistamp.com
It is important to us that we receive your feedback and suggestions for improvement.

Sample Programs

Edit the file DigiStamp.properties to input your DigiStamp Account number and password before running the demo programs..

The sample programs are the quickest way to review and learn the toolkit. Documentation is included with the API documentation ( see package dgs.tlkt.demo ).

The source code for the demos is included with the toolkit delivery. This source also demonstrates using the underlying Java VM to perform signature and certificate chain verification.

1. Time Stamp a File

To run the sample programs, see the DemoTSfile.bat file in the "demo" directory where you installed the toolkit.

The demo program named ProductionProcess is a compact summary of the steps you would take in your client program.

2. Sign and Time Sample a PDF file

To run the sample programs, see the DemoPDF.bat file in the "demo" directory where you installed the toolkit.

The demo program named PdfSignerDemo has source code documentation that explains how to configure and run this demo.

This function requires 3 libraries:

1. DigiStamp Java Toolkit (included)
2. A modified version of iText (included)
3. BouncyCastle - You will need to download BouncyCastle from http://www.bouncycastle.org/latest_releases.html. We tested with bcprov-jdk16-141.jar, bcmail-jdk16-141.jar. Place these jars in directory: DigiStampJToolkit\demos\tsPDF\lib

There is additaional information on PDF signatures here: http://www.digistamp.com/acrobat.htm. After you create the new signed and times tamped file, please review this signature properties using Acrobat Reader and this method:

Technical notes

Proxy servers

Using the toolkit behind a proxy server requires VM level commands:

// configure the VM to use a communications proxy
System.getProperties().put("proxySet","true");
// your proxy server address:
System.getProperties().put("proxyHost","127.0.0.1");
// your proxy server port:
System.getProperties().put("proxyPort","80");

JIT. Use of the JIT run time optimizer in VM 1.1.8 and earlier causes failures in the toolkit and the JIT can not be used.

Failover testing and using TSATEST3. The toolkit has features to failover to another DigiStamp time stamp server if one fails to respond. This is described in the configuration class. To help you test failover capabilities you can specify TSATEST3 in your testing configuration. TSATEST3 is always in a "failed" condition.

SSL

The toolkit has a configuration value to set when you want to use SSL for Internet communications to the DigiStamp server. When using SSL you must provide a HTTPS protocol handler. For example, when using JSSE you will need to add this lines of code to be executed one time:

System.getProperties().put("java.protocol.handler.pkgs","com.sun.net.ssl.internal.www.protocol");
java.security.Security.addProvider(new com.sun.net.ssl.internal.ssl.Provider());

Starting with Java VM 1.4, SSL libraries are included in the J2SE run time. Priort to VM 1.4, you needed to have the 3 jar files that come with JSSE to your class path (jsse.jar jnet.jar jcert.jar). The toolkit has been tested with JSSE 1.0.2+. SSL is supported on our servers named: TSA1, TSA2 and TSATEST2

We have noticed that on the first Internet call that uses SSL from the VM there will be a performance penalty of about 6 or 7 seconds. On subsequent calls the penalty is about .2 or .3 seconds. Your results may vary. The initial penalty of 6 seconds is a little high. It seems that there is some overhead in calculating the initial random number for the SSL handshake. An customer tells us that their approach was to execute a "dummy SSL" call in a separate thread when the VM loads to resolve this initial performance hit.

Consider if you need to use SSL? We want you to consider your risks when you run withOUT SSL:
1. replay attack
2. the hash of your "document" is open on transmission
3. the returned time stamp is open on transmission

The verification of the time stamp upon receipt avoids the risk of spoofing and transmission errors; when not using SSL. Also, your password is never sent as clear text; SSL or not.

You need to judge the risks and importance. We can discuss with you further.

Change History

November 14, 2008 v2.3.2.Beta.1

Add a demo program to demonstrate signing and time stamping a PDF file. The structure of the delivery archive was changed to support additional demo programs.

May 14, 2006 v2.1

Add a demo program to verify a timestamp using source code libraries from BouncyCastle.

February 9, 2005 v2.1

The DigiStamp Internet servers now reports time in milliseconds and includes an expanded certificate chain-of-authority to verify the audit process. Added suppport for additional message digest algorithms, for example SHA-256. The API's general class structure was not changed, but method signatures and names were changed. We suggest looking at the demo source code that is included to see how method names have changed.

August 1, 2003 v1.2.4

Resolved issue where class files would not load in Java Bean IDE enviroment using VM 1.4.

June 26, 2001 v1.2.3

Resolved issue where "timeOut" configuration was being reduced to half the time specified.

June 20, 2001 v1.2.2

Support was added for retrieving the x.509 public key certificates as part of the resulting time stamp. Changes made to the "time stamp request" to request the certificates and changes to "CMSTsToken" to access the returned certificates. The example program "DemoTStlktVM13" was enhanced to demonstrate how you could use this certificate capability.

Support for TSA Policy was added to the time stamp request and the associated accessor on TstInfo.

April 12, 2001 v1.2

Class name changes:
DgsComm - was DgsCommTSR
DgsConfig - was PDGS_TIMESTAMP_PARA

Multi-threaded model support changes were implement using a different design. This is based on feedback from users. The class DgsComm no longer extend Thread. Example programs using SwingWorker utility demonstrate the new threading model.

Configuration enhancements allow a "time out" and "hold out" concept. Using these configurations you can set the length of time that you process waits for a response from the time stamp server before executing failover. Also, if a time stamp server does file to respond then it will not be used again for a user specified durations. See DgsConfig.

JavaDoc was upgraded to v1.2 format. Significant improvements in the content.

An additional example program was added and the existing examples improved.

October 15, 2000 v.1.1

Included an example for verifying the authenticity of a time stamp locally (no Internet call to DigiStamp). This requires the use of Java 2 SDK version 1.3 or an external provider of the RSA algorithm.

Upgraded to Draft 10 of the IETF Time Stamp Protocol. This resulted in changes to ‘clock accuracy’ accessors in class TstInfo. Time stamps created by previous version of the toolkit are still supported.

The class TsToken was removed to reduce the number of indirections. The class CMSTsToken was enhanced to contain the methods from the removed TsToken class.

September 5, 2000 v.1.1 Beta

Documentation upgrade
Resolve issue using ‘round robin’ did not fail over to second server

March 20, 2000 v.1.0 Beta