TLS and Workspace PKI

Hovel's workspace PKI gives one daemon-owned lifecycle to the X.509 credentials used by Mesh providers, listening posts, implants, stagers, services, payloads, and external integrations. It replaces copied PEM strings and provider-specific certificate state with immutable generations, explicit trust, staged assignment changes, revocation, bounded signing authority, and auditable secret use.

This is workspace infrastructure, not a public Web PKI and not a general secret manager. The daemon owns certificate lifecycle and custody; a provider advertises how it can consume selected material; the consuming TLS stack owns the live handshake.

What problem it solves

A workspace certificate is more than a key and a PEM file. Hovel must also know:

• which authority and exact authority generation issued it;
• which profile, crypto backend, compatibility target, and TLS groups were resolved at issuance;
• which logical consumer is serving it and which trust generation that consumer uses;
• whether a new credential is merely staged or has become active;
• whether a generation was revoked and which fresh CRL communicates that fact;
• when a signing key or private-key projection was authorized and used; and
• how a provider received material without copying secrets into durable operation records.

The workspace PKI makes those relationships explicit. A failed issue, delivery, or rollout cannot silently replace a consumer's active credential, and changing a trust set's default does not silently move assignments already pinned to an older immutable trust generation.

Custody is not target-created credential evidence

Hovel uses the word credential for two deliberately different things. Keep their storage and display policies separate.

The model

Leaf lifecycle: issue, stage, activate

Issuance persists an idempotent intent before a backend can create a key or sign. The intent commits the exact backends, capability hashes, compatibility target, resolved TLS groups, template, issuer generation, key identity, and generation identity. A retry cannot silently switch to a different backend or policy snapshot.

A newly renewed or rotated generation is active in certificate inventory, but it does not replace an assignment automatically. Stage it on each intended assignment, perform the provider or deployment work, and activate only after that work succeeds. The assignment's previous active pointers remain authoritative until the revision-fenced activation commits.

Trust, revocation, and CRL publication

Revocation recording and CRL publication are separate on purpose. Revocation first changes workspace truth synchronously. Publication then builds a durable signing plan from the authority's effective revocation snapshot.

CRL publication advances through planned, signing, and signed phases before a completed immutable CRL generation is stored. An ownership lease fences concurrent workers; a signed checkpoint lets authorized crash reconciliation validate and finish without invoking an ambiguous signer twice. These worker leases are concurrency controls, not signing authorization.

Trust resolution rechecks certificate validity and CRL freshness. An expired CRL makes that trust generation unusable even though the immutable historical record remains inspectable. Automatic CRL refresh scheduling is not implemented, so publication and subsequent trust staging remain explicit operations.

Authority rollover without a trust gap

The daemon API implements rollover as one durable, revision-fenced operation. Root rollover places old and replacement CA generations in the overlap generation's anchor list. Subordinate rollover places them in the intermediate list and preserves the ancestor chain to an anchor.

The operation can track all eligible peer-trust assignments, an explicit set, or no Hovel-tracked consumers. Live rollovers reserve the trust set and required assignments so unrelated mutations cannot invalidate the proof. Cancellation is available only before overlap activation; once active trust changes, operators must complete the fenced workflow.

Rollover methods, acknowledgement inspection, and reservation errors are implemented in the daemon RPC and OpenAPI contract. There are no matching imperative hovel pki rollover commands today.

Signing leases are authority, not authority state

Authority lifecycle state and permission to use its signing key are independent. An unlock request grants an in-memory SigningLease scoped to the authenticated actor and operation. The lease expires automatically, disappears on daemon restart, and does not rewrite the authority or its CA generation.

• Unlock requires the request's explicit signing-lease approval.
• Every signing use rechecks authority state, lease scope, expiry, CA constraints, generation ownership, validity, and key binding.
• Lock removes only the matching actor and operation's lease; another scope cannot revoke it.
• Key access and signing authorization produce audit events without recording private bytes.

Encryption at rest and secret boundaries

• Local key material is serialized into a versioned AES-256-GCM envelope. Associated data binds schema, cipher, master-key version, workspace identity, key ID, and algorithm.
• Authority, generation, and issuance JSON remains inspectable metadata; HMAC-SHA-256 tags detect tampering with authenticated persisted records. Encryption is for private key material, not for public certificate inventory.
• The master-key file is the local root of trust. Its keys are base64-encoded, not encrypted by Hovel, so owner, permission, regular-file, symlink/reparse-point, and link-count checks matter.
• Initialization and open are separate. If an initialized workspace loses its master-key file, ordinary open fails closed rather than creating an unrelated key.
• The envelope code supports versioned master-key rotation and rewrap, but no current CLI or daemon RPC method exposes that maintenance operation.

Normal list and inspect methods never return private-key material. The daemon's ExportPKIBundle response is the one external control response that can: private export must match the generation's explicit-private-export policy, carry approvePrivateKeyExport, use the privileged local transport, and is audited and marked Cache-Control: no-store. For an externally held key, a bundle carries a provider reference rather than private bytes.

Crypto backends, compatibility targets, and credential providers

These three extension points answer different questions:

A crypto backend is privileged daemon infrastructure; a credential provider is a module-side consumer. Selecting a runtime TLS library does not select the issuer, and selecting an issuer does not force a TLS library on the consumer. See credential delivery and stamping and the provider development guide for the plugin boundary.

Classical and post-quantum-hybrid profiles

The domain reserves ML-DSA key and signature identifiers and a hybrid-pq-preferred policy for future capability negotiation. The default backend and current compatibility targets do not advertise ML-DSA, and no built-in profile selects the preferred-with-classical-fallback policy. Those are extension points, not current provider support.

A minimal operator workflow

The imperative CLI is daemon-backed. The following uses only current commands. Replace angle-bracket values with IDs returned by the preceding JSON/list operations; keep idempotency keys stable only when retrying the same request.

# Discover or initialize local custody.
hovel pki status --workspace .hovel --json
hovel pki init --workspace .hovel --yes
hovel pki backend list --workspace .hovel
hovel pki profile list --workspace .hovel

# Create a lab root, then read its generated authority ID.
hovel pki authority create "Lab Root" \
  --workspace .hovel \
  --role root \
  --profile root-modern \
  --idempotency-key lab-root-v1 \
  --yes
hovel pki authority list --workspace .hovel --json

# Grant this CLI actor/operation a short signing lease and issue one leaf.
hovel pki authority unlock <authority-id> \
  --workspace .hovel \
  --duration 5m \
  --approve
hovel pki certificate issue listener.internal \
  --workspace .hovel \
  --issuer <authority-id> \
  --profile tls-server \
  --idempotency-key listener-cert-v1 \
  --yes
hovel pki certificate list --workspace .hovel --json

# Bind a stable consumer slot, then stage and activate the returned generation.
hovel pki assignment bind mesh-provider/listener-west \
  --workspace .hovel \
  --id assignment-listener-west \
  --consumer-type mesh-listener \
  --purpose tls-server \
  --profile tls-server \
  --idempotency-key listener-assignment-v1 \
  --yes
hovel pki assignment stage assignment-listener-west <generation-id> \
  --workspace .hovel \
  --revision 1 \
  --idempotency-key listener-stage-v1 \
  --yes
hovel pki assignment inspect assignment-listener-west --workspace .hovel --json
hovel pki assignment activate assignment-listener-west \
  --workspace .hovel \
  --revision 2 \
  --idempotency-key listener-activate-v1 \
  --yes
hovel pki authority lock <authority-id> --workspace .hovel

Revision values above match a new assignment's first stage and activation only. In automation, inspect immediately before each mutation and send the observed revision; stale revisions must fail. A plain tls-server assignment does not verify a peer and may omit trust. TLS-client and mTLS purposes require an active trust set, and staging pins its exact active trust generation alongside the certificate generation.

Assignment-backed delivery into Mesh

The current external delivery path is deliberately narrow and implemented on StartMeshListener, RunMeshTask, OpenMeshStream, and OpenMeshBridge. The caller sends non-secret assignment, slot, projection, and form selectors plus a credential request context with approveCredentialUse: true. The daemon derives the allowed provider, listener, and node consumer bindings; verifies the active assignment and the provider's exact descriptor; resolves material; and invokes delivery and the consuming Mesh method in the same provider process.

POST /hovel.daemon.v1.DaemonService/StartMeshListener
Content-Type: application/json

{
  "moduleId": "lab-relay-mesh@v1.0.0",
  "request": {
    "listenerId": "listener-west",
    "name": "west TLS listener",
    "kind": "https-beacon",
    "deployment": "separate",
    "management": "provider",
    "config": { "bind": "127.0.0.1:8443" }
  },
  "credentials": [
    {
      "requestId": "listener-west-cert-v1",
      "assignmentId": "assignment-listener-west",
      "slotName": "listener-certificate",
      "capability": "runtime",
      "material": {
        "projection": "certificate-der",
        "form": "public"
      }
    },
    {
      "requestId": "listener-west-private-key-v1",
      "assignmentId": "assignment-listener-west",
      "slotName": "listener-private-key",
      "capability": "runtime",
      "material": {
        "projection": "private-key-pkcs8",
        "form": "private-bytes"
      }
    }
  ],
  "credentialContext": {
    "actorId": "operator-web",
    "operationId": "start-listener-west-v1",
    "correlationId": "change-listener-west-v1",
    "approveCredentialUse": true
  }
}

This request is valid only if the provider advertises the exact runtime slot and the active assignment is bound to the listener operation. The production selector accepts only runtime certificate-der/public, public-key-spki/public, and private-key-pkcs8/private-bytes combinations. It never returns resolved material to the HTTP caller. One assignment-and-slot pair may appear only once in a request, so a TLS identity must use distinct certificate and private-key slots for its certificate-der/public and private-key-pkcs8/private-bytes selections.

What is implemented, and what is not

Decision guide

Related documentation