Certificate Signing

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

Signing PDFs

Server Certificate
Custom Certificate
Organization Certificate

Easiest option - uses an auto-generated server certificate. No setup needed for users.

Go to Certificate Sign tool
Upload PDF
Select "Sign with Stirling PDF"
Configure signature appearance (optional)
Sign and download

Configuration:

Settings File
Environment Variable

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

SYSTEM_SERVERCERTIFICATE_ENABLED=true
SYSTEM_SERVERCERTIFICATE_ORGANIZATIONNAME="My Company"
SYSTEM_SERVERCERTIFICATE_VALIDITY=365

Use your own X.509 certificate (PKCS#12 .p12/.pfx or PEM format).

Go to Certificate Sign tool
Upload PDF
Select "Upload Certificate"
Upload certificate file and enter password
Configure signature appearance
Sign and download

# Generate a test certificate
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365

# Convert to PKCS#12
openssl pkcs12 -export -out mycert.p12 -inkey key.pem -in cert.pem

Place your organization certificate in the configs directory so all users can sign without uploading their own:

configs/
  └── keystore.p12

system:
  serverCertificate:
    enabled: false  # Disable auto-generation

KEYSTORE_PASSWORD=your-password

Users will see a "Sign with [Organization Name]" option.

Signature Appearance

Visible: Appears as a box on the PDF page with configurable position, size, page, and displayed text (name, date, reason).

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

Source	Config Key	What It Trusts
Server certificates	`serverAsAnchor`	PDFs signed by your Stirling PDF instance
System trust store	`useSystemTrust`	OS-trusted CAs
Mozilla CA bundle	`useMozillaBundle`	Mozilla's curated CA list
Adobe AATL	`useAATL`	Adobe Approved Trust List
EU EUTL	`useEUTL`	EU 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

Mode	What it does
`none`	Skip revocation checks entirely
`ocsp`	Check in real-time against the certificate authority's server (requires internet)
`crl`	Download a list of revoked certificates (can work offline with cached lists)
`ocsp+crl`	Try 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.

Configuration Examples

Minimal (Default)
Enterprise
High-Security
EU eIDAS

system:
  serverCertificate:
    enabled: true

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

system:
  serverCertificate:
    enabled: true
    organizationName: Acme Corp
    validity: 365

security:
  validation:
    trust:
      serverAsAnchor: true
      useSystemTrust: true
      useMozillaBundle: true
      useAATL: false
    allowAIA: false
    revocation:
      mode: ocsp
      hardFail: false

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

security:
  validation:
    trust:
      serverAsAnchor: false
      useSystemTrust: false
      useMozillaBundle: false
      useAATL: false
      useEUTL: true
    eutl:
      lotlUrl: https://ec.europa.eu/tools/lotl/eu-lotl.xml
      acceptTransitional: true
    allowAIA: false
    revocation:
      mode: ocsp+crl
      hardFail: true

API Usage

Sign (Server Cert)
Sign (Custom Cert)
Validate

curl -X POST http://stirling-pdf:8080/api/v1/security/cert-sign \
  -F "[email protected]" \
  -F "certType=server" \
  -F "reason=Approved" \
  -F "location=bottom-right" \
  -F "showSignature=true" \
  -o signed.pdf

curl -X POST http://stirling-pdf:8080/api/v1/security/cert-sign \
  -F "[email protected]" \
  -F "certType=custom" \
  -F "[email protected]" \
  -F "password=certpass" \
  -o signed.pdf

curl -X POST http://stirling-pdf:8080/api/v1/security/validate-signature \
  -F "[email protected]"

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

Ensure SYSTEM_SERVERCERTIFICATE_ENABLED=true is set. Check logs with docker logs stirling-pdf | grep -i certificate.

Signing PDFs​

Signature Appearance​

Validating Signatures​

Trust Sources​

Revocation Checking​

Configuration Examples​

API Usage​

Troubleshooting​

"Certificate not trusted"​

Revocation check fails​

Server certificate not generated​

Related​