Cryptography
Every algorithm, key and protocol Hegemony uses, and how each stands against a quantum computer. The same list is attached to each release, beside the bills of materials, as hegemony-cryptography.cbom.json, a CycloneDX cryptography bill of materials (CBOM). Both come from scripts/sbom/cryptography.py.
Defaults of other products and libraries (Keycloak's signing key, Caddy's certificate, a library's TLS groups) were checked against the versions named here.
Quantum safety
- Hybrid post-quantum. Two key exchanges at once: X25519 and ML-KEM-768 (FIPS 203). Reading the traffic needs both broken, so a quantum computer alone does not reveal it.
- Quantum-vulnerable. A public-key algorithm that a large enough quantum computer breaks (Shor's algorithm). For a key exchange, traffic recorded today could be read then. For a signature, forging needs that computer at the time.
- Quantum-resistant. A symmetric cipher, message authentication code or hash. A quantum computer weakens these only modestly; at these sizes they need no change.
- Not for security. A checksum or an identifier that protects nothing.
What changes first
- Key exchange. Traffic recorded today could be read later, so this matters now. TLS from the HTTPS overlay, the bundled OpenBao and the Python services offers X25519MLKEM768, and CI checks it. Device SSH offers mlkem768x25519-sha256 on every transport; most network devices do not support it yet.
- Signatures. These follow once ML-DSA (FIPS 204) reaches Keycloak, the JOSE standards and the bundled registry.
- Symmetric ciphers, message authentication codes and hashes need no change.
Not encrypted by Hegemony itself: traffic between the services on their internal Docker network, other than to OpenBao, and data the database and the bundled object store keep on disk.
Algorithms
| Algorithm | Kind | Quantum safety | Used by |
|---|---|---|---|
| X25519MLKEM768 | Key encapsulation | Hybrid post-quantum | HTTPS overlay, Outbound HTTPS and SMTP, Bundled OpenBao listener |
| mlkem768x25519-sha256 (SSH) | Key encapsulation | Hybrid post-quantum | Device SSH: shell steps, asyncssh and scrapli transports, Device SSH: netmiko transport, Git over SSH |
| X25519 | Key agreement | Quantum-vulnerable | HTTPS overlay, Outbound HTTPS and SMTP, Bundled OpenBao listener, Device SSH: shell steps, asyncssh and scrapli transports, Device SSH: netmiko transport, Git over SSH |
| ECDH over NIST P-256, P-384 and P-521 | Key agreement | Quantum-vulnerable | Device SSH: shell steps, asyncssh and scrapli transports, Device SSH: netmiko transport |
| Finite-field Diffie-Hellman (groups 14 and 16) | Key agreement | Quantum-vulnerable | Device SSH: netmiko transport |
| RSA 2048 with SHA-256 (RS256) | Signature | Quantum-vulnerable | Access tokens |
| RSA with SHA-256 or SHA-512 | Signature | Quantum-vulnerable | Bundled OpenBao listener, Device SSH: shell steps, asyncssh and scrapli transports, Device SSH: netmiko transport, Git over SSH |
| ECDSA P-256 with SHA-256 | Signature | Quantum-vulnerable | HTTPS overlay |
| ECDSA over NIST P-256, P-384 and P-521 | Signature | Quantum-vulnerable | Device SSH: shell steps, asyncssh and scrapli transports, Device SSH: netmiko transport, Git over SSH |
| Ed25519 | Signature | Quantum-vulnerable | Registry tokens, Device SSH: shell steps, asyncssh and scrapli transports, Device SSH: netmiko transport, Git over SSH |
| AES-256-GCM | Authenticated encryption | Quantum-resistant | Event-stream tickets, Terraform and OpenTofu state, State data keys, wrapped by Transit, State data keys, wrapped by the platform key, Bundled OpenBao seal, HTTPS overlay, Outbound HTTPS and SMTP, Bundled OpenBao listener, Device SSH: shell steps, asyncssh and scrapli transports, Device SSH: netmiko transport |
| AES-128-GCM | Authenticated encryption | Quantum-resistant | HTTPS overlay, Outbound HTTPS and SMTP, Bundled OpenBao listener, Device SSH: shell steps, asyncssh and scrapli transports, Device SSH: netmiko transport |
| AES-128 and AES-256 in counter mode | Block cipher | Quantum-resistant | Device SSH: netmiko transport |
| ChaCha20-Poly1305 | Authenticated encryption | Quantum-resistant | HTTPS overlay, Outbound HTTPS and SMTP, Device SSH: shell steps, asyncssh and scrapli transports |
| HMAC-SHA256 | Message authentication | Quantum-resistant | Personal access tokens, Run and step tokens, Inbound webhook signatures, Outgoing webhook signatures, Device SSH: netmiko transport, Object store requests, Egress policy networks |
| HMAC-SHA512 | Message authentication | Quantum-resistant | Inbound webhook signatures |
| HMAC-SHA1 | Message authentication | Quantum-resistant | One-time codes |
| HKDF-SHA256 | Key derivation | Quantum-resistant | Event-stream tickets, Registry tokens |
| Argon2id | Key derivation | Quantum-resistant | Passwords |
| SHA-256 | Hash | Quantum-resistant | Sign-in code exchange, Event-stream tickets, Terraform and OpenTofu state, Object store requests, SSH host key fingerprints, Content digests, Release digests |
| SHA-512 | Hash | Quantum-resistant | Content digests |
| MD5 | Hash | Not for security | Device and object store checksums |
| SHA-1 | Hash | Not for security | Bill of materials serial numbers |
Sign-in and access
Access tokens
Keycloak signs each access token; the API accepts only RS256 and checks it against the keys the realm publishes.
- Algorithms: RSA 2048 with SHA-256 (RS256) (quantum-vulnerable)
- Implemented by: Keycloak 26.1.4 signs; PyJWT 2.15 verifies
- Key: An RSA 2048 key Keycloak generates for the realm (Realm settings → Keys)
- Where:
apps/api/auth/jwt_validator.py,deploy/compose/keycloak/realm-export.json
Sign-in code exchange
OpenID Connect with PKCE: the browser proves it started the sign-in with a SHA-256 hash of a one-time secret (S256).
- Protocol: OpenID Connect
- Algorithms: SHA-256 (quantum-resistant)
- Implemented by: oidc-client-ts in the UI; keycloak-init requires S256 on the client
- Key: A random secret per sign-in, kept in the browser
- Where:
apps/ui/src/auth/AuthProvider.tsx,deploy/compose/keycloak/keycloak-init.sh
Passwords
Keycloak stores a hash of each password, never the password.
- Algorithms: Argon2id (quantum-resistant)
- Implemented by: Keycloak 26.1.4 default: 5 passes, 7 MiB, 32-byte hash
- Where:
deploy/compose/keycloak/realm-export.json
One-time codes
Time-based one-time codes (TOTP, RFC 6238) for multi-factor authentication: 6 digits every 30 seconds.
- Algorithms: HMAC-SHA1 (quantum-resistant)
- Implemented by: Keycloak 26.1.4 default OTP policy
- Key: A secret per user, made when the user sets up the authenticator app
- Where:
deploy/compose/keycloak/keycloak-init.sh
Personal access tokens
256 random bits. The database keeps only an HMAC-SHA256 of the token under a server-side pepper, so it can be checked but not read back.
- Algorithms: HMAC-SHA256 (quantum-resistant)
- Implemented by: Python secrets and hmac
- Key: HEGEMONY_PAT_PEPPER, required in production; rotated with HEGEMONY_PAT_PEPPER_PREVIOUS
- Where:
apps/api/services/api_tokens.py
Run and step tokens
Short-lived tokens a running step uses for state and registry access: 256 random bits, kept as HMAC-SHA256 like personal access tokens, valid at most 24 hours.
- Algorithms: HMAC-SHA256 (quantum-resistant)
- Implemented by: Python secrets and hmac
- Key: HEGEMONY_PAT_PEPPER; while rotating, HEGEMONY_PAT_PEPPER_PREVIOUS too
- Where:
apps/api/services/run_tokens/tokens.py
Internal service token
The worker and scheduler call the API's internal routes with a shared secret.
- Implemented by: Python hmac (constant-time comparison)
- Key: HEGEMONY_INTERNAL_API_TOKEN, required in production
- Where:
apps/api/auth/rbac_middleware.py,packages/core/settings.py
Event-stream tickets
The browser trades its token for a ticket to open a live event stream: 256 random bits, single use, valid 5 minutes. In Redis, a ticket's entry is named by an HKDF-SHA256 value derived from it, what it grants is encrypted with AES-256-GCM under a key derived from it, and the index of a user's tickets is named by a SHA-256 of the user's id.
- Algorithms: HKDF-SHA256 (quantum-resistant), AES-256-GCM (quantum-resistant), SHA-256 (quantum-resistant)
- Implemented by: Python secrets and hashlib; cryptography 50 (HKDF, AESGCM)
- Where:
apps/api/routers/bff.py,apps/api/services/ticket_store.py
Registry tokens
The API signs the bearer tokens the bundled registry (zot) accepts, valid 5 minutes.
- Algorithms: Ed25519 (quantum-vulnerable), HKDF-SHA256 (quantum-resistant)
- Implemented by: PyJWT and cryptography sign; zot verifies
- Key: HEGEMONY_REGISTRY_TOKEN_KEY: an Ed25519 private key, or a secret of at least 32 characters turned into one with HKDF-SHA256
- Where:
extensions/registry/src/hegemony_registry/services/registry_tokens.py,extensions/registry/src/hegemony_registry/settings.py
Webhooks
Inbound webhook signatures
A sender signs the timestamp and body with HMAC-SHA256; requests older than the replay window (5 minutes by default) are refused. A webhook in NetBox's mode takes NetBox's HMAC-SHA512 of the body alone, which carries no timestamp, so it has no replay window. A webhook can use a bearer secret instead.
- Algorithms: HMAC-SHA256 (quantum-resistant), HMAC-SHA512 (quantum-resistant)
- Implemented by: Python hmac
- Key: The webhook's secret, kept in a secret backend and rotatable
- Where:
apps/api/services/webhooks.py,apps/api/routers/hooks.py
Inbound webhook addresses
Each webhook's address carries 256 random bits.
- Implemented by: Python secrets
- Where:
apps/api/routers/webhooks.py
Outgoing webhook signatures
Notifications sent to a webhook can carry an HMAC-SHA256 of the body, or of a timestamp and the body.
- Algorithms: HMAC-SHA256 (quantum-resistant)
- Implemented by: Python hmac
- Key: The channel's secret, from a secret reference
- Where:
plugins/notification_core_transports/src/hegemony_notification_core_transports/outgoing_webhook.pyin hegemony-notification-plugins
Data at rest
Terraform and OpenTofu state
Each state version is compressed, then encrypted with AES-256-GCM under a fresh 256-bit data key and a 12-byte random nonce, bound to its organization and state. The SHA-256 of each version is stored in clear beside it, to identify the version.
- Algorithms: AES-256-GCM (quantum-resistant), SHA-256 (quantum-resistant)
- Implemented by: cryptography 50 (AESGCM)
- Key: A new data key per version, stored only wrapped (below)
- Where:
apps/api/services/tf_state/crypto.py
State data keys, wrapped by Transit
With an OpenBao or Vault backend, Transit makes and unwraps each data key under a key per organization.
- Algorithms: AES-256-GCM (quantum-resistant)
- Implemented by: OpenBao or Vault Transit (aes256-gcm96), through hvac
- Key: Transit key hegemony-org-<organization>-tf-state, kept in OpenBao or Vault
- Where:
apps/api/services/tf_state/keys.py,plugins/secret_vault/src/hegemony_secret_vault/vault_client.pyin hegemony-secret-plugins
State data keys, wrapped by the platform key
Without Transit, each data key is wrapped with AES-256-GCM under one platform key.
- Algorithms: AES-256-GCM (quantum-resistant)
- Implemented by: cryptography 50 (AESGCM)
- Key: HEGEMONY_TF_STATE_ENCRYPTION_KEY (256 bits)
- Where:
apps/api/services/tf_state/keys.py,packages/core/settings.py
Bundled OpenBao seal
The bundled OpenBao encrypts its storage under a key it unseals with at start.
- Algorithms: AES-256-GCM (quantum-resistant)
- Implemented by: OpenBao 2.6.2 static seal
- Key: A 256-bit key from openssl rand, in a file only OpenBao can read
- Where:
deploy/openbao/config.hcl,deploy/openbao/prep.sh
Network
HTTPS overlay
The optional Caddy proxy in front of the UI and Keycloak. It offers X25519MLKEM768 first and still accepts X25519.
- Protocol: TLS 1.2, 1.3
- Algorithms: X25519MLKEM768 (hybrid post-quantum), X25519 (quantum-vulnerable), ECDSA P-256 with SHA-256 (quantum-vulnerable), AES-128-GCM (quantum-resistant), AES-256-GCM (quantum-resistant), ChaCha20-Poly1305 (quantum-resistant)
- Implemented by: Caddy 2.11 (Go crypto/tls)
- Key: Caddy's local certificate authority, ECDSA P-256 (self-signed)
- Note: Checked in CI by scripts/check-pq-tls.py --proxy
- Where:
deploy/compose/docker-compose.https.yml,deploy/compose/https/Caddyfile,scripts/check-pq-tls.py
Outbound HTTPS and SMTP
Connections the API, worker and scheduler make: identity providers, Git, registries, secret backends, object stores, NetBox, webhooks, HTTP steps and email. They offer X25519MLKEM768 first; the server decides what is used.
- Protocol: TLS 1.2, 1.3
- Algorithms: X25519MLKEM768 (hybrid post-quantum), X25519 (quantum-vulnerable), AES-128-GCM (quantum-resistant), AES-256-GCM (quantum-resistant), ChaCha20-Poly1305 (quantum-resistant)
- Implemented by: Python ssl with OpenSSL 3.5.7 (Debian 13), through httpx, aiohttp, requests, boto3, hvac and aiosmtplib
- Key: Certificates checked against the system or certifi authorities
- Note: Checked weekly by scripts/check-pq-tls.py --client-image
- Where:
deploy/compose/Dockerfile.api,scripts/check-pq-tls.py
Bundled OpenBao listener
The API, worker and scheduler reach the bundled OpenBao over TLS 1.2 or later; it accepts X25519MLKEM768.
- Protocol: TLS 1.2, 1.3
- Algorithms: X25519MLKEM768 (hybrid post-quantum), X25519 (quantum-vulnerable), RSA with SHA-256 or SHA-512 (quantum-vulnerable), AES-128-GCM (quantum-resistant), AES-256-GCM (quantum-resistant)
- Implemented by: OpenBao 2.6.2 (Go crypto/tls)
- Key: A private certificate authority (RSA 4096) and server certificate (RSA 2048), both SHA-256, made by prep.sh and renewed 30 days before expiry
- Where:
deploy/openbao/config.hcl,deploy/openbao/prep.sh,apps/api/routers/settings.py
Device SSH: shell steps, asyncssh and scrapli transports
Sessions to network devices and servers. mlkem768x25519-sha256 is offered first; a device without it gets classical key exchange. The step SDK's policy removes SHA-1, CBC and group exchange (whose server-chosen group may be under 2048 bits) unless a step sets allow_legacy_ssh.
- Protocol: SSH 2.0
- Algorithms: mlkem768x25519-sha256 (SSH) (hybrid post-quantum), X25519 (quantum-vulnerable), ECDH over NIST P-256, P-384 and P-521 (quantum-vulnerable), Ed25519 (quantum-vulnerable), ECDSA over NIST P-256, P-384 and P-521 (quantum-vulnerable), RSA with SHA-256 or SHA-512 (quantum-vulnerable), ChaCha20-Poly1305 (quantum-resistant), AES-256-GCM (quantum-resistant), AES-128-GCM (quantum-resistant)
- Implemented by: asyncssh 2.24 defaults, filtered by the step SDK's SSH policy
- Key: Device credentials from the secret store; host keys checked against the organization's trust store
- Where:
apps/worker/shell_transport.py,apps/worker/host_key_trust.py,transports/transport_asyncssh/src/hegemony_transport_asyncssh/transport.pyin hegemony-step-plugins,transports/transport_scrapli/src/hegemony_transport_scrapli/transport.pyin hegemony-step-plugins
Device SSH: netmiko transport
Sessions through netmiko, including its bastion hop. paramiko 5.1 offers mlkem768x25519-sha256 first; a device without it gets classical key exchange.
- Protocol: SSH 2.0
- Algorithms: mlkem768x25519-sha256 (SSH) (hybrid post-quantum), X25519 (quantum-vulnerable), ECDH over NIST P-256, P-384 and P-521 (quantum-vulnerable), Finite-field Diffie-Hellman (groups 14 and 16) (quantum-vulnerable), Ed25519 (quantum-vulnerable), ECDSA over NIST P-256, P-384 and P-521 (quantum-vulnerable), RSA with SHA-256 or SHA-512 (quantum-vulnerable), AES-128 and AES-256 in counter mode (quantum-resistant), AES-128-GCM (quantum-resistant), AES-256-GCM (quantum-resistant), HMAC-SHA256 (quantum-resistant)
- Implemented by: paramiko 5.1 defaults through netmiko, filtered by the step SDK's SSH policy; group exchange refuses a server group under 2048 bits
- Key: Device credentials from the secret store; host keys checked against the organization's trust store
- Where:
transports/transport_netmiko/src/hegemony_transport_netmiko/transport.pyin hegemony-step-plugins
Git over SSH
Git repositories reached over SSH use the OpenSSH client in the API image. Debian 13 ships OpenSSH 10.0, which offers mlkem768x25519-sha256 first.
- Protocol: SSH 2.0
- Algorithms: mlkem768x25519-sha256 (SSH) (hybrid post-quantum), X25519 (quantum-vulnerable), Ed25519 (quantum-vulnerable), ECDSA over NIST P-256, P-384 and P-521 (quantum-vulnerable), RSA with SHA-256 or SHA-512 (quantum-vulnerable)
- Implemented by: OpenSSH client from Debian 13
- Key: The repository's deploy key, from the secret store
- Note: Not checked by a test
- Where:
apps/api/services/git_ops.py,deploy/compose/Dockerfile.api
Object store requests
Requests to the object store are signed with AWS Signature Version 4.
- Algorithms: HMAC-SHA256 (quantum-resistant), SHA-256 (quantum-resistant)
- Implemented by: botocore
- Key: The object store's access key and secret
- Where:
apps/api/services/s3_client.py
Integrity and identifiers
SSH host key fingerprints
Trusted host keys are shown and matched by SHA-256 fingerprint.
- Algorithms: SHA-256 (quantum-resistant)
- Implemented by: cryptography 50, Python hashlib
- Where:
apps/api/services/ssh_host_keys.py
Content digests
Files, attachments, artifacts, flow versions and container images are identified and checked by digest.
- Algorithms: SHA-256 (quantum-resistant), SHA-512 (quantum-resistant)
- Implemented by: Python hashlib
- Where:
apps/api/routers/flows/attachments.py,apps/worker/api_utils.py,extensions/registry/src/hegemony_registry/services/oci_archive.py
Egress policy networks
Each egress policy's sandbox network takes its name, labels and IPv6 subnet from an HMAC-SHA256 of the policy, so steps under the same policy share one network.
- Algorithms: HMAC-SHA256 (quantum-resistant)
- Implemented by: Python hmac
- Key: HEGEMONY_SANDBOX_TOKEN, the sandbox daemon's attestation token
- Where:
packages/core/egress.py,apps/worker/egress_enforcement.py
Release digests
Container images are published and promoted by digest, and plugin wheels are pinned by the SHA-256 their releases list.
- Algorithms: SHA-256 (quantum-resistant)
- Implemented by: Docker, Python hashlib
- Where:
.github/workflows/docker-publish.yml,scripts/release/manifest.py
Device and object store checksums
MD5 where the other side offers nothing else: network operating systems verify uploaded images with it, and object stores report it as the ETag. Marked as not for security in the code.
- Algorithms: MD5 (not for security)
- Implemented by: Python hashlib (usedforsecurity=False)
- Where:
apps/api/routers/repositories.py,apps/api/services/s3_client.py,apps/api/services/storage/bootstrap.py
Bill of materials serial numbers
Serial numbers are UUID version 5, which hashes with SHA-1 by definition. Marked as not for security in the code.
- Algorithms: SHA-1 (not for security)
- Implemented by: Python hashlib (usedforsecurity=False)
- Where:
scripts/sbom/cyclonedx.py