Version: 2.0 (Beta)

Certificate Signing

Stirling-PDF provides comprehensive PDF certificate signing and validation capabilities. Digitally sign PDFs with X.509 certificates and validate existing signatures against trusted certificate chains.

Overview

Two main features:

Sign PDFs - Apply digital signatures using certificates
Validate Signatures - Verify certificate-signed PDFs against trust chains

Use Cases:

Legal document signing
Contract verification
Invoice authentication
Compliance requirements (eIDAS, etc.)
Enterprise document workflows

Signing PDFs

Methods

1. Sign with Stirling-PDF (Server Certificate)

Easiest option - Use auto-generated server certificate.

How it works:

Server generates self-signed certificate on first startup
Certificate persists across restarts
Users sign PDFs with one click
No certificate management needed

Use cases:

Internal documents
Non-legal signatures
Quick signing workflows
Testing and development

Steps:

Go to Certificate Sign tool
Upload PDF
Select "Sign with Stirling-PDF"
Configure signature appearance (optional):
- Position on page
- Size
- Visible or invisible
- Text to display
Click Sign
Download signed PDF

Configuration:

system:
  serverCertificate:
    enabled: true                    # Enable auto-generation
    organizationName: Stirling-PDF   # Certificate org name
    validity: 365                    # Days until expiration
    regenerateOnStartup: false       # Keep same cert across restarts

Environment Variables:

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

2. Sign with Custom Certificate

For legal/official documents - Use your own certificate.

Requirements:

X.509 certificate in PKCS#12 (.p12) or PEM format
Private key
Optional: Certificate chain

Steps:

Go to Certificate Sign tool
Upload PDF
Select "Upload Certificate"
Upload your certificate file (.p12, .pfx, or .pem)
Enter certificate password
Configure signature appearance
Click Sign
Download signed PDF

Supported formats:

.p12 / .pfx - PKCS#12 (most common)
.pem - PEM-encoded certificate + key
.crt + .key - Separate cert and key files

Example with openssl:

# Generate your own certificate (for testing)
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365

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

3. Server-Managed Custom Certificates

For admins - Provide organization certificate for all users.

How to set up:

Place certificate in configs directory:
```
configs/
  └── keystore.p12
```

Configure in settings.yml:

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

Set certificate password via environment variable:
```
KEYSTORE_PASSWORD=your-password
```

Users see:

"Sign with [Organization Name]" option
No need to upload certificate
Consistent signing across organization

Signature Appearance

Configure how signature appears on PDF:

Visible Signature

Signature appears as box on PDF page.

Options:

Position: X/Y coordinates or page location (top-left, center, etc.)
Size: Width and height in points
Page: Which page(s) to sign
Text: Name, date, reason displayed
Image: Optional signature image

Example configuration:

Signature:
  Position: Bottom-Right
  Page: Last
  Size: 200x100 points
  Display:
    - Signer Name
    - Sign Date
    - Reason: "Approved"

Invisible Signature

Signature embedded in PDF metadata, not visible.

Use cases:

Digital timestamping
Authentication without visual mark
Multiple signatures on same document

Signing Multiple PDFs

Batch signing - Sign multiple PDFs with same certificate.

Methods:

Multi-Tool:
- Upload multiple PDFs
- Apply certificate sign operation
- All PDFs signed with same cert
- Download as zip

Pipeline (Automation):

{
  "name": "Sign Documents",
  "pipeline": [
    {
      "operation": "cert-sign",
      "parameters": {
        "certType": "server",
        "reason": "Approved",
        "location": "bottom-right"
      }
    }
  ]
}

Validating Signatures

What is Signature Validation?

Verify that:

✅ PDF was signed by claimed certificate
✅ Certificate is trusted (in trust chain)
✅ Certificate was valid at signing time
✅ PDF has not been modified since signing
✅ Certificate has not been revoked

Trust Chains

Stirling-PDF checks multiple trust sources:

1. Server-Generated Certificates

security:
  validation:
    trust:
      serverAsAnchor: true  # Trust server-generated certs

Use case: Trust PDFs signed by your Stirling-PDF instance.

2. System Trust Store

security:
  validation:
    trust:
      useSystemTrust: true  # Use OS certificate store

What it includes:

Operating system's trusted CA certificates
Certificates added by system administrator
Standard public CAs (Let's Encrypt, DigiCert, etc.)

Use case: Trust certificates from public certificate authorities.

3. Mozilla CA Bundle

security:
  validation:
    trust:
      useMozillaBundle: true  # Mozilla's curated CA list

What it includes:

Mozilla's trusted CA certificate bundle
Regularly updated list of trusted CAs
Well-maintained, widely trusted

Use case: Standard web trust model for PDFs.

4. Adobe Approved Trust List (AATL)

security:
  validation:
    trust:
      useAATL: true  # Adobe's approved CAs
    aatl:
      url: https://trustlist.adobe.com/tl.pdf

What it includes:

Certificate authorities approved by Adobe
Widely recognized for PDF signing
Automatically updated from Adobe

Use case: Enterprise PDF workflows, Adobe-signed documents.

5. EU Trusted List (EUTL)

security:
  validation:
    trust:
      useEUTL: true  # EU eIDAS trust list
    eutl:
      lotlUrl: https://ec.europa.eu/tools/lotl/eu-lotl.xml
      acceptTransitional: false  # Accept transitional CAs

What it includes:

EU member state trusted service providers
eIDAS-compliant certificates
European government and business CAs

Use case: EU legal documents, eIDAS compliance, government workflows.

Revocation Checking

Verify certificate has not been revoked:

security:
  validation:
    revocation:
      mode: ocsp+crl  # Options: none, ocsp, crl, ocsp+crl
      hardFail: false  # Fail validation if revocation check fails

Revocation Methods

Method	Description	Speed	Reliability
none	No revocation check	Instant	⚠️ Not recommended
ocsp	Online Certificate Status Protocol	Fast	✅ Real-time
crl	Certificate Revocation List	Slower	✅ Works offline
ocsp+crl	Try OCSP, fall back to CRL	Medium	✅ Best balance

Hard Fail vs Soft Fail

Soft Fail (hardFail: false):

✅ Validation succeeds if revocation check unavailable
⚠️ Warning shown: "Could not verify revocation status"
Use when network reliability uncertain

Hard Fail (hardFail: true):

❌ Validation fails if revocation check unavailable
✅ Stricter security
Use for high-security environments

Authority Information Access (AIA)

Automatically fetch missing intermediate certificates:

security:
  validation:
    allowAIA: false  # Enable AIA certificate fetching

What it does:

Downloads intermediate certificates from URLs in certificate
Completes certificate chain automatically
Makes validation more likely to succeed

Security consideration:

Disabled by default (security best practice)
Enable only in controlled environments
Requires outbound HTTPS access

Configuration Examples

Minimal Configuration (Default)

Works out-of-box for basic signing:

system:
  serverCertificate:
    enabled: true

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

Capabilities:

✅ Sign with server certificate
✅ Validate system-trusted signatures
✅ No external dependencies

Standard Enterprise Setup

Balanced security and usability:

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

Capabilities:

✅ Sign with company certificate
✅ Validate against multiple trust sources
✅ OCSP revocation checking (soft fail)
✅ Works in most environments

High-Security Configuration

Strict validation for regulated industries:

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

Capabilities:

✅ Only trust external CAs (not server-generated)
✅ Multiple trust sources (AATL + EUTL)
✅ Dual revocation checking
✅ Hard fail on revocation check failure
Use for: Finance, legal, government

EU eIDAS Compliance

For European legal documents:

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

Capabilities:

✅ eIDAS-compliant validation
✅ Only EU member state CAs trusted
✅ Strict revocation checking
Use for: EU contracts, government, regulated industries

Using the Tools

Certificate Sign Tool

Location: Security → Certificate Sign

Features:

Upload PDF(s) to sign
Choose certificate source
Configure signature appearance
Batch signing support
Preview signature location

Workflow:

Upload PDF(s)
Select certificate:
- Server certificate
- Upload custom certificate
- Use organization certificate (if configured)
Configure appearance:
- Visible or invisible
- Position and size
- Text and image
- Page selection
Add metadata:
- Reason for signing
- Location
- Contact info
Sign and download

Validate Signature Tool

Location: Security → Validate Signature (planned)

Features:

Upload signed PDF
Check signature validity
View certificate details
Check trust chain
Verify revocation status

Output:

✅ Signature Valid

Signer: CN=John Doe, O=Acme Corp
Signed: 2025-01-15 10:30:00 UTC
Certificate: RSA 2048-bit

Trust Chain:
  ✅ Acme Corp Root CA
  ✅ Acme Corp Intermediate CA
  ✅ John Doe

Revocation: ✅ Not revoked (OCSP)
Document: ✅ Not modified

API Usage

Sign PDF via API

Endpoint: POST /api/v1/security/cert-sign

Example with server certificate:

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

Example with custom certificate:

curl -X POST http://stirling-pdf:8080/api/v1/security/cert-sign \
  -F "fileInput=@document.pdf" \
  -F "certType=custom" \
  -F "certificateFile=@mycert.p12" \
  -F "password=certpass" \
  -F "reason=Contract Approval" \
  -o signed.pdf

Validate Signature via API

Endpoint: POST /api/v1/security/validate-signature

Example:

curl -X POST http://stirling-pdf:8080/api/v1/security/validate-signature \
  -F "fileInput=@signed.pdf" \
  | jq .

Response:

{
  "valid": true,
  "signer": "CN=John Doe, O=Acme Corp",
  "signDate": "2025-01-15T10:30:00Z",
  "trustChain": [
    "CN=Acme Corp Root CA",
    "CN=Acme Corp Intermediate CA",
    "CN=John Doe"
  ],
  "revocationStatus": "not_revoked",
  "documentModified": false,
  "errors": []
}

Troubleshooting

Signature validation fails

Symptom: "Certificate not trusted" error.

Solutions:

Enable appropriate trust source:

security:
  validation:
    trust:
      useSystemTrust: true  # Or useMozillaBundle, useAATL, etc.

Add certificate to system trust store:

# Copy CA certificate to container
docker cp ca-cert.crt stirling-pdf:/usr/local/share/ca-certificates/

# Update trust store
docker exec stirling-pdf update-ca-certificates

Check certificate chain complete:
- Ensure intermediate certificates included
- Or enable AIA fetching (if secure environment)

Revocation check fails

Symptom: "Unable to check revocation status" warning.

Solutions:

Check network access:
- Container needs HTTPS access to OCSP/CRL servers
- Check firewall rules
- Verify DNS resolution

Use soft fail:

security:
  validation:
    revocation:
      hardFail: false  # Validation succeeds despite revocation check failure

Use CRL instead of OCSP:

security:
  validation:
    revocation:
      mode: crl  # CRL more reliable in restricted networks

Server certificate not generated

Symptom: "Sign with Stirling-PDF" option not available.

Solutions:

Check configuration:

system:
  serverCertificate:
    enabled: true  # Must be enabled

Check logs for errors:

docker logs stirling-pdf | grep -i certificate

Verify write permissions:

# Ensure configs directory writable
docker exec stirling-pdf ls -la /configs/

Manually regenerate:

system:
  serverCertificate:
    regenerateOnStartup: true  # Force regeneration

Restart container, then set back to false.

EUTL/AATL not loading

Symptom: Validation fails for EUTL/AATL certificates.

Solutions:

Check network access:

# Test from container
docker exec stirling-pdf curl -I https://ec.europa.eu/tools/lotl/eu-lotl.xml
docker exec stirling-pdf curl -I https://trustlist.adobe.com/tl.pdf

Check configuration URLs:

security:
  validation:
    aatl:
      url: https://trustlist.adobe.com/tl.pdf  # Verify correct URL
    eutl:
      lotlUrl: https://ec.europa.eu/tools/lotl/eu-lotl.xml

Check for proxy requirements:

# If behind corporate proxy
system:
  proxy:
    host: proxy.company.com
    port: 8080

Security Best Practices

For Signing

Use appropriate certificates:
- Server certificates: Internal/testing only
- Custom certificates: Legal/official documents
- Organization certificates: Centralized management
Protect private keys:
- Use strong passwords for PKCS#12 files
- Store keys securely (not in Docker image)
- Rotate certificates regularly
Configure appearance:
- Visible signatures for accountability
- Include signer name, date, reason
- Position consistently across documents

For Validation

Enable appropriate trust sources:
- System trust: General validation
- AATL: Adobe ecosystem
- EUTL: EU legal documents
- Don't enable all unless needed
Revocation checking:
- Always enable for production (at least OCSP)
- Use hard fail for high-security
- Use soft fail for reliability
AIA fetching:
- Disable by default (security)
- Only enable in controlled environments
- Monitor network traffic
Trust chain verification:
- Verify full chain to root CA
- Don't trust self-signed (except server certs for internal use)
- Check expiration dates

Legal Considerations

Disclaimer: Stirling-PDF provides tools for PDF signing and validation. Legal validity depends on jurisdiction and use case.

When Certificates Are Legally Binding

Generally accepted:

✅ Certificates from trusted CAs (AATL, EUTL)
✅ eIDAS-qualified certificates (EU)
✅ Certificates with proof of identity verification
✅ Proper timestamping

May not be legally binding:

⚠️ Self-signed certificates (server-generated)
⚠️ Certificates without identity verification
⚠️ Expired certificates at signing time

Compliance

EU eIDAS:

Use EUTL trust list
eIDAS-qualified certificates
Qualified timestamping
Long-term validation (LTV)

US ESIGN Act:

Consent to electronic signatures
Record retention requirements
Identity verification

Consult legal counsel for your specific requirements.

Learn More

Configuration:

System and Security Settings - Technical configuration details
Extra Settings - All certificate-related configuration options

Migration:

Settings Changes - V2 new settings
New Features - Feature overview

Related Tools:

Sign - Handwritten/image signatures
Add Password - PDF encryption
Permissions - Access control

Summary

Stirling-PDF certificate signing provides:

✅ Easy signing - Server certificates work out-of-box ✅ Custom certificates - Use your own for legal documents ✅ Organization certificates - Centralized cert management ✅ Comprehensive validation - Multiple trust sources ✅ Revocation checking - OCSP and CRL support ✅ EU compliance - eIDAS/EUTL support ✅ Flexible configuration - From basic to enterprise ✅ API access - Automate workflows

Perfect for:

Internal document workflows
Legal document signing
Contract management
Invoice verification
Compliance requirements
Enterprise automation

Overview​

Signing PDFs​

Methods​

1. Sign with Stirling-PDF (Server Certificate)​

2. Sign with Custom Certificate​

3. Server-Managed Custom Certificates​

Signature Appearance​

Visible Signature​

Invisible Signature​

Signing Multiple PDFs​

Validating Signatures​

What is Signature Validation?​

Trust Chains​

1. Server-Generated Certificates​

2. System Trust Store​

3. Mozilla CA Bundle​

4. Adobe Approved Trust List (AATL)​

5. EU Trusted List (EUTL)​

Revocation Checking​

Revocation Methods​

Hard Fail vs Soft Fail​

Authority Information Access (AIA)​

Configuration Examples​

Minimal Configuration (Default)​

Standard Enterprise Setup​

High-Security Configuration​

EU eIDAS Compliance​

Using the Tools​

Certificate Sign Tool​

Validate Signature Tool​

API Usage​

Sign PDF via API​

Validate Signature via API​

Troubleshooting​

Signature validation fails​

Revocation check fails​

Server certificate not generated​

EUTL/AATL not loading​

Security Best Practices​

For Signing​

For Validation​

Legal Considerations​

When Certificates Are Legally Binding​

Compliance​

Learn More​

Summary​

Overview

Signing PDFs

Methods

1. Sign with Stirling-PDF (Server Certificate)

2. Sign with Custom Certificate

3. Server-Managed Custom Certificates

Signature Appearance

Visible Signature

Invisible Signature

Signing Multiple PDFs

Validating Signatures

What is Signature Validation?

Trust Chains

1. Server-Generated Certificates

2. System Trust Store

3. Mozilla CA Bundle

4. Adobe Approved Trust List (AATL)

5. EU Trusted List (EUTL)

Revocation Checking

Revocation Methods

Hard Fail vs Soft Fail

Authority Information Access (AIA)

Configuration Examples

Minimal Configuration (Default)

Standard Enterprise Setup

High-Security Configuration

EU eIDAS Compliance

Using the Tools

Certificate Sign Tool

Validate Signature Tool

API Usage

Sign PDF via API

Validate Signature via API

Troubleshooting

Signature validation fails

Revocation check fails

Server certificate not generated

EUTL/AATL not loading

Security Best Practices

For Signing

For Validation

Legal Considerations

When Certificates Are Legally Binding

Compliance

Learn More

Summary