### Run InstallCert Tool (Native Installer)

Source: https://github.com/intoolswetrust/jsignpdf/blob/master/website/docs/JSignPdf.adoc

Execute the InstallCert tool from a native installer. It can be run with or without a hostname and optional password.

```bash
$ InstallCert

or

$ InstallCert hostname[:port] [cacertPwd]
```

--------------------------------

### Local Development Setup

Source: https://github.com/intoolswetrust/jsignpdf/blob/master/website/README.md

Commands to set up and run the Hugo development server locally. Run these commands in the website directory.

```bash
cd website
hugo mod get -u github.com/imfing/hextra   # first time only
./prepare.sh
hugo server                                # http://localhost:1313/jsignpdf/
```

--------------------------------

### Example CLI Error for Unsupported PAdES Level

Source: https://github.com/intoolswetrust/jsignpdf/blob/master/design-doc/3.1-engine-dss.md

This example shows the error message displayed when the selected engine does not support the specified PAdES level option. Use --list-engines to see available engines.

```bash
jsignpdf --pades-level LTA contract.pdf
ERROR: The selected engine 'openpdf' does not support the following options:
  --pades-level     (capability PADES_BASELINE_LTA)
Use --list-engines to see available engines.
```

--------------------------------

### Engine Mismatch Error Example

Source: https://github.com/intoolswetrust/jsignpdf/blob/master/design-doc/3.1-signing-engines.md

This example demonstrates the error message produced when the selected engine does not support a requested option. The error lists all unsupported options and the active engine.

```bash
jsignpdf --engine pdfbox -L "%signer\n%timestamp" foo.pdf
ERROR: The selected engine 'pdfbox' does not support the following options:
  --l2-text         (capability VISIBLE_LAYER2_TEXT)
Use --list-engines to see available engines.
```

--------------------------------

### Configure PKCS#11 Configuration File

Source: https://github.com/intoolswetrust/jsignpdf/blob/master/website/docs/JSignPdf.adoc

Example content for a basic PKCS#11 configuration file used to connect to a hardware token. This file is typically placed at `<config-dir>/pkcs11.cfg`.

```properties
name=Test
library=/path/to/your/PKCSDriver.so
```

--------------------------------

### Live Preview JSignPdf Website (Docker)

Source: https://github.com/intoolswetrust/jsignpdf/blob/master/website/README.md

Starts a live preview server for the JSignPdf website using Docker. Accessible at http://localhost:1313/jsignpdf/. Ensure JSIGNPDF_VERSION is set.

```bash
# Live preview at http://localhost:1313/jsignpdf/
docker run --rm -it -p 1313:1313 -e JSIGNPDF_VERSION=3.0.0-BETA-3 \
  -v "$PWD:/src" -w /src/website hugomods/hugo:exts \
  sh -c './prepare.sh && hugo server --bind 0.0.0.0 --baseURL http://localhost:1313/jsignpdf/'
```

--------------------------------

### Configure Java VM Options

Source: https://github.com/intoolswetrust/jsignpdf/blob/master/website/docs/JSignPdf.adoc

Add Java VM options to the .cfg file for native installers to increase memory allocation.

```config
java-options=-Xmx512m
```

--------------------------------

### Configure PKCS#11 with Slot

Source: https://github.com/intoolswetrust/jsignpdf/blob/master/website/docs/JSignPdf.adoc

Example PKCS#11 configuration file specifying a particular slot for the hardware token. This is useful when multiple certificates are present on the token.

```properties
name=Test
library=/path/to/your/PKCSDriver.so
slot=2
```

--------------------------------

### Generate a Self-Signed Keystore

Source: https://github.com/intoolswetrust/jsignpdf/blob/master/website/content/quickstart/_index.md

Use the `keytool` command to generate a self-signed keystore for testing purposes. Ensure you have Java Development Kit (JDK) installed.

```shell
keytool -genkeypair -alias mykey -keyalg RSA -keysize 2048 \
    -keystore keystore.p12 -storetype PKCS12
```

--------------------------------

### Create and Configure NSS Database for PKCS#11 Testing

Source: https://github.com/intoolswetrust/jsignpdf/blob/master/README.md

This script sets up a temporary NSS database to simulate a PKCS#11 token. It installs necessary tools, creates a password file, initializes an NSS database, and generates a self-signed certificate. This allows testing the PKCS#11 keystore type in JSignPdf without actual hardware.

```bash
sudo apt install -y libnss3-tools

echo "pass123+" > /tmp/newpass.txt
echo "dsadasdasdasdadasdasdasdasdsadfwerwerjfdksdjfksdlfhjsdk" > /tmp/noise.txt
mkdir /tmp/nssdb

MODUTIL_CMD="modutil -force -dbdir /tmp/nssdb"
$MODUTIL_CMD -create
$MODUTIL_CMD -changepw "NSS Certificate DB" -newpwfile /tmp/newpass.txt

certutil -S -v 240 -k rsa -n "CN=localhost" -t "u,u,u" -x \
         -s "CN=localhost" -d /tmp/nssdb \
         -f /tmp/newpass.txt -z /tmp/noise.txt

# Workaround for https://bugzilla.redhat.com/show_bug.cgi?id=1760437
touch /tmp/nssdb/secmod.db

mkdir -p ~/.config/jsignpdf

cat <<EOT >~/.config/jsignpdf/pkcs11.cfg 
name=testPkcs11
nssLibraryDirectory=/usr/lib/x86_64-linux-gnu
nssSecmodDirectory=/tmp/nssdb
nssModule=keystore
EOT
```

--------------------------------

### Platform Script with JSIGNPDF_LIB_DIR

Source: https://github.com/intoolswetrust/jsignpdf/blob/master/design-doc/3.1-separate-release-steps.md

This example shows how platform-specific build scripts (`build-linux-installers`, `build-macos-installers`, `build-windows-installers`) can be configured to use an external library directory via the `JSIGNPDF_LIB_DIR` environment variable.

```bash
# Example usage within a script (not a direct snippet from source):
# If JSIGNPDF_LIB_DIR is set, use it; otherwise, default to distribution/target/appassembler/lib
LIB_DIR=${JSIGNPDF_LIB_DIR:-distribution/target/appassembler/lib}

# ... script logic using $LIB_DIR ...
```

--------------------------------

### Launch JSignPdf from Cross-Platform ZIP (Windows)

Source: https://github.com/intoolswetrust/jsignpdf/blob/master/website/docs/JSignPdf.adoc

Execute the JSignPdf launcher script from the extracted ZIP archive on Windows. This starts the default JavaFX graphical interface.

```cmd
> bin\jsignpdf.cmd       # Windows
```

--------------------------------

### Java VM Options Configuration

Source: https://github.com/intoolswetrust/jsignpdf/blob/master/website/docs/JSignPdf.adoc

Example of how to configure Java Virtual Machine options in a .cfg file for JSignPdf launchers. This is useful for increasing heap size or setting other JVM properties.

```ini
[JavaOptions]
java-options=--add-exports=java.base/sun.security.util=ALL-UNNAMED
java-options=-Xmx1g
java-options=-Dswing.aatext=true
```

--------------------------------

### Basic JSignPdf Signing with OpenPDF

Source: https://github.com/intoolswetrust/jsignpdf/blob/master/website/docs/JSignPdf.adoc

Example of signing a PDF document using the OpenPDF engine on the command line. Ensure the 'cert.p12' keystore and 'document.pdf' are accessible.

```shell
jsignpdf --engine openpdf -ksf cert.p12 -ksp secret document.pdf
```

--------------------------------

### Launch JSignPdf from Cross-Platform ZIP (Linux/macOS)

Source: https://github.com/intoolswetrust/jsignpdf/blob/master/website/docs/JSignPdf.adoc

Execute the JSignPdf launcher script from the extracted ZIP archive on Linux or macOS. This starts the default JavaFX graphical interface.

```bash
$ bin/jsignpdf.sh        # Linux / macOS
```

--------------------------------

### Build JSignPdf with Maven

Source: https://github.com/intoolswetrust/jsignpdf/blob/master/README.md

Use this command to clean and install the JSignPdf project using Apache Maven. The resulting artifacts will be located in the 'distribution/target/' directory.

```bash
mvn clean install
```

--------------------------------

### Release Notes Markdown Format Example

Source: https://github.com/intoolswetrust/jsignpdf/blob/master/distribution/doc/release-notes/README.md

This is the standard structure for a release notes file. It includes a version header, an introductory paragraph, and a flat bulleted list for changes. Inline code and bold text are the only allowed markup.

```markdown
# Version X.Y.Z

One short intro paragraph summarising the release. Plain prose, no links.
(A blank line starts a second intro paragraph if you really need one.)

- **Bold lead-in** followed by a sentence or two describing the change.
- Another item. Inline `code` and **bold** are the only markup allowed.
- Items may wrap across multiple source lines; a new item starts with `- `.
```

--------------------------------

### Launch JSignPdf with Swing GUI (Cross-Platform ZIP)

Source: https://github.com/intoolswetrust/jsignpdf/blob/master/website/docs/JSignPdf.adoc

Start JSignPdf using the classic Swing GUI by setting the jsignpdf.swing system property via JAVA_OPTS when launching from the cross-platform ZIP.

```bash
$ JAVA_OPTS=-Djsignpdf.swing=true bin/jsignpdf.sh
```

--------------------------------

### Run InstallCert Tool (Cross-Platform ZIP)

Source: https://github.com/intoolswetrust/jsignpdf/blob/master/website/docs/JSignPdf.adoc

Execute the InstallCert tool from a cross-platform ZIP archive using Java's classpath.

```bash
$ java -cp "lib/*" net.sf.jsignpdf.InstallCert hostname[:port] [cacertPwd]
```

--------------------------------

### List Keys in Keystore

Source: https://github.com/intoolswetrust/jsignpdf/blob/master/distribution/demo/README.md

Lists all available keys within the specified demo keystore. This is useful for verifying keystore contents.

```shell
../bin/jsignpdf.sh \
    -kst PKCS12 -ksf jsmith.p12 -ksp 123456 \
    -lk
```

--------------------------------

### Live Preview with Git Worktree Support (Docker)

Source: https://github.com/intoolswetrust/jsignpdf/blob/master/website/README.md

Runs a live preview server for the JSignPdf website with support for git worktrees. Mounts the common git directory and configures safe directories. Ensure JSIGNPDF_VERSION is set.

```bash
GIT_COMMON_DIR="$(cd "$(git rev-parse --git-common-dir)" && pwd)"

docker run --rm -it -p 1313:1313 -e JSIGNPDF_VERSION=3.0.0-BETA-3 \
  -v "${PWD}:${PWD}" \
  -v "${GIT_COMMON_DIR}:${GIT_COMMON_DIR}:ro" \
  -w "${PWD}/website" hugomods/hugo:exts \
  sh -c 'git config --global --add safe.directory "*" && ./prepare.sh && hugo server --bind 0.0.0.0 --baseURL http://localhost:1313/jsignpdf/'
```

--------------------------------

### List Available Keystore Types

Source: https://github.com/intoolswetrust/jsignpdf/blob/master/website/docs/JSignPdf.adoc

Lists the available keystore types that can be used with the `-kst` option for specifying the keystore type during signing.

```shell
-lkt, --list-keystore-types
```

--------------------------------

### Sign PDF with Timestamp and Visible Signature

Source: https://github.com/intoolswetrust/jsignpdf/blob/master/website/content/quickstart/_index.md

Add a trusted timestamp and a visible signature to a PDF using command-line options. This example includes timestamping and signature positioning.

```shell
bin/jsignpdf.sh \
    -kst PKCS12 -ksf keystore.p12 -ksp mypassword \
    -ts https://freetsa.org/tsr -ha SHA256 \
    -V -llx 50 -lly 50 -urx 250 -ury 120 \
    mydocument.pdf
```

--------------------------------

### Sign PDF using Command Line

Source: https://github.com/intoolswetrust/jsignpdf/blob/master/website/content/_index.md

Automate PDF signing with the command-line interface. Specify keystore type, file, password, output directory, and input PDF file.

```bash
jsignpdf -kst PKCS12 -ksf my.p12 \
         -ksp "$PASS" -d output/ \
         contract.pdf
```

--------------------------------

### Setting JAVA_OPTS for OutOfMemoryError

Source: https://github.com/intoolswetrust/jsignpdf/blob/master/website/docs/JSignPdf.adoc

Demonstrates how to set the JAVA_OPTS environment variable to increase the Java heap size when running JSignPdf from a cross-platform ZIP distribution. This example allocates 512 MB of heap.

```bash
$ JAVA_OPTS=-Xmx512m bin/jsignpdf.sh
```

--------------------------------

### Setting DSS Engine Trust Knobs via CLI

Source: https://github.com/intoolswetrust/jsignpdf/blob/master/design-doc/3.1-advanced-overrides.md

Example of using the `-o` flag to configure DSS engine trust settings, such as enabling online mode and specifying trusted certificate files.

```bash
jsignpdf doc.pdf -eng dss -pl LT -ts <tsa> \
  -o engine.dss.online.enabled=true \
  -o engine.dss.trust.certFiles=/path/ca.pem
```

--------------------------------

### List Available Keystore Types

Source: https://github.com/intoolswetrust/jsignpdf/blob/master/website/docs/JSignPdf.adoc

Lists all available keystore types that can be used with JSignPdf.

```shell
jsignpdf -lkt
```

--------------------------------

### Configuring DSS Engine Options via Command Line

Source: https://github.com/intoolswetrust/jsignpdf/blob/master/website/docs/JSignPdf.adoc

Example of overriding DSS engine properties for a single run using the '-o' option. This sets online revocation data fetching and specifies trusted certificate files.

```shell
jsignpdf doc.pdf -eng dss -pl LT -ts <tsa-url> \
    -o engine.dss.online.enabled=true \
    -o engine.dss.trust.certFiles=/path/to/ca.pem
```

--------------------------------

### List Available Signing Engines

Source: https://github.com/intoolswetrust/jsignpdf/blob/master/design-doc/3.1-signing-engines.md

Use the --list-engines option to display all available signing engines and identify the default engine. This command exits successfully after printing the list.

```bash
jsignpdf --list-engines
```

--------------------------------

### JSignPdf Command Line Usage

Source: https://github.com/intoolswetrust/jsignpdf/blob/master/website/docs/JSignPdf.adoc

Displays the help screen for JSignPdf command-line usage, listing all available options grouped by category. Use this to understand the various parameters for batch signing.

```shell
usage: jsignpdf [file1.pdf [file2.pdf ...]] [-a] [--bg-path
       <file>] [--bg-scale <scale>] [-c <contact>] [-cl <level>] [--crl] [-d
       <path>] [--disable-acrobat6-layer-mode] [--disable-assembly]
       [--disable-copy] [--disable-fill] [--disable-modify-annotations]
       [--disable-modify-content] [--disable-screen-readers] [-e] [-ec <file>]
       [--enable-stdin-passwords] [-eng <engine>] [-fs <size>] [--gui] [-h]
       [-ha <algorithm>] [--img-path <file>] [-ka <alias>]
       [-ki <index>] [-kp <password>] [-ksf <file>] [-ksp <password>] [-kst
       <type>] [-l <location>] [--l2-text <text>] [--l4-text <text>] [-le] [-lk]
       [-lkt] [-llx <position>] [-lly <position>] [-lp] [-lpf <file>] [-o
       <key=value>] [--ocsp]
       [--ocsp-server-url <responderUrl>] [-op <prefix>] [-opwd <password>] [-os
       <suffix>] [--overwrite] [-pe <mode>] [-pg <pageNumber>] [-pr <right>] [--proxy-host
       <hostname>] [--proxy-port <port>] [-pl <level>] [--proxy-type <type>] [-q] [-r
       <reason>] [--render-mode <mode>] [-sn <signer>] [-ta <method>] [-ts <URL>]
       [--tsa-policy-oid <policyOID>] [-tscf <file>] [-tscp <password>] [-tsct
       <ks-type>] [-tsh <algorithm>] [-tsp <password>] [-tsu <username>] [-upwd
       <password>] [-urx <position>] [-ury <position>] [-v] [-V]
```

--------------------------------

### Enable PKCS#11 Debugging

Source: https://github.com/intoolswetrust/jsignpdf/blob/master/website/docs/JSignPdf.adoc

Command to run JSignPdf with PKCS#11 keystore and SunPKCS11 debugging enabled. This helps in troubleshooting hardware token integration issues.

```shell
JAVA_OPTS="-Djava.security.debug=pkcs11keystore -Djava.security.debug=sunpkcs11" \
    bin/jsignpdf.sh
```

--------------------------------

### Build JSignPdf Website (Docker)

Source: https://github.com/intoolswetrust/jsignpdf/blob/master/website/README.md

Builds the JSignPdf website for production using Docker. Ensure JSIGNPDF_VERSION is set.

```bash
# Production build → website/public/
docker run --rm -e JSIGNPDF_VERSION=3.0.0-BETA-3 \
  -v "$PWD:/src" -w /src/website hugomods/hugo:exts \
  sh -c './prepare.sh && hugo --gc --minify'
```

--------------------------------

### List Available Signing Engines

Source: https://github.com/intoolswetrust/jsignpdf/blob/master/website/docs/JSignPdf.adoc

Lists the available signing engines that can be selected using the `-eng` option. This allows you to choose a specific engine for the signing process.

```shell
-le, --list-engines
```

--------------------------------

### List Key Aliases in Keystore (Quiet Mode)

Source: https://github.com/intoolswetrust/jsignpdf/blob/master/website/docs/JSignPdf.adoc

Lists the key aliases within a specified keystore in quiet mode. This is useful for identifying available certificates without verbose output.

```shell
jsignpdf -kst PKCS12 -ksf my_certificate.pfx \
  -ksp myVeryPrivatePassword -lk -q
```

--------------------------------

### EngineRegistry Class

Source: https://github.com/intoolswetrust/jsignpdf/blob/master/design-doc/3.1-signing-engines.md

Manages the discovery and retrieval of available SigningEngine implementations.

```java
public final class EngineRegistry {
    public static EngineRegistry getInstance();
    public Optional<SigningEngine> findById(String id);
    public List<SigningEngine> listAll();      // sorted: default first, then by id
    public SigningEngine getDefault();         // resolves advanced.properties → "openpdf"
}
```

--------------------------------

### JSignPdf Architecture Overview

Source: https://github.com/intoolswetrust/jsignpdf/blob/master/AGENTS.md

Illustrates the flow of control and data from the command-line interface (CLI) or graphical user interface (GUI) to the core signing logic and engine.

```text
CLI (SignerOptionsFromCmdLine)  ──┐
                                  ├──> BasicSignerOptions ──> SignerLogic.signFile() ──> SigningEngine
GUI (JavaFX / Swing)            ──┘         (model)              (orchestration)         (openpdf | dss)
```