Digital Signatures & Certificates

Overview

DocuTrust applies cryptographic digital signatures to completed documents using X.509 certificates. Signatures conform to the PAdES (PDF Advanced Electronic Signatures) standard and include RFC 3161 timestamps from a Time Stamping Authority (TSA) to prove the document existed at a specific point in time.

Get Current Certificate

Retrieve details about the currently configured signing certificate.

curl -X GET "https://spitshake.io/api/settings/certificate" \
  -H "X-Auth-Token: YOUR_API_TOKEN"

{
  "configured": true,
  "subject": "CN=DocuTrust Signing CA, O=DocuTrust Inc., L=San Francisco, ST=California, C=US",
  "issuer": "CN=DocuTrust Root CA, O=DocuTrust Inc., C=US",
  "serial_number": "A1B2C3D4E5F6A7B8",
  "not_before": "2025-01-01T00:00:00Z",
  "not_after": "2028-01-01T00:00:00Z",
  "fingerprint_sha256": "AB:CD:EF:12:34:56:78:9A:BC:DE:F0:12:34:56:78:9A:AB:CD:EF:12:34:56:78:9A:BC:DE:F0:12:34:56:78:9A",
  "key_algorithm": "RSA",
  "key_size": 2048,
  "signature_algorithm": "SHA256withRSA",
  "source": "generated",
  "created_at": "2025-01-15T10:30:00Z"
}

{
  "configured": false,
  "subject": null,
  "issuer": null,
  "serial_number": null,
  "not_before": null,
  "not_after": null,
  "fingerprint_sha256": null,
  "key_algorithm": null,
  "key_size": null,
  "signature_algorithm": null,
  "source": null,
  "created_at": null
}

Generate Self-Signed Certificate

Generate a new self-signed X.509 certificate for document signing. This replaces any existing certificate.

curl -X POST "https://spitshake.io/api/settings/certificate/generate" \
  -H "X-Auth-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "common_name": "DocuTrust Signing CA",
    "organization": "DocuTrust Inc.",
    "country": "US",
    "state": "California",
    "locality": "San Francisco",
    "key_size": 2048,
    "validity_years": 3
  }'

{
  "configured": true,
  "subject": "CN=DocuTrust Signing CA, O=DocuTrust Inc., L=San Francisco, ST=California, C=US",
  "issuer": "CN=DocuTrust Signing CA, O=DocuTrust Inc., L=San Francisco, ST=California, C=US",
  "serial_number": "F0E1D2C3B4A59687",
  "not_before": "2026-04-08T00:00:00Z",
  "not_after": "2029-04-08T00:00:00Z",
  "fingerprint_sha256": "12:34:56:78:9A:BC:DE:F0:12:34:56:78:9A:BC:DE:F0:12:34:56:78:9A:BC:DE:F0:12:34:56:78:9A:BC:DE:F0",
  "key_algorithm": "RSA",
  "key_size": 2048,
  "signature_algorithm": "SHA256withRSA",
  "source": "generated",
  "created_at": "2026-04-08T15:00:00Z"
}

Import Certificate

Import an existing PKCS#12 (.p12 or .pfx) certificate file. This is useful when you have a certificate issued by a trusted Certificate Authority.

curl -X POST "https://spitshake.io/api/settings/certificate/import" \
  -H "X-Auth-Token: YOUR_API_TOKEN" \
  -F "certificate=@/path/to/signing-cert.p12" \
  -F "password=your-p12-password"

{
  "configured": true,
  "subject": "CN=My Company Signing, O=My Company LLC, C=US",
  "issuer": "CN=DigiCert SHA2 Assured ID CA, O=DigiCert Inc, C=US",
  "serial_number": "0A1B2C3D4E5F6A7B8C9D0E1F",
  "not_before": "2025-06-01T00:00:00Z",
  "not_after": "2027-06-01T00:00:00Z",
  "fingerprint_sha256": "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99",
  "key_algorithm": "RSA",
  "key_size": 4096,
  "signature_algorithm": "SHA256withRSA",
  "source": "imported",
  "created_at": "2026-04-08T15:10:00Z"
}

{
  "error": "Unable to read the certificate file. Please ensure it is a valid PKCS#12 (.p12 or .pfx) file and the password is correct."
}

{
  "error": "The imported certificate expired on 2024-12-31T00:00:00Z. Please provide a valid, non-expired certificate."
}

TSA Timestamping

All digital signatures include an RFC 3161 timestamp from a Time Stamping Authority. This provides cryptographic proof that the signature existed at a specific time, independent of the signer’s local clock.

Timestamp Configuration

DocuTrust uses FreeTSA as the primary timestamping authority with an automatic fallback mechanism:

Priority	TSA Server	Protocol
Primary	`https://freetsa.org/tsr`	RFC 3161 over HTTP
Fallback	Internal timestamp	System clock with certificate binding

The TSA timestamp is embedded directly into the PDF signature dictionary, making it verifiable by any PAdES-compliant reader (Adobe Acrobat, Foxit, etc.).

Signature Structure

Each signed document contains:

PDF Document
├── Signature Dictionary
│   ├── /Type /Sig
│   ├── /Filter /Adobe.PPKLite
│   ├── /SubFilter /adbe.pkcs7.detached
│   ├── /ByteRange [0 offset1 offset2 end]
│   ├── /Contents <PKCS#7 SignedData>
│   │   ├── Signer Certificate (X.509)
│   │   ├── Signature Value (RSA/SHA-256)
│   │   └── Timestamp Token (RFC 3161)
│   ├── /Reason (Signed via DocuTrust)
│   └── /M (D:20260408150000+00'00')
└── Document Content (integrity-protected)

PAdES Compliance

DocuTrust signatures are PAdES-B (Basic) compliant:

Requirement	Implementation
Signature format	PKCS#7 (CMS) SignedData
Hash algorithm	SHA-256
Signature algorithm	RSA (2048-bit minimum)
Timestamp	RFC 3161 TSA token embedded
Certificate	X.509 v3 with digitalSignature key usage
PDF integration	Incremental update with ByteRange coverage

Verification

Signed documents can be verified using:

Adobe Acrobat Reader — Opens the Signatures panel automatically
Foxit PDF Reader — Displays signature validity in the toolbar
Any PAdES-compliant validator — The PKCS#7 structure is standard-compliant

Self-signed certificates will show as “unknown” trust in PDF readers. For full trust chain validation, import a certificate issued by a publicly trusted Certificate Authority.

Getting Started

Core Guides

Embedding

Features

Security & Compliance

Legal

Digital Signatures & Certificates

Overview

Get Current Certificate

Generate Self-Signed Certificate

Import Certificate

TSA Timestamping

Timestamp Configuration

Signature Structure

PAdES Compliance

Verification

​Overview

​Get Current Certificate

​Generate Self-Signed Certificate

​Import Certificate

​TSA Timestamping

​Timestamp Configuration

​Signature Structure

​PAdES Compliance

​Verification

Overview

Get Current Certificate

Generate Self-Signed Certificate

Import Certificate

TSA Timestamping

Timestamp Configuration

Signature Structure

PAdES Compliance

Verification