Skip to content

Repository navigation

Security: egagofur/DocSeal

Security

SECURITY.md

Security Policy & Cryptographic Guidelines

Project: DocSeal (Privacy-First Document Watermarking & Provenance Toolkit)
Date: August 2026

1. Security Philosophy & Principles

DocSeal is designed for privacy-preserving document protection and provenance. It is built under the following non-negotiable security principles:

  1. Local-First / Offline Execution: No document bytes, keys, or metadata are ever transmitted over the network.
  2. Zero PII in Payloads: Watermark payloads MUST NEVER contain Personally Identifiable Information (such as Indonesian NIK, tax numbers, passport numbers, home addresses, or phone numbers). All payloads use opaque, cryptographically random identifiers (UUIDv4/UUIDv7 or HMAC hashes).
  3. No Homegrown Cryptography: All cryptographic primitives rely on standard, peer-reviewed implementations (ed25519-dalek for signatures, sha2/blake3 for hashing, chacha20 for PRNG).
  4. Honest Capabilities & No False Claims: The project explicitly rejects marketing buzzwords such as "AI-proof" or "impossible to remove." The security objective is to raise the cost of forgery and provide mathematically verifiable provenance.

2. Cryptographic Specifications

Component Standard / Primitive Key Length / Hash Size Library
Digital Signatures Ed25519 (RFC 8032) 256-bit private / 256-bit public ed25519-dalek (2.1)
Document Hashing SHA-256 (FIPS 180-4) & BLAKE3 256-bit digest sha2 (0.10) / blake3 (1.5)
Key Derivation HMAC-SHA256 (RFC 2104) 256-bit output hmac (0.12)
PRNG Seeding ChaCha20 (RFC 8439) 256-bit seed rand_chacha (0.3)
Error Correction Reed-Solomon $GF(2^8)$ $(n=32, k=16)$ Custom pure-Rust $GF(2^8)$ codec

3. Key Management Best Practices

  1. Private Key Storage:
    • Private signing keys must be kept secure by document issuers. Never distribute or embed private keys inside public documents or repositories.
    • For automated environments, load private keys from secure environment variables (DOCGUARD_SIGNING_KEY) or hardware security modules (HSM / PKCS#11).
  2. Public Key Distribution:
    • Verification relies only on the issuer's public key (formatted as did:key:z6MkwS... or base64 raw bytes).
    • Public keys can be safely distributed or embedded in verification manifests.
  3. Revocation & Rotation:
    • Manifests include an optional expires_at ISO 8601 timestamp. Verifiers must reject expired manifests.

4. Input Validation & Hardening

  1. Decompression Bomb Protection:
    • Image decoding enforces maximum dimension limits (default: 8192 x 8192 pixels / 64 megapixels) and maximum allocation bounds.
  2. PDF Parser Hardening:
    • PDF parsing restricts maximum recursion depth (32 levels) to protect against circular reference attacks.
  3. Constant-Time Verification:
    • Ed25519 signature checks execute in constant time, preventing timing side-channel attacks.

5. Vulnerability Reporting

If you discover a security vulnerability in DocSeal:

  • Do not open a public GitHub issue.
  • Send a detailed advisory with reproduction steps to the project maintainers via encrypted email or GitHub Private Security Advisory.
  • Maintainers will acknowledge within 48 hours and coordinate a coordinated disclosure timeline.

There aren't any published security advisories