JOIN OUR AFFILIATE NETWORK

Join our affiliate network and become a local SSL expert

♦ learn more about our program ♦
Menu
picture of tbs certificates
picture of tbs certificates
Certificates
Our products range
Partners
Support
Focus


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 to be validated to
-location location: entity location. Example: CAEN (France) at
-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:

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