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 21 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).

A preset is a named bundle of signing settings that you can save once and reload with a single click. Presets are useful when you regularly switch between different configurations — for example, one with a timestamp authority enabled and one without, or different visible-signature layouts for different document types.

Presets capture everything in the Signing options reference (keystore, signature properties, visible-signature options, TSA, encryption and rights, OCSP/CRL, proxy). Passwords are included only if Store passwords is enabled at the time you save the preset; in that case they are encrypted with a machine-local seed tied to the current user account and are silently ignored on load if the preset file is used under a different user.home. If you want a preset without stored passwords, disable Store passwords before saving — no password keys are written to the file in that case. Loading a preset without passwords also clears any passwords already entered in the UI, so switching to a password-less preset never silently reuses credentials from an earlier selection. The currently loaded input and output file paths are not part of a preset.

Open File > Preferences…​ (shortcut Ctrl+, / ⌘,) for application-wide tweaks that fall outside the per-document signing options. The dialog has the following tabs:

Most settings apply immediately on OK. The two tabs marked Takes effect after restart — Network and PKCS#11 — only take effect on the next launch. Reset section to defaults restores the bundled defaults for the active tab only; other tabs keep their current values.

The values persist in <config-dir>/advanced.properties (see Advanced application configuration).

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):

Passing a password on the command line exposes it to every local process that can read /proc/<pid>/cmdline (and to shell history). To avoid that, JSignPdf can read password values from standard input (or, in an interactive terminal, from the console) instead.

Opt in with --enable-stdin-passwords and use - as the value of any password option. Any of the six password options can use the sentinel: -ksp, -kp, -opwd, -upwd, -tscp, -tsp.

When more than one option uses -, the values are consumed from stdin in a fixed canonical order regardless of the order in which they appear on the command line:

Before blocking on each read, JSignPdf prints a progress line such as [jsignpdf] Reading password for --keystore-password (1/2) from stdin…​ to stderr so you can verify the order matches what your pipe is feeding. Use -q / --quiet to suppress it.

When a console is attached (an interactive terminal), - switches to a prompted, no-echo read via java.io.Console.readPassword:

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.

In JSignPdf 2.x the same options lived in <install dir>/conf/conf.properties and the PKCS#11 provider was pointed to by a pkcs11config.path key in that file. Starting with 3.0.0 those files move under your per-user configuration directory:

The 3.0.0 distribution no longer ships an <install dir>/conf/ directory and there is no automatic migration of pre-3.0.0 install-dir tweaks. If you previously customized conf.properties or maintained a pkcs11.cfg, re-enter the values via the Preferences dialog — or copy your old files into <config-dir>/advanced.properties and <config-dir>/pkcs11.cfg by hand before launching 3.0.0.

Starting with JSignPdf 3.0.0, per-user state is stored in a platform-native configuration directory instead of a single file in your home folder. The directory holds the main config file (config.properties, which persists the last-used signing settings), a presets/ subdirectory (see Using presets), and — once you save changes from the Preferences dialog — the advanced-config files advanced.properties and pkcs11.cfg (see Advanced application configuration).

The default location depends on your operating system:

You can override the default by setting the JSIGNPDF_CONFIG_DIR environment variable to any directory path — useful for portable installs, scripted tests, or keeping multiple profiles side-by-side.

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.