Security & Licensing Guide

Donjon v7.0 implements a post-quantum cryptographic licensing system using dual signatures. This guide explains the security architecture, cryptographic primitives, and operational procedures for license management.

Post-Quantum Cryptography Overview

Quantum computers threaten current public-key cryptography. Shor's algorithm can efficiently factor large integers and compute discrete logarithms, breaking RSA and elliptic-curve cryptography. Donjon addresses this with a hybrid post-quantum + classical approach.

Cryptographic Strategy

Layer	Algorithm	Standard	Purpose
Post-Quantum	ML-DSA-65	NIST FIPS 204	Quantum-resistant digital signature
Classical	Ed25519	RFC 8032	Proven classical digital signature

ML-DSA-65 (NIST FIPS 204)

ML-DSA (Module-Lattice-Based Digital Signature Algorithm), formerly known as CRYSTALS-Dilithium, is NIST's primary post-quantum digital signature standard, finalized in FIPS 204 (August 2024).

Why ML-DSA-65?

• NIST standardized — First finalized post-quantum signature standard (FIPS 204, August 2024)
• High security level — Designed for long-term license protection against both classical and quantum threats
• Performance — Fast verification suitable for startup-time license checks
• Well-studied foundation — Based on lattice-based cryptography with extensive academic review

Dual-Signature Verification

Donjon v2 licenses carry two independent signatures over the same payload. Both must verify successfully for the license to be accepted.

Verification Overview

License files carry two independent digital signatures. The platform verifies both signatures using embedded public keys, checks expiry, machine binding, and revocation status. No network call is required.

Why Dual Signatures?

• Defense in depth — If either algorithm is compromised, the other still protects
• Future-proofing — Classical signatures protect against flaws in new PQC algorithms; post-quantum signatures protect against quantum attacks on classical crypto

Machine Fingerprinting

Licenses can be bound to a specific machine to prevent unauthorized redistribution. The fingerprint is a deterministic SHA-256 hash of stable hardware identifiers.

Fingerprint Components

The machine fingerprint is a deterministic hash of stable hardware identifiers including network adapter, hostname, platform, processor, and OS-level machine ID. The fingerprint is computed locally and never transmitted.

Air-Gap Security Model

Donjon's license system is designed to work completely offline. No network call is required for license verification.

How It Works

• Public keys are embedded — Both the Ed25519 and ML-DSA-65 public keys are compiled into the product. The private keys never leave the license generation tool.
• Verification is local — The platform verifies signatures using the embedded public keys. No license server callback is needed.
• Revocation is file-based — A local data/revoked.json file lists revoked license IDs. This file can be updated manually or via a periodic sync when connectivity is available.

Offline Capabilities

Operation	Online Required?
License verification	No
All scanning operations	No (except cloud scanner)
AI analysis (template mode)	No
Report generation	No
Compliance mapping	No
License activation (initial)	File transfer only
Revocation list updates	Optional sync
Vulnerability DB updates	Pre-populate before air-gap

License Server Architecture

License Generation

Licenses are created by a separate offline admin tool that is never distributed with the product. The product contains only public verification keys — even full source code access does not allow forging licenses.

Key Security Properties

• No private keys in product: Only public verification keys are embedded. Signing keys are kept offline.
• Asymmetric cryptography: The signing key and verification key are different, eliminating shared-secret risks.
• Dual algorithm protection: Both classical and post-quantum signatures must verify successfully.

License Server: license.donjonsec.com

The optional license server (license.donjonsec.com) provides:

• License purchase and download portal
• Revocation list distribution
• License transfer processing
• Renewal management

The server is optional -- it is not contacted during normal product operation. It is only used for administrative license lifecycle events.

Revocation Process

Licenses can be revoked when necessary (theft, terms violation, replacement).

Revocation Mechanism

1. The revoked license ID is added to the master revocation list on license.donjonsec.com
2. The revocation list is distributed as revoked.json in the product's data/ directory
3. On each license load, the platform checks the local revocation list
4. If the license ID is found, the platform falls back to Community tier

Revoked license IDs are maintained in a local revocation list file within the platform's data directory.

Security Best Practices for Deployment

Platform Security

• Run with least privilege. Donjon does not require root/admin access for most operations. Only grant elevated privileges for specific scans (e.g., SYN scans with nmap).
• Protect the data directory. The evidence database contains sensitive scan results. Set appropriate file permissions (chmod 700 data/ on Linux).
• Use HTTPS. The web dashboard runs on port 8443. Configure TLS certificates for production deployments.
• Rotate API keys. Change API keys periodically and use different keys for different integrations.

Data Protection

• Enable AI data sanitization. Always set sanitize_external: true when using external AI providers. This strips IP addresses and hostnames before sending data.
• Credential storage uses Fernet encryption. The credential manager encrypts stored credentials using symmetric encryption.
• Cloud credentials are never stored in portable mode. When running from USB, cloud provider credentials are not persisted to prevent accidental exposure.
• Container scanner uses read-only operations only. No exec or attach commands are used.

License Security

• Do not share license files. Machine-bound licenses are non-transferable without support approval.
• Keep the revocation list updated. Periodically sync revoked.json in connected environments.
• Verify license integrity. If you suspect tampering, re-download the license from the portal.

Network Security

• Only scan authorized targets. Unauthorized scanning may violate laws and regulations. Always obtain written authorization.
• Use dedicated scan networks. When possible, scan from a dedicated assessment VLAN.
• Monitor scan traffic. Inform network security teams before running scans to avoid triggering alerts.

Incident Response

Compromised License

1. Revoke the license immediately. Contact support at donjonsec.com to add the license to the revocation list.
2. Distribute the updated revocation list. Update data/revoked.json on all deployments.
3. Issue a replacement license. Generate a new license with a new license ID.

Compromised Scan Data

1. Isolate the affected system. Disconnect from the network if the evidence database was exposed.
2. Assess the exposure. Determine what scan data, findings, and credentials may have been exposed.
3. Notify affected parties. If scan results include information about third-party systems, notify the system owners.
4. Rotate credentials. If the credential manager was compromised, rotate all stored credentials.
5. Review audit logs. Use the audit trail (GET /api/v1/audit) to understand what actions were taken.

Suspected License Forgery

The dual-signature scheme makes forgery computationally infeasible. If you suspect a forged license:

1. Check the platform log for signature verification results
2. Verify the license.json file has not been modified (check file hashes)
3. Ensure all required cryptographic dependencies are properly installed
4. Contact support with the license ID and verification log output