Skip to main content

Certificate Signing

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

Signing PDFs​

Uses an auto-generated server certificate, so users can sign without uploading their own. This is a Pro/Enterprise feature and must be enabled by an administrator; it is not available on the free self-hosted edition.

  1. Go to Certificate Sign tool
  2. Upload PDF
  3. In the Certificate source step, choose Server (shown only when the server certificate feature is enabled)
  4. Configure signature appearance (optional)
  5. Sign and download

Configuration (Pro/Enterprise):

system:
  serverCertificate:
    enabled: true
    organizationName: Stirling-PDF
    validity: 365
    regenerateOnStartup: false

Signature Appearance​

Visible: Appears as a box on a chosen page showing the signer name, signing date, and reason, with an optional logo.

Invisible: Embedded in PDF metadata only, not visible on the page.

Validating Signatures​

Verify that a PDF was signed by the claimed certificate, the certificate is trusted, the PDF hasn't been modified, and the certificate hasn't been revoked.

Trust Sources​

SourceConfig KeyWhat It Trusts
Server certificatesserverAsAnchorPDFs signed by your Stirling PDF instance
System trust storeuseSystemTrustOS-trusted CAs
Mozilla CA bundleuseMozillaBundleMozilla's curated CA list
Adobe AATLuseAATLAdobe Approved Trust List
EU EUTLuseEUTLEU Trusted List (eIDAS)

Revocation Checking​

Certificates can be revoked (invalidated) after they're issued - for example if a private key is compromised. Revocation checking lets Stirling PDF verify that a certificate is still valid at the time of use.

security:
  validation:
    revocation:
      mode: none       # Options: none, ocsp, crl, ocsp+crl
      hardFail: false
ModeWhat it does
noneSkip revocation checks entirely
ocspCheck in real-time against the certificate authority's server (requires internet)
crlDownload a list of revoked certificates (can work offline with cached lists)
ocsp+crlTry real-time check first, fall back to the list if that fails

hardFail controls what happens when the revocation check itself fails (e.g. server unreachable):

  • false (default) - validation passes with a warning
  • true - validation fails entirely. Use this in high-security environments where you'd rather reject a signature than skip the check.

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. Pick a Time Stamp Authority (TSA), then download the timestamped file. The timestamp is added without altering the rest of the file, so any existing signatures stay intact.

Trusted Time Stamp Authorities​

You can pick from the built-in TSA presets below, or your administrator can add more. Built-in presets:

ProviderURL
DigiCerthttp://timestamp.digicert.com
Sectigohttp://timestamp.sectigo.com
SSL.comhttp://ts.ssl.com
FreeTSAhttps://freetsa.org/tsr
MeSignhttp://tsa.mesign.com

If you don't choose one, the server default is used (DigiCert by default). Administrators can allow additional TSA servers and change the default in settings.yml:

security:
  timestamp:
    defaultTsaUrl: http://timestamp.digicert.com
    customTsaUrls:
      - https://tsa.example.com/timestamp

API Usage​

# 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 Examples​

system:
  serverCertificate:
    enabled: true

security:
  validation:
    trust:
      serverAsAnchor: true
      useSystemTrust: true
note

The system.serverCertificate.* keys are honoured only on Pro/Enterprise editions. On the free self-hosted edition, setting enabled: true has no effect and the Server certificate source stays hidden; use a custom certificate (Upload), or This device in the desktop app, instead. All security.validation.* and security.timestamp.* settings apply to every edition.

API Usage​

# certType must be one of PEM, PKCS12, PFX, JKS, SERVER, WINDOWS_STORE, PKCS11 (uppercase)
# certType=SERVER requires the Pro/Enterprise server certificate feature to be enabled
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

See API Documentation for complete endpoint reference.

Troubleshooting​

"Certificate not trusted"​

Enable the appropriate trust source in config, or add your CA certificate to the system trust store:

docker cp ca-cert.crt stirling-pdf:/usr/local/share/ca-certificates/
docker exec stirling-pdf update-ca-certificates

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​

The server certificate feature requires a Pro/Enterprise license; on the free self-hosted edition it stays disabled regardless of configuration. With a license, ensure SYSTEM_SERVERCERTIFICATE_ENABLED=true is set. Check logs with docker logs stirling-pdf | grep -i certificate.

x