Certificate Signing

Digitally sign PDFs with X.509 certificates and validate existing signatures against trusted certificate chains.

Signing PDFs#

# Generate a test certificate as PKCS#12
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365
openssl pkcs12 -export -out mycert.p12 -inkey key.pem -in cert.pem

# Replace the server certificate with your own keystore (.p12 or .pfx only)
curl -X POST http://stirling-pdf:8080/api/v1/admin/server-certificate/upload \
  -H "X-API-KEY: <admin-api-key>" \
  -F "[email protected]" \
  -F "password=keystore-password"

STIRLING_PKCS11_LIBRARIES=/usr/lib/opensc-pkcs11.so,/opt/vendor/lib/libvendor-pkcs11.so

Signature Appearance#

• pageNumber is 1-indexed. Defaults: Show signature off, Show logo on, page 1.
• The Location value is not drawn in the box.
• Show logo overlays a fixed image that ships with the application; it is not a place to supply your own.
• Signing refuses an expired or not-yet-valid certificate, whichever source it came from.
• Signing does not embed an RFC 3161 timestamp. For proof of when the document was signed, run Timestamp PDF on the signed file afterwards.
• To strip signatures from a PDF, use the Remove Certificate Sign tool (POST /api/v1/security/remove-cert-sign).

Validating Signatures#

The Validate PDF Signature tool validates signatures against the configured trust sources. Revocation is off by default (none).

The settings panel has a single optional input, Custom Certificate File X.509 (Optional), which accepts .cer, .crt, .pem and .der. Results can be downloaded as a PDF report, a CSV, or the raw JSON.

Trust Sources#

Revocation Checking#

hardFail

• false (default) - the check soft-fails and validation continues. The signature is reported with revocation status soft-fail, shown in the UI as Valid, signer not verified
• true - the signature is reported as untrusted. Use this where you would rather reject a signature than skip the check

The full configuration reference for these keys lives on the System and Security page.

Timestamping PDFs#

Use the Timestamp PDF tool to add a trusted RFC 3161 timestamp that proves your PDF existed at a particular point in time. Existing signatures stay intact and the document never leaves your server.

Trusted Time Stamp Authorities#

Built-in presets:

• The allowed set is the five presets plus defaultTsaUrl plus customTsaUrls, compared case-insensitively.
• Any other URL is rejected with TSA URL is not in the allowed list. Contact your administrator to add it via settings.yml (security.timestamp.customTsaUrls).

# tsaUrl is optional; omit to use the server default
curl -X POST http://stirling-pdf:8080/api/v1/security/timestamp-pdf \
  -F "[email protected]" \
  -F "tsaUrl=http://timestamp.digicert.com" \
  -o timestamped.pdf

Configuration Example#

High-security validation, on top of the defaults:

security:
  validation:
    trust:
      serverAsAnchor: false
      useSystemTrust: true
      useAATL: true
      useEUTL: true
    allowAIA: false
    revocation:
      mode: ocsp+crl
      hardFail: true

API Usage#

# certType must be one of PEM, PKCS12, PFX, JKS, SERVER, WINDOWS_STORE, PKCS11 (uppercase)
# certType=SERVER requires a Server or Enterprise license
curl -X POST http://stirling-pdf:8080/api/v1/security/cert-sign \
  -F "[email protected]" \
  -F "certType=SERVER" \
  -F "reason=Approved" -F "location=London" \
  -F "showSignature=true" -F "pageNumber=1" \
  -o signed.pdf

# PKCS12/PFX use p12File; JKS uses jksFile; PEM uses privateKeyFile + certFile
curl -X POST http://stirling-pdf:8080/api/v1/security/cert-sign \
  -F "[email protected]" \
  -F "certType=PKCS12" \
  -F "[email protected]" -F "password=certpass" \
  -o signed.pdf

# Desktop app only; the request must come from the local machine.
# WINDOWS_STORE selects a cert by alias and takes no PIN; PKCS11 uses pkcs11LibraryPath
# (+ optional pkcs11Slot), with password as the token PIN.
curl -X POST http://localhost:8080/api/v1/security/cert-sign \
  -F "[email protected]" \
  -F "certType=PKCS11" \
  -F "pkcs11LibraryPath=/usr/lib/opensc-pkcs11.so" \
  -F "alias=my-signing-key" \
  -F "password=token-pin" \
  -o signed.pdf

# What this process can do. Not gated - returns desktop=false off the desktop app.
curl http://localhost:8080/api/v1/security/cert-sign/hardware/capabilities

# Windows certificate store (desktop app, local request only)
curl http://localhost:8080/api/v1/security/cert-sign/hardware/windows-certificates

# PKCS#11 token (desktop app, local request only). Omit slot for the first
# slot holding a token.
curl -X POST http://localhost:8080/api/v1/security/cert-sign/hardware/pkcs11-certificates \
  -H "Content-Type: application/json" \
  -d '{"libraryPath":"/usr/lib/opensc-pkcs11.so","pin":"token-pin"}'

# Returns a JSON array with one result per signature found
curl -X POST http://stirling-pdf:8080/api/v1/security/validate-signature \
  -F "[email protected]"

# Optional certFile REPLACES the configured trust anchors for this request
curl -X POST http://stirling-pdf:8080/api/v1/security/validate-signature \
  -F "[email protected]" \
  -F "[email protected]"

See API Documentation for complete endpoint reference.

cert-sign, remove-cert-sign, timestamp-pdf and validate-signature can be disabled individually or by group - see Endpoint or Feature Customisation.

Troubleshooting#

"Certificate not trusted"#

Enable the appropriate trust source, or add your CA to the trust store used by the Java runtime. Updating OS CA files alone is not sufficient unless the container/runtime also synchronises them into Java's trust store. Trust sources are loaded during service initialisation; restart the application after changing them.

Revocation check fails#

Check that the container has HTTPS access to OCSP/CRL servers. Use hardFail: false or switch to crl mode for restricted networks.

Server certificate not generated#

Requires a Server or Enterprise license. Check logs with docker logs stirling-pdf | grep -i certificate.

"This device" is missing from the Certificate source step#

• Call GET /api/v1/security/cert-sign/hardware/capabilities.
• desktop: false means it is not the desktop app.

"PKCS#11 driver is not in the allowed list"#

The driver path you typed is neither auto-detected nor configured. Add its absolute path to STIRLING_PKCS11_LIBRARIES and confirm the file exists at exactly that path - a configured path that is missing on disk is dropped without a message.

"Hardware-backed signing can only be used from this device"#

The request reached the server from another host. Hardware signing accepts only loopback, any-local, and addresses bound to the machine's own interfaces.

Signature shows "Valid, signer not verified"#

The cryptography is sound but a trust caveat applies. Check the detail list on the result: an untrusted or self-signed certificate needs the issuer adding as a trust anchor, and a soft-fail revocation status means the responder could not be reached.

Related Documentation#

• System and Security Settings - the full configuration reference for server certificates, trust sources, revocation and AIA
• Sign - handwritten and visual signatures, and how they differ from a digital signature
• Shared Signing - collecting certificate signatures from several participants on one document
• Endpoint or Feature Customisation - disabling cert-sign, remove-cert-sign, timestamp-pdf or validate-signature
• Modes and Licensing - the license tiers and what each one includes
• Paid Offerings - the full feature comparison across Free, Server and Enterprise
• API documentation - complete endpoint reference