DOCSEARCHbyAlgolia
Submit Docs

JSignPdf Documentation

repository·master·Indexed 19 days ago

https://github.com/intoolswetrust/jsignpdf

A Java-based desktop application and command-line tool for adding digital signatures to PDF documents. It supports PKCS#12, PKCS#11, and Java keystores, RFC 3161 timestamping, and long-term validation (LTV) via CRL/OCSP embedding. Features include visible signature placement, targeting pre-placed signature fields, and PAdES LT/LTA signature generation using the EU DSS engine.

Tokens
43.1K
Snippets
94
Records
171
Agent score
62%

What's inside JSignPdf

  1. Overview of JSignPdf features

    master

    JSignPdf is a Java desktop application for adding digital signatures to PDF documents. Key capabilities include:

    • UI Options: Primarily uses a JavaFX desktop UI with PDF preview and drag-to-place visible signatures. You can switch to the legacy Swing UI using the system property -Djsignpdf.swing=true.
    • Keystores: Supports PKCS#12, Java keystore, and PKCS#11 (for hardware tokens, smartcards, and HSMs).
    • Timestamping: Supports RFC 3161 TSA with optional authentication.
    • LTV (Long-Term Validation): Supports CRL and OCSP embedding.
    • Signing Engines: Uses pluggable backends. The default is OpenPDF. The bundled EU DSS engine produces PAdES signatures at baseline levels B / T / LT / LTA (use --pades-level to specify).
    • Automation: Includes a command-line / batch mode with full parity to the GUI for non-interactive signing.

  2. Available JSignPdf Windows Artifacts

    master

    JSignPdf provides several distribution formats for Windows x64. Note that 32-bit Windows support has been dropped in favor of x64-only installers. For non-Windows users or 32-bit users, the cross-arch ZIP is provided.

    Windows x64 Artifacts (via jpackage):

    • JSignPdf-${VERSION}-win-x64.exe: A WiX-based EXE installer including an MPL-2.0 license page.
    • JSignPdf-${VERSION}-win-x64.msi: A WiX-based MSI installer including an MPL-2.0 license page.
    • JSignPdf-${VERSION}-win-x64.zip: A portable app-image containing a bundled JRE.

    Cross-Architecture Artifact:

    • jsignpdf-${VERSION}.zip: A cross-arch, no-JRE distribution. This is intended for users who wish to run JSignPdf using their own existing JRE (including 32-bit users, Linux, or Mac users).

  3. What is included in a signature preset?

    master

    A preset captures your signing configuration but does not capture session state (like recent files or window positions).

    Included in presets:

    • Keystore: ksType, ksFile, keyAlias, keyIndex.
    • Passwords: ksPasswd, keyPasswd, pdfOwnerPwd, pdfUserPwd, tsaPasswd, tsaCertFilePwd.
    • Signature Metadata: signerName, reason, location, contact.
    • Visuals: visible, page, positionLLX/Y/URX/Y, bgImgScale, renderMode, l2Text, l4Text, l2TextFontSize, imgPath, bgImgPath, acro6Layers.
    • TSA & Encryption: All tsa.* keys, PDF encryption, rights, OCSP/CRL, and proxy settings.

    Excluded from presets:

    • Recent-file list, last-used input/output paths, and window geometry.

  4. Compare OpenPDF 3.x and PDFBox 3.x for JSignPdf signing capabilities

    master

    This comparison evaluates the two primary PDF library candidates for JSignPdf's signing engine.

    OpenPDF 3.x is effectively API-compatible with the current JSignPdf codebase. It provides high-level, 'Direct' APIs for most signing tasks, including core CMS signing, signature metadata, visible signature appearance (including layered text), and TSA/OCSP/CRL embedding. Migration to OpenPDF 3.x is largely mechanical, involving a package rename from com.lowagie to org.openpdf and a change in the PdfStamper.createSignature method where the PDF-version parameter type changed from char to String.

    PDFBox 3.x provides the necessary cryptographic primitives but requires more 'Manual' assembly for high-level signing features. While it is superior for PAdES-LTV support (which OpenPDF does not support), it lacks built-in high-level APIs for visible signature layers (n2/n4), TSA/OCSP/CRL embedding helpers, and specific signature appearance modes. Using PDFBox would require implementing custom logic for layered XObjects and managing the TSA/OCSP HTTP clients manually.

  5. Canonical password read order for stdin

    master

    When using --enable-stdin-passwords and multiple password options are marked with -, JSignPdf consumes values from stdin in a fixed, deterministic order. This order is independent of how the options appear on the command line.

    When scripting, you must feed passwords in this exact sequence:

    1. --keystore-password (-ksp)
    2. --key-password (-kp)
    3. --owner-password (-opwd)
    4. --user-password (-upwd)
    5. --tsa-cert-password (-tscp)
    6. --tsa-password (-tsp)

    This fixed order allows callers to skip lines in their input stream if they are not providing certain passwords.

  6. Understand the fallback policy for file dialogs

    master

    If the XDG Desktop Portal backend fails (e.g., due to a DBus error, an unrecoverable response, or a signal that never arrives), JSignPdf follows this fallback policy:

    1. Immediate Fallback: The application immediately attempts to open the standard JavaFX (fx) chooser so the user's workflow is not interrupted.
    2. One-Time Notification: After the fallback dialog closes, a single non-modal Alert is shown to the user with the following text:
      • Title: File dialog
      • Body: Could not open the system file dialog. Using the built-in one instead.
    3. Session Restriction: Once a portal failure occurs, the application sets portalDisabledThisSession=true. The application will not attempt to use the portal again for the remainder of the session; it will use the fx backend exclusively.

  7. Understand the Linux Sandbox File Chooser behavior

    master

    When running JSignPdf inside a Linux sandbox (like Flatpak or Snap), the application attempts to use the XDG Desktop Portal to provide a native file selection experience.

    Activation Logic

    The portal file chooser is activated only if the application detects it is running in a sandbox via the presence of:

    • /.flatpak-info
    • FLATPAK_ID
    • SNAP environment variables

    Fallback Mechanism

    If the portal is unreachable or fails, JSignPdf follows a specific failure sequence to minimize user interruption:

    1. Immediate Fallback: The built-in JavaFX file chooser is opened immediately.
    2. Deferred Notification: A single Alert(WARNING) is shown after the JavaFX chooser is closed. This alert informs the user: "Could not open the system file dialog. Using the built-in one instead."
    3. Session-level suppression: The warning alert is only shown once per session to avoid spamming the user if multiple failures occur.

  9. Understand JSignPdf configuration and preset locations

    master

    JSignPdf 3.0.0+ uses platform-specific, XDG-compliant locations for configuration. If no override is provided via JSIGNPDF_CONFIG_DIR, the application resolves paths as follows:

    PlatformDefault Location
    Linux / BSD / Unix$XDG_CONFIG_HOME/jsignpdf/ (if set) or $HOME/.config/jsignpdf/
    Windows%APPDATA%\JSignPdf\ (or %USERPROFILE%\AppData\Roaming\JSignPdf\ if %APPDATA% is unset)
    macOS$HOME/Library/Application Support/JSignPdf/

    Note on Migration: If you are upgrading from a version prior to 3.0.0, the application will automatically migrate your existing ~/.JSignPdf file to the new config.properties location within the new directory structure. The legacy file is left in place to support downgrades.

  10. Use the EU DSS (PAdES) signing engine

    master

    The dss engine (ID: dss) is a pluggable backend that produces PAdES signatures at four ETSI baseline levels. It is required for long-term validation (LTA).

    PAdES Levels

    LevelDescription
    BBasic signature (default when dss is selected)
    TB + a signature timestamp (automatically upgraded if a TSA is configured)
    LTT + embedded validation material (certificates and OCSP/CRL responses)
    LTALT + an archive timestamp

    Requirements and Limitations

    • Hash Algorithms: Must use SHA256, SHA384, or SHA512. SHA1 and RIPEMD160 are rejected.
    • Incompatible Features: Certificate-based PDF encryption and CloudFoxy external signing are not available with the dss engine.
    • Trust Material: For LT and LTA levels, the engine needs reachable OCSP/CRL endpoints and a configured trust anchor set (configured via engine.dss.* keys).
    # Sign with PAdES Level LT using the DSS engine
jsignpdf -eng dss -pl LT -ksf cert.p12 -ksp secret -ha SHA256 document.pdf

  11. Use the EU LOTL Official Journal (OJ) keystore

    master

    The eu-oj-keystore.p12 keystore is used to validate the signature of the EU List of Trusted Lists (LOTL) itself via LOTLSource.setCertificateSource(...).

    Important: This keystore is NOT a trust anchor for document signers. Document signer trust is managed via engine.dss.trust.truststoreFile.

    Keystore Details

    • Type: PKCS12
    • Default Password: dss-password (consistent with DSS demonstrations convention)
    • Default Loading Method: DssTrustConfigurer.ojKeystoreCertificateSource() using the OJ_KEYSTORE_RESOURCE constant.

    Runtime Configuration

    You can override the default keystore settings at runtime using the following configuration keys:

    • engine.dss.trust.eu.ojKeystoreFile
    • engine.dss.trust.eu.ojKeystorePassword

  12. Important constraints for JSignPdf Windows packaging

    master

    When modifying the packaging process or maintaining the installer, adhere to these critical constraints:

    • Stable Upgrade UUID: The --win-upgrade-uuid is fixed at 7b3d6e4c-9a51-4a8b-9b1c-7e8c1a4d2f10. This must not be regenerated, as it ensures that MSI upgrades are recognized correctly by Windows (allowing a single entry in Add/Remove Programs).
    • WiX Version: jpackage on JDK 17+ requires WiX 3.x.
    • Version Formatting: The jpackage --app-version flag only accepts numeric formats (MAJOR[.MINOR[.MICRO]]). Non-numeric suffixes like -SNAPSHOT or -RC1 must be stripped before passing the version to jpackage.