Crypto Overview

How cryptography works in AEGIS -- signatures, encryption, and key management.

AEGIS uses cryptography for three purposes: tamper-evident governance signatures on override approvals, PII encryption at rest in telemetry events, and MCP tool schema integrity via the AMTSS protocol. All crypto is optional -- AEGIS functions without any crypto dependencies installed, but production deployments should enable at least signatures and PII encryption.

Three Capabilities

1. Override Signatures (Two-Key Approval)

When a proposal fails governance gates but needs to proceed, two custodians (Risk Lead + Security Lead) must each sign the override request. AEGIS validates both signatures before approving.

• Provider: BIP-322 Schnorr (default) or Ed25519 + ML-DSA-44 hybrid (post-quantum)
• Module: src/workflows/override.py -- DualSignatureValidator
• Guide: Override Workflow

2. PII Encryption at Rest

Telemetry events may contain personally identifiable information (actor IDs, override justifications, proposal context). AEGIS encrypts 12 PII fields using hybrid post-quantum encryption before they reach any sink.

• Provider: X25519 + ML-KEM-768 + AES-256-GCM
• Module: src/telemetry/encryption.py -- PIIEncryptionEnricher
• Key hierarchy: KEK (master) wraps DEK (data), DEK encrypts fields

3. MCP Tool Schema Signing (AMTSS)

The Autonomous MCP Tool Schema Signing protocol signs the tools/list response so agents can verify tool definitions have not been tampered with in transit.

• Provider: Ed25519 (via cryptography library)
• Module: src/crypto/schema_signer.py -- ToolSchemaSigner
• Activation: Automatic when cryptography is installed

Dependency Groups

Install only what you need:

The cryptography library (for Ed25519 and AMTSS) is included in the crypto group. For post-quantum, you also need the native liboqs library installed on the system.

# Recommended production install
pip install -e ".[crypto,pqc,kms]"

# Development/testing (all crypto features)
pip install -e ".[crypto,pqc]"

Signature Provider Hierarchy

AEGIS selects the best available signature provider automatically:

The hybrid provider is not auto-selected yet (pending GAP-Q1 full validation). Use it explicitly for post-quantum defense-in-depth:

from crypto import get_hybrid_provider

provider = get_hybrid_provider()  # Ed25519 + ML-DSA-44

KEK Provider Hierarchy

Key Encryption Key (KEK) providers protect HybridKEM private keys at rest. Auto-detection tries providers in order:

from aegis_governance import get_kek_provider

provider = get_kek_provider()        # auto-detect best available
provider = get_kek_provider("kms")   # force AWS KMS

Key Hierarchy

                    +-------------------+
                    |    KEK (Master)   |  Stored in KMS / HSM / env var
                    |  Never in DB/logs |
                    +--------+----------+
                             |
                        wraps / unwraps
                             |
                    +--------v----------+
                    |   DEK (Data Key)  |  Versioned, rotatable
                    | HybridKEM keypair |  (X25519 + ML-KEM-768)
                    +--------+----------+
                             |
                      encrypts / decrypts
                             |
                    +--------v----------+
                    |     Payload       |  PII fields in telemetry
                    | AES-256-GCM bulk  |  Override signatures
                    +-------------------+

The KEK never leaves its secure boundary (KMS/HSM). DEKs are encrypted by the KEK before storage. Payloads are encrypted by the DEK using AES-256-GCM.

Quick Start

Override Signatures (Minimal)

from aegis_governance import DualSignatureValidator

validator = DualSignatureValidator()  # auto-selects BIP322 or Ed25519
msg_hash = validator.create_message_hash(
    proposal_id="prop-001",
    justification="Emergency hotfix required",
    failed_gates=["risk"],
)
# Each custodian signs msg_hash with their private key
# See: Override Workflow guide

PII Encryption (Minimal)

from telemetry.encryption import create_pii_enricher
from telemetry.pipeline import TelemetryPipeline
from aegis_governance import get_kek_provider

kek = get_kek_provider()  # auto-detect
public_key = kek.get_public_key()

enricher = create_pii_enricher(
    public_key=public_key,
    dek_version="dek-v1-20260101",
)

pipeline = TelemetryPipeline()
pipeline.add_enricher(enricher)

Check Crypto Availability

from crypto import (
    BIP322_AVAILABLE,
    HYBRID_AVAILABLE,
    HYBRID_KEM_AVAILABLE,
    SCHEMA_SIGNER_AVAILABLE,
)

print(f"BIP-322 signatures: {BIP322_AVAILABLE}")
print(f"Hybrid signatures:  {HYBRID_AVAILABLE}")
print(f"Hybrid encryption:  {HYBRID_KEM_AVAILABLE}")
print(f"Schema signing:     {SCHEMA_SIGNER_AVAILABLE}")

Related Documentation

• Override Workflow -- Two-key approval process step-by-step
• Key Management Guide -- KEK lifecycle, rotation, provisioning
• Python SDK: Key Management -- API reference
• Post-Quantum Rationale -- See the hybrid signature design rationale in the sections above