Skip to main content

Documentation Index

Fetch the complete documentation index at: https://certplane.kippel.org/llms.txt

Use this file to discover all available pages before exploring further.

Certplane splits certificate management into two distinct phases. In the first phase, a host proves its identity to an internal CA and receives a long-lived identity certificate. In the second phase, that identity certificate acts as a credential when the host connects to the broker to request and renew publicly trusted service certificates. Your private keys never leave the host at any point.

​
The two binaries

Certplane is made up of two programs that you run in different places:

certplane-agent

Runs on each managed host. Generates key pairs locally, contacts step-ca during enrollment, and connects to the broker over mTLS to request and renew service certificates. The agent is the only component that touches private keys.

certplane-broker

Runs as a central server. Accepts mTLS connections from agents, validates their identity certificates, enforces the declarative policy file, and calls your public CA via ACME to obtain or renew service certificates. The broker caches issued certificates to avoid unnecessary CA calls.

​
Two-phase flow

Enrollment is a one-time setup step that gives a host a verifiable machine identity. It happens before the host can request any service certificate.What you do:
  1. Generate a short-lived bootstrap token on your step-ca instance for the host’s identity name (e.g., edge01.h.int.example.com).
  2. Write the token to the host at the path referenced in the agent config.
  3. Run certplane-agent enroll --config agent.yml.
What the agent does:
  1. Generates a private key (identity.key) locally — it never leaves the host.
  2. Creates a certificate signing request (CSR) containing the host identity name.
  3. Sends the CSR along with the bootstrap token to step-ca.
  4. step-ca validates the token, signs the CSR, and returns identity.crt.
  5. The agent writes identity.crt to disk. Enrollment is complete.
The bootstrap token is consumed on first use. After enrollment, the agent uses identity.crt directly for all future broker connections.
If you need to re-enroll a host, generate a new bootstrap token from step-ca. The old token cannot be reused.

​
Key security properties

Keys never leave the host. Both identity.key and service.key are generated on the host and stored locally. Only CSRs (which contain no secret material) are sent over the network. mTLS authentication. Every connection from an agent to the broker is mutually authenticated using TLS. The broker requires the agent to present a valid identity.crt signed by the configured internal CA. An agent without a valid identity certificate cannot reach the broker at all. Policy enforcement. The broker checks every certificate request against the policy file before contacting the public CA. If a host’s identity is not registered, or if it requests a profile it is not authorized for, the request is rejected. The policy file is the single authoritative source for what each host is allowed to receive. Audit log. The broker writes an audit record for every certificate issuance decision. The audit failure mode (fail_open or fail_closed) controls behavior if the audit subsystem itself encounters an error.

​
What happens at each trust boundary

BoundaryProtocolWhat is verified
Agent → step-ca (enrollment)HTTPSBootstrap token (one-time use); step-ca root fingerprint
Agent → broker (renewal)mTLSAgent’s identity.crt signed by internal CA
Broker → public CA (ACME)HTTPS + dns-01DNS record ownership via Cloudflare API
For step-by-step setup instructions, see Broker Setup, Agent Enrollment, and Running the Agent. To understand how to control what each host can request, see Policy Overview.