JSignPdf User Guide

JSignPdf is released under LGPL and/or MPL license. It can be freely used for both personal and commercial use. For details look directly to the license files.

The project started at the beginning of 2008.

A greater change comes in 2021, where the project was switched to use the OpenPDF library instead of the old version of the iText library.

Starting with version 3.0.0, JSignPdf ships with a new document-centric JavaFX interface as the default graphical frontend. The classic Swing GUI remains available for backward compatibility.

The author of JSignPdf is Czech developer Josef (kwart) Cacek. He works in Java since 2000. Some links to Josef’s projects:

If you don’t find the relevant information in this document or on the JSignPdf GitHub page (https://github.com/intoolswetrust/jsignpdf), use the JSignPdf Google Group to ask the community.

JSignPdf Google Group

JSignPdf releases are available on the GitHub releases page:

https://github.com/intoolswetrust/jsignpdf/releases

Each release provides the following artifacts:

If you use the platform-independent ZIP archive, you need Java Runtime Environment (JRE) version 11 or newer. You can download it freely from the web, for instance:

To sign PDF documents you need a keystore containing your private key. If you don’t have one yet:

The most common keystore types supported by Java are:

JSignPdf has been also extended to support external keystore types like smart cards, or network HSMs. The first example is CloudFoxy (https://gitlab.com/cloudfoxy).

Every release bundles a small demo/ folder so you can try JSignPdf immediately without generating your own certificate or finding a sample PDF:

You can find the folder:

When JSignPdf is installed via the Windows EXE / MSI installer (or extracted from the win-x64.zip portable archive), four launchers are available:

All four launchers share the bundled JRE — you do not need to have Java installed separately. For installer-based deployments the launchers live in <install dir>\ (with Start Menu shortcuts to the GUI launchers); in the portable ZIP they are directly in the extracted folder.

All platforms (with Java 21 or newer installed) can run the JAR file JSignPdf.jar directly. Use the following command in the directory where the application is located:

On Linux and macOS a convenience shell script is bundled in bin/jsignpdf.sh which adds the JVM options required on Java 21+ and then launches the JAR.

By default, JSignPdf opens the JavaFX graphical interface (see Using the JavaFX UI). To start the classic Swing GUI instead, set the jsignpdf.swing system property:

If command line arguments for signing are provided, JSignPdf runs in batch mode without opening any GUI (see Command line (batch mode)).

When JSignPdf starts, the main window is empty and invites you to load a document. You can either drag and drop a PDF file onto the window or use File > Open (or the Open button in the toolbar).

Once a PDF is loaded, the document preview appears on the right, and the configuration panels on the left become active. The status bar at the bottom shows the file name and page count.

The left sidebar contains five collapsible panels that expose all signing options. Expand a panel by clicking its header.

At a minimum, you need to select a keystore and provide its password in the Certificate panel. All other options have sensible defaults.

To add a visible signature to the PDF, enable Visible signature in the Signature Appearance panel. You can then configure the render mode, signature text, status text, images, and font size.

To position the signature on the page, hold Shift and drag a rectangle directly on the document preview. The coordinates are updated automatically in the sidebar.

When you are ready, click the Sign button in the toolbar. JSignPdf signs the document and displays the result in the Output Console at the bottom of the window.

The signed PDF is saved to the output path shown in the Signature Properties panel. By default, it is the input file name with a _signed suffix (e.g. document_signed.pdf).

See Keystore selection and Key alias & key password for details.

See Signing properties for details.

See Visible signature options for details.

See Encryption for details.

See TSA — timestamps and Certificate revocation checking for details.

See Proxy settings for details.

Sign a PDF using the Windows certificate store:

Sign and encrypt a PDF, disabling printing:

List available keystore types:

List key aliases in a keystore (quiet mode):

JavaFX panel: Certificate

The Keystore means the location where the private keys are located.

By default, JSignPdf displays keystore types provided by Java Runtime itself and the Bouncy Castle cryptographic provider.

JSignPdf has been extended to support remote/external keystore types. The first entry is "CloudFoxy" (https://gitlab.com/cloudfoxy), which is a REST API for physical smart cards, initially developed to support eIDAS signatures.

If you use PKCS#12 or Java keystore types (JKS, JCEKS), you have to select the file where the keys are stored and provide the password of this file. Path to the keystore file can be inserted directly by typing or you can use the browse button to navigate through the file system with Open File Dialog.

JavaFX panel: Certificate

When you have more private keys stored in the keystore, you can select which one will be used to sign the PDF file by filling the Key alias field. Either you can type alias name directly (combo box is editable) or you can load all names by pressing the Load keys button and then select one from the drop-down list.^[1]

If you don’t fill the Key alias field the first alias read from keystore will be used.

Each key in the keystore can be protected with its password. If this password differs from the password of keystore, fill it in the Key password input field.

JavaFX panel: Signature Properties

JavaFX panel: Encryption & Rights

The Encryption option enables additional fields for support of PDF security. By using this you can either sign secured PDFs (and change the rights and user password) or you can add encryption to unencrypted PDF during the signing.

JavaFX panel: Signature Appearance

Enabling the Visible signature option allows you to create a visible field with signature directly in the signed PDF. You can configure parameters (position/texts/images) of the visible signature.

JavaFX panel: Timestamp & Validation

To add a timestamp to the signature you will need a timestamping authority (TSA). Fill the server address into the TSA URL field and if the server requires authentication, choose the authentication type and fill either the TSA User and TSA Password fields or the path to the certificate’s private key (it has to be a PKCS#12 keystore) and the password. You can also set TSA Policy OID, which will be sent to the TSA server in the request, but typically the server uses the right policy by itself.

JavaFX panel: Timestamp & Validation

JSignPdf supports two standard ways of certificate revocation checking — CRL and OCSP. Most X.509 certificates support CRL, but it has some disadvantages (for instance the size of the list and possibly outdated information). OCSP solves these issues, but not all Certification Authorities (CA) support it.

If some "online" feature (TSA, CRL, OCSP) is enabled and JSignPdf runs behind a firewall, you can set the proxy, which will be used for all internet connections. Proxy type DIRECT means no proxy will be used.

The property file conf/conf.properties contain several option groups:

If you need to change JVM properties for the Windows launchers (for example to increase the maximum heap), edit the corresponding .cfg file under the app subfolder of the installation. jpackage creates one .cfg per launcher:

Each .cfg file contains a [JavaOptions] section with one java-options= entry per option. Add additional options as further java-options= lines, for example:

If you see an OutOfMemoryError in the program console, you need to allow Java to use more memory.

When running from the platform-independent ZIP, add -Xmx<size> to your Java command. The following example allows Java to use 512 MB of heap:

When running from the Windows EXE / MSI / portable ZIP, add a new java-options=-Xmx512m line to the .cfg file of the affected launcher (see Java VM options for the Windows EXE launchers).

When JSignPdf connects to a server through HTTPS (e.g. to a TSA server for timestamping), it may fail with a SSLHandshakeException. This happens because Java ships with a keystore of trusted root certificates (cacerts), and if the server’s certificate is not signed by one of these trusted authorities, the connection is refused.

If you trust the server, you can add its certificate to the Java cacerts keystore using the bundled InstallCert tool (see InstallCert Tool).

If JSignPdf doesn’t list your certificate when you press Load keys:

If timestamping fails:

JSignPdf comes with a command line utility for adding server certificates to the Java cacerts keystore. This is useful when connecting to HTTPS servers whose certificates are not signed by a well-known CA (see SSL/TLS certificate errors).

If you don’t provide a hostname argument, you will be asked for it.

The certificate chain will be displayed and you can choose which one will be imported.