Signing Certificates

​

Overview

​

What is a Signing Certificate?

• Signer information - Names, emails, and roles of all recipients
• Timeline - Complete chronological record of all events
• Authentication details - How each signer was authenticated
• Signature images - Visual representation of signatures
• Signature IDs - Unique identifiers for each signature
• Device information - Browser, OS, and IP addresses
• QR verification code - For independent verification
• Cryptographic seal - Tamper-evident signature

​

Certificate Generation

​

Generation Process

​

Code Reference

packages/lib/server-only/pdf/generate-certificate-pdf.ts
packages/lib/server-only/pdf/render-certificate.ts

​

Certificate Contents

​

Header Information

Signing Certificate

​

Recipient Table

​

Column 1: Signer Events

• Name - Full name of the recipient
• Email - Email address
• Role - Recipient role (Signer, Approver, Viewer, CC, Assistant)
• Authentication Level - How they authenticated:
  • Email (default)
  • Account Authentication
  • Two-Factor Authentication
  • Two-Factor Re-Authentication
  • Password Re-Authentication
  • Passkey Re-Authentication

​

Column 2: Signature

• Signature Image - Visual representation of signature (if applicable)
  • Drawn signatures shown as image
  • Typed signatures shown in Caveat font
  • Green border indicating valid signature
• Signature ID - Unique identifier in format:
  Signature ID:
  CKLD2J8A0000108L7E5QG9Z8W
  
• IP Address - IP address at time of signing
• Device - Operating system and browser:
  Windows 10 - Chrome 122.0.0.0
  macOS - Safari 17.2
  

​

Column 3: Details

• Sent - When invitation was sent:
  2024-03-15 10:00:00 AM (UTC)
  
• Viewed - When recipient opened document:
  2024-03-15 10:15:00 AM (UTC)
  
• Signed/Rejected - When action was completed:
  2024-03-15 10:30:00 AM (UTC)
  
  For rejections, shown in red with rejection reason
• Reason - Why this signature was required:
  • Signers: “I am signing this document as a party to the agreement”
  • Approvers: “I am approving this document in my capacity as an authorized approver”
  • Viewers: “I am viewing this document for informational purposes”
  • Document owner: “I am the owner of this document”

​

Footer Information

Signing certificate provided by:
[Documenso Logo]

• Scannable QR code linking to verification page
• URL format: https://documen.so/share/{qrToken}
• Allows independent verification of certificate authenticity

​

Certificate Configuration

​

Organization Settings

type OrganisationGlobalSettings = {
  includeSigningCertificate: boolean;  // Append certificate to PDF
  includeAuditLog: boolean;            // Append audit log to PDF
  documentTimezone: string;            // Timezone for dates
  documentDateFormat: string;          // Date format string
  brandingEnabled: boolean;            // Show custom branding
  brandingLogo: string;                // Custom logo URL
};

​

Document-Level Settings

type DocumentMeta = {
  timezone: string;              // 'America/New_York', 'Europe/London', etc.
  dateFormat: string;            // 'yyyy-MM-dd hh:mm a' (default)
};

​

Date and Time Formats

2024-03-15 10:30:00 AM (UTC)

// ISO format
dateFormat: 'yyyy-MM-dd HH:mm:ss'
// Result: 2024-03-15 10:30:00

// European format  
dateFormat: 'dd/MM/yyyy HH:mm'
// Result: 15/03/2024 10:30

// US format
dateFormat: 'MM/dd/yyyy hh:mm a'
// Result: 03/15/2024 10:30 AM

​

Certificate Events

​

Document Events

• DOCUMENT_SENT - Document was sent to recipients
• DOCUMENT_COMPLETED - All recipients completed
• DOCUMENT_REJECTED - Document was rejected

​

Recipient Events

• EMAIL_SENT - Invitation email sent to recipient
• DOCUMENT_OPENED - Recipient viewed the document
• DOCUMENT_FIELD_INSERTED - Field was completed (with authentication method)
• DOCUMENT_RECIPIENT_COMPLETED - Recipient completed all fields
• DOCUMENT_RECIPIENT_REJECTED - Recipient rejected the document

​

Event Data Structure

type AuditLogEvent = {
  type: string;
  createdAt: DateTime;
  ipAddress: string | null;
  userAgent: string | null;
  data: {
    recipientId?: number;
    fieldSecurity?: {
      type: 'ACCOUNT' | 'TWO_FACTOR_AUTH' | 'PASSWORD' | 'PASSKEY';
    };
  };
};

​

Authentication Levels

​

Access Authentication

• Email - Via email link only (no additional auth)
• Account Authentication - Logged into Documenso account
• Two-Factor Authentication - Account + 2FA required

​

Action Authentication

• Email - No re-authentication required
• Account Re-Authentication - Re-entered password
• Two-Factor Re-Authentication - 2FA code required
• Password Re-Authentication - Document password required
• Passkey Re-Authentication - Hardware key required

​

QR Code Verification

type Envelope = {
  qrToken: string;  // Example: "ckld2j8a0000108l7e5qg9z8w"
};

​

Verification Process

1. Scan QR code on certificate page
2. Navigate to verification page:
   https://documen.so/share/{qrToken}
   
3. View certificate details:
   • Document title
   • Completion date
   • All signers and their status
   • Verification that certificate is authentic

​

Security Features

• Unique token - Generated once at completion
• Immutable - Cannot be changed after generation
• Publicly verifiable - Anyone with QR code can verify
• No sensitive data - Only shows completion status

​

PDF Digital Signatures

​

Signing Process

import { signPdf } from '@documenso/signing';

const signedPdf = await signPdf({
  pdf: pdfDoc  // PDF with certificate appended
});

​

Signature Methods

​

Local Signing

• Uses locally stored certificate
• For development and self-hosted deployments
• Certificate must be provided in environment

​

Google Cloud HSM

• Uses Google Cloud Key Management Service
• Hardware Security Module (HSM) backed
• Enterprise-grade security
• Certificate chain support

​

Certificate Standards

• PAdES (PDF Advanced Electronic Signatures)
• ISO 32000 (PDF specification)
• ETSI EN 319 142 (PAdES baseline profile)

​

Signature Verification

• Adobe Acrobat Reader
• PDF viewers supporting digital signatures
• Programmatic verification via PDF libraries

• Document has not been modified
• Signature is from trusted source
• Certificate is valid
• Timestamp is accurate

​

Multi-Page Certificates

​

Pagination Logic

// Calculate available height per page
const maxTableHeight = pageHeight - pageTopMargin - pageBottomMargin;

// Group recipients into pages
const groupedRows = groupRowsIntoPages({
  recipients,
  maxHeight: maxTableHeight,
  columnWidths,
  i18n
});

• “Signing Certificate” header
• Table header row
• As many recipient rows as fit
• Page border and styling

• Remaining recipients
• Branding footer
• QR verification code

• If QR code doesn’t fit on last page
• Dedicated page for branding and QR code

​

Certificate Customization

​

Custom Branding

type OrganisationGlobalSettings = {
  brandingEnabled: boolean;
  brandingLogo: string;              // Logo image URL
  brandingUrl: string;               // Company website
  brandingCompanyDetails: string;    // Company info text
};

​

Hide Powered By

type OrganisationClaim = {
  flags: {
    hidePoweredBy: boolean;
  };
};

​

Custom Date Formats

// Common formats
'yyyy-MM-dd'              // 2024-03-15
'yyyy-MM-dd HH:mm'        // 2024-03-15 14:30
'yyyy-MM-dd hh:mm a'      // 2024-03-15 02:30 PM
'dd/MM/yyyy'              // 15/03/2024
'MM/dd/yyyy'              // 03/15/2024
'dd MMM yyyy'             // 15 Mar 2024
'MMMM d, yyyy'            // March 15, 2024

​

Audit Log PDF

​

Audit Log Contents

• Complete event timeline - Every action taken
• Field-level details - Which fields were completed
• Authentication records - Auth methods for each action
• System metadata - Request IDs, user agents
• Webhook deliveries - External notifications sent

​

Configuration

organisationGlobalSettings: {
  includeAuditLog: true  // Append audit log to PDF
}

​

Format

• Chronological event listing
• Expandable event details
• JSON data structures
• Color-coded event types

​

Best Practices

​

Certificate Configuration

• Enable certificates for all legally binding documents
• Configure timezone to match your jurisdiction
• Use consistent date format across organization
• Enable QR codes for easy verification
• Include audit logs for compliance-critical documents

​

Security

• Use HSM signing for production environments
• Protect private keys if using local signing
• Enable authentication for sensitive documents
• Archive signed PDFs with certificates intact
• Test verification before production use

​

User Experience

• Explain certificate purpose to recipients
• Include verification instructions in emails
• Brand certificates for professional appearance
• Keep recipient count reasonable for readable certificates
• Test multi-page layouts for large recipient lists

​

API Access

​

Download Certificate

GET /api/v1/documents/:id/certificate

• PDF file containing signing certificate
• Content-Type: application/pdf
• Filename: {document-title}_certificate.pdf

​

Download Complete Package

GET /api/v1/documents/:id/download

• Complete signed PDF with certificate appended
• Optionally includes audit log
• Content-Type: application/pdf
• Filename: {document-title}_signed.pdf

​

Verify via QR Token

GET /share/:qrToken

• Public verification page
• Document completion status
• Signer information
• Completion timestamp

​

Certificate Storage

• Generated once at document completion
• Appended to PDF automatically
• Stored with document in document storage
• Immutable after generation
• Verifiable via QR code indefinitely

​

Compliance Considerations

​

Legal Validity

• Evidence of intent - Who signed and when
• Non-repudiation - Signers cannot deny signing
• Audit trail - Complete chronological record
• Authentication proof - How identity was verified
• Tamper evidence - Cryptographic seal

​

Industry Standards

• ESIGN Act (United States)
• UETA (Uniform Electronic Transactions Act)
• eIDAS (European Union)
• SOC 2 (audit trail requirements)
• HIPAA (healthcare documentation)
• 21 CFR Part 11 (FDA electronic records)

​

Data Retention

• Retain signed PDFs with certificates
• Archive for required period (often 7+ years)
• Maintain verification capability via QR tokens
• Backup cryptographic keys securely
• Document retention policy in writing