Upgrading
hoike’s crate version is still 0.2.0, but the current build carries the October 2026 security-audit remediation (findings F01–F12), and several fixes change behavior that earlier 0.2.0 builds accepted. A configuration, state directory, or procedure that worked before can now fail at load or at startup rather than being silently accepted. This page covers what changes when you move a deployment to the hardened build, and what operators coming from 0.1.x should expect.
The authoritative upstream reference is the migration contract in the hoike repository.
Start by running the new binary against your existing configuration:
hoike check --config /etc/hoike/hoike.toml
hoike check is read-only; it never creates or changes state. Every change below is visible to it.
Configuration changes
Every configuration table parses with deny_unknown_fields. Unknown keys — typos, stale keys, keys removed in this build — fail at load instead of being silently ignored. See Configuration Reference.
| Change | Action |
|---|---|
storage.max_chain is removed | Delete the key from [storage]; a config that sets it fails to parse. Only full, uncompressed bundles are admitted now, so there is no delta-chain depth left to bound. |
seal_key + seal_cert pair required for production signing | Every signer/combined CA with signing_key.type = "file" or "pkcs11" must configure both keys. Exactly one of the two is an error, and so is reusing the OCSP signing key as the seal key. See Signer Mode. |
forward_to must be HTTPS | An http:// target fails startup and hoike check unless forward_insecure = true is set explicitly (lab use only). |
CRL sources require issuer_cert | See CRL sources below. |
State changes
State directories are operator-acknowledged state now, not a cache.
hoike init-state --config PATHbefore the first serve. A fresh state directory must be bootstrapped explicitly;servenever creates state implicitly. Existing valid state continues to work unchanged — run this only for new deployments and new state directories.- One writer per state directory.
serve,init-state, andimporthold an OS-level exclusiveflockon.writer.lockfor their full process lifetime; a second writer is rejected immediately. Stop the previous writer before starting a new one. - Missing or corrupt state is a recovery error, never a silent fresh timeline that forgets recorded high-water marks. Recovery means restoring from backup.
- Back up and restore the state directory as one unit — marks, snapshots, and lock file together. See Anti-Rollback Protection.
- Old binaries are not qualified to read the new snapshot state. Once the new build has written state, do not point an older binary at the same directory.
Bundle admission
Admission is fail-closed. Before upgrading edge nodes:
- Provision seal trust on every node that receives bundles from elsewhere —
seal_signer_pins,seal_trust_anchors, orseal_authorizationsunder[storage]. A node with no trust configured refuses bundles at startup instead of loading them with a warning. See Seal Trust Policy. - Only full, uncompressed bundles are admitted. Delta bundles, delta chains, tombstones, and compression are rejected before any durable state change. Materialize deltas into a full bundle with
ahu applyfirst. storage.allow_unauthenticated_bundles = true(defaultfalse) is the escape hatch for local demos: it permits structure-only admission, and only when no other trust is configured. Configured trust never downgrades to it.
Gossip authentication
gossip.auth_mode defaults to "required": unsigned, unknown, and forged broadcasts are dropped, and identity_key is mandatory. A non-empty legacy peer_keys fails configuration with migration instructions — replace it with peer_identities before anything else.
Fleets upgrading from builds without broadcast authentication should follow the four-step rollout in Gossip Configuration:
- Provision per-node identities and complete
peer_identitiesfleet-wide. - Set
auth_mode = "permissive"— unsigned legacy broadcasts are accepted, signed ones verified, unknown or forged ones rejected. - Configure
identity_keyon every node. - Set
auth_mode = "required"fleet-wide.
Mixed fleets stay interoperable at the frame level while you roll this out.
Import
hoike import is an offline, authenticated, recoverable installation:
hoike import --bundle /media/usb/enterprise.ahu \
--ca enterprise-issuing-01 \
--config /etc/hoike/hoike.toml
--forceis removed. Import refuses an active writer by design, so stophoike servefirst.- The bundle is authenticated under the configured seal trust and scope authorizations, even when
allow_unauthenticated_bundlespermits unauthenticated demo serving. - State must already have been initialized with
hoike init-state. - The source is read exactly once, the generation snapshot is immutable, and the state descriptor commits atomically before the bundle path is published. A failure before the commit leaves the previous generation byte-for-byte intact.
See Air-Gap Deployments for the full media-transfer workflow.
ahu verify and ahu apply
ahu verify no longer reports success without verifying the seal. A bare invocation fails; choose a mode:
ahu verify bundle.ahu --config /etc/hoike/hoike.toml # authenticated under configured trust
ahu verify bundle.ahu --structure-only # structure and digests only
--entries adds per-response OCSP signature checks via the embedded responder keys, and requires --config.
ahu apply produces an unsigned intermediate by default; a checksum is not a CMS seal. A sealed, installable result requires authenticated inputs plus the seal pair:
ahu apply base.ahu delta.ahu -o merged.ahu \
--seal-key seal.p8 --seal-cert seal.crt \
--input-signer-pin seal-signer.crt
CRL sources
issuer_cert is required for every CRL source and is enforced at startup and by hoike check. It is trusted configuration: its subject and public key must match the CA identity the bundle is scoped to. A config that omits it fails to start. See Revocation Sources.
0.1.x and supported versions
hoike’s security policy supports 0.2.x only; 0.1.x is unsupported. 0.2 still reads material produced by 0.1:
- 0.1 bundles load under the same admission rules — the ahu 0.1 wire profile is unchanged.
- Legacy cookie-only sync state is ignored; the dogtag-sync source runs one full directory refresh after the upgrade.
- Valid legacy state JSON remains readable; existing state continues to work unchanged.
Upgrade sequence
- Validate the configuration with the new binary:
hoike check --config /etc/hoike/hoike.toml(read-only). - Fix the configuration: remove
max_chain, addseal_key/seal_certpairs, add CRLissuer_cert, migratepeer_keystopeer_identities. - Provision seal trust on every edge that receives bundles from another machine.
- Stop the old writer, then start the new binary. New state directories need
hoike init-statefirst. - In gossip fleets, run the four-step authentication rollout once the binary upgrade is done.