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.

Each host that should be authorized to request certificates must have an entry in the hosts section of the policy file. An entry maps the host’s identity CN — as issued by step-ca — to the list of profiles that host is allowed to request. The broker evaluates this mapping on every incoming request, so adding or removing a host from the hosts section takes effect as soon as the policy is reloaded.

​
Host entry fields

​
identity
string
required
The Common Name (CN) of the host’s identity certificate as issued by step-ca. The broker extracts the CN from the mTLS client certificate presented during the request and compares it against this value. The match must be exact.
​
profiles
string[]
required
The list of profile names this host is allowed to request. Profile names must match a key defined in the profiles section of the same policy file. Any profile not listed here is rejected for this host, even if the profile exists in the policy.

​
Host key vs identity field

The key you use for each entry under hosts is a human-readable label used for your own reference. The identity field is the machine identity the broker actually validates against. These are two distinct values:
FieldRoleExample
Host key (YAML key)Human label for the entrypvvl-edge01
identityCN from the step-ca certificatepvvl-edge01.h.int.example.com
The broker ignores the host key entirely during request validation. Only the identity value is compared against the CN of the presenting certificate.

​
Example: one host authorized for multiple profiles

policy.yml
hosts:
  pvvl-edge01:
    identity: pvvl-edge01.h.int.example.com
    profiles:
      - public_edge_main
      - api_services
In this example, the host presenting a certificate with CN pvvl-edge01.h.int.example.com is allowed to request either the public_edge_main or api_services profile. A request for any other profile name is rejected.

​
Rejection behaviour

The broker rejects a request in two cases:
  • Unknown identity: the CN of the presenting mTLS certificate does not match the identity field of any entry in hosts. The broker closes the connection without issuing a certificate.
  • Unauthorized profile: the host’s identity is recognized, but the requested profile is not listed in that host’s profiles array. The broker returns an error and does not contact the ACME provider.
Neither rejection produces a certificate or consumes an ACME rate-limit slot.
The identity field is case-sensitive and must match the CN of the host’s step-ca certificate exactly, including subdomain depth and domain suffix. A mismatch of even one character causes every request from that host to be rejected.