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), ask the community in the JSignPdf Google Group.

Report bugs and request features in the issue tracker (https://github.com/intoolswetrust/jsignpdf/issues). Please don’t use it for usage questions — the Google Group is the place for those. Security vulnerabilities must not be reported as a public issue — use GitHub’s private vulnerability reporting instead, as described in the security policy.

Pull requests are welcome; CONTRIBUTING.md covers what to include in a bug report and what a pull request needs to pass.

Translations are maintained on Weblate and new languages are always welcome — no development environment required.

JSignPdf releases are available on the GitHub releases page:

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

Each release provides per-platform installers (each bundles its own Java 21 runtime) plus two cross-platform ZIPs for users who already have Java.

The Homebrew formula installs the cross-platform distribution against Homebrew’s openjdk@21 package and puts jsignpdf on the PATH for both the GUI and the CLI. The brew trust step is required because Homebrew refuses to load formulae from third-party taps until they are trusted.

jsignpdf-${VERSION}-SHA256SUMS.txt covers every artifact above. Releases are also mirrored on SourceForge.

The cross-platform ZIPs require 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 one of the native installers, four launchers are registered with the desktop environment and (on Linux and Windows) added to PATH:

All four launchers share the bundled JRE — you do not need to have Java installed separately.

After extracting jsignpdf-${VERSION}-full.zip (or -minimal.zip), launch JSignPdf from inside the extracted folder:

The launcher scripts find your JRE via JAVA_HOME, falling back to java on PATH. They invoke a small bootstrap class (com.intoolswetrust.jsignpdf.Bootstrap) which checks the Java version, picks the matching JavaFX platform jars from lib/javafx/ and then starts the application.

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 via JAVA_OPTS:

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 create the signature rectangle, hold Shift and drag directly on the document preview. The coordinates are updated automatically in the sidebar.

Once the signature rectangle is visible, it can be adjusted directly in the preview:

The mouse cursor changes according to the available operation. The preview also renders the configured signature text and images inside the rectangle, making it easier to position and size the signature before signing.

The preview reproduces the appearance of the OpenPDF engine. It is an approximation of the final result: the DSS engine wraps and insets the signature text slightly differently, so with that engine the preview shows the right content and placement, but the text may not break across lines exactly as it does in the signed document.

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, the input file name is combined with the Output suffix from the same panel, so document.pdf becomes document_signed.pdf.

The suffix is used exactly as typed, so it has to include the separator: signed produces document_signed.pdf and -DL produces document-DL.pdf. Because it becomes part of a file name, the field does not accept the path separators or reserved characters / \ : * ? " < > | (or leading/trailing spaces), and is limited to 40 characters. Leaving the field empty falls back to the configured default, which the field shows as its prompt text. The starting value comes from the output.suffix key, set by the Output file suffix field in the Preferences dialog; changing it in the _Signature Properties panel overrides it for the current document, is remembered for the next session, and is stored in a preset along with the other signing settings. Typing a full path into Output file always wins over the suffix.

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.

Documents that are meant to be signed by several people usually carry the signature boxes already: the form author pre-places an empty signature field for each signer ("Signature #1", "Signature #2"), and every signer fills their own box. JSignPdf can sign into such a field instead of creating a new one. The bundled demo/service-agreement.pdf carries one, so you can try this out right away — see Demo files.

Empty signature fields are shaded on the page preview as soon as a document is opened, so you can see where the boxes are before picking one. JSignPdf draws the shading itself, independently of the preview backend in use; fields with a zero-size or hidden widget are not shaded, because they are invisible in any viewer too.

In the JavaFX UI, the Signature field combo box at the top of the Signature Appearance panel lists the empty signature fields of the opened document. Pick one and the signature goes there; the selected field gets a stronger marker on the page preview and the position controls are switched off, because the field’s own rectangle decides where the signature lands. The live appearance preview follows the selected field, so the signature text and image are rendered inside its rectangle just as they are for a rectangle you draw yourself. Visible signature is turned on and locked (in the panel, the toolbar and the menu alike) for as long as a field is selected, because the appearance is always drawn into the field — switch back to (create new field) if you want an invisible signature, or pick a field whose rectangle has zero size, which gives one anyway. The combo stays on (create new field) for documents without empty fields, and the selection is reset whenever you open another document.

On the command line, -lsf shows what a document offers:

and -sf picks one of them:

Things worth knowing:

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.

A document timestamp (a DocTimeStamp with the ETSI.RFC3161 subfilter) proves that the bytes of a PDF existed at a point in time. It is not a signature: no private key is involved, nothing is claimed about who the document belongs to, and no signature field is filled. JSignPdf appends one with the --timestamp-only flag:

Two uses:

The operation needs the DSS engine — add -eng dss, or set engine=dss in advanced.properties once. The OpenPDF engine cannot produce document timestamps and refuses the operation with a message naming the missing DOC_TIMESTAMP capability. --tsa-server-url is mandatory, and all the other TSA options (--tsa-authentication, --tsa-user, --tsa-password, --tsa-policy-oid, --tsa-hash-algorithm, the TSA certificate options and the proxy options) apply unchanged.

In the JavaFX UI the same operation is the Timestamp toolbar button and Signing > Add Timestamp… (Ctrl+T / ⌘T). Both are enabled once a document is open and the DSS engine is selected; the certificate and appearance panels are not consulted. The TSA URL field is required regardless of the TSA toggle, which means "timestamp the signature I am about to make" — a different thing.

Things worth knowing:

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.

JSignPdf 3.1 bundles a second engine, EU DSS (PAdES) (id dss), built on the European Commission’s Digital Signature Service library. It produces PAdES signatures (ETSI.CAdES.detached) at the four ETSI baseline levels, which the OpenPDF engine cannot create:

Select it with -eng dss on the command line (or the PAdES Level sidebar section in the GUI) and pick the level with -pl / --pades-level:

DSS requires a PAdES digest, so the hash algorithm must be SHA256, SHA384 or SHA512 (SHA1/RIPEMD160 are rejected). Certificate-based PDF encryption and CloudFoxy external signing are not available with dss; use the OpenPDF engine for those.

Trust material for LT/LTA. The B and T levels work fully offline (only T needs network access to the TSA). The LT and LTA levels embed revocation data, so they need reachable OCSP/CRL endpoints and a trust anchor set. These are configured with engine.dss. keys in advanced.properties (also editable from the *DSS engine tab of the Preferences dialog):

If LT/LTA is requested but revocation data cannot be reached (for example, with online fetching disabled), the signing fails with a logged error rather than silently emitting a weaker level. The log also records which trust anchors were loaded and every AIA / CRL / OCSP call the engine made, which is usually enough to tell a network problem from a missing anchor — see Reading the signing diagnostics.

On the command line these keys can be set for a single run with -o (see General options), without editing advanced.properties:

LT and LTA extend a signature by appending validation material (the DSS dictionary) and, for LTA, an archive timestamp after the signature, as PDF incremental updates. This is required by the levels and is explicitly permitted by ISO 32000-2 and ETSI EN 319 142.

A certification signature (certification level other than NOT_CERTIFIED — i.e. CERTIFIED_NO_CHANGES_ALLOWED, CERTIFIED_FORM_FILLING, or CERTIFIED_FORM_FILLING_AND_ANNOTATIONS) records a DocMDP restriction on what may change after signing. Some strict PDF readers (for example Foxit) treat the LT/LTA additions as violating that restriction and report the document as modified or corrupted since it was signed, even though the signature validates on the official eIDAS/EU validators and in Adobe. To keep LT/LTA signatures compatible with the widest range of readers, leave the certification level at the default NOT_CERTIFIED.

Password-based PDF encryption combined with signing is likewise not honoured uniformly across readers. If a signed document must validate in third-party viewers, prefer an unencrypted document.

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 four bundled 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:

The app/ folder lives under the install root: %ProgramFiles%\JSignPdf\app\ on Windows, /opt/jsignpdf/lib/app/ on Linux, JSignPdf.app/Contents/app/ on macOS.

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

The same .cfg files are present inside the per-platform portable ZIPs (jsignpdf-${VERSION}-windows-x64.zip, jsignpdf-${VERSION}-linux-x64.zip, …​) under JSignPdf/app/ (Windows / Linux) or JSignPdf.app/Contents/app/ (macOS).

If you see an OutOfMemoryError in the program console, the document is bigger than the heap Java was given.

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:

With debug output enabled, JSignPdf logs the certificate material it uses and, for the DSS engine, every network call it makes while collecting validation data. This is what to look at when a signature fails for a reason that is not obvious from the error message itself.

Turn it on by ticking Debug output on the General tab of the Preferences dialog, or by setting debug=true in advanced.properties (it can also be set for a single CLI run with -o debug=true). It is off by default so normal runs stay quiet. Everything below is emitted only while it is on.

Certificate chain. Right after the key is loaded, the whole signing chain is dumped — one block per certificate, leaf first:

The id=C-…​ value is the identifier the DSS engine uses in its own error messages, so a No revocation data found for C-…​ failure can be matched to a real certificate without inspecting it with openssl. A certificate outside its validity window is flagged with (EXPIRED) / (NOT YET VALID) next to the dates. The timestamp token’s own chain is dumped the same way once the TSA has answered.

Trust anchors (DSS engine). Each configured engine.dss.trust.* source is logged with the number of anchors it contributed, followed by the total. A total of 0 means nothing is trusted at all — a configuration problem — as opposed to a specific CA simply not being covered:

Revocation and issuer downloads (DSS engine). For LT/LTA, every AIA, CRL and OCSP call is reported twice: once for the HTTP request (URL, response size, elapsed time, or the failure) and once for what the answer meant, naming the certificate it was for:

A FAILED line names the responder that could not be reached and why — the usual cause of an LT/LTA failure behind a proxy or a firewall (see Proxy settings). A no CRL data / no OCSP data line means the certificate itself carries no matching distribution point, which no amount of trust configuration can fix.

These messages are logged at the FINE level, which debug=true enables. The -q / --quiet flag silences all output (including the normal progress messages) regardless of the debug setting; for full control over what is logged, point Java at your own configuration with JAVA_OPTS=-Djava.util.logging.config.file=<file>.

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

When installed via a native installer (MSI / DEB / RPM / DMG / Flatpak) it is exposed as the InstallCert launcher:

From a cross-platform ZIP the tool is reachable via java -cp against the bundled jars:

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.