> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spitshake.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Digital Signatures & Certificates
> Manage X.509 certificates for PAdES-compatible digital signatures with RFC 3161 timestamping.
## 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.
```bash cURL theme={null}
curl -X GET "https://spitshake.io/api/settings/certificate" \
-H "X-Auth-Token: YOUR_API_TOKEN"
```
```json 200 OK theme={null}
{
"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"
}
```
```json 200 — No Certificate theme={null}
{
"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.
```bash cURL theme={null}
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
}'
```
```json 201 Created theme={null}
{
"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.
```bash cURL theme={null}
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"
```
```json 201 Created theme={null}
{
"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"
}
```
```json 422 — Invalid File theme={null}
{
"error": "Unable to read the certificate file. Please ensure it is a valid PKCS#12 (.p12 or .pfx) file and the password is correct."
}
```
```json 422 — Expired Certificate theme={null}
{
"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](https://freetsa.org) 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
│ │ ├── 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.