TBSSignaturePDF signature tool
Case in general
It is a command line tool that allow to edit a PDF document in order to sign it. easy to use, this tool does not require any installation. Just download it and copy it in the repertory from which it will be executed.
Here is the launch command:
java -jar TBSSignaturePDF.jar -in xxx -pkcs12 xxx -passwd xxx
This tool has several optional functions (timestamping for example). With a timestamp it is possible to know the exact date and time of the signature.
The tool can be used under Windows and Linux. It has been developed in a Java 1.6 environment.
Parameters
The tool has several arguments gathered in 2 categories:
Mandatory parameters:
-in PDFfile -pkcs12 pkcs12file -passwd password -alias cert-name
Optional parameters:
-out signedPDFfile -mode PPK* -reason reason -location location -visibleSignature -visibleSignllx 50 -visibleSignllx 75 -visibleSignurx 100 -visibleSignury 100 -visibleSignNumPage 5 -tsaHost http://url.com/tsa -tsaLogin login -tsaPasswd passWord -proxyHost host -proxyPort port -proxyLogin login -proxyPasswd passwd
Parameters details
-in PDFfile: file to sign
-pkcs12: pkcs12 file (.p12 or .pfx format)
-passwd: pkcs12 fil password
-out signedPDFfile: destination file. By default: signed.pdf
-mode PPK*: PPKMS, PPKVS, PPKLite modes. By default: PPKMS
-reason reason: Signature reason. Example: document validated
-location location: entity location. Example: CAEN (France)
-visibleSignature: conspicuous signature display on the document
-visibleSignllx: x coordinate of the bottom left hand corner of the signature (by default 100)
-visibleSignlly: y coordinate of the bottom left hand corner of the signature (by default 100)
-visibleSignurx: x coordiante of the top right hand corner of the signature (by default 200)
-visibleSignury: y coordiante of the top right hand corner of the signature (by default 200)
-visibleSignNumPage: page number on which the signature is going to be displayed (by default 1)
-alias: specification of a certificate alias contained in the keystore to be used
-tsaHost: timestamping authority address
-tsaLogin: timestamping authority connection login
-tsaPasswd: timestamping authority connection password
-proxyHost host: specifies the proxy address
-proxyPort port: specifies the proxy port
-proxyLogin login: specifies the login to be used on the proxy (if needed)
-proxyPasswd passwd: specifies the password to be used on the proxy (if needed)
Timestamping
why timestamping your documents? Timestamping associates a creation hour to your document. Timestamping is done by a external server considered as "trusted".
It can be compared to a postmark, the date on the stamp is the real date of sending.
To do so you need to go through an external server. Our certificates can use Comodo's signature server: http://timestamp.comodoca.com/rfc3161.
Maybe you use a proxy? If so, timestamping request cannot be sent. To troubleshoot, indicate the proxy parameters via the different parameters "-proxyHost", "-proxyLogin", "-proxyPasswd".
Signature certificate
The pkcs12 file used by the tool is a keystore.
What's a keystore?
It is a file containing several certificates. In order to differentiate them we use an "alias". an alias is a unique identification chain in the store. For the tool to know wich certificate to use in the store, specify the alias matching the signature certificate. If not, it will use the first certificate of the keystore.
How to find the certificate alias to use?
we are going to use Keytool. Enter the following command in a terminal:
keytool -storetype pkcs12 -v -list -keystore "/paths/keystore.p12" | grep "Alias name"
Indicate the path to your keystore (instead of "/path/keystore.p12") .
You should get:
alias name: cert1
In that case, we will use the signature tool with the argument
-alias cert1.
Example
Signature of the mydoc.pdf PDF file with the clef1 certificate contained in the mykey.pfx store.
java -jar TBSSignaturePDF.jar -in mydoc.pdf -pkcs12 mykey.pfx -passwd mykeypwd -alias clef1
Signature of the mydoc.pdf PDF file with a destination file
java -jar TBSSignaturePDF.jar -in mydoc.pdf -pkcs12 mykey.pfx -passwd mykeypwd -out mydoc_signed.pdf
Nota: for files names, indicate absolute paths.
Signature of the mydoc.pdf PDF file with timestamping thanks to the server http://timestamp.comodoca.com/rfc3161
java -jar TBSSignaturePDF.jar -in mydoc.pdf -pkcs12 mykey.pfx -passwd mykeypwd -alias clef1 -tsaHost http://timestamp.comodoca.com/rfc3161
Signature of the mydoc.pdf PDF file with timestamping thanks to the server http://timestamp.comodoca.com/rfc3161 needing a login/password connection
java -jar TBSSignaturePDF.jar -in mydoc.pdf -pkcs12 mykey.pfx -passwd mykeypwd -alias clef1 -tsaHost http://timestamp.comodoca.com/rfc3161 -tsaLogin user1 -tsaPasswd s3cret
Signature of the mydoc.pdf PDF file with timestamping thanks to the server http://timestamp.comodoca.com/rfc3161 through a proxy with identification
java -jar TBSSignaturePDF.jar -in mydoc.pdf -pkcs12 mykey.pfx -passwd mykeypwd -alias clef1 -tsaHost http://timestamp.comodoca.com/rfc3161 -proxyHost 192.168.20.02 -proxyLogin userProxy -proxyPasswd passProxy
Issues
if you encounter that kind of mistake:
java.io.IOException: exception unwrapping private key - java.security.InvalidKeyException: Illegal key size ...
due to the use of a too big a key (> 1024-bit), here is how to troubleshoot:
- consult Oracle website to retrieve the JCE Unlimited Strength Jurisdiction Policy Files.
- Unzip the archive.
- Place the "local_policy.jar" and "US_export_policy.jar" files in the lib/security file of your Java installation repertory.
It deletes the Java restrictions on authorized key sizes. You can now use keys over than 1024-bit long.
under MacOS Lion and higher
Installing JAVA on MAC OS: http://java.com/fr/download/mac_download.jsp?locale=fr
Download "Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 7":
http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html
Usually java is installed on user machines as an internet plugin in the file:
/Library/Internet\ Plug-Ins/JavaAppletPlugin.plugin
Then, the files "local_policy.jar" and "US_export_policy.jar" must be copied in:
/Library/Internet Plug-Ins/JavaAppletPlugin.plugin/Contents/Home/lib/security
and in order to execut the command line you can use the JAVA command here:
/Library/Internet\ Plug-Ins/JavaAppletPlugin.plugin/Contents/Home/bin/java
Credits
We'd like to thank Bruno Lowagie and Paulo Soares for the classes they publicly released under GPL license and that eased this tool development.
Additional script
To ease the tool use, here is a bash script that allow to store the by default parameters, and prevent to enter the password on a command line (no history).
Use: signed-pdf.sh pdf-name.pdf ["signature reason"]
Just download the program and edit the 13 first variables to adapt to your environment.
example of use:
$ pdf-signed 20070119_tarifs_tbs-certificats.pdf "approved tariffs" /cert/20100120-staff-tag.pfx Password of the above certificate? ---------------------------------------------------------- Welcome to the PDF documents signature program You want to sign the 20070119_tarifs_tbs-certificats.pdf.nosig document with the certificate /cert/20100120-staff-tag.pfx of alias cert1 by using PPKMS mode You want to timestamp the document with the server: http://timestamp.comodoca.com/rfc3161 Reason: approved tariffs Location: TBS INTERNET - Caen Step 1 : KeyStore and key loading. KeyStore OK Private key OK Step 2: files management. Files OK Step 3: signature + timestamp token appending. The PDF documents signature program completed successfully. The signed pdf is stored here: 20070119_tarifs_tbs-certificats.pdf