Skip to content

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 ​

  1. 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.
  2. Signatures. These follow once ML-DSA (FIPS 204) reaches Keycloak, the JOSE standards and the bundled registry.
  3. 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 ​

AlgorithmKindQuantum safetyUsed by
X25519MLKEM768Key encapsulationHybrid post-quantumHTTPS overlay, Outbound HTTPS and SMTP, Bundled OpenBao listener
mlkem768x25519-sha256 (SSH)Key encapsulationHybrid post-quantumDevice SSH: shell steps, asyncssh and scrapli transports, Device SSH: netmiko transport, Git over SSH
X25519Key agreementQuantum-vulnerableHTTPS 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-521Key agreementQuantum-vulnerableDevice SSH: shell steps, asyncssh and scrapli transports, Device SSH: netmiko transport
Finite-field Diffie-Hellman (groups 14 and 16)Key agreementQuantum-vulnerableDevice SSH: netmiko transport
RSA 2048 with SHA-256 (RS256)SignatureQuantum-vulnerableAccess tokens
RSA with SHA-256 or SHA-512SignatureQuantum-vulnerableBundled OpenBao listener, Device SSH: shell steps, asyncssh and scrapli transports, Device SSH: netmiko transport, Git over SSH
ECDSA P-256 with SHA-256SignatureQuantum-vulnerableHTTPS overlay
ECDSA over NIST P-256, P-384 and P-521SignatureQuantum-vulnerableDevice SSH: shell steps, asyncssh and scrapli transports, Device SSH: netmiko transport, Git over SSH
Ed25519SignatureQuantum-vulnerableRegistry tokens, Device SSH: shell steps, asyncssh and scrapli transports, Device SSH: netmiko transport, Git over SSH
AES-256-GCMAuthenticated encryptionQuantum-resistantEvent-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-GCMAuthenticated encryptionQuantum-resistantHTTPS 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 modeBlock cipherQuantum-resistantDevice SSH: netmiko transport
ChaCha20-Poly1305Authenticated encryptionQuantum-resistantHTTPS overlay, Outbound HTTPS and SMTP, Device SSH: shell steps, asyncssh and scrapli transports
HMAC-SHA256Message authenticationQuantum-resistantPersonal access tokens, Run and step tokens, Inbound webhook signatures, Outgoing webhook signatures, Device SSH: netmiko transport, Object store requests, Egress policy networks
HMAC-SHA512Message authenticationQuantum-resistantInbound webhook signatures
HMAC-SHA1Message authenticationQuantum-resistantOne-time codes
HKDF-SHA256Key derivationQuantum-resistantEvent-stream tickets, Registry tokens
Argon2idKey derivationQuantum-resistantPasswords
SHA-256HashQuantum-resistantSign-in code exchange, Event-stream tickets, Terraform and OpenTofu state, Object store requests, SSH host key fingerprints, Content digests, Release digests
SHA-512HashQuantum-resistantContent digests
MD5HashNot for securityDevice and object store checksums
SHA-1HashNot for securityBill 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.py in 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.py in 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.py in hegemony-step-plugins, transports/transport_scrapli/src/hegemony_transport_scrapli/transport.py in 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.py in 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

Released as open source under the AGPL-3.0-or-later license. Development is sponsored by Rexonix s.r.o. Contact — [email protected].