ACME — Automatic Certificate Management Environment

iya-sts is an ACME server (RFC 8555) with RFC 9773 renewal information, the ip (RFC 8738) and email (RFC 8823) identifier types, certificate profiles and the permanent-identifier type of device attestation. Every trust realm has its own, issuing from the realm’s ACME Issuing CA — one of the Issuing CAs of the realm’s certificate authority, under the realm’s Intermediate and the service Root.

Two things make it different from a public CA, and both are deliberate:

• An account is bound to one directory entry, for life. A new account REQUIRES an External Account Binding (RFC 8555 section 7.3.4), and an EAB key is issued for exactly one person or application. Every certificate the account is issued names that entry and is written onto it.
• No challenge ever reaches out to you. An identifier is authorized from the directory entry: a host name an administrator registered on it, a person’s own mail, or the entry’s own identifier. Those authorizations are created valid, so a client has nothing to do; an identifier the entry does not own is refused when the order is placed.

The endpoints

All under the realm’s base URL (https://host:8081 in the default realm, https://host:8081/realm/<id> in another). A client needs only the first.

The path is /enroll/acme and not /acme, because the first segment of a path is also where a trust realm’s id goes.

Getting an External Account Binding key

An EAB key is issued for ONE entry:

• by the person themselves, on the user portal;
• by an administrator, for any person or application in the realm — on Protocols → Cert issuance → ACME (/admin/acme), or through the management API:

curl -s -H "Authorization: Bearer $ADMIN_API_TOKEN" \
     -H 'Content-Type: application/json' \
     -d '{"kind":"person","identifier":"alice"}' \
     https://host:8081/realm/acme-demo/admin-api/acme/create-eab

{
  "ok": true,
  "kid": "eab-p-YWxpY2U-a770cbcdf277212f",
  "hmacKey": "fTOM027GWjv59Gz4qXrudgK7hbtsdWRmOoIW5VZEZ1w",
  "alg": "HS256",
  "expiresAt": "2026-09-20T17:36:05.195Z",
  "directory": "https://host:8081/realm/acme-demo/enroll/acme/directory",
  "certbot": "certbot register --server … --eab-kid … --eab-hmac-key …"
}

The HMAC key is shown once. It is stored sealed on the entry and nothing reads it back. A key binds one account and no other, and must bind within acme.eabLifetimeS (a week by default). This is also how an administrator issues for somebody else: create the key for their entry and hand it to whoever runs the client — the account, and every certificate it gets, belongs to that entry.

Host names

A dns or ip identifier is authorized only when it is registered on the entry the account is bound to. An administrator registers one on /admin/acme, or:

curl -s -H "Authorization: Bearer $ADMIN_API_TOKEN" \
     -H 'Content-Type: application/json' \
     -d '{"kind":"application","identifier":"web1","hostName":"web1.example.com"}' \
     https://host:8081/realm/acme-demo/admin-api/acme/add-host-name

A registered *.example.com authorizes that wildcard, and only when written so. The same registration serves EST and SCEP.

Configuring ACME

For the realm: Protocols → Cert issuance → ACME

The ACME page of the console (/admin/acme) holds everything about the realm’s server: the directory URL, the endpoints, the ACME Issuing CA, the profiles, the External Account Binding keys (create one for a person or an application, delete one), the accounts, the certificates issued (each with a Revoke), the registered host names, and the acme.* settings (see Configuration). Viewing it needs Admin Read; changing anything needs Admin Write. A realm’s own administrators manage their realm’s page. Monitoring → Cert issuance → ACME enrollments shows what the server has done.

To get a client running, for any entry:

1. Turn the server on (acme.enabled, on by default) and narrow acme.allowedProfiles if needed.
2. Register the host names the entry may be issued under Registered host names (a dns or ip identifier is refused otherwise).
3. Create an EAB key for the entry under External Account Binding keys, and hand the kid and HMAC key to whoever runs the client.

For one application

An application’s own rules are set on its page, **Directory → Applications →