Skip to main content
The broker enforces a single declarative policy file (policy.path in broker.yml). It defines named profiles (the shape of a certificate request) and hosts (which identities may request which profiles). The authoritative schema is schemas/policy.schema.json.

​
Minimum policy

version: 1

profiles:
  public_edge_main:
    type: wildcard
    dns_names:
      - "*.example.com"
    acme:
      challenge: dns-01
      credentials: cloudflare/example-com
    renew_before: 720h

hosts:
  edge01:
    identity: edge01.h.int.example.com
    profiles:
      - public_edge_main

​
Top-level keys

KeyRequiredNotes
versionnoMust equal 1 if set. Reserved for future migrations. Default: 1.
profilesyesMap of profile name → profile definition. At least one profile.
hostsyesMap of host label → host definition. At least one host.
The broker rejects unknown top-level keys (additionalProperties: false).

​
How a request is authorized

When an agent calls POST /v1/certificates:
  1. The broker reads the CN of the client certificate (the agent’s identity).
  2. It looks up that identity in hosts.<label>.identity. If no host entry has a matching identity, the request is denied.
  3. The requested profile (from the JSON body) must appear in that host’s profiles list.
  4. The CSR’s DNS names must satisfy the profile’s dns_names rules — wildcard profiles require the SANs to fall under the configured wildcard label; multi_san profiles require the SANs to be exactly drawn from the allowed list.
  5. If all checks pass, the broker serves a cached bundle or issues via ACME.
Every decision — allow or deny, with reason code — is recorded in the audit log.

​
Hot reload

Set policy.watch: true in broker.yml to reload the policy when the file changes on disk. The broker logs the new policy hash so you can correlate reloads with the audit stream.

​
Validate before deploying

certplane-broker -c /etc/certplane/broker.yml policy validate --policy /etc/certplane/policy.yml
This compiles the policy in the same code path the server uses. On success it prints: 
policy ok: hash=abc123… profiles=N identities=M
The same hash appears in the broker’s startup log and audit events, which makes it easy to confirm which policy is live.

​
Continue