Configuration Reference

hoike is configured with a single TOML file, loaded once at startup. The default path is /etc/hoike/hoike.toml; override it with --config:

hoike serve --config /path/to/hoike.toml

Every key can also be set via environment variable using the HOIKE_ prefix, double-underscore section separators, and uppercase names. For example, server.listen becomes HOIKE_SERVER__LISTEN. Environment variables take precedence over the config file.

[server]

Top-level server settings that control the process mode, listener, and request limits.

[server]
mode   = "edge"
listen = "0.0.0.0:2560"
max_request = 8192

Mode validation

mode is the single most important setting. It determines which code paths are active:

• signer — reads revocation sources, produces ahu bundles, does not serve OCSP queries.
• edge — serves pre-signed responses from bundles, holds no private keys.
• combined — runs both signer and edge in one process.

hoike validates mode-specific constraints at startup. For example, nonce_policy = "live" on an edge node is a fatal error (edge nodes have no signing keys).

[storage]

Paths and limits for bundle storage and persistent state.

[storage]
bundle_dir = "/var/lib/hoike/bundles"
state_db   = "/var/lib/hoike/state"
max_chain  = 24

Operational note: Back up state_db alongside your bundle directory. If state_db is lost, the node cannot detect rollback or fork attacks until it re-establishes its high-water marks from a trusted source.

[gossip]

SWIM gossip protocol settings for edge fleet coordination. Gossip provides membership tracking, generation announcements (new bundles), and urgent revocation notices. See Gossip Configuration for a deep dive.

[gossip]
enabled      = true
bind         = "0.0.0.0:7946"
seeds        = ["edge-a.pki.example:7946", "edge-b.pki.example:7946"]
identity_key = "/etc/hoike/gossip.key"
node_name    = "edge-01"

Disabling gossip

For air-gap or single-node deployments, disable gossip entirely:

[gossip]
enabled = false

When gossip is disabled, bundles must be delivered out-of-band (removable media, hoike import, or a scheduled file copy). See Air-Gap Deployments.

[[ca]]

Each [[ca]] section configures one CA whose certificates this responder handles. hoike supports multiple [[ca]] sections for multi-CA deployments. Requests are routed to the correct CA by issuerKeyHash lookup. See Multi-CA Routing.

Identity and source

Signing

CertID and compatibility

Nonce handling

Timing and batch production

Completeness

Source types

The source field is an inline table that specifies where revocation data comes from.

CRL source (implemented):

source = { type = "crl", path = "/var/lib/hoike/crls/enterprise.crl" }

Dogtag source (planned):

source = { type = "dogtag", url = "https://ca01.pki.example:8443", auth = "mtls", cert = "/etc/hoike/ra.pem" }

[[ca]]
label          = "enterprise-issuing-01"
source         = { type = "crl", path = "/var/lib/hoike/crls/enterprise.crl" }
signing        = "ca-direct"
sig_alg        = "ecdsa-p256"
responder_id   = "by-key"
certid_compat  = "dual"
nonce_policy   = "ignore"
validity       = "24h"
batch_interval = "1h"
jitter         = "2h"
archive_cutoff = "1y"
completeness   = "authoritative-complete"

Duration strings

Duration values use a human-readable format: a number followed by a unit suffix.

Validation rules

hoike validates the configuration at startup and exits with a descriptive error if any rule is violated:

Complete annotated example

# /etc/hoike/hoike.toml — Edge node serving two CAs with gossip

[server]
mode        = "edge"           # Keyless serving from pre-signed bundles
listen      = "0.0.0.0:2560"   # IANA-assigned OCSP port
max_request = 8192             # Max POST body; GET is path-limited to ~255 bytes

[storage]
bundle_dir = "/var/lib/hoike/bundles"   # Where ahu bundles are read from
state_db   = "/var/lib/hoike/state"     # Epoch high-water marks — MUST persist across restarts
max_chain  = 24                         # Accept up to 24 delta bundles before requiring a full

[gossip]
enabled      = true
bind         = "0.0.0.0:7946"
seeds        = ["edge-a.pki.example:7946", "edge-b.pki.example:7946"]
identity_key = "/etc/hoike/gossip.key"
node_name    = "edge-01"

# Enterprise issuing CA — CRL-based, pre-signed responses
[[ca]]
label          = "enterprise-issuing-01"
source         = { type = "crl", path = "/var/lib/hoike/crls/enterprise.crl" }
signing        = "ca-direct"
sig_alg        = "ecdsa-p256"
responder_id   = "by-key"
certid_compat  = "dual"          # Accept both SHA-256 and SHA-1 CertID hashes
nonce_policy   = "ignore"        # Pre-signed — nonce omitted from responses
validity       = "24h"           # Signer outage budget: 24h − 1h = 23h
batch_interval = "1h"
jitter         = "2h"
archive_cutoff = "1y"
completeness   = "authoritative-complete"

# Partner issuing CA — delegated responder, nonces forwarded to signer
[[ca]]
label          = "partner-issuing-01"
source         = { type = "crl", path = "/var/lib/hoike/crls/partner.crl" }
signing        = "delegated"
responder_cert = "/etc/hoike/partner-ocsp.pem"
responder_key  = "/etc/hoike/partner-ocsp.key"
sig_alg        = "ecdsa-p384"
responder_id   = "by-key"
certid_compat  = "sha256"        # Partner clients all support SHA-256
nonce_policy   = "forward"       # Proxy nonce-bearing requests to signer
forward_to     = "https://signer.pki.example:2560"
validity       = "12h"
batch_interval = "30m"
jitter         = "1h"
archive_cutoff = "6m"            # Partner certs are short-lived
completeness   = "partial"       # CRL may not list every certificate

Environment variable overrides

Any configuration key can be overridden with an environment variable. The naming convention is:

HOIKE_<SECTION>__<KEY>

Double underscores separate section from key; single underscores within a key name are preserved.

Environment variables are useful for container deployments where the base config file is baked into the image and per-instance settings (like node_name or listen) vary.

Note: [[ca]] array sections cannot be fully configured via environment variables due to TOML array-of-tables semantics. Use the config file for CA definitions.