# 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.

Why Post-Quantum Matters for Licensing

License forgery resistance must remain strong for the full expected lifetime of the product. A license signed today must resist adversaries who may have access to quantum computers in the future. By signing with both classical and post-quantum algorithms, Donjon ensures license integrity even against "harvest now, decrypt later" attacks.

### 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.

Fingerprint Stability

Any change to the fingerprint components (hostname change, NIC replacement, OS reinstall) will cause a machine-bound license to fail verification. Contact support for a license transfer if your hardware changes.

## 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.

Air-Gap Revocation

In air-gapped environments, update the revocation list manually by copying the latest `revoked.json` from a connected machine to the air-gapped system'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