Introduction

Akāmu is a self-hosted certificate authority that speaks the ACME protocol defined in RFC 8555. It is written in Rust and is designed to be operated inside a private network or behind a reverse proxy, issuing X.509 certificates to ACME clients such as certbot, acme.sh, or any RFC 8555-compliant library. The project is organized as a Cargo workspace. In addition to the server binary, it ships standalone client libraries — see Client Libraries.

For a detailed breakdown of RFC and draft coverage — including which sections are implemented, which are intentionally omitted, and post-quantum support — see the RFC Support Reference.

What it does

• Implements the full RFC 8555 ACME server protocol: directory, nonces, accounts, orders, authorizations, challenges, certificate issuance, and revocation.
• Validates domain ownership using http-01, dns-01, tls-alpn-01, and dns-persist-01 challenge types (RFC 8555 §8, RFC 8737, and the Let’s Encrypt dns-persist-01 specification).
• Validates TNAuthList and JWTClaimConstraints identifiers using the tkauth-01 challenge type (RFC 9447 / RFC 9448), verifying signed authority tokens issued by an external Token Authority.
• Issues end-entity certificates signed by a built-in Certificate Authority whose key and self-signed root are generated automatically on first run, or loaded from existing PEM files.
• Persists all ACME objects (accounts, orders, authorizations, challenges, certificates, nonces) in a SQL database. The supported backends are SQLite (default; single-file, no external service required), PostgreSQL, and MariaDB/MySQL, selected by the database.url configuration key.
• Generates and serves CRLs (Certificate Revocation Lists) at GET /ca/crl.
• Serves OCSP responses at GET /ca/ocsp/{request} and POST /ca/ocsp (RFC 6960).
• Implements the ACME Renewal Information extension (RFC 9773) so ACME clients know when to renew.
• Optionally appends issued certificates to a Merkle Tree Certificate transparency log using the synta-mtc library.
• When external_account_required = true, performs full HMAC verification of the externalAccountBinding JWS (HS256/HS384/HS512), confirms the payload is the account key, and atomically consumes the EAB key on account creation. EAB keys can be provisioned in two ways: statically in the TOML config under [server.eab_keys], or derived on demand via HKDF-SHA-256 (RFC 5869) when [server].eab_master_secret is set and the client authenticates via GSSAPI or a trusted proxy (GET /acme/eab).
• Optionally terminates TLS directly using rustls, with an auto-generated certificate on first run. Supports mutual TLS (mTLS) client certificate authentication with configurable CA trust anchors, chain depth, RSA modulus enforcement, and post-quantum client certificate acceptance.
• Supports multi-node clustering through a built-in CRDT + gossip replication layer. All domain state (accounts, orders, authorizations, challenges, certificates, EAB keys, operators, delegations, MTC) is replicated to every cluster member via signed gossip envelopes. Nodes are registered with each other via the POST /admin/gossip/register admin endpoint. When the [gossip] section is absent the node runs in single-node mode with no replication overhead.

What it does not do

• It does not support wildcard certificates via http-01 or tls-alpn-01 (only dns-01 and dns-persist-01 can authorize wildcard identifiers per RFC 8555 §7.1.3).

Technology stack

Standards implemented

• RFC 8555 — Automatic Certificate Management Environment (ACME)
• RFC 8659 — DNS CAA Resource Record
• RFC 8657 — CAA Extensions: accounturi and validationmethods
• RFC 8737 — ACME TLS-ALPN-01 Challenge Type
• RFC 8738 — ACME IP Identifier Validation
• RFC 8739 — ACME Short-Term, Automatically Renewed (STAR) Certificates
• RFC 9444 — ACME for Subdomains
• RFC 9447 — ACME Challenges Using an Authority Token (tkauth-01)
• RFC 9448 — ACME TNAuthList Authority Token
• RFC 9773 — ACME Renewal Information (ARI)
• RFC 9799 — ACME Extensions for .onion Special-Use Domain Names
• RFC 7807 — Problem Details for HTTP APIs (error responses)
• RFC 5280 — X.509 Certificate and CRL profile
• RFC 6960 — Online Certificate Status Protocol (OCSP)
• Let’s Encrypt dns-persist-01 — Persistent DNS challenge type
• draft-ietf-acme-profiles-01 — ACME certificate profiles
• draft-ietf-lamps-pq-composite-sigs — ML-DSA composite TLS signature schemes (provisional code points)
• draft-ietf-plants-merkle-tree-certs-04 — Merkle Tree Certificates (MTC), transparency-log-backed certificate format (experimental OIDs, pre-IANA)

Reading guide

The documentation is split into three sections targeting distinct audiences:

Quick navigation

New to Akāmu? Start with the Quick Start guide.

Deploying or configuring the server? See the Configuration Reference for every configuration key, or Operator Roles for RBAC setup.

Building an ACME client or integrating via the API? Start with ACME Protocol Reference for the wire-level details, Admin API for the management REST API, or akamu-client for the Rust library.

Contributing to Akāmu? Read the Architecture chapter first — it includes a full system diagram covering all subsystems and their interactions.

Installation

Prerequisites

• Rust toolchain 1.75 or later (install via rustup)
• OpenSSL development headers (required by synta-certificate’s cryptography backend and by rustls-native-ossl, the TLS crypto provider)

Fedora / RHEL

sudo dnf install openssl-devel

Debian / Ubuntu

sudo apt install libssl-dev

Checking out the source

git clone <akamu-repo> akamu

All synta dependencies are fetched automatically from crates.io — no manual checkout required.

Building from source

The repository is a Cargo workspace with seven members: the akamu server binary, akamu-jose, akamu-client, akamu-cli, akamuctl, akamu-cosigner, and akamu-ldap (the OpenLDAP C-binding library, used by the server when reading profiles from LDAP).

cd akamu
cargo build --release

This compiles all seven workspace members. The binaries are placed at:

• target/release/akamu — the ACME server
• target/release/akamu-cli — the command-line client
• target/release/akamuctl — the admin CLI
• target/release/akamu-cosigner — the MTC cosigner daemon

To build only the server:

cargo build --bin akamu --release

To build only the CLI:

cargo build --bin akamu-cli --release

Note: The first build downloads and compiles all dependencies including bundled SQLite. It can take several minutes on a first run.

Verifying the build

./target/release/akamu --help

The binary accepts a single optional argument: the path to the configuration file (defaults to config.toml in the current directory).

Installing the binary

Copy the binary to a location in $PATH:

sudo install -m 0755 target/release/akamu /usr/local/bin/akamu

systemd service (optional)

Create /etc/systemd/system/akamu.service:

[Unit]
Description=ACME Certificate Server
After=network.target

[Service]
Type=simple
User=akamu
Group=akamu
ExecStart=/usr/local/bin/akamu /etc/akamu/config.toml
Restart=on-failure
RestartSec=5s

# Logging
StandardOutput=journal
StandardError=journal

# Security hardening
NoNewPrivileges=true
ProtectSystem=strict
ReadWritePaths=/var/lib/akamu /etc/akamu

[Install]
WantedBy=multi-user.target

Then enable and start:

sudo systemctl daemon-reload
sudo systemctl enable --now akamu

Running tests

cargo test

cargo test runs tests across all workspace members: the server, akamu-jose, and akamu-client. To limit the run to a specific crate:

cargo test -p akamu          # server tests only
cargo test -p akamu-jose     # JWK/JWS primitive tests
cargo test -p akamu-client   # ACME client library tests

All tests are self-contained and do not require external services. Some integration tests start local HTTP or TLS servers on ephemeral ports.

First Run

This chapter walks through the minimal steps to get Akāmu running and reachable by ACME clients.

1. Create directories

sudo mkdir -p /etc/akamu /var/lib/akamu
sudo chown akamu:akamu /etc/akamu /var/lib/akamu
sudo chmod 0750 /etc/akamu /var/lib/akamu

2. Write a minimal configuration file

Copy the example configuration and adjust it:

sudo cp config.toml.example /etc/akamu/config.toml
sudo chmod 0640 /etc/akamu/config.toml

At a minimum you need:

listen_addr = "0.0.0.0:8080"
base_url    = "https://acme.example.com"

[database]
url = "sqlite:///var/lib/akamu/akamu.db"

[ca]
key_file  = "/etc/akamu/ca.key.pem"
cert_file = "/etc/akamu/ca.cert.pem"

[mtc]
log_path = "/var/lib/akamu/mtc.log"
enabled  = false

Replace acme.example.com with the actual hostname your ACME clients will use.

Note: listen_addr is the address the server binds to. base_url is the public-facing URL that appears in all ACME responses, including the directory and certificate URLs. They do not have to match — for example you might bind on 0.0.0.0:8080 and have a reverse proxy forward HTTPS traffic from port 443 to that address.

3. Start the server

akamu /etc/akamu/config.toml

On first run, because neither ca.key.pem nor ca.cert.pem exist, the server generates a new EC P-256 CA key and a 10-year self-signed CA certificate and writes them to the configured paths. You will see log output like:

INFO akamu: loading config from '/etc/akamu/config.toml'
INFO akamu: opening database '/var/lib/akamu/akamu.db'
INFO akamu: loading CA from '/etc/akamu/ca.key.pem'
INFO akamu::ca::init: Generating new CA key (ec:P-256) — writing to /etc/akamu/ca.key.pem and /etc/akamu/ca.cert.pem
INFO akamu::ca::init: Generated CA certificate (ec:P-256, 10 years)
INFO akamu: ACME server listening on 0.0.0.0:8080 (base_url=https://acme.example.com)

4. Verify the server is running

curl -s https://acme.example.com/acme/directory | python3 -m json.tool

Expected output:

{
    "keyChange": "https://acme.example.com/acme/key-change",
    "meta": {},
    "newAccount": "https://acme.example.com/acme/new-account",
    "newNonce": "https://acme.example.com/acme/new-nonce",
    "newOrder": "https://acme.example.com/acme/new-order",
    "revokeCert": "https://acme.example.com/acme/revoke-cert"
}

5. Install the CA certificate in your trust store (optional)

ACME clients will reject certificates issued by an unknown CA unless you install the CA certificate in your system’s trust store or tell the client to trust it explicitly.

Copy the CA certificate:

sudo cp /etc/akamu/ca.cert.pem /usr/local/share/ca-certificates/akamu-ca.crt
sudo update-ca-certificates          # Debian/Ubuntu
# or
sudo update-ca-trust                 # Fedora/RHEL

Logging

The server uses the tracing crate. Control log verbosity with the RUST_LOG environment variable:

RUST_LOG=debug akamu /etc/akamu/config.toml

Useful levels: error, warn, info (default), debug, trace.

Reverse proxy configuration (nginx)

The server speaks plain HTTP internally. An nginx TLS termination configuration:

server {
    listen 443 ssl;
    server_name acme.example.com;

    ssl_certificate     /etc/nginx/ssl/acme.example.com.crt;
    ssl_certificate_key /etc/nginx/ssl/acme.example.com.key;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Running behind a reverse proxy (Unix socket)

Instead of binding a TCP port, Akāmu can listen on a Unix domain socket. This avoids exposing a TCP port and simplifies firewall rules when the reverse proxy runs on the same host.

Set listen_addr to a unix: path (TLS must be absent or disabled — the proxy terminates TLS):

listen_addr = "unix:/run/akamu/akamu.sock"
base_url    = "https://acme.example.com"
# No [tls] section — TLS is terminated at the proxy

The AKAMU_LISTEN environment variable overrides listen_addr without touching the config file:

AKAMU_LISTEN=unix:/run/akamu/akamu.sock akamu /etc/akamu/config.toml

nginx

server {
    listen 443 ssl;
    server_name acme.example.com;

    ssl_certificate     /etc/nginx/ssl/acme.example.com.crt;
    ssl_certificate_key /etc/nginx/ssl/acme.example.com.key;

    location / {
        proxy_pass http://unix:/run/akamu/akamu.sock;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Apache

ProxyPass        / unix:/run/akamu/akamu.sock|http://localhost/
ProxyPassReverse / unix:/run/akamu/akamu.sock|http://localhost/

Trusted proxies and X-Remote-User

If you use server.trusted_proxies for admin auth via X-Remote-User, all connections arriving over a Unix socket are treated as locally trusted (no CIDR check). The header is still required — any connection without it receives a 401.

systemd socket activation

The provided unit files support socket activation, which lets systemd pre-bind the socket before the service starts:

systemctl enable --now akamu.socket akamu.service

The socket is created at /run/akamu/akamu.sock (mode 0660). The reverse proxy process must be in group akamu to connect. When using socket activation, listen_addr in the config file is ignored — the pre-bound socket is passed via LISTEN_FDS.

Stale socket files are removed automatically on config-based startup. Under socket activation, systemd owns the socket file and no cleanup is needed.

Your First Certificate

This chapter shows how to obtain a certificate from your freshly running Akāmu using two common ACME clients: certbot and acme.sh.

Both examples use the http-01 challenge, which is the simplest to set up: the ACME server makes an HTTP request to port 80 of the domain being validated.

Before you begin

Make sure:

1. Akāmu is running and reachable at https://acme.example.com/acme/directory.
2. The CA certificate (/etc/akamu/ca.cert.pem) has been added to the system trust store, or you plan to pass it explicitly to the ACME client.
3. Port 80 is reachable on the domain you want to certify so the http-01 challenge can succeed.

Using certbot

Install certbot

sudo apt install certbot      # Debian/Ubuntu
sudo dnf install certbot      # Fedora/RHEL

Obtain a certificate

sudo certbot certonly \
  --standalone \
  --server https://acme.example.com/acme/directory \
  --email admin@yourdomain.com \
  --agree-tos \
  -d yourdomain.com

If the CA certificate is not yet trusted system-wide, pass it via --no-verify-ssl (insecure, for testing only) or add it to certbot’s CA bundle.

What happens

1. certbot fetches the directory at https://acme.example.com/acme/directory.
2. It creates an ACME account with the provided email address.
3. It places a new order for yourdomain.com.
4. Akāmu creates an authorization and a set of challenge objects for the domain.
5. certbot writes the key authorization file to /.well-known/acme-challenge/<token> on port 80.
6. certbot signals readiness by POSTing to the challenge URL.
7. Akāmu fetches http://yourdomain.com/.well-known/acme-challenge/<token> and verifies the response matches the expected key authorization.
8. Once the challenge is valid, certbot POSTs a CSR to the finalize URL.
9. Akāmu validates the CSR, issues the certificate, and returns the certificate URL.
10. certbot downloads the certificate from https://acme.example.com/acme/cert/<id>.

The certificate and private key are written to /etc/letsencrypt/live/yourdomain.com/.

Using acme.sh

Install acme.sh

curl https://get.acme.sh | sh -s email=admin@yourdomain.com

Register an account and obtain a certificate

~/.acme.sh/acme.sh \
  --issue \
  --standalone \
  --server https://acme.example.com/acme/directory \
  -d yourdomain.com \
  --ca-bundle /etc/akamu/ca.cert.pem

The --ca-bundle flag tells acme.sh to trust your private CA when connecting to the ACME server. Remove it if the CA is already in the system trust store.

Install the certificate to a target location

~/.acme.sh/acme.sh \
  --install-cert \
  -d yourdomain.com \
  --cert-file /etc/ssl/yourdomain.com/cert.pem \
  --key-file /etc/ssl/yourdomain.com/key.pem \
  --fullchain-file /etc/ssl/yourdomain.com/fullchain.pem \
  --reloadcmd "systemctl reload nginx"

Checking the issued certificate

After a successful run, inspect the certificate:

openssl x509 -in /etc/letsencrypt/live/yourdomain.com/cert.pem -text -noout

Key fields to verify:

• Issuer: matches the common_name and organization from your [ca] configuration.
• Subject Alternative Name: contains DNS:yourdomain.com.
• Extended Key Usage: TLS Web Server Authentication.
• Validity: 90 days from issuance (default; adjustable via validity_days).

Renewal

Both clients support automatic renewal. They check the certificate expiry and renew when less than 30 days remain.

For certbot:

sudo systemctl enable --now certbot.timer

For acme.sh, renewal is installed automatically as a cron job during --install-cert.

The ACME Renewal Information endpoint (/acme/renewal-info/<cert_id>) is available for clients that support RFC 9773. It suggests a renewal window in the last third of the certificate’s validity period by default.

Troubleshooting

Challenge validation fails with a connection error

Ensure port 80 is open on the domain being validated. For the http-01 challenge the server makes a plain HTTP request to port 80; no TLS is involved.

Certificate is not trusted

The certificate is issued by your private CA. Install the CA certificate (/etc/akamu/ca.cert.pem) in the trust store of every system that needs to trust the issued certificates.

“account does not exist” error on renewal

If you re-created the database, existing accounts were lost. Re-register with certbot register or re-run acme.sh --register-account.

Using akamu-client (Rust)

If you are writing a Rust application and want to obtain a certificate programmatically, you can use the akamu-client library directly. For command-line usage without writing Rust code, see akamu-cli.

use akamu_client::{
    AccountKey, AccountOptions, AcmeClient,
    Http01Solver, Identifier, build_csr,
};
use std::{fs, time::Duration};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Generate or load an account key
    let key = if std::path::Path::new("account.pem").exists() {
        let pem = fs::read("account.pem")?;
        AccountKey::from_pem(&pem)?
    } else {
        let k = AccountKey::generate("ec:P-256")?;
        fs::write("account.pem", k.to_pem()?)?;
        k
    };

    // 2. Connect to the ACME directory
    let client = AcmeClient::new("https://acme.example.com/acme/directory").await?;

    // 3. Register an account (agree to Terms of Service)
    let opts = AccountOptions {
        contacts: vec!["mailto:admin@example.com".to_string()],
        agree_tos: true,
        eab: None,
    };
    let account = client.new_account(&key, opts).await?;

    // 4. Place an order for the desired identifiers
    let ids = vec![Identifier::Dns("example.com".to_string())];
    let order = client.new_order(&account, ids).await?;

    // 5. Start the built-in http-01 solver on port 80
    let solver = Http01Solver::new(80);
    solver.start().await?;

    // 6. Solve each authorization
    for authz_url in &order.authorizations {
        let authz = client.get_authorization(&account, authz_url).await?;
        let challenge = authz
            .challenges
            .into_iter()
            .find(|c| c.challenge_type == "http-01")
            .ok_or("http-01 challenge not available")?;

        // Present the key authorization at the well-known URL
        let key_auth = account.key_authorization(&challenge.token);
        solver.present(&challenge.token, &key_auth).await?;

        // Signal readiness to the ACME server
        client.trigger_challenge(&account, &challenge).await?;

        // Poll until the authorization is validated
        loop {
            tokio::time::sleep(Duration::from_secs(2)).await;
            let updated = client.get_authorization(&account, authz_url).await?;
            match updated.status.as_str() {
                "valid"   => break,
                "invalid" => return Err("authorization failed".into()),
                _         => continue,
            }
        }

        // Remove the challenge token from the solver
        solver.cleanup(&challenge.token).await?;
    }

    // 7. Generate a certificate key, build a CSR, and finalize the order
    let cert_key = AccountKey::generate("ec:P-256")?;
    fs::write("cert.key.pem", cert_key.to_pem()?)?;

    let csr_der  = build_csr(&["example.com"], &cert_key)?;
    let finalized = client.finalize(&account, &order, &csr_der).await?;

    let cert_url = finalized.certificate.ok_or("no certificate URL")?;

    // 8. Download the certificate bundle and write to disk
    let pem = client.download_certificate(&account, &cert_url).await?;
    fs::write("cert.pem", &pem)?;

    println!("Certificate written to cert.pem");
    println!("Private key written to cert.key.pem");
    Ok(())
}

Add the following to your Cargo.toml:

[dependencies]
akamu-client = { path = "/path/to/akamu/crates/akamu-client" }
tokio = { version = "1", features = ["full"] }

Operator Roles

Operator Guide — This section is for administrators who deploy and run Akāmu. It covers configuration, account management, certificate issuance policies, and operational concerns. If you are building an ACME client or integrating with the API, see the API Reference. If you are contributing to Akāmu itself, see the Implementation Guide.

Akamu’s admin API uses role-based access control to enforce least privilege and separation of duties. Every admin request is authenticated, and every operator has exactly one role. The role determines which endpoints the operator may call. Roles are assigned at operator creation time and can be changed later by an administrator.

Understanding the roles before provisioning operators is important: a mis-scoped operator can either have too much access (a security risk) or too little (causing operational failures).

Role hierarchy

The four roles form a strict access hierarchy. Higher roles have a superset of the read permissions of lower roles, but lower roles do NOT inherit write permissions from higher roles.

administrator
    |-- ca_operations
    |       |-- ca_ra (read only within own CA scope)
    |               |-- auditor (read only, no CA data)

More precisely:

• administrator can call every endpoint.
• ca_operations can call everything administrator can except operator management, server config reads, and profile write operations.
• ca_ra is a scoped RA role. It can do a subset of ca_operations reads but only within its assigned CA, and can revoke and issue EAB keys. It cannot see other CAs or perform any CA infrastructure operations.
• auditor is read-only and cannot perform any write operations.

Per-role reference

administrator

The administrator role is for PKI administrators who need full control over the server. Assign it to the smallest possible number of humans and avoid using it for automated service accounts.

Key capabilities:

• All endpoints without restriction.
• Create, update, activate, deactivate, and unlock operators.
• Read and write certificate profiles.
• Read server configuration.
• Manage EAB keys (create and delete).
• Revoke certificates from any CA.
• Force CRL regeneration for any CA or all CAs.
• Cross-sign CAs.
• Manage RFC 9115 delegation objects.
• Deactivate ACME accounts.
• Query the audit log.

Key restrictions:

• None. This role has full access.

Typical use case: A human PKI administrator who needs to bootstrap the system, manage other operators, update certificate profiles, or respond to a security incident that requires account deactivation or forced revocation.

Example:

akamuctl operator add \
    --name alice \
    --role administrator \
    --cert-file /etc/akamu/alice-client.pem

ca_operations

The ca_operations role is for automated CA infrastructure processes and operations staff who manage the certificate lifecycle but do not need to manage operators or read the server configuration.

Key capabilities:

• List and view CAs and their certificates.
• Download CA certificates.
• Force CRL regeneration (global and per-CA).
• Cross-sign CAs.
• List, view, and download issued certificates.
• Create and delete EAB keys.
• Revoke certificates from any CA.
• Manage RFC 9115 delegation objects (create, update, delete).
• Manage ACME account profile grants (set but not clear).
• View accounts, orders, profiles, EAB keys, stats.
• Query the audit log.

Key restrictions:

• Cannot manage operators (no access to /admin/operators endpoints).
• Cannot read server configuration (GET /admin/config).
• Cannot write certificate profiles (no POST, PUT, or DELETE on profiles).
• Cannot deactivate ACME accounts.
• Cannot clear account profile grant lists.

CA scope (optional): A ca_operations operator can be assigned a ca_id scope. When scoped, the operator’s visibility is limited to the assigned CA: GET /admin/cas returns only that CA, CRL/cross-sign operations are restricted to the scoped CA, and certificate and order queries are automatically filtered. Unlike ca_ra, a ca_id scope is optional for ca_operations; an unscoped ca_operations operator has server-wide access.

EAB keys and CA scope: Even a scoped ca_operations operator may create EAB keys. EAB keys are not bound to any CA — they are used for ACME account registration which is server-global — so this is intentional. Only an administrator may set for_operator_id when creating an EAB key via POST /admin/eab to assign it to a different operator for web UI login.

Typical use case: A CI/CD pipeline that issues EAB keys for new devices, or an operations team member who manages revocation and CRL generation without having the ability to create new operators.

Example:

akamuctl operator add \
    --name ci-pipeline \
    --role ca_operations \
    --cert-file /etc/akamu/ci-client.pem

ca_ra

The ca_ra role is for front-line registration authority (RA) staff or automated RA services that operate on behalf of a single specific CA. This role is intentionally narrow: it cannot see data from other CAs and cannot perform any CA infrastructure operations.

Key capabilities:

• View EAB keys.
• List and view certificates issued by the scoped CA only.
• Download certificates issued by the scoped CA only.
• Revoke certificates issued by the scoped CA only.
• View accounts and orders (filtered to the scoped CA automatically).
• View profiles, delegations, stats.

Key restrictions:

• Cannot create or delete EAB keys (POST /admin/eab, DELETE /admin/eab/{kid}).
• Cannot list or view CAs (GET /admin/cas, GET /admin/cas/{id}).
• Cannot see cross-certificates.
• Cannot force CRL regeneration.
• Cannot cross-sign CAs.
• Cannot manage operators.
• Cannot read server configuration.
• Cannot write certificate profiles or delegation objects.
• Cannot manage ACME accounts (deactivate, set/clear profile grants).
• Cannot query the audit log.
• Cannot view or act on certificates from a CA other than its assigned ca_id.
• Requires a ca_id scope to be assigned. An unscoped ca_ra operator is rejected at every restricted endpoint with 403 Forbidden.

Special requirement — ca_id: See CA scope for ca_ra below.

Typical use case: A registration authority system at a branch office that accepts certificate requests for a specific CA (for example, rsa), issues EAB keys for new ACME clients, and revokes certificates when devices are decommissioned, without having any visibility into the rest of the PKI.

Example:

akamuctl operator add \
    --name branch-ra \
    --role ca_ra \
    --ca-id rsa \
    --cert-file /etc/akamu/branch-ra.pem

auditor

The auditor role is for security auditors, compliance officers, and monitoring systems that need read access to the server’s operational data but must never be able to make changes.

Key capabilities:

• Query the audit event log (GET /admin/audit).
• List and view issued certificates (across all CAs).
• List and view EAB keys.
• List and view accounts, orders, and profiles.
• View delegations.
• View cross-certificates.
• View server statistics.

Key restrictions:

• No write operations at all.
• Cannot view CA details or CA certificates.
• Cannot download certificate content (PEM/DER).
• Cannot view server configuration.
• Cannot manage operators.

Typical use case: A security operations center tool that polls the audit log for anomalies, or a compliance dashboard that tracks certificate issuance counts and expiry windows.

Example:

akamuctl operator add \
    --name soc-monitor \
    --role auditor \
    --gssapi-principal soc-svc@EXAMPLE.COM

Permission matrix

The table below is the authoritative route-by-role matrix derived from the server source code. Y means the role is permitted. Where ca_ra is permitted on a cert or account endpoint, the server automatically enforces the CA scope filter — the operator only sees data belonging to its assigned CA.

Note on ca_ra scoping: When ca_ra is listed as permitted on a cert, account, or order endpoint, the server silently overrides any ca_id query parameter the operator supplies and substitutes the operator’s assigned ca_id. An unscoped ca_ra (one with an empty ca_id) is rejected at all such endpoints with 403 Forbidden.

Creating operators

All operator creation requires the administrator role.

Create an mTLS operator

# administrator — full access human admin
akamuctl operator add \
    --name alice \
    --role administrator \
    --cert-file /etc/akamu/alice-client.pem

# ca_operations — automated CA pipeline
akamuctl operator add \
    --name ca-pipeline \
    --role ca_operations \
    --cert-file /etc/akamu/pipeline-client.pem

# ca_ra — scoped RA for the 'rsa' CA
akamuctl operator add \
    --name branch-ra \
    --role ca_ra \
    --ca-id rsa \
    --cert-file /etc/akamu/branch-ra.pem

# auditor — read-only monitoring
akamuctl operator add \
    --name soc-monitor \
    --role auditor \
    --cert-file /etc/akamu/soc-monitor.pem

The --cert-file flag accepts a PEM file. akamuctl computes the SHA-256 fingerprint of the DER-encoded leaf certificate locally and sends only the fingerprint to the server. The private key never leaves the operator’s machine.

Create a GSSAPI/Kerberos operator

akamuctl operator add \
    --name bob \
    --role auditor \
    --gssapi-principal bob@EXAMPLE.COM

Dual-credential operator

An operator can authenticate by either mTLS or GSSAPI by supplying both credentials at creation time:

akamuctl operator add \
    --name carol \
    --role ca_operations \
    --cert-file /etc/akamu/carol-client.pem \
    --gssapi-principal carol@EXAMPLE.COM

Change an operator’s role

# Promote an auditor to ca_operations
akamuctl operator update 4 --role ca_operations

# Assign a ca_ra operator to a different CA
akamuctl operator update 5 --role ca_ra --ca-id ec

When a role or CA scope changes, all active sessions for that operator are invalidated immediately.

Choosing a role

Use this guide to decide which role to assign:

When in doubt, start with auditor and escalate only when a required operation fails. The server returns 403 Forbidden with a clear error message when a role is insufficient for a requested endpoint.

CA scope for ca_ra

The ca_id field on a ca_ra operator is a mandatory scope that restricts the operator to data belonging to a single CA. It must be the ID string of a CA configured in the server’s [ca.*] sections (for example, "rsa" or "ec").

Why it is required: Without a CA scope, a ca_ra operator would have server-wide revocation and EAB-issuance authority, which defeats the purpose of the role. The server enforces this: any ca_ra operator that reaches a restricted endpoint with an empty ca_id receives 403 Forbidden.

What it controls:

• GET /admin/certs: the ca_id query parameter is ignored; only certs from the scoped CA are returned.
• GET /admin/certs/{id}/download: the server returns 404 Not Found if the certificate belongs to a different CA.
• POST /admin/revoke: 403 Forbidden if the target certificate belongs to a different CA.
• GET /admin/accounts and GET /admin/orders: automatically filtered to the scoped CA.

Assigning a CA scope at creation:

akamuctl operator add \
    --name branch-ra \
    --role ca_ra \
    --ca-id rsa \
    --cert-file /etc/akamu/branch-ra.pem

Changing the CA scope after creation:

# Move the operator to a different CA
akamuctl operator update 5 --role ca_ra --ca-id ec

The --ca-id flag is only accepted when --role ca_ra is also provided (or the operator already has the ca_ra role). Supplying --ca-id for any other role is rejected by the server.

Revoking without a scope: If you need to create a ca_ra operator without a CA scope initially and assign the scope in a second step, use operator add followed by operator update:

# Step 1: create with scope (required at creation if role is ca_ra)
akamuctl operator add --name branch-ra --role ca_ra --ca-id rsa \
    --cert-file /etc/akamu/branch-ra.pem

# Later: reassign to a different CA
akamuctl operator update 7 --role ca_ra --ca-id ec

There is no way to store a ca_ra operator with an empty ca_id; the server rejects such a request at POST /admin/operators with 400 Bad Request.

Authentication methods

Operators authenticate to the admin API using one or more of three mechanisms:

• mTLS client certificate — the operator presents a TLS client certificate during the handshake. The server looks up the SHA-256 fingerprint of the DER-encoded leaf in the operators table. This is the recommended mechanism for automated service accounts.

• GSSAPI/Kerberos — the operator sends an Authorization: Negotiate header with a SPNEGO token. The server validates the token and looks up the extracted principal in the operators table. This is the recommended mechanism for human operators in organizations with Kerberos infrastructure.

• Bearer session token — after a successful mTLS or GSSAPI login, the returned token is used for subsequent requests. Session tokens idle-expire after session_ttl_secs (default one hour).

An operator record can hold both a cert_fingerprint and a gssapi_principal, allowing the same logical operator to authenticate by either method.

For configuration details and security notes on GSSAPI, see EAB and Kerberos Authentication. For the full authentication protocol including session token expiry and the bounded session store, see Admin API and Operator Management.

Configuration Reference

Akāmu reads a single TOML configuration file whose path is passed as the first command-line argument:

akamu /etc/akamu/config.toml

If no argument is given, the server looks for config.toml in the current working directory.

The file is parsed once at startup. Changes require a restart. Unknown keys produce a parse error on startup (serde’s strict TOML parser).

Complete example

listen_addr  = "0.0.0.0:8080"
base_url     = "https://acme.example.com"
crdt_db_url  = "sqlite:///var/lib/akamu/crdt.db"

[database]
url = "sqlite:///var/lib/akamu/akamu.db"

[[ca]]
id               = "default"
is_default       = true
key_file         = "/etc/akamu/ca.key.pem"
cert_file        = "/etc/akamu/ca.cert.pem"
key_type         = "ec:P-256"
hash_alg         = "sha256"
validity_days    = 90
ca_validity_years = 10
common_name      = "Example ACME CA"
organization     = "Example Org"
crl_url              = "http://acme.example.com/ca/crl"
crl_next_update_secs = 86400
ocsp_url             = "http://acme.example.com/ca/ocsp"

[mtc]
log_path = "/var/lib/akamu/mtc.log"
enabled  = false
# log_number = 1
# tree_minimum_index = 0
# trust_anchor_id = "1.3.6.1.4.1.44363.47.10.1"

[server]
terms_of_service_url        = "https://acme.example.com/tos.html"
website_url                 = "https://acme.example.com"
caa_identities              = ["acme.example.com"]
external_account_required   = false
order_expiry_secs           = 86400
authz_expiry_secs           = 86400
max_body_bytes              = 65536
ari_retry_after_secs        = 21600
ari_explanation_url         = "https://acme.example.com/docs/renewal-policy"
allow_subdomain_auth        = false
account_scope               = "server"
star_min_lifetime_secs      = 86400
star_max_duration_secs      = 31536000
star_allow_certificate_get  = true
tor_connectivity_enabled    = false
dns_resolver_addr           = "1.1.1.1:853"
dns_dot_server_name         = "cloudflare-dns.com"
dns_persist01_resolver_addr = "127.0.0.1:5354"
validate_dnssec             = true
trusted_proxies             = ["127.0.0.1/32"]
eab_master_secret           = "Zm9vYmFyYmF6cXV4cXV1eGZvb2JhcmJhenF1eHF1dXg"
delegation_enabled          = false
allow_certificate_get       = false

[server.gssapi]
keytab_file  = "/etc/akamu/http.keytab"   # omit and set gssproxy = true to use gssproxy instead
service_name = "HTTP"

# [server.webui]
# static_dir = "/usr/share/akamu/webui"

[tls.client_auth]
ca_certs = ["/etc/akamu/operator-ca.pem"]
required = false

[admin]
session_ttl_secs = 3600

[email_challenge]
enabled             = true
from_address        = "acme-validation@example.com"
send_script         = "/etc/akamu/send-email.sh"
webhook_hmac_secret = "replace-with-output-of--openssl-rand-hex-32"

# [delegation_upstream]
# directory_url            = "https://upstream-ca.example.com/acme/directory"
# account_key_file         = "/etc/akamu/upstream-acme.key.pem"
# contacts                 = ["mailto:admin@example.com"]
# challenge_solver         = "dns-01"
# challenge_deploy_script  = "/etc/akamu/upstream-dns-deploy.sh"
# challenge_cleanup_script = "/etc/akamu/upstream-dns-cleanup.sh"
# poll_interval_secs       = 10

[tkauth]
enabled                 = false
# trusted_ta_ca_files   = ["/etc/akamu/ta-root.pem"]
# token_authority_url   = "https://ta.example.com"
# max_validity_secs     = 3600
# jti_prune_interval_secs = 3600
# [[tkauth.claim_encoders]]
# claim   = "sub"
# encoder = "krb5-kpn"

[gossip]
peers                      = ["https://node2.example.com", "https://node3.example.com"]
interval_secs              = 15
tombstone_ttl_secs         = 604800
ownership_ttl_secs         = 150
gossip_envelope_max_age_secs = 300
clock_skew_tolerance_secs  = 30
fan_out                    = 3

[profiles]
refresh_interval_secs = 3600

[profiles.providers.local]
type = "builtin"

[profiles.providers.local.profiles.tlsserver]
description   = "Standard TLS server certificate"
validity_days = 90
key_usage     = ["digital_signature", "key_encipherment"]
eku           = ["server_auth"]

Top-level keys

listen_addr

Required. The address the server binds to. Two forms are accepted:

# TCP (bind on all interfaces)
listen_addr = "0.0.0.0:8080"

# TCP (localhost only — behind a reverse proxy on the same host)
listen_addr = "127.0.0.1:8080"

# Unix domain socket (reverse proxy on the same host)
listen_addr = "unix:/run/akamu/akamu.sock"

The AKAMU_LISTEN environment variable overrides this field without touching the config file — useful for socket-activated deployments or overriding the bind address at start time:

AKAMU_LISTEN=unix:/run/akamu/akamu.sock akamu /etc/akamu/config.toml

Constraint: Unix domain sockets and [tls] are mutually exclusive. When listen_addr is a Unix path and [tls].enabled = true, the server exits at startup with an error. TLS termination must be handled by the reverse proxy in front of the socket.

See Running behind a reverse proxy (Unix socket) in the quickstart for nginx, Apache, and systemd socket-activation examples.

base_url

Required. The public HTTPS base URL of the ACME server. This value is embedded in every URL the server returns to clients — directory endpoint URLs, account URLs, order URLs, certificate download URLs, etc.

base_url = "https://acme.example.com"

It must match the URL that ACME clients use to reach the directory. It must not end with a slash.

crdt_db_url

Optional. Default: absent (uses [database].url).

SQLite connection URL for the separate CRDT database used when multi-node clustering is enabled (see [gossip]). When absent, CRDT tables are created in the main [database] database. A separate database is recommended in production clustering deployments to isolate CRDT write traffic from ACME traffic.

Only SQLite is supported for the CRDT database (sqlite://… URL format). The file and its WAL journal are created automatically if they do not exist.

crdt_db_url = "sqlite:///var/lib/akamu/crdt.db"

[database]

url

Required. Database connection URL. The format depends on the compiled backend:

For SQLite, the database file and its WAL journal are created automatically if they do not exist.

[database]
url = "sqlite:///var/lib/akamu/akamu.db"

Use sqlite::memory: for an ephemeral in-memory database (useful for testing; all data is lost when the process exits).

max_connections

Optional. Default: 1 for SQLite, 10 for PostgreSQL/MariaDB.

Maximum number of pooled database connections. For SQLite, this must remain 1 to avoid SQLITE_BUSY_SNAPSHOT errors under concurrent writes; the default is correct for production SQLite deployments.

[database]
url      = "postgres://akamu:secret@localhost/akamu"
max_connections = 20

require_tls

Optional. Default: false.

When true, the server refuses to start unless the database URL explicitly enables SSL/TLS encryption:

Set true in production deployments where the database is not co-located with the server process (FPT_ITT.1).

[database]
url         = "postgres://akamu:secret@db.example.com/akamu?sslmode=verify-full"
require_tls = true

[[ca]] / [ca]

Akāmu supports one or more CA instances. Use the TOML array-of-tables syntax [[ca]] to configure multiple CAs; the legacy single [ca] table continues to work and is treated as a single CA with id = "default" and is_default = true.

# Single CA (backward-compatible)
[ca]
key_file  = "/etc/akamu/ca.key.pem"
cert_file = "/etc/akamu/ca.cert.pem"

# Multiple CAs
[[ca]]
id         = "rsa"
is_default = true
key_file   = "/etc/akamu/rsa-ca.key.pem"
cert_file  = "/etc/akamu/rsa-ca.cert.pem"

[[ca]]
id        = "ec"
key_file  = "/etc/akamu/ec-ca.key.pem"
cert_file = "/etc/akamu/ec-ca.cert.pem"

id

Required when multiple [[ca]] entries are present. Optional for a single [ca] table (defaults to "default").

Unique identifier for this CA. Must be lowercase alphanumeric with _ or - allowed, at most 64 characters. Reserved ACME path segments (directory, new-nonce, new-account, new-order, new-authz, revoke-cert, key-change) are rejected at startup.

[[ca]]
id = "rsa"

is_default

Required (as true) for exactly one CA when multiple [[ca]] entries are configured. Implicit true for the legacy single [ca] table.

The default CA is also served at the backward-compatible /acme/directory alias (without a CA ID prefix).

[[ca]]
id         = "rsa"
is_default = true

caa_identities (per-CA)

Optional. Default: [] (inherit from [server].caa_identities).

Per-CA list of CA domain names for CAA record verification (RFC 8659). When non-empty, this list overrides [server].caa_identities for orders processed through this CA’s ACME endpoint. When empty (the default), the server-level list applies.

[[ca]]
id             = "rsa"
caa_identities = ["rsa.acme.example.com", "acme.example.com"]

key_file

Required. Path to the CA private key PEM file.

• If both key_file and cert_file are absent on disk, a new key is generated and written to this path on first run.
• If both files are present, they are loaded without modification.
• If exactly one file is present, the server refuses to start.

key_file = "/etc/akamu/ca.key.pem"

cert_file

Required. Path to the CA certificate PEM file. Same presence rules as key_file.

cert_file = "/etc/akamu/ca.cert.pem"

key_type

Optional. Default: "ec:P-256".

Algorithm used when auto-generating a new CA key. Ignored when loading an existing key from key_file.

Composite ML-DSA variants (draft-ietf-lamps-pq-composite-sigs-19, sub-arcs 37–54 — requires OpenSSL 3.5+):

Each composite variant also accepts the canonical COMPSIG-* label (case-insensitive, with or without the COMPSIG- prefix). For example, sub-arc 40 accepts all three forms: "composite-mldsa44-ecdsa-p256-sha256", "COMPSIG-MLDSA44-ECDSA-P256-SHA256", and "mldsa44-ecdsa-p256-sha256".

hash_alg is ignored for composite CA keys. The hash algorithm is fixed by the composite algorithm specification (e.g. SHA-256 for sub-arc 40, SHA-512 for sub-arc 46). Set hash_alg to a valid value for any non-composite CA that shares the same config stanza; Akāmu silently ignores it for composite keys. For pure ML-DSA keys, hash_alg is also ignored — ML-DSA has no separate hash parameter.

OID stability note: The composite OIDs (sub-arcs 37–54) are defined by draft-ietf-lamps-pq-composite-sigs-19 and are provisional pending IANA allocation. They may change as the draft advances toward RFC publication.

key_type = "ec:P-256"

Example: composite CA key with ML-DSA-65 + ECDSA-P384:

[[ca]]
id       = "composite-pq"
key_file  = "/etc/akamu/composite-ca.key.pem"
cert_file = "/etc/akamu/composite-ca.cert.pem"
key_type  = "composite-mldsa65-ecdsa-p384-sha512"
hash_alg  = "sha512"   # ignored for composite keys; set for documentation clarity

hash_alg

Optional. Default: "sha256".

Hash algorithm used for signing certificates and CRLs.

hash_alg = "sha256"

validity_days

Optional. Default: 90.

Default validity period in days for issued end-entity certificates. The validity window starts at the moment the certificate is signed.

validity_days = 90

ca_validity_years

Optional. Default: 10.

Validity period in years for the auto-generated CA certificate. Ignored when loading an existing certificate.

ca_validity_years = 10

common_name

Optional. Default: "ACME Server CA".

Common Name (CN) used in the Subject and Issuer fields of the auto-generated CA certificate.

common_name = "Example ACME CA"

organization

Optional. Default: "ACME Server".

Organization (O) used in the Subject and Issuer fields of the auto-generated CA certificate.

organization = "Example Org"

crl_url

Optional. Default: absent (no CDP extension).

If set, this URL is included as a CRL Distribution Point (CDP) URI in the CRLDistributionPoints extension of every issued end-entity certificate.

crl_url = "http://acme.example.com/ca/crl"

Set this to the URL of the built-in /ca/crl endpoint (i.e. {base_url}/ca/crl) to use the server’s built-in CRL endpoint. The endpoint is served by Akāmu and requires no external CRL generation.

ocsp_url

Optional. Default: absent (no AIA OCSP extension).

If set, this URL is included in the AuthorityInfoAccess (AIA) extension as an OCSP responder URI in every issued end-entity certificate.

ocsp_url = "http://acme.example.com/ca/ocsp"

Set this to the URL of the built-in /ca/ocsp endpoint (i.e. {base_url}/ca/ocsp) to use the server’s built-in OCSP responder. Both GET and POST OCSP requests are handled at this base URL.

crl_next_update_secs

Optional. Default: 86400 (1 day).

Controls the nextUpdate field in the CRL served at /ca/crl. The nextUpdate is set to the current time plus this many seconds. Adjust to match how frequently clients are expected to re-fetch the CRL.

crl_next_update_secs = 86400   # one day (default)

enforce_validity_cap

Optional. Default: false.

When true, certificate issuance is rejected at the time of signing if the computed validity period exceeds 200 days (the current CA/B Forum BR §6.3.2 hard limit since 2026-03-15). When false (the default), the server only emits a startup warning for validity periods exceeding the limit, allowing private or enterprise PKI deployments to use longer validity periods without chaining to a public root.

Public WebPKI CAs should set this to true to enforce the limit at issuance time rather than relying solely on the startup warning.

[ca]
enforce_validity_cap = true

require_encrypted_key

Optional. Default: false.

When true, the server refuses to load a plaintext (unencrypted) PEM private key from a file (FCS_STG_EXT.1). Only PKCS#8 encrypted PEM (ENCRYPTED PRIVATE KEY) or PKCS#11 URIs are accepted. Use key_password_file to supply the decryption passphrase when using an encrypted PEM file.

[ca]
require_encrypted_key = true
key_password_file     = "/etc/akamu/ca-key-passphrase"

key_password_file

Optional. Default: absent.

Path to a file containing the passphrase used to decrypt an encrypted PEM CA private key. The file is read once at startup; trailing newlines are stripped. Required when require_encrypted_key = true and key_file points to a filesystem path (not a PKCS#11 URI).

[ca]
key_password_file = "/etc/akamu/ca-key-passphrase"

[mtc]

log_path

Required. Path to the disk-backed Merkle Tree Certificate transparency log file.

[mtc]
log_path = "/var/lib/akamu/mtc.log"

The file is created automatically on first run when enabled = true. It is never written when enabled = false, but the path must still be specified.

enabled

Optional. Default: false.

When true, each issued certificate is appended as a leaf to the MTC transparency log. The leaf index is stored in the certificates database table (mtc_log_index column).

enabled = false

MTC standalone certificate format

When issue_as = "mtc" is set in a profile, the server builds a standalone certificate for each issued certificate. The standalone certificate is a standard X.509 v3 Certificate where:

• signatureAlgorithm is id-alg-mtcProof (experimental OID 1.3.6.1.4.1.44363.47.0 from the Cloudflare PEN arc)
• signatureValue carries a TLS-encoded MTCProof (inclusion proof + cosignature records); per draft-04 §4.3, MTCProof has a leading extensions field (uint16 length-prefixed; empty = \x00\x00), start/end as uint48 (6-byte big-endian), and a uint8-prefixed cosigner_id in each MtcSignature
• serialNumber encodes the log entry index per draft §6.1

The GET /acme/mtc/cert/{cert_id}/standalone and GET /acme/mtc/landmarks/{seq}/cert endpoints return the DER-encoded certificate with Content-Type: application/pkix-cert and the X-MTC-Version: draft-04 response header.

OID stability note: The OIDs are experimental and pre-IANA. They will change when draft-ietf-plants-merkle-tree-certs is published as an RFC, requiring a coordinated update of the synta-mtc library and relying implementations. When [mtc] is enabled and [mtc.signing_key] is configured, the auto-generated CA certificate includes the id-pe-mtcCertificationAuthority extension (experimental OID 1.3.6.1.4.1.44363.47.2), identifying the CA as an MTC-capable issuer.

checkpoint_interval_secs

Optional. Default: 3600 (1 hour).

How often the checkpoint background task fires, in seconds. A checkpoint is produced only when the log has grown since the last one; if the tree size has not changed the task is a no-op. Requires [mtc.signing_key] to be configured.

checkpoint_interval_secs = 3600

checkpoint_retention_count

Optional. Default: 1000.

Maximum number of checkpoint rows to retain in the mtc_checkpoints database table. After each new checkpoint is produced, rows beyond this limit are pruned (oldest first). Their associated cosignature rows in mtc_cosignatures are also deleted via the foreign-key ON DELETE CASCADE constraint.

checkpoint_retention_count = 1000

landmark_interval_secs

Optional. Default: 86400 (1 day).

How often the landmark background task fires, in seconds. A new landmark is allocated only when the tree has grown since the last landmark; otherwise the task is a no-op. Requires [mtc.signing_key] to be configured.

landmark_interval_secs = 86400

max_active_landmarks

Optional. Default: 100.

Maximum number of landmark rows to retain in the mtc_landmarks table. After each new landmark is built, rows beyond this limit are pruned (oldest first by sequence number).

max_active_landmarks = 100

hash_alg

Optional. Default: "sha256".

Hash algorithm used for Merkle tree leaf hashing. Valid values:

The algorithm is stored in the log file’s header at creation time and cannot be changed for an existing log. If you change hash_alg after the log file already exists, Akāmu will refuse to start with an error identifying the mismatch. To switch algorithms you must delete the log file (and its lock file, if any) and let the server recreate it from scratch.

[mtc]
hash_alg = "sha256"

log_number

Optional. Default: 1.

Log number for serialNumber encoding per draft-04 §6.1. The serial number of each standalone certificate is computed as (log_number << 48) | entry_index. Each CA log should receive a unique, consecutive-from-1 log number.

[mtc]
log_number = 1

tree_minimum_index

Optional. Default: absent.

Minimum valid entry index (§5.2.3 log pruning). When set, the value is included in the Checkpoint.treeMinimumIndex field, indicating that entries below this index may have been pruned from the log. Relying parties should not attempt to verify inclusion proofs for entries below this index.

[mtc]
tree_minimum_index = 100

trust_anchor_id

Optional. Default: absent.

The CA’s own TrustAnchorID OID in dotted-decimal notation. Per draft-04 §5.4, each CA MUST operate a CA cosigner whose cosigner ID is the same as its CA ID. When set, a self-cosignature is produced alongside any external cosignatures during checkpoint production. The signing key configured in [mtc.signing_key] is used for the self-cosignature.

When absent, no self-cosignature is produced.

[mtc]
trust_anchor_id = "1.3.6.1.4.1.44363.47.10.1"

[mtc.signing_key]

Optional subsection. When present, enables checkpoint production and standalone/landmark certificate construction. The signing key must be distinct from the X.509 CA key (§5.5 of draft-ietf-plants-merkle-tree-certs).

key_file

Required within [mtc.signing_key]. Path to the MTC signing key PEM file. If absent on disk, a new key of key_type is generated and written here on startup.

key_type

Optional. Default: "ec:P-256".

Key algorithm for auto-generation. Accepts the same values as [ca].key_type. Per §5.4.2 of the draft, only ECDSA P-256/P-384, Ed25519, and ML-DSA are valid MTC signing algorithms; prefer EC or EdDSA.

hash_alg

Optional. Default: "sha256".

Hash algorithm used for ECDSA/RSA signing of MTC checkpoints and cosignatures: "sha256", "sha384", "sha512". Ignored for EdDSA and ML-DSA signing key types.

This field controls the signing hash only and is unrelated to the Merkle tree leaf-hash algorithm, which is configured separately via [mtc].hash_alg.

[mtc.signing_key]
key_file = "/var/lib/akamu/mtc-signing.key"
key_type = "ec:P-256"
hash_alg = "sha256"

[[mtc.cosigners]]

Optional array of external cosigner entries. After each checkpoint is produced, Akāmu POSTs the DER-encoded Checkpoint to each cosigner URL and stores the returned SubtreeSignature. Multiple entries are supported; all cosigners are contacted in parallel.

Each entry has the following fields:

url

Required. URL to POST the DER-encoded Checkpoint to (e.g. https://cosigner.example.com/sign).

cosigner_id_cert_pem

Optional. Path to the cosigner’s X.509 identity certificate PEM file. When set, the file is loaded at startup and added to the TLS trust store for that cosigner’s HTTPS connection, in addition to the system root CAs. This allows cosigners whose TLS certificate chains to an operator-provisioned CA to be used without installing that CA system-wide. The certificate is also used for cryptographic verification of received SubtreeSignature values.

trust_anchor_id

Optional. The expected TrustAnchorID OID of the cosigner in dotted-decimal notation (e.g. "1.3.6.1.4.1.44363.47.10.1"). Per draft-ietf-plants-merkle-tree-certs-04 §4.1, CosignerID is now an OBJECT IDENTIFIER (TrustAnchorID ::= OBJECT IDENTIFIER) rather than a SEQUENCE of hash algorithm and public key. When set, Akāmu verifies that the SubtreeSignature.cosigner OID in each response matches this value. When absent, the OID identity check is skipped; cryptographic verification via cosigner_id_cert_pem still applies when that field is set. Operators must agree on the OID value with their cosigner operator.

Security constraint: Setting trust_anchor_id without also setting cosigner_id_cert_pem is a hard startup error. OID-only verification provides no cryptographic assurance — anyone who knows the OID could forge a cosignature. Both fields must be set together to enable verified cosignature acceptance.

[[mtc.cosigners]]
url                  = "https://cosigner1.example.com/sign"
cosigner_id_cert_pem = "/etc/akamu/cosigner1-id.pem"
trust_anchor_id      = "1.3.6.1.4.1.44363.47.10.1"   # optional; TrustAnchorID OID

[[mtc.cosigners]]
url = "https://cosigner2.example.com/sign"

[server]

The [server] section is optional. When omitted entirely, all fields take their default values.

audit_log_file

Optional. Default: absent (use systemd journal namespace).

Path to a JSONL (JSON Lines) audit log file. When set, audit events are written as append-only JSON Lines to this file instead of the systemd journal namespace socket. Each line is a JSON object with occurred_at, AKAMU_EVENT_TYPE, AKAMU_OUTCOME, and optional AKAMU_SUBJECT, AKAMU_PRINCIPAL, AKAMU_DETAIL fields.

When absent (the default), the server writes to the akamu journal namespace (see contrib/systemd/journald@akamu.conf). Use this option on systems without systemd or when journal namespace sockets are not available.

External logrotate(8) with copytruncate is expected for log rotation. Each audit query scans at most 500,000 lines to prevent unbounded reads on unrotated files.

[server]
audit_log_file = "/var/log/akamu/audit.jsonl"

terms_of_service_url

Optional. Default: absent.

URL of the Terms of Service document. When set, it appears in the meta.termsOfService field of the ACME directory response.

terms_of_service_url = "https://acme.example.com/tos.html"

website_url

Optional. Default: absent.

URL of the operator’s website. When set, it appears in the meta.website field of the directory response.

website_url = "https://acme.example.com"

caa_identities

Optional. Default: empty list.

List of CA domain names for CAA record verification (RFC 8659). When set, Akāmu queries CAA DNS records before issuing each certificate and verifies that at least one issue (or issuewild for wildcard) record authorises one of these CA domain names. The values also appear in meta.caaIdentities of the directory response.

When the list is empty (the default), CAA checking is skipped entirely — including RFC 8657 accounturi enforcement, because accounturi is evaluated as part of the CAA record check.

caa_identities = ["acme.example.com"]

account_scope

Optional. Default: "server".

Controls whether ACME accounts are shared across all CAs or isolated per CA.

[server]
account_scope = "server"

external_account_required

Optional. Default: false.

When true, new-account requests must include an externalAccountBinding field (RFC 8555 §7.3.4). Requests without it are rejected with urn:ietf:params:acme:error:externalAccountRequired (HTTP 403). The directory response also includes meta.externalAccountRequired: true.

When enabled, the server performs full HMAC verification: it resolves the kid in the eab_keys database table (populated either from [server.eab_keys] at startup or by HKDF derivation via GET /acme/eab), verifies the HS256/HS384/HS512 MAC, confirms the payload is the account key, and atomically consumes the key at account creation so each EAB key can only be used once.

external_account_required = true

eab_keys

Optional. Default: {}.

Pre-shared External Account Binding keys, expressed as a TOML table under [server.eab_keys]. Each entry maps a key identifier (kid) to its base64url-encoded raw HMAC key bytes. The key material must be at least 16 bytes; 32 bytes (256 bits) is recommended for HS256.

Keys are loaded at startup and persisted in the database. A key that has been consumed (used to create an account) is never overwritten on a subsequent restart, so spent keys remain invalidated across restarts.

[server.eab_keys]
"kid-1" = "c2VjcmV0LWhtYWMta2V5LWJ1ZmZlcg"   # base64url, no padding
"kid-2" = "YW5vdGhlci1rZXktaGVyZQ"

To generate a key:

openssl rand -base64 32 | tr '+/' '-_' | tr -d '='

eab_master_secret

Optional. Default: absent.

Base64url-encoded master secret (must decode to at least 32 bytes) used to derive deterministic EAB credentials via HKDF-SHA-256 (RFC 5869). When set, the GET /acme/eab endpoint derives a unique (kid, hmac_key) pair for each authenticated principal using the following construction:

kid      = base64url( HKDF-SHA256(IKM=master_secret, info="akamu-eab-v1-kid:<principal>", L=16) )
hmac_key = base64url( HKDF-SHA256(IKM=master_secret, info="akamu-eab-v1-key:<principal>", L=32) )

The same (master_secret, principal) pair always produces the same (kid, hmac_key). Credentials are stored in the eab_keys table on first request and returned on subsequent requests. Once the kid has been consumed by an account registration, re-fetching GET /acme/eab for that principal returns HTTP 409 Conflict.

When eab_master_secret is absent, GET /acme/eab returns only {"principal":"…"} (backward-compatible stub behaviour, no EAB credentials).

Authentication for GET /acme/eab requires either [server.gssapi] (standalone GSSAPI/SPNEGO) or trusted_proxies (reverse-proxy mode supplying X-Remote-User).

Generate a suitable secret:

openssl rand -base64 32 | tr '+/' '-_' | tr -d '='

[server]
external_account_required = true
eab_master_secret = "Zm9vYmFyYmF6cXV4cXV1eGZvb2JhcmJhenF1eHF1dXg"

order_expiry_secs

Optional. Default: 86400 (24 hours).

Number of seconds after creation before an order expires. Expired orders cannot be finalized.

order_expiry_secs = 86400

authz_expiry_secs

Optional. Default: 86400 (24 hours).

Number of seconds after creation before an authorization expires. Expired authorizations must be re-created via a new order.

authz_expiry_secs = 86400

max_body_bytes

Optional. Default: 65536 (64 KiB).

Maximum size in bytes of JOSE+JSON request bodies. Requests larger than this limit are rejected with HTTP 413. This applies to all POST endpoints that carry ACME payloads, and also to the admin API listener.

max_body_bytes = 65536   # 64 KiB

http_validation_port

Optional. Default: 80.

TCP port used when the server fetches http-01 challenge responses. RFC 8555 §8.3 requires port 80 in production deployments. Override this to a high port for local testing or non-standard network environments.

http_validation_port = 80

http_validation_allow_private_ips

Optional. Default: false.

When false (the default), the initial connection target and any redirect targets that resolve to private, link-local, or loopback IP addresses (RFC 1918, 169.254.0.0/16, 127.0.0.0/8, fc00::/7, fe80::/10, etc.) are blocked to prevent SSRF attacks against cloud metadata endpoints such as 169.254.169.254. Both IP literals and hostnames are checked: for hostnames, every resolved address must be globally routable.

Set to true only in isolated test environments where the http-01 challenge responder intentionally runs on a private address.

http_validation_allow_private_ips = false   # default — recommended for all production deployments

dns_persist_issuer_domains

Optional. Default: absent (dns-persist-01 disabled).

The issuer domain(s) placed in the issuer-domain-names field of dns-persist-01 challenge objects and matched against the first token of TXT records during validation. When this field is set, the server offers dns-persist-01 as an additional challenge type for all dns identifiers. When absent, dns-persist-01 is not offered and existing clients are unaffected.

Accepts either a single string or an array of strings. Multi-tenant or multi-identity deployments can list all accepted issuer domains; validation succeeds when the TXT record’s issuer domain matches any of the configured values.

See dns-persist-01 Challenge for the full description of the challenge type and TXT record format.

# Single domain
dns_persist_issuer_domains = "acme.example.com"

# Multiple domains (multi-tenant or multi-identity deployments)
dns_persist_issuer_domains = ["acme.example.com", "acme.example.org"]

dns_resolver_addr

Optional. Default: absent (system resolver).

Override the DNS resolver used for dns-01, dns-persist-01, and CAA record lookups. Format: "<ip>:<port>". When absent, the system default resolver is used. Useful for split-horizon DNS deployments where the ACME server cannot reach the public resolver, and for integration testing against a local stub server.

dns_resolver_addr = "127.0.0.1:5353"

dns_persist01_resolver_addr

Optional. Default: absent (falls back to dns_resolver_addr).

Resolver override used exclusively for dns-persist-01 TXT lookups at _validation-persist.*. When set, this address is used instead of dns_resolver_addr for dns-persist-01 validation only. Useful when persistent TXT records are served by a different DNS infrastructure than the one used for dns-01 and CAA lookups.

dns_resolver_addr           = "127.0.0.1:5353"   # used for dns-01 and CAA
dns_persist01_resolver_addr = "127.0.0.1:5354"   # used only for dns-persist-01

dns_dot_server_name

Optional. Default: absent (plain UDP).

TLS server name (SNI hostname) for DNS-over-TLS (DoT, RFC 7858). When set, all DNS challenge validation queries — dns-01, dns-persist-01, and CAA record lookups — are sent over TLS to the resolver specified by dns_resolver_addr instead of plain UDP.

Use DoT when the network path between the Akāmu server and its resolver is untrusted: for example, when the resolver is a public DNS provider reached over the Internet, when the operator wants to prevent on-path DNS hijacking by an ISP, or to satisfy privacy requirements that prohibit cleartext DNS queries.

dns_resolver_addr must be set to the DoT server’s IP address and port 853 when this field is present. The TLS certificate presented by the resolver is verified against the system root CA store (system OpenSSL). LDAP SRV lookups for certificate profile providers are unaffected — they always use plain UDP.

DoT and DNSSEC validation (validate_dnssec = true) are independent and can be enabled at the same time. DoT protects the query transport channel; DNSSEC authenticates the DNS response data itself.

# DoT only — encrypt queries to Cloudflare's resolver
dns_resolver_addr    = "1.1.1.1:853"
dns_dot_server_name  = "cloudflare-dns.com"

# DoT + DNSSEC — encrypted transport and cryptographic response validation
dns_resolver_addr    = "1.1.1.1:853"
dns_dot_server_name  = "cloudflare-dns.com"
validate_dnssec      = true

ari_retry_after_secs

Optional. Default: 21600 (6 hours).

The value of the Retry-After header returned on GET /acme/renewal-info/{cert-id} responses (RFC 9773 §4.3). Controls how frequently ACME clients poll for renewal information.

ari_retry_after_secs = 21600

ari_explanation_url

Optional. Default: absent.

URL included in GET /acme/renewal-info/{cert-id} responses as the explanationURL field (RFC 9773 §4.1). When set, it points clients to a human-readable page explaining why early renewal is being suggested (for example, an incident notice or CA policy update). When absent, the field is omitted from the response entirely.

ari_explanation_url = "https://acme.example.com/docs/renewal-policy"

allow_subdomain_auth

Optional. Default: false.

When true, the directory meta includes "subdomainAuthAllowed": true, advertising that the server supports RFC 9444 subdomain authorization. Clients may then:

• Include "subdomainAuthAllowed": true in POST /acme/new-authz requests.
• Reference an ancestor domain in newOrder via the ancestorDomain identifier field.

allow_subdomain_auth = true

star_min_lifetime_secs

Optional. Default: absent (STAR not advertised).

Minimum certificate lifetime in seconds for ACME STAR orders (RFC 8739). When set, the directory meta includes an auto-renewal object advertising STAR capability. Clients that place STAR orders must request a lifetime value greater than or equal to this minimum.

Setting this field enables the STAR background reissuance task.

star_min_lifetime_secs = 86400   # 1 day minimum

star_max_duration_secs

Optional. Default: absent.

Maximum total renewal duration in seconds for ACME STAR orders. When set, it is included in the directory meta.auto-renewal object as max-duration. Clients must supply an end-date that does not exceed this value beyond the order creation time.

star_max_duration_secs = 31536000   # 1 year maximum

star_allow_certificate_get

Optional. Default: true.

Controls whether the rolling STAR certificate URL (/acme/cert/star/<order-id>) can be fetched with an unauthenticated GET request. When true, the directory meta.auto-renewal object includes "allow-certificate-get": true and clients may request this capability per order by including "allow-certificate-get": true in the auto-renewal object of newOrder. When false, the capability is not advertised and unauthenticated GET requests are rejected.

star_allow_certificate_get = true

delegation_enabled

Optional. Default: false.

When true, Akāmu activates the RFC 9115 delegation API surface:

• The directory meta object includes "delegation-enabled": true.
• Every account response includes a "delegations" URL.
• The delegation listing and fetch endpoints become active:
  • POST /acme/delegations/{account_id} — list delegations for an account (POST-as-GET).
  • POST /acme/delegation/{id} — fetch a single delegation object (POST-as-GET).
• POST /acme/new-order accepts the "delegation" field to link an order to a delegation.
• Delegation orders start in ready status and return "authorizations": [].

Delegations themselves are managed via the Admin API (/admin/delegations). The [admin] section must be configured before delegations can be created.

[server]
delegation_enabled = true

allow_certificate_get

Optional. Default: false.

When true, the directory meta object includes "allow-certificate-get": true for RFC 9115 delegation orders (distinct from the star_allow_certificate_get flag, which covers RFC 8739 STAR certificates). When an order is placed with "allow-certificate-get": true in the new-order payload, the certificate endpoint for that order can be fetched with an unauthenticated GET rather than a POST-as-GET. The capability is advertised in the directory only when this flag is true.

[server]
allow_certificate_get = true

tor_connectivity_enabled

Optional. Default: false.

Controls whether the server offers http-01 and tls-alpn-01 challenge types for .onion identifiers. RFC 9799 §4 prohibits offering those challenge types unless the CA can actually reach the Tor network. When false (the default), only onion-csr-01 is offered for .onion identifiers. Set to true only when the Akāmu server process can make outbound Tor connections to hidden services (for example, via torsocks or a SOCKS5 proxy configured at the OS level).

tor_connectivity_enabled = true

validate_dnssec

Optional. Default: true.

Controls whether DNSSEC validation is enforced during DNS-based challenge verification (dns-01, dns-persist-01) and CAA record lookups. CA/B Forum BR §3.2.2.4 and §3.2.2.8.1 require DNSSEC validation for publicly trusted CAs as of 2026-03-15. Set to false only for testing environments or deployments where the DNS infrastructure is not yet DNSSEC-signed; doing so makes the CA non-compliant.

validate_dnssec = true

trusted_proxies

Optional. Default: empty (proxy header mode disabled).

List of CIDR blocks (IPv4 or IPv6) whose connecting IP address is trusted to supply an X-Remote-User header. When a request arrives from one of these addresses, akamu reads the header value as the already-authenticated principal name — the reverse proxy is expected to have completed SPNEGO or another authentication step before forwarding the request.

Requests from addresses not in this list never have X-Remote-User honoured, regardless of what the header contains.

Mutually exclusive with [server.gssapi]. Setting both trusted_proxies and [server.gssapi] at the same time is a configuration error; the server exits at startup with an error message.

[server]
trusted_proxies = ["127.0.0.1/32", "::1/128", "10.0.0.0/8"]

Security note: keep this list tightly scoped to the IP addresses of your reverse proxy or load balancer. Adding broad ranges (e.g. 0.0.0.0/0) allows any client to impersonate any principal.

[server.gssapi]

Optional. When absent, standalone GSSAPI mode is disabled.

Mutually exclusive with trusted_proxies. Setting both at the same time is a configuration error; the server exits at startup with an error message.

Configures akamu to accept Authorization: Negotiate tokens directly, without a reverse proxy. At startup the server acquires a combined initiator+acceptor credential (GSS_C_BOTH) using gss_acquire_cred_from and then uses gss_accept_sec_context to validate each SPNEGO token. The GSS_C_BOTH usage flag is required for S4U2Self constrained delegation (used internally for LDAP profile lookups). Credentials are acquired either directly from keytab_file or, when gssproxy = true, via the gssproxy daemon (which intercepts the underlying GSSAPI call and supplies credentials from its own keytab configuration).

Use this mode when you want akamu to handle Kerberos authentication itself rather than delegating to a front-end proxy such as Apache or Nginx.

Security behaviors in standalone GSSAPI mode:

• Token size limit. Authorization: Negotiate tokens larger than 128 KiB are rejected with 400 Bad Request. Legitimate Kerberos tickets are always smaller than this limit.
• Case-insensitive scheme matching. The "Negotiate " prefix is matched case-insensitively per RFC 7235 §2.1.
• TLS channel bindings (RFC 5929). When akamu terminates TLS itself, the tls-server-end-point binding is computed from the leaf certificate and passed to gss_accept_sec_context, binding the Kerberos exchange to the TLS channel. Channel bindings are disabled automatically when the server certificate uses ML-DSA (pure or composite) or Ed448, because RFC 5929 defines no canonical hash for those algorithms.
• Replay detection. After a successful context acceptance, akamu checks whether GSS_C_REPLAY_FLAG is set. When the flag is absent (common when clients connect over TLS, because TLS already provides replay protection), a debug-level log entry is emitted and the authentication proceeds normally. This behaviour is intentional: browsers and TLS-first clients typically do not negotiate Kerberos-level replay protection.
• GSSAPI without TLS. Running standalone GSSAPI without TLS is permitted but emits a warn-level log at startup: SPNEGO tokens are vulnerable to interception and relay attacks without TLS.
• No mechanism configured. When neither trusted_proxies nor [server.gssapi] is set, authenticated endpoints return 404 Not Found.

keytab_file

Required when gssproxy = false (the default). Must be absent when gssproxy = true. Path to the HTTP service keytab file. The akamu process must be able to read this file; no other user should have read access to it. The path is logged at debug level only. Setting both keytab_file and gssproxy = true is a configuration error; the server exits at startup.

keytab_file = "/etc/akamu/http.keytab"

Generate the keytab for an IPA-managed host:

ipa-getkeytab -s ipa.example.com -p HTTP/akamu.example.com@EXAMPLE.COM \
    -k /etc/akamu/http.keytab
chmod 600 /etc/akamu/http.keytab
chown akamu: /etc/akamu/http.keytab

gssproxy

Optional. Default: false.

When true, GSSAPI credential acquisition is delegated to the gssproxy daemon instead of reading a keytab file directly. The akamu process must have a matching entry in /etc/gssproxy/conf.d/ (typically matched by UID). The server sets GSS_USE_PROXY=yes in its environment before the first GSSAPI call so that the GSSAPI library routes the credential request through gssproxy. No direct access to a keytab file on disk is needed. keytab_file must be absent when this is true.

# gssproxy mode — no keytab access required for the akamu process
[server.gssapi]
gssproxy     = true
service_name = "HTTP"

service_name

Optional. Default: "HTTP".

Host-based service name to acquire credentials for. MIT Kerberos appends @<local-hostname> when no realm is specified, so "HTTP" is correct for a single-homed host. Use "HTTP@akamu.example.com" to be explicit.

service_name = "HTTP"

Proxy mode example

[server]
trusted_proxies = ["192.168.1.10/32"]

In this configuration, only connections from 192.168.1.10 (the reverse proxy) are allowed to supply X-Remote-User. Requests from any other source that reach an authenticated endpoint return 404 Not Found (no authentication mechanism is configured for those connections).

Standalone GSSAPI examples

Keytab mode — akamu reads the keytab file directly:

[server.gssapi]
keytab_file  = "/etc/akamu/http.keytab"
service_name = "HTTP"

gssproxy mode — akamu delegates credential acquisition to gssproxy (no direct keytab access required for the akamu process):

[server.gssapi]
gssproxy     = true
service_name = "HTTP"

In both configurations, akamu handles Authorization: Negotiate directly. Clients must obtain a Kerberos service ticket for HTTP/<hostname> before calling authenticated endpoints.

[server.webui]

Optional. When absent, the /ui/ routes are not registered and return 404.

When present, Akāmu serves the built PatternFly management web UI from a directory of static files. The UI is mounted at /ui/* on the same listener as the ACME and admin APIs; no separate process or proxy is required.

When [server.webui] is absent (the default), no /ui/* routes are registered at all. Requests to /ui/ and GET / receive 404 responses as if the routes did not exist.

When [server.webui] is present:

• GET /ui/* serves static files from static_dir.
• Directory requests fall back to index.html inside that directory (SPA routing support).
• GET / permanently redirects to /ui/.
• Security headers (Content-Security-Policy, X-Frame-Options, etc.) are added to every /ui/* response.

The admin API (/admin/*) is served on the same listener and is called directly by the browser — no additional proxy is needed.

static_dir

Optional. Default: absent (web UI disabled).

Absolute path to the directory containing the built web UI files. The directory must contain at minimum an index.html file.

When static_dir is absent but [server.webui] is present, the section is accepted without error and no routes are registered — the behavior is identical to omitting [server.webui] entirely. Set static_dir to actually serve the UI.

Config validation rejects a relative path with a startup error.

[server.webui]
static_dir = "/usr/share/akamu/webui"

Source build example (absolute path required):

[server.webui]
static_dir = "/home/user/akamu/webui/dist"

[tls]

The [tls] section enables Akāmu to terminate TLS directly on the main listen_addr socket, without a reverse proxy. When this section is absent or enabled = false, the server operates over plain HTTP.

[tls]
enabled    = true
cert_file  = "/etc/akamu/server.pem"
key_file   = "/etc/akamu/server-key.pem"
protocols  = ["TLSv1.2", "TLSv1.3"]

[tls.client_auth]
required          = false
ca_files          = ["/etc/akamu/client-ca.pem"]
profile           = "webpki"
allow_post_quantum = false
max_chain_depth   = 8
minimum_rsa_modulus = 2048

enabled

Optional. Default: false.

When true, the server listens with TLS on listen_addr. When false, the socket accepts plain HTTP connections.

[tls]
enabled = true

cert_file

Optional. Path to the PEM file containing the server TLS certificate chain (leaf certificate first). When this file is absent on disk and key_file is also absent, Akāmu generates a self-signed certificate on first run using bootstrap_key_type and server_name.

cert_file = "/etc/akamu/server.pem"

key_file

Optional. Path to the PEM file containing the server TLS private key (PKCS#8 or SEC1, unencrypted). Same auto-generation rules as cert_file.

key_file = "/etc/akamu/server-key.pem"

protocols

Optional. Default: ["TLSv1.2", "TLSv1.3"].

List of TLS protocol versions the server accepts. Both TLS 1.2 and TLS 1.3 are enabled by default.

protocols = ["TLSv1.2", "TLSv1.3"]

server_name

Optional. Default: "localhost".

Hostname placed in the CN and SAN of the auto-generated server certificate. Only used when cert_file and key_file are absent on disk.

server_name = "acme.example.com"

bootstrap_key_type

Optional. Default: "ec:P-256".

Key algorithm for the auto-generated server certificate. Only used when cert_file and key_file are absent on disk. Accepts the same values as [ca].key_type.

bootstrap_key_type = "ec:P-256"

[tls.client_auth]

Optional. When absent, client certificate authentication is disabled.

Configures mutual TLS (mTLS) client certificate authentication. When present, the server requests a client certificate during the TLS handshake.

required

Optional. Default: false.

When true, connections that present no client certificate are rejected. When false, client certificates are optional — presented certificates are still verified if provided.

required = true

ca_files

Required within [tls.client_auth]. List of PEM files containing the trusted CA certificates used to verify client certificates.

ca_files = ["/etc/akamu/client-ca.pem"]

profile

Optional. Default: "webpki".

Certificate validation profile. Accepted values:

profile = "webpki"

allow_post_quantum

Optional. Default: false.

When true, ML-DSA and hybrid composite post-quantum signature algorithms (draft-ietf-lamps-pq-composite-sigs) are accepted in client certificates and CertificateVerify messages. When false, only classical algorithms are accepted.

allow_post_quantum = false

max_chain_depth

Optional. Default: 8.

Maximum certificate chain depth accepted for client certificates. Chains longer than this value are rejected.

max_chain_depth = 8

minimum_rsa_modulus

Optional. Default: 2048.

Minimum RSA modulus size in bits for RSA client certificates. Connections presenting an RSA certificate with a smaller key are rejected.

minimum_rsa_modulus = 2048

[email_challenge]

The [email_challenge] section enables the RFC 8823 email-reply-00 challenge type for S/MIME certificate issuance. When this section is absent or enabled = false, the server does not offer email-reply-00 challenges and rejects orders with email identifier types.

See email-reply-00 in the Challenges reference for the full protocol description, CSR requirements, and webhook payload format.

[email_challenge]
enabled             = true
from_address        = "acme-validation@example.com"
send_script         = "/etc/akamu/send-email.sh"
webhook_hmac_secret = "replace-with-output-of--openssl-rand-hex-32"

enabled

Optional. Default: false.

Set to true to activate the email-reply-00 challenge type. When false, any POST to /acme/email-webhook returns 503 Service Unavailable.

from_address

Required when enabled = true. The email address the server sends challenge emails from. This value is returned to clients in the from field of the challenge object and passed to the send script as $ACME_FROM.

from_address = "acme-validation@example.com"

The domain portion of this address is used to construct the Message-ID header (<uuid@from-domain>).

send_script

Required when enabled = true. Absolute path to an executable that sends the challenge email. The server invokes it with no arguments; all parameters are passed as environment variables:

Exit code 0 = success. Any non-zero exit code marks the challenge invalid and the client may retry.

The script is responsible for DKIM signing of the outbound email. Akāmu does not perform SMTP or DKIM internally.

send_script = "/etc/akamu/send-email.sh"

send_script_timeout_secs

Optional. Default: 30.

Maximum time in seconds the server waits for send_script to exit. If the script does not exit within this limit, the server kills it and marks the challenge invalid. Must be at least 1. Increase this if your mail transfer agent has a slow startup or must authenticate to a relay.

send_script_timeout_secs = 30

webhook_hmac_secret

Required when enabled = true. A shared secret used to authenticate POST /acme/email-webhook requests. The caller must include the header:

X-Akamu-Signature: sha256=<lowercase-hex(HMAC-SHA256(raw-body, webhook_hmac_secret))>

Choose a long random value (≥256 bits recommended). Requests with a missing, malformed, or incorrect signature are rejected with 403 Forbidden.

webhook_hmac_secret = "replace-with-output-of--openssl-rand-hex-32"

Keep this value secret. Anyone who knows it can submit webhook payloads and influence challenge outcomes.

[delegation_upstream]

The [delegation_upstream] section configures Akāmu to act as an ACME client toward an upstream CA when processing RFC 9115 delegation orders. When this section is present, a background task polls delegation orders in processing status and drives them through the full ACME flow on the upstream CA: account registration (if needed), order creation, dns-01 challenge deployment, finalization, and certificate retrieval.

When this section is absent, Akāmu operates only as an IdO ACME server — it issues delegation orders but does not drive an upstream CA leg. The background task is not started.

[delegation_upstream]
directory_url           = "https://upstream-ca.example.com/acme/directory"
account_key_file        = "/etc/akamu/upstream-acme.key.pem"
contacts                = ["mailto:admin@example.com"]
challenge_solver        = "dns-01"
challenge_deploy_script = "/etc/akamu/upstream-dns-deploy.sh"
# challenge_cleanup_script = "/etc/akamu/upstream-dns-cleanup.sh"
# poll_interval_secs = 10

directory_url

Required within [delegation_upstream]. ACME directory URL of the upstream CA. Akāmu fetches the directory at startup to discover the upstream CA’s endpoint URLs.

directory_url = "https://upstream-ca.example.com/acme/directory"

account_key_file

Required within [delegation_upstream]. Path to a PEM file containing the ACME account key used when registering with the upstream CA. The file is loaded at startup. If the key file is absent on disk, a new EC P-256 key is generated and written to this path on first run.

account_key_file = "/etc/akamu/upstream-acme.key.pem"

contacts

Optional. Default: [].

List of contact URIs (e.g. mailto: addresses) submitted to the upstream CA when registering the ACME account. Omit if the upstream CA does not require contacts.

contacts = ["mailto:admin@example.com"]

challenge_solver

Required within [delegation_upstream]. Challenge type used to satisfy the upstream CA’s authorizations. Only "dns-01" is currently supported.

challenge_solver = "dns-01"

challenge_deploy_script

Required within [delegation_upstream]. Absolute path to an executable that deploys the dns-01 TXT record at the upstream CA’s direction. The script is invoked with env_clear(); only the following environment variables are set:

Exit code 0 = record deployed successfully. Any non-zero exit code marks the challenge attempt as failed.

challenge_deploy_script = "/etc/akamu/upstream-dns-deploy.sh"

The cleanup script is called only after the authorization has transitioned to valid at the upstream CA — not immediately after the deploy script exits. This ensures the TXT record remains queryable for the full upstream validation window.

challenge_cleanup_script

Optional. Default: absent (no cleanup).

Absolute path to an optional cleanup executable invoked after the upstream authorization has become valid. Receives the same CERTBOT_DOMAIN and CERTBOT_VALIDATION variables as the deploy script, plus CERTBOT_AUTH_OUTPUT="". Use it to remove the TXT record from DNS.

challenge_cleanup_script = "/etc/akamu/upstream-dns-cleanup.sh"

poll_interval_secs

Optional. Default: 10.

How often the background task polls the upstream CA for order and authorization status, in seconds.

poll_interval_secs = 10

[tkauth]

The [tkauth] section enables the RFC 9447 tkauth-01 challenge type for TNAuthList (RFC 9448) and JWTClaimConstraints (draft-ietf-acme-authority-token-jwtclaimcon) identifier types. When this section is absent or enabled = false, orders containing these identifier types are rejected.

See tkauth-01 in the Challenges reference for the full protocol description including the authority token format, validation steps, and claim encoder configuration.

[tkauth]
enabled                 = true
trusted_ta_ca_files     = ["/etc/akamu/ta-root.pem"]
token_authority_url     = "https://ta.example.com"   # optional hint
max_validity_secs       = 3600
jti_prune_interval_secs = 3600

[[tkauth.claim_encoders]]
claim   = "sub"
encoder = "krb5-kpn"

enabled

Optional. Default: false.

Set to true to activate the tkauth-01 challenge type. When false, any order with TNAuthList or JWTClaimConstraints identifiers is rejected with unsupportedIdentifier.

trusted_ta_ca_files

Required when enabled = true. List of absolute paths to PEM files containing trusted CA certificates for Token Authority signing certificate validation. The signing certificate presented in the authority token (via x5u or x5c) must chain to one of these CA roots. Not used for kid-signed tokens (which rely on trust_jwks_urls in per-profile configuration instead).

trusted_ta_ca_files = ["/etc/akamu/ta-root.pem"]

token_authority_url

Optional. Default: absent.

URL hint included in tkauth-01 challenge responses as the token-authority field. When set, ACME clients that read this field can use it to discover where to obtain an authority token. This is informational only; the server does not contact this URL itself.

token_authority_url = "https://ta.example.com"

max_validity_secs

Optional. Default: 3600 (1 hour).

Maximum accepted lifetime of an authority token: tokens with exp − now > max_validity_secs are rejected. This caps how long into the future a Token Authority may pre-issue tokens, limiting the window in which a stolen token could be replayed.

max_validity_secs = 3600

jti_prune_interval_secs

Optional. Default: 3600 (1 hour).

How often the background task purges expired JTI (JWT ID) entries from the replay-prevention cache in the database. Lower values reduce database growth at the cost of more frequent pruning queries. The background task only runs when [tkauth] is enabled.

jti_prune_interval_secs = 3600

Operators can also trigger manual pruning via the admin API or akamuctl:

POST /admin/tkauth/prune-jti
POST /admin/tkauth/prune-jti?dry_run=true

akamuctl tkauth prune-jti
akamuctl tkauth prune-jti --dry-run   # count without deleting

[[tkauth.claim_encoders]]

Optional array of claim-to-extension encoder entries. Each entry maps a JWT claim name in permittedValues of the validated JWTClaimConstraints token to a built-in certificate extension encoder. The encoder runs at finalize time and injects the claim value as a Subject Alternative Name in the issued certificate.

[[tkauth.claim_encoders]]
claim   = "sub"
encoder = "krb5-kpn"
# default_realm = "EXAMPLE.COM"   # appended when claim value has no '@'

[[tkauth.claim_encoders]]
claim   = "upn"
encoder = "ms-upn"

[[tkauth.claim_encoders]]
claim   = "dns"
encoder = "dns-san"

Built-in encoder names:

Each encoder entry has these fields:

A permittedValues entry with exactly one value is injected as a SAN using the matching encoder. Entries with multiple permitted values are skipped (the server cannot determine which specific value to attest).

[gossip]

The [gossip] section enables multi-node clustering via CRDT replication. When present, Akāmu gossips CRDT deltas to the listed peer nodes over HTTP (POST /gossip/sync). All domain state — accounts, orders, authorizations, challenges, certificates, EAB keys, operators, delegations, and MTC data — is replicated to every cluster member. When absent, the node operates in single-node mode with no replication.

Gossip envelopes are signed with ML-KEM-768 + ECDSA-P256 to authenticate the source. Before gossip can proceed between two nodes, each node’s keys must be registered on the other node via POST /admin/gossip/register.

[gossip]
peers                        = ["https://node2.example.com", "https://node3.example.com"]
interval_secs                = 15
tombstone_ttl_secs           = 604800
ownership_ttl_secs           = 150
gossip_envelope_max_age_secs = 300
clock_skew_tolerance_secs    = 30
fan_out                      = 3

peers

Optional. Default: [].

List of peer gossip URLs to push CRDT state to. Each entry must be the HTTPS base URL of a peer Akāmu node (scheme, host, and optional port; no trailing path). Peers are contacted each gossip round; the fan_out setting limits how many are contacted per round.

peers = ["https://node2.acme.internal:8443", "https://node3.acme.internal:8443"]

interval_secs

Optional. Default: 15.

How often (in seconds) the background gossip loop fires and pushes CRDT deltas to peers. Lower values reduce replication lag at the cost of more network traffic.

interval_secs = 15

tombstone_ttl_secs

Optional. Default: 604800 (7 days).

How long tombstone records are retained in the CRDT before they are garbage-collected. Tombstones must be retained long enough to ensure every peer in the cluster has received the deletion before the record is purged.

tombstone_ttl_secs = 604800

ownership_ttl_secs

Optional. Default: 150.

Lease duration in seconds for write-ownership of orders and MTC entries. Each node refreshes its ownership lease every gossip round. When a lease expires (the owning node has been silent for ownership_ttl_secs), another node may take over.

ownership_ttl_secs = 150

gossip_envelope_max_age_secs

Optional. Default: 300 (5 minutes).

Maximum age in seconds of a gossip envelope. Envelopes timestamped more than this many seconds in the past are rejected as potential replays.

gossip_envelope_max_age_secs = 300

clock_skew_tolerance_secs

Optional. Default: 30.

Maximum acceptable clock difference between cluster nodes in seconds. Gossip envelopes timestamped more than this many seconds in the future are rejected. Ensure NTP synchronisation across all cluster members keeps skew well below this threshold.

clock_skew_tolerance_secs = 30

fan_out

Optional. Default: 0 (contact all peers).

Maximum number of peers contacted per gossip round. When set to a positive integer, only that many peers are selected at random each round; this reduces O(N²) gossip overhead in clusters larger than roughly five nodes while convergence still occurs transitively in O(log_k(N)) rounds. Set to 0 to contact all configured peers every round.

fan_out = 3   # recommended for clusters of 5+ nodes

[profiles]

The [profiles] section configures the certificate profile subsystem. Profiles are loaded from one or more providers at startup, cached in memory, and refreshed periodically by a background task. Akāmu’s own CA always signs; profiles only control which extensions are included and with what values. When no providers are configured, every order falls back to CA defaults (digitalSignature KeyUsage, serverAuth EKU, and the [ca] validity/URL settings).

When at least one provider is configured and a newOrder request omits the profile field, the server checks whether a profile named "default" exists in the registry. If it does, "default" is applied automatically and echoed back in the order response. If no "default" profile exists, the order falls back to the CA’s built-in defaults.

See Certificate Profiles for the complete reference including all provider types, key usage names, EKU OIDs, and three-state URL semantics.

refresh_interval_secs

Optional. Default: 3600 (1 hour).

How often the background task re-reads profiles from all providers. Set to 0 to disable automatic refresh (profiles are loaded once at startup and never refreshed).

[profiles]
refresh_interval_secs = 1800   # refresh every 30 minutes

[profiles.providers.<name>]

Each key under [profiles.providers] names a provider. The required type field selects the backend:

# Builtin provider: inline declarations
[profiles.providers.local]
type = "builtin"

[profiles.providers.local.profiles.tlsserver]
description   = "Standard TLS server certificate"
validity_days = 90
key_usage     = ["digital_signature", "key_encipherment"]
eku           = ["server_auth"]

# Dogtag provider: load .cfg files from a directory
[profiles.providers.dogtag_prod]
type        = "dogtag"
profile_dir = "/etc/pki/pki-tomcat/ca/profiles/ca"
profiles    = ["caServerCert"]   # empty = all .cfg files

# Dogtag provider: load profiles from LDAP (simple bind, single server)
# Setting tls_ca_cert_file triggers STARTTLS automatically on ldap:// URIs.
[profiles.providers.dogtag_ldap]
type     = "dogtag"
profiles = ["caServerCert"]

[profiles.providers.dogtag_ldap.ldap]
uri                = "ldap://dogtag.example.com:389"
base_dn            = "dc=example,dc=com"
bind_dn            = "uid=admin,ou=people,dc=example,dc=com"
bind_password_file = "/etc/akamu/ldap-password"
tls_ca_cert_file   = "/etc/ssl/certs/dogtag-ldap-ca.pem"   # triggers STARTTLS

# Dogtag provider: multiple servers for failover (GSSAPI)
[profiles.providers.dogtag_ha]
type     = "dogtag"
profiles = ["caServerCert"]

[profiles.providers.dogtag_ha.ldap]
uris    = ["ldap://dogtag1.example.com:389", "ldap://dogtag2.example.com:389"]
base_dn = "dc=example,dc=com"
gssapi  = true

# IPA provider: filesystem fallback
[profiles.providers.ipa_prod]
type        = "ipa"
profile_dir = "/etc/pki/pki-tomcat/ca/profiles/ca"
profiles    = ["caIPAserviceCert"]

# IPA provider: SRV-based discovery with GSSAPI
[profiles.providers.ipa_ldap]
type     = "ipa"
profiles = ["caIPAserviceCert"]

[profiles.providers.ipa_ldap.ldap]
srv_domain = "example.com"   # resolves _ldap._tcp.example.com SRV records
base_dn    = "o=ipaca"
gssapi     = true

[ldap] sub-table fields (applies to both dogtag and ipa providers)

Server selection — at least one of the following is required

Explicit servers (uri / uris) are always tried before SRV-discovered servers. An error is returned at startup if none of the three keys is set.

Search parameters — required

Authentication — choose one method

TLS

Additional builtin profile fields

Beyond the core extension fields, each builtin profile supports four groups of optional settings:

Multi-CA restriction

Certificate format

Per-profile authorization

tkauth-01 JWKS trust

The http+unix:// form allows co-located Token Authorities (for example, an Ekishib IdP on the same host) to be reached without a network port. Encode the socket path with / as %2F:

[profiles.providers.local.profiles.kerberos-svc]
description     = "Kerberos service certificate"
ca_ids          = ["kerberos-ca"]
trust_jwks_urls = [
    "https://idp.example.com/jwks",
    "http+unix://%2Frun%2Fekishib%2Fekishib.sock/jwks",
]

JWKS responses are cached in memory for 5 minutes and refreshed independently per URL.

See Certificate Profiles for detailed descriptions with examples.

[admin]

The [admin] section enables the server-side Admin API. Admin endpoints (/admin/*) are served on the same listener as the main ACME API — there is no separate admin listener. When this section is absent, all admin endpoints return 404. This is the default; no admin access is possible without explicit configuration.

Operator authentication uses one or both of:

• mTLS client certificates — configure [tls.client_auth] with required = false and the operator CA(s); the connecting client presents a certificate signed by one of those CAs.
• GSSAPI/Kerberos — configure [admin.gssapi]; clients authenticate via a Kerberos service ticket without requiring a client certificate.

At least one of [tls.client_auth] or [admin.gssapi] must be configured; the server exits at startup if neither is set.

# mTLS client authentication — operator CA(s) accepted for /admin/* requests.
[tls.client_auth]
ca_certs = ["/etc/akamu/operator-ca.pem"]
required = false   # allow GSSAPI-only clients that carry no cert

[admin]
session_ttl_secs = 3600

# Bootstrap operator (mTLS) — generated and registered on first run when operators table is empty.
# bootstrap_operator_cert_file = "/etc/akamu/admin-bootstrap.pem"
# bootstrap_operator_key_file  = "/etc/akamu/admin-bootstrap-key.pem"

# Bootstrap operator (GSSAPI) — mutually exclusive with cert bootstrap above.
# When operators table is empty at startup, registers this principal as Administrator.
# bootstrap_operator_gssapi_principal = "admin@EXAMPLE.COM"

# Optional: also accept GSSAPI-authenticated operators
[admin.gssapi]
keytab_file  = "/etc/akamu/http.keytab"   # omit and set gssproxy = true to use gssproxy instead
service_name = "HTTP"

bootstrap_key_type

Optional. Default: "ec:P-256".

Key algorithm used when auto-generating the bootstrap operator certificate. Same syntax as ca.key_type.

bootstrap_key_type = "ec:P-256"

bootstrap_operator_cert_file

Optional.

Path where the bootstrap Administrator operator’s client certificate will be written on first run. When this file (and bootstrap_operator_key_file) are absent and the operators table is empty, Akāmu generates a client certificate signed by the Akāmu CA and registers the operator automatically. Both fields must be set together.

bootstrap_operator_cert_file = "/etc/akamu/admin-bootstrap.pem"

bootstrap_operator_key_file

Optional.

Path where the bootstrap Administrator operator’s client private key will be written on first run. Must be set alongside bootstrap_operator_cert_file.

bootstrap_operator_key_file = "/etc/akamu/admin-bootstrap-key.pem"

bootstrap_operator_name

Optional. Default: "admin".

Name recorded in the operators table for the auto-provisioned bootstrap administrator.

bootstrap_operator_name = "admin"

bootstrap_operator_gssapi_principal

Optional. Default: unset.

Kerberos principal for the GSSAPI bootstrap Administrator operator (e.g. "admin@REALM"). When set and the operators table is empty at startup, Akāmu inserts an Administrator row with this principal so that the first akamuctl login --gssapi succeeds without a prior akamuctl operator add. Mutually exclusive with bootstrap_operator_cert_file / bootstrap_operator_key_file.

bootstrap_operator_gssapi_principal = "admin@EXAMPLE.COM"

auth_rate_limit

Optional. Default: 20.

Maximum credential presentations (Bearer session token, mTLS client certificate, or GSSAPI token) accepted from a single source IP in a rolling 5-minute window before that source receives 429 Too Many Requests. This limits audit-event floods that could otherwise trigger the audit_alarm_action or, when audit_overflow = "halt", refuse all new requests.

auth_rate_limit = 20

session_ttl_secs

Optional. Default: 3600 (1 hour).

Inactive session expiry in seconds. Operator sessions that have had no activity for this duration are invalidated and require re-authentication.

session_ttl_secs = 3600

session_lock_secs

Optional. Default: 900 (15 minutes).

Inactivity threshold before a session enters locked state (FTA_SSL_EXT.1). After this many idle seconds, requests that present the session token receive 423 Locked instead of 401 Unauthorized. The session is not destroyed; the operator must re-authenticate to obtain a fresh token. This value must be less than session_ttl_secs.

session_lock_secs = 900

max_failed_auth

Optional. Default: 5.

Maximum number of failed authentication attempts allowed for an operator before the account is locked (FIA_AFL.1). Once the threshold is exceeded, further authentication attempts return 423 Locked until an administrator calls POST /admin/operators/{id}/unlock (or uses akamuctl operator unlock).

max_failed_auth = 5

lockout_duration_secs

Optional. Default: 1800 (30 minutes).

How long in seconds the operator account remains locked after exceeding max_failed_auth (FIA_AFL.1). After this duration the lock is automatically cleared; an administrator may also clear it early with operator unlock.

lockout_duration_secs = 1800

audit_max_events

Optional. Default: absent (unlimited). Backward-compatible alias: audit_max_rows.

Maximum number of audit events since startup before the audit_overflow policy triggers. Audit events are written to the configured audit backend (systemd journal namespace, JSONL file, or in-process store), not to the database. The counter is in-memory and resets on restart. The audit backend manages its own disk retention independently (see contrib/systemd/journald@akamu.conf for journald, or external logrotate(8) for the file backend).

Negative values are treated as unlimited (with a startup warning). Zero is also treated as unlimited.

audit_max_events = 500000

audit_overflow

Optional. Default: "drop_oldest".

Policy applied when audit_max_events is reached. Accepted values:

audit_overflow = "drop_oldest"

audit_alarm_threshold

Optional. Default: 10.

Number of SecurityViolation audit events in a rolling 5-minute window that triggers the alarm response configured by audit_alarm_action.

audit_alarm_threshold = 10

audit_alarm_action

Optional. Default: "syslog".

Action taken when the audit_alarm_threshold is exceeded. Accepted values:

audit_alarm_action = "syslog"

[admin.gssapi]

Optional. When absent, GSSAPI authentication for the admin interface is disabled.

Configures GSSAPI/Kerberos authentication for operators accessing the admin API. When set, operators can authenticate by presenting a Kerberos service ticket without requiring a client certificate.

keytab_file

Required when gssproxy = false (the default). Must be absent when gssproxy = true. Path to the Kerberos keytab file for the admin service principal. The akamu process must be able to read this file; no other user should have read access to it. Setting both keytab_file and gssproxy = true is a configuration error; the server exits at startup.

keytab_file = "/etc/akamu/http.keytab"

gssproxy

Optional. Default: false.

When true, GSSAPI credential acquisition for the admin service principal is delegated to the gssproxy daemon. The akamu process must have a matching entry in /etc/gssproxy/conf.d/. The server sets GSS_USE_PROXY=yes in its environment before the first GSSAPI call. No direct access to a keytab file on disk is needed. keytab_file must be absent when this is true.

# gssproxy mode for the admin interface
[admin.gssapi]
gssproxy     = true
service_name = "HTTP"

service_name

Optional. Default: "HTTP".

Host-based service name. MIT Kerberos appends @<local-hostname> when no realm is specified.

service_name = "HTTP"

Admin endpoints and RBAC roles:

See Admin API and Operator Management for the full request/response format of each endpoint.

Account Management

ACME accounts are persistent identities that tie a public key to one or more email addresses. Every order, authorization, and certificate is associated with an account.

Account lifecycle

stateDiagram-v2
    direction LR
    [*] --> valid : create account<br/>POST /acme/new-account
    valid --> deactivated : POST status=deactivated
    deactivated --> [*]

Accounts start in valid status. A valid account can:

• Create new orders.
• Manage existing orders and authorizations.
• Download certificates.
• Revoke certificates it owns.
• Update its contact list.
• Rotate its key.
• Deactivate itself.

A deactivated account is permanently disabled. All subsequent requests using a deactivated account’s key are rejected.

Creating an account

Send a POST request to /acme/new-account with a JWS signed by the account’s public key in jwk form. The payload must contain:

Contact values must be URIs (containing :). The server does not restrict schemes — mailto:, tel:, and other URI schemes are accepted. Reachability is not verified.

Example payload:

{
  "contact": ["mailto:admin@example.com"],
  "onlyReturnExisting": false
}

Response on creation (201 Created):

{
  "status": "valid",
  "contact": ["mailto:admin@example.com"],
  "orders": "https://acme.example.com/acme/orders/<account-id>"
}

The Location header contains the account URL: https://acme.example.com/acme/account/<account-id>.

If an account already exists for the submitted key and onlyReturnExisting is false, the server returns the existing account with HTTP 200 rather than creating a duplicate.

Reading account details

POST to the account URL (/acme/account/<id>) with an empty payload (POST-as-GET). The kid header must reference the account being queried, and it must match the account ID in the URL.

Updating contact information

POST to /acme/account/<id> with a payload containing the new contact array:

{
  "contact": ["mailto:new-admin@example.com"]
}

Contact addresses are replaced entirely; partial updates are not supported.

Deactivating an account

POST to /acme/account/<id> with:

{
  "status": "deactivated"
}

The account is immediately marked deactivated. This action is irreversible.

Key rollover

To replace an account’s signing key without losing the account:

1. Construct an outer JWS signed with the old key addressed to /acme/key-change.
2. Embed an inner JWS signed with the new key as the payload. The inner JWS payload must contain { "account": "<account-url>" }.

POST /acme/key-change
Content-Type: application/jose+json

{
  "protected": "<outer-header-signed-with-old-key>",
  "payload": "<inner-jws-signed-with-new-key>",
  "signature": "<outer-signature>"
}

sequenceDiagram
    participant C as ACME Client
    participant S as Akāmu Server

    Note over C: Currently holds old private key
    C->>C: Generate new key pair
    C->>C: Build inner JWS signed by NEW key
    Note right of C: payload = {"account": "https://…/acme/account/ID"}
    C->>C: Wrap in outer JWS signed by OLD key
    Note right of C: url = /acme/key-change, kid = account URL

    C->>S: POST /acme/key-change
    S->>S: Verify outer JWS signature (old key from DB)
    S->>S: Verify inner JWS signature (new key from inner jwk)
    S->>S: Check inner payload account == outer kid account URL
    S->>S: Check new key not registered to another account
    S->>S: Replace stored account key
    S-->>C: 200 OK (account object)

    Note over C: All future requests must be signed with the new key

The server verifies:

• The outer JWS is signed by the current account key.
• The inner JWS is signed by the new key (jwk must be present in the inner header).
• The inner payload’s account field matches the account URL derived from the outer kid.
• The new key is not already registered to another account.

On success, the account’s stored key and thumbprint are replaced with the new key. Subsequent requests must be signed with the new key.

Profile grants

Accounts may have a profile_grants attribute that restricts which certificate profiles they are allowed to request. When a profile is configured with require_account_grant = true, the account’s profile_grants must include that profile’s name or the finalization request is denied.

An account with no grants (the default) can only request profiles that do not require a grant.

Viewing and modifying grants

Grants are managed through the Admin API (requires [admin] to be configured in config.toml):

GET    /admin/account/{id}/profile-grants   → {"profile_grants": ["p1"]}
PUT    /admin/account/{id}/profile-grants   ← {"profile_grants": ["p1", "p2"]}
DELETE /admin/account/{id}/profile-grants

All admin endpoints require Authorization: Bearer <token>.

EAB grant inheritance

When an EAB key is provisioned with profile_grants via POST /admin/eab, any account created using that EAB key automatically inherits those grants at account creation time. The transfer is atomic — the same database transaction that inserts the new account and marks the EAB key as used also sets the profile_grants on the account row.

POST /admin/eab
{"kid":"key-1","hmac_key_b64u":"<base64url>","profile_grants":["internal"]}

After an account is created using key-1, it will have profile_grants = ["internal"] without any additional admin action.

Delegation URL

When server.delegation_enabled = true, the account object includes an additional "delegations" URL:

{
  "status": "valid",
  "contact": ["mailto:admin@example.com"],
  "orders": "https://acme.example.com/acme/orders/<account-id>",
  "delegations": "https://acme.example.com/acme/delegations/<account-id>"
}

POST-as-GET to the delegations URL returns the list of delegation objects available for that account. NDC clients use this URL to discover which CSR templates they are authorized to use. See Orders — Delegation orders and the RFC 9115 configuration reference for the full workflow.

Security considerations

• Each account is identified by the SHA-256 thumbprint of its JWK public key. The server uses this thumbprint to look up accounts without needing to parse or compare full public key material on every request.
• Key rollover is the only mechanism to change the signing key. There is no password or other credential; possession of the private key is the sole proof of identity.
• Contact URIs are not validated for reachability. The server accepts any URI containing : (e.g. mailto:, tel:); it does not restrict the scheme or verify that the address is reachable.

Orders

An ACME order is the top-level object that represents a request to obtain a certificate. It contains:

• The list of identifiers (domain names or IP addresses) to be included in the certificate.
• A set of authorizations — one per identifier — that must be completed before the certificate can be issued.
• A finalize URL where the ACME client submits a CSR once all authorizations are valid.
• An expires timestamp after which the order can no longer be finalized.

Order lifecycle

stateDiagram-v2
    direction LR
    [*] --> pending : new-order
    pending --> ready : all authorizations valid
    pending --> invalid : any authorization fails
    ready --> processing : finalize (submit CSR)
    processing --> valid : certificate issued
    processing --> invalid : CSR validation failed
    valid --> [*]
    invalid --> [*]

Creating an order

POST to /acme/new-order with a JWS signed by the account key. The payload:

{
  "identifiers": [
    { "type": "dns", "value": "example.com" },
    { "type": "dns", "value": "www.example.com" }
  ]
}

Supported identifier types:

Wildcard identifiers (*.example.com) are accepted as dns type identifiers. Only dns-01 (and dns-persist-01, when configured) can authorize wildcard identifiers. Attempting to validate a wildcard with http-01 or tls-alpn-01 will fail.

dns-persist-01 (draft-ietf-acme-dns-persist) is offered alongside the standard DNS challenges when the server operator has configured at least one entry in server.dns_persist_issuer_domains. If that list is empty the challenge type is not offered.

.onion identifiers (RFC 9799) are submitted as type: "dns" with a v3 .onion value (a 56-character base32 label followed by .onion, e.g. bbcweb3hytmzhn5d532owbu6oqadra5z3ar726vq5kgwwn6aucdccrad.onion). Only v3 addresses are accepted; v2 (16-character label) addresses are rejected. The server always offers onion-csr-01 for these identifiers. When server.tor_connectivity_enabled = true, it also offers http-01 and tls-alpn-01 (for CAs with Tor network connectivity). dns-01 and dns-persist-01 are never offered for .onion identifiers.

Response (201 Created):

{
  "status": "pending",
  "expires": "2026-04-11T12:00:00Z",
  "identifiers": [
    { "type": "dns", "value": "example.com" },
    { "type": "dns", "value": "www.example.com" }
  ],
  "authorizations": [
    "https://acme.example.com/acme/authz/<authz-id-1>",
    "https://acme.example.com/acme/authz/<authz-id-2>"
  ],
  "finalize": "https://acme.example.com/acme/order/<order-id>/finalize"
}

The Location header contains the order URL.

Reading an order

POST to /acme/order/<id> with an empty payload (POST-as-GET). The response contains the current state of the order, including the certificate URL once the order is in valid status.

Completing authorizations

For each authorization URL in the order’s authorizations array, the client must complete one challenge. See the Challenges chapter for details.

For onion-csr-01 (RFC 9799), the challenge response payload must carry the validation CSR rather than being empty. The client POSTs:

{ "csr": "<base64url-encoded DER PKCS#10 CSR>" }

The CSR must contain:

• The .onion domain in a SubjectAlternativeName dNSName entry.
• The cabf-onion-csr-nonce extension (OID 2.23.140.41) whose value is the key authorization string (token.thumbprint).
• A self-signature by the CSR key.
• An Ed25519 signature by the hidden-service key whose public key is encoded in the .onion address (the outer CSR signature, or the CSR key itself when it is the hidden-service key).

Finalizing an order

Once all authorizations are in valid status (order status becomes ready), POST a CSR to the finalize URL:

{
  "csr": "<base64url-encoded-DER-CSR>"
}

The CSR must:

• Be a valid PKCS#10 DER structure.
• Have a valid self-signature.
• Contain a SubjectAlternativeName extension listing exactly the identifiers from the order (no more, no fewer).
• Not assert cA=TRUE in BasicConstraints.

The server validates the CSR and immediately issues the certificate. On success, the order status changes to valid and the response includes the certificate field:

{
  "status": "valid",
  "certificate": "https://acme.example.com/acme/cert/<cert-id>",
  ...
}

Order expiry

Orders expire after order_expiry_secs seconds (default 86400, one day). An expired order cannot be finalized. A new order must be created.

Error handling

If a challenge fails, the corresponding authorization transitions to invalid. The server also marks the order invalid and records the error on the order object:

{
  "status": "invalid",
  "error": {
    "type": "urn:ietf:params:acme:error:connection",
    "detail": "connection error during challenge: TCP connect to example.com:80: ..."
  }
}

Create a new order and begin the authorization process again.

Delegation orders (RFC 9115)

When the server has delegation_enabled = true, ACME clients can place a delegation order by including a "delegation" field in the new-order payload. The value is the URL of a delegation object previously created by the IdO via the Admin API.

{
  "identifiers": [
    { "type": "dns", "value": "cdn.example.com" }
  ],
  "delegation": "https://acme.example.com/acme/delegation/b1c2d3e4-…",
  "allow-certificate-get": true
}

Delegation order behaviour differences from regular orders:

The NDC (delegate client) discovers the delegation URL by fetching the IdO’s account object and following the "delegations" URL, then POST-as-GETting POST /acme/delegations/{account_id} to list available delegation objects.

Response on creation (201 Created) for a delegation order:

{
  "status": "ready",
  "identifiers": [
    { "type": "dns", "value": "cdn.example.com" }
  ],
  "authorizations": [],
  "finalize": "https://acme.example.com/acme/order/<order-id>/finalize"
}

The NDC may immediately proceed to finalize the order with a CSR. The CSR is validated against the delegation’s stored CSR template before issuance proceeds.

Challenges

A challenge is the mechanism by which Akāmu verifies that an ACME client controls the identifier (domain name, IP address, email address, or telephone-number authority) in an authorization. The server supports seven challenge types: http-01, dns-01, tls-alpn-01, dns-persist-01, onion-csr-01, email-reply-00, and tkauth-01.

For each identifier in an order, the server creates one challenge of each supported type. The client chooses which challenge type to complete.

dns-persist-01 is an opt-in type that requires explicit server configuration. When it is not configured, clients see the standard three types and are not affected. See dns-persist-01 below for the full description.

onion-csr-01 is offered exclusively for .onion identifiers (Tor hidden services) and uses a CSR-based proof-of-control mechanism rather than a network probe. See onion-csr-01 below for the full description.

email-reply-00 is offered exclusively for email identifiers (RFC 8823 S/MIME) and uses a two-channel token delivered by email. It requires explicit server configuration. See email-reply-00 below for the full description.

tkauth-01 is offered exclusively for TNAuthList and JWTClaimConstraints identifiers (RFC 9447/9448). The client obtains a signed JWT from an external Token Authority and submits it in the challenge response. It requires explicit server configuration. See tkauth-01 below for the full description.

Key authorization

Before responding to any challenge, compute the key authorization string:

key_authorization = token + "." + base64url(SHA-256(JWK-thumbprint-of-account-key))

Where:

• token is the challenge token provided by the server in the authorization object.
• The SHA-256 is computed over the JWK thumbprint string (itself a base64url-encoded SHA-256 of the canonical JSON of the account public key).
• base64url uses the URL-safe alphabet without padding characters.

In practice, ACME client libraries compute this for you.

dns-persist-01 does not use this formula. Instead of a token, the client receives an issuer-domain-names array, and the server matches the account URI directly against the TXT record. See dns-persist-01 below for details.

onion-csr-01 uses the standard token.thumbprint key authorization formula. The server also includes an authKey field in the challenge object containing the JWK thumbprint so the client can construct the key authorization without a separate lookup.

Responding to a challenge

To signal that the client has provisioned the challenge response, POST to the challenge URL with an empty JSON object payload:

{}

onion-csr-01 is an exception: the POST body must include the DER-encoded CSR (see onion-csr-01 for the payload format).

The server immediately marks the challenge as processing and spawns a background task to validate it. The response returns the current challenge status:

{
  "type": "http-01",
  "url": "https://acme.example.com/acme/chall/<authz-id>/http-01",
  "status": "processing",
  "token": "<token>"
}

Poll the authorization URL (POST-as-GET) to check when validation completes.

Challenge status transitions

stateDiagram-v2
    direction LR
    [*] --> pending : authorization created
    pending --> processing : client POSTs {} to challenge URL
    processing --> valid : server probe succeeds
    processing --> invalid : server probe fails
    valid --> [*]
    invalid --> [*]

A challenge that is already processing or valid is returned as-is if the client POSTs to it again.

Challenge types at a glance

flowchart TD
    A([Authorization created]) --> B{"Choose one<br/>challenge type"}

    B -->|http-01| C["Serve key auth at<br/>/.well-known/acme-challenge/TOKEN<br/>on port 80"]
    B -->|dns-01| D["Add DNS TXT record<br/>_acme-challenge.DOMAIN<br/>= base64url(SHA-256(key_auth))"]
    B -->|tls-alpn-01| E["Configure TLS on port 443<br/>ALPN: acme-tls/1<br/>Cert with id-pe-acmeIdentifier ext<br/>= SHA-256(key_auth)"]
    B -->|dns-persist-01| F["Persistent DNS TXT record<br/>_validation-persist.DOMAIN<br/>with issuer + accounturi + policy fields"]
    B -->|onion-csr-01| G2["Build DER CSR with<br/>cabf-onion-csr-nonce ext (OID 2.23.140.41)<br/>= key_auth (UTF8String)<br/>Sign with hidden-service Ed25519 key"]

    C & D & E & F --> G["POST {} to challenge URL"]
    G2 --> G2P["POST {csr: base64url-DER} to challenge URL"]
    G & G2P --> H["Server validates in background"]

    H -->|probe succeeds| I(["Authorization → valid<br/>Order → ready when all valid"])
    H -->|probe fails| J(["Authorization → invalid<br/>Order → invalid<br/>Create new order to retry"])

    classDef ok   fill:#f0fdf4,stroke:#16a34a,color:#0f172a
    classDef fail fill:#fef2f2,stroke:#dc2626,color:#0f172a
    class I ok
    class J fail

http-01

The server makes an HTTP/1.1 GET request to:

http://<domain>/.well-known/acme-challenge/<token>

on port 80. The response body (trimmed of whitespace) must equal the key authorization string.

Provisioning

Create a file at the path /.well-known/acme-challenge/<token> on the web server for the domain being validated. The file content must be exactly the key authorization string.

Example:

If the token is abc123 and the key authorization is abc123.XYZ...:

File path:    /.well-known/acme-challenge/abc123
File content: abc123.XYZ...

For Apache or nginx, ensure that requests to /.well-known/acme-challenge/ are served from the document root without authentication and without redirects.

Constraints

• Port 80 must be reachable from the ACME server.
• The response body must be less than 1 MiB.
• HTTP 3xx redirects are followed (up to 10 hops), including redirects to HTTPS targets.
• IPv6 addresses are supported as ip type identifiers; the URL literal uses bracket notation (e.g., http://[2001:db8::1]/.well-known/acme-challenge/<token>).
• Wildcard identifiers (*.example.com) cannot be validated with http-01 (RFC 8555 §7.1.3).

dns-01

The server queries the DNS TXT record at:

_acme-challenge.<domain>

At least one TXT record value must equal:

base64url(SHA-256(key_authorization))

For example, if SHA-256(key_authorization) produces the bytes \xde\xad..., the expected TXT value is the base64url encoding of those 32 bytes.

Provisioning

Add a DNS TXT record:

Name:    _acme-challenge.example.com
Type:    TXT
TTL:     60
Content: <base64url-SHA256-of-key-authorization>

Concrete example:

1. Token: mytoken
2. JWK thumbprint: mythumbprint
3. Key authorization: mytoken.mythumbprint
4. SHA-256 of key auth (hex): e3b0c4... (varies; compute for your actual values)
5. base64url of SHA-256: 47DEQp... (varies)
6. TXT record value: 47DEQp...

Use openssl dgst -sha256 -binary <<< "mytoken.mythumbprint" | base64 -w0 | tr '+/' '-_' | tr -d '=' to compute it manually.

Wildcard domains

For a wildcard identifier *.example.com, the leading *. is stripped before constructing the DNS query. The TXT record must be placed at _acme-challenge.example.com, not _acme-challenge.*.example.com.

DNS propagation

The server uses the system default DNS resolver (or the address configured via server.dns_resolver_addr). If the TXT record has not propagated by the time the server queries, validation will fail. Use a short TTL (60 seconds or less) to speed up propagation.

tls-alpn-01

The server opens a TLS connection to port 443 of the domain being validated, advertising the ALPN protocol acme-tls/1. The applicant’s TLS server must respond with a certificate that:

1. Contains the domain as a dNSName in the SubjectAlternativeName extension.
2. Contains the id-pe-acmeIdentifier extension (OID 1.3.6.1.5.5.7.1.31) marked critical, with a value of OCTET STRING { SHA-256(key_authorization) }.

Provisioning

Set up a TLS virtual host that listens on port 443, responds only to ALPN negotiation for acme-tls/1, and presents a specially crafted certificate. Most ACME clients handle this automatically.

The certificate must:

• Be self-signed (the server does not verify the trust chain for this challenge type; it only checks the extensions).
• Have id-pe-acmeIdentifier as a critical extension.
• Have the SHA-256 hash of the key authorization (32 raw bytes) wrapped in an OCTET STRING as the extension value.

TLS version support

The validator accepts both TLS 1.2 and TLS 1.3 connections.

Constraints

• Port 443 must be reachable from the ACME server.
• Wildcard identifiers are not supported by tls-alpn-01 (RFC 8737 §3).
• IP address identifiers (ip type) are supported; the server connects to the IP address directly.
• RFC 8737 §3 requires exactly one SAN entry in the validation certificate. Certificates that contain more than one SAN are rejected.

dns-persist-01

dns-persist-01 is a DNS-based challenge type that differs from dns-01 in one important way: the TXT record is persistent. It does not change from one certificate renewal to the next. Once an operator provisions the record, it remains valid for every subsequent renewal by the same ACME account — no per-renewal DNS changes are required.

The challenge type is defined by the IETF draft draft-ietf-acme-dns-persist. It is available only for dns type identifiers; IP address identifiers are not supported.

This type is opt-in: it is offered to clients only when server.dns_persist_issuer_domains is set in config.toml. When that field is absent, only the standard three types are advertised and existing clients are unaffected.

How it works

When dns-persist-01 is offered, the client does not receive a token field. Instead it receives an issuer-domain-names array:

{
  "type": "dns-persist-01",
  "url": "https://acme.example.com/acme/chall/<authz-id>/dns-persist-01",
  "status": "pending",
  "issuer-domain-names": ["acme.example.com"]
}

The ACME client must ensure that a TXT record exists at _validation-persist.<domain> before signalling the challenge. The server queries that name and evaluates each TXT record value against a set of rules.

TXT record format

_validation-persist.<domain>. IN TXT "<issuer-domain>; accounturi=<account-uri>[; policy=wildcard][; persistUntil=<ISO8601Z>]"

Fields are separated by semicolons. Field order is not significant except that the issuer domain must appear first.

Concrete example for account https://acme.example.com/acme/account/42 validating example.com through a CA with issuer domain acme.example.com:

_validation-persist.example.com. 300 IN TXT "acme.example.com; accounturi=https://acme.example.com/acme/account/42"

For a wildcard certificate (*.example.com), add policy=wildcard:

_validation-persist.example.com. 300 IN TXT "acme.example.com; accounturi=https://acme.example.com/acme/account/42; policy=wildcard"

A single TXT record containing policy=wildcard also satisfies non-wildcard orders for the same domain.

What the server checks

The server performs a TXT lookup at _validation-persist.<base-domain> (the *. prefix is stripped for wildcard orders). It accepts the challenge as soon as one record satisfies all of:

1. The first ;-delimited token equals the CA’s issuer domain (case-insensitive, trailing dot stripped).
2. accounturi=<uri> matches the requesting account’s full URI.
3. For wildcard orders, policy=wildcard is present.
4. If persistUntil=<timestamp> is present, the timestamp is at or after the current time.

Unknown key-value tokens are silently ignored, allowing forward-compatible extensions.

Key authorization

Unlike the other challenge types, dns-persist-01 does not use a token · thumbprint key authorization. The server stores the account URI in the key_auth database column instead, and matches it directly against the accounturi= field in the TXT record.

Wildcard certificates

To validate *.example.com, the TXT record must include policy=wildcard. The query name is always _validation-persist.example.com — the *. prefix is stripped before the DNS lookup.

persistUntil expiry

The optional persistUntil field lets an operator set an explicit expiry on the authorization grant, independently of the DNS TTL. Format: YYYY-MM-DDTHH:MM:SSZ (literal Z; lowercase z also accepted).

• Timestamp at or after current time → field is valid; evaluation continues.
• Timestamp before current time → record rejected, even if all other fields match.
• Timestamp unparseable → record rejected.

Records without persistUntil never expire through this mechanism; their lifetime is determined by DNS TTL and operator action.

Configuration

All fields belong to the [server] section of config.toml.

dns_persist_issuer_domains

Optional. Default: absent (dns-persist-01 disabled).

The issuer domain(s) placed in issuer-domain-names challenge objects and matched against the first token of TXT records. When set, dns-persist-01 is offered alongside the standard types for all dns identifiers.

Accepts either a single string or an array of strings. Multi-tenant or multi-identity deployments can list all accepted issuer domains; validation succeeds when any configured domain matches.

[server]
# Single domain
dns_persist_issuer_domains = "acme.example.com"

# Multiple domains
dns_persist_issuer_domains = ["acme.example.com", "acme.example.org"]

dns_resolver_addr

Optional. Default: absent (system resolver).

DNS resolver override for dns-01, dns-persist-01, and CAA validation. Format: "<ip>:<port>". The http-01 and tls-alpn-01 validators are not affected.

[server]
dns_resolver_addr = "127.0.0.1:5353"

Useful for split-horizon DNS (where the ACME server cannot reach the public resolver) and for integration tests against a local stub server.

dns_persist01_resolver_addr

Optional. Default: absent (falls back to dns_resolver_addr).

Resolver override used exclusively for dns-persist-01 validation. When set, this address is used instead of dns_resolver_addr for TXT lookups at _validation-persist.*. Useful when persistent TXT records are served by a different DNS infrastructure than the one used for dns-01 and CAA lookups.

[server]
dns_resolver_addr        = "127.0.0.1:5353"   # used for dns-01 and CAA
dns_persist01_resolver_addr = "127.0.0.1:5354" # used only for dns-persist-01

dns_dot_server_name

Optional. Default: absent (plain UDP).

TLS server name (SNI hostname) for DNS-over-TLS (DoT, RFC 7858). When set, all DNS challenge validation queries — dns-01, dns-persist-01, and CAA record lookups — are sent over TLS instead of plain UDP. dns_resolver_addr must be set to the DoT server’s IP address and port 853.

Use DoT when the path between the Akāmu server and its resolver is untrusted (e.g. a public resolver reached over the open Internet, an ISP that intercepts cleartext DNS queries, or a network with strict privacy requirements). The TLS certificate presented by the resolver is verified against the system root CA store. LDAP SRV lookups for certificate profile providers are unaffected.

DoT and DNSSEC validation (validate_dnssec = true) are independent and can be used together: DoT protects the transport channel while DNSSEC authenticates the response data.

[server]
# DoT only
dns_resolver_addr   = "1.1.1.1:853"
dns_dot_server_name = "cloudflare-dns.com"

# DoT + DNSSEC
dns_resolver_addr   = "1.1.1.1:853"
dns_dot_server_name = "cloudflare-dns.com"
validate_dnssec     = true

Limitations

• No IP address identifier support. dns-persist-01 is defined only for DNS name identifiers; IP address identifiers are not supported (no TXT record format is specified in draft-ietf-acme-dns-persist for IP identifiers).

onion-csr-01 (RFC 9799)

onion-csr-01 validates control of a Tor v3 hidden service (.onion) identifier. Instead of making a network probe, the server verifies a PKCS #10 CSR that the client constructs and submits in the challenge response body. The challenge type is defined by RFC 9799.

This challenge is offered only for .onion DNS identifiers. It cannot be used for regular DNS names or IP address identifiers. The identifier in the ACME order must use "type": "dns" and the value must be a valid v3 .onion address (56-character base32 label + .onion). v2 .onion addresses (16-character label) are rejected.

Challenge object

When the authorization is created for a .onion identifier, the server includes an onion-csr-01 challenge object. Unlike other challenge types, it also carries an authKey field containing the account’s JWK thumbprint:

{
  "type": "onion-csr-01",
  "url": "https://acme.example.com/acme/chall/<authz-id>/onion-csr-01",
  "status": "pending",
  "token": "<token>",
  "authKey": "<jwk-thumbprint>"
}

The authKey field is provided as a convenience: the client needs the JWK thumbprint to compute the key authorization, and authKey exposes it directly so the client does not need to derive it from the account key a second time.

Key authorization

Compute the key authorization using the standard formula:

key_authorization = token + "." + authKey

Where authKey is the authKey field from the challenge object (equal to base64url(SHA-256(JWK-thumbprint-of-account-key))).

Client provisioning

The client must build a DER-encoded PKCS #10 CSR that satisfies all of the following:

1. Subject Alternative Name: contains the .onion domain as a dNSName.
2. cabf-onion-csr-nonce extension (OID 2.23.140.41): the extension value is a DER UTF8String (tag 0x0C) containing the key authorization string (token.thumbprint). This extension does not need to be marked critical.
3. Signature: the CSR must be signed by the hidden-service Ed25519 private key — the key whose public key is encoded in the v3 .onion address. The most common approach is to use the hidden-service key directly as the CSR key, producing a single self-signature that also proves hidden-service key control.

Example OID DER encoding for 2.23.140.41: 06 04 67 81 0C 29

Challenge response

POST to the challenge URL with the base64url-encoded DER CSR as the payload (this is the only challenge type where the POST body is not an empty {}):

{
  "csr": "<base64url-encoded DER CSR>"
}

The server decodes the csr field from base64url immediately and returns 400 Bad Request if the field is missing or the encoding is invalid.

Server validation

After the challenge is flipped to processing, the server performs these checks synchronously (no network probe is made):

1. Decode the 32-byte Ed25519 public key from the v3 .onion address label (56-character lowercase base32, version byte 0x03).
2. Parse the DER CSR structure.
3. Verify the CSR self-signature.
4. Locate the cabf-onion-csr-nonce extension (OID 2.23.140.41) and verify that its value decodes to the expected key authorization string.
5. Verify that the Ed25519 signature over the CertificationRequestInfo DER is valid under the hidden-service public key. This succeeds if the CSR signing key is the hidden-service key (self-signed CSR), or if the outer CSR signature verifies directly with the hidden-service key.
6. Verify that the CSR’s SAN extension contains the .onion domain as a dNSName.

Challenge types offered for .onion identifiers

RFC 9799 §4 requires that onion-csr-01 is always offered for .onion identifiers and that dns-01 is never offered. Whether http-01 and tls-alpn-01 are also offered depends on the server.tor_connectivity_enabled configuration:

• tor_connectivity_enabled = false (default): only onion-csr-01 is offered. The server cannot reach .onion addresses, so HTTP and TLS probes would always fail.
• tor_connectivity_enabled = true: onion-csr-01, http-01, and tls-alpn-01 are all offered, giving the client a choice.

dns-persist-01 is never offered for .onion identifiers.

Constraints

• Only valid for dns type identifiers whose value ends in .onion.
• Only v3 .onion addresses (56-character base32 label) are accepted; v2 addresses are rejected at order/pre-authorization creation time.
• dns-01 and dns-persist-01 are never offered for .onion identifiers.
• Wildcard .onion identifiers (*.xxx...xxx.onion) are not supported.

Configuration

No additional server configuration is required to enable onion-csr-01; it is always offered when an order or pre-authorization contains a .onion identifier. To additionally offer http-01 and tls-alpn-01 for .onion identifiers (requires Tor network access from the server), set:

[server]
tor_connectivity_enabled = true

Challenge failure

If validation fails, the challenge transitions to invalid and an error is recorded:

{
  "type": "http-01",
  "status": "invalid",
  "token": "<token>",
  "error": {
    "type": "urn:ietf:params:acme:error:connection",
    "detail": "connection error during challenge: TCP connect to example.com:80: connection refused"
  }
}

Common error types:

For onion-csr-01, the server also returns an immediate 400 Bad Request (before the background validation task starts) if the POST body is not valid JSON with a csr field, or if the csr value is not valid base64url.

A failed authorization invalidates the parent order. Create a new order to try again.

email-reply-00 (RFC 8823)

email-reply-00 is defined by RFC 8823. It is the only challenge type offered for email identifier orders and proves email address control via a DKIM-authenticated reply email. Issuing S/MIME certificates using this challenge requires the [email_challenge] configuration section — see email_challenge configuration.

Protocol

1. The client creates an order with {"type": "email", "value": "user@example.com"}.

2. The server returns an authorization with an email-reply-00 challenge object:

   {
     "type": "email-reply-00",
     "url": "https://acme.example.com/acme/chall/<id>",
     "status": "pending",
     "token": "<base64url(token-part2)>",
     "from": "acme-validation@example.com"
   }
   

   from is the address the server will send the challenge email from. token is token-part2 (server-generated, ≥128 bits of random data).

3. The client POSTs {} to the challenge URL to trigger the challenge. The server:

   • Generates token-part1 (≥128 bits of random data) and a Message-ID.
   • Stores both in the database.
   • Invokes the configured send_script to send an email to the identifier address with subject ACME: <base64url(token-part1)> and the generated Message-ID.

4. The client reads the email, extracts token-part1 from the Subject header, then computes:

   full_token  = base64url(token-part1) || base64url(token-part2)
   key_auth    = full_token || "." || base64url(SHA-256(canonical-JWK))
   response    = base64url(SHA-256(key_auth))
   

5. The client sends a reply email (preserving In-Reply-To and DKIM signing) with body:

   -----BEGIN ACME RESPONSE-----
   <response>
   -----END ACME RESPONSE-----
   

6. Mail routing infrastructure (a filter script, procmail rule, or email service webhook) POSTs the reply to POST /acme/email-webhook. See Webhook endpoint below.

7. The server verifies the DKIM domain, extracts and verifies the response digest, and marks the challenge and authorization valid.

8. The client finalizes with a CSR containing an rfc822Name SAN matching the email address and the emailProtection EKU.

Key authorization formula

email-reply-00 uses a modified key authorization:

full_token = base64url(token-part1) || base64url(token-part2)
key_auth   = full_token || "." || base64url(SHA-256(canonical-JWK))
response   = base64url(SHA-256(key_auth as UTF-8 bytes))

Where base64url(SHA-256(canonical-JWK)) is the JWK thumbprint of the account key per RFC 7638 — the same value used as thumbprint in the standard key authorization formula. Do not hash the thumbprint string itself; hash the canonical JWK JSON.

This is different from the standard token.thumbprint formula used by http-01/dns-01/tls-alpn-01. The response value (not key_auth) is what the client sends in the reply body.

CSR requirements

The CSR submitted at finalize time must:

• Contain an rfc822Name Subject Alternative Name matching the email identifier value (case-insensitive).
• Use the emailProtection Extended Key Usage (OID 1.3.6.1.5.5.7.3.4).
• Not contain any DNS/IP SANs that were not authorized by a separate authorization.

The certificate profile should be configured to enforce email_protection EKU. See the S/MIME profile example in the profiles documentation.

Webhook endpoint

POST /acme/email-webhook receives the client’s reply from any mail routing tool that can POST JSON:

{
  "from":        "user@example.com",
  "in_reply_to": "<uuid@acme-server.example.com>",
  "dkim_domain": "example.com",
  "dkim_status": "pass",
  "body":        "-----BEGIN ACME RESPONSE-----\nABC123==\n-----END ACME RESPONSE-----"
}

DKIM trust model: The server does not perform DKIM verification itself. DKIM verification is the responsibility of the webhook caller (the mail routing script or MTA filter). The server enforces two properties on every request:

1. dkim_domain must match the domain part of from (case-insensitively). This prevents a malicious script from claiming DKIM pass for a different domain.
2. dkim_status must equal "pass" (case-insensitively; some MTAs report "Pass" or "PASS").

If your MTA or mail service provides DKIM results in a format other than "pass", normalize it in your routing script before POSTing to the webhook.

HMAC authentication: Every POST must include the header:

X-Akamu-Signature: sha256=<lowercase-hex(HMAC-SHA256(raw-body, webhook_hmac_secret))>

The webhook_hmac_secret is configured in [email_challenge]. Requests with a missing, malformed, or incorrect signature are rejected with 403 Forbidden. All other responses are 200 OK regardless of the challenge outcome (to prevent webhook callers from retrying indefinitely on validation failures).

Example send script

The server invokes the configured send_script with these environment variables:

Exit code 0 = success. Non-zero = the challenge is marked invalid and the client must retry.

A minimal script using sendmail:

#!/bin/bash
set -euo pipefail
sendmail -f "$ACME_FROM" "$ACME_TO" <<EOF
From: $ACME_FROM
To: $ACME_TO
Subject: $ACME_SUBJECT
Message-ID: $ACME_MESSAGE_ID
Auto-Submitted: $ACME_AUTO_SUBMITTED
MIME-Version: 1.0
Content-Type: text/plain

This email was sent automatically as part of an ACME S/MIME certificate
issuance request. If you did not request a certificate, ignore this email.
EOF

The script is responsible for DKIM signing. The server does not sign outbound email.

tkauth-01 (RFC 9447 / RFC 9448)

tkauth-01 validates control of a TNAuthList or JWTClaimConstraints identifier by verifying a signed JWT authority token issued by an external Token Authority (TA). This challenge type is defined by RFC 9447; the TNAuthList profile is defined by RFC 9448.

Unlike network-based challenges, tkauth-01 relies on the TA asserting the client’s authority over the identifier out-of-band. The server only verifies the cryptographic integrity of the token and the atc claim binding.

Challenge object

When an order contains a TNAuthList or JWTClaimConstraints identifier, the authorization contains a tkauth-01 challenge object:

{
  "type": "tkauth-01",
  "url": "https://acme.example.com/acme/chall/<authz-id>/tkauth-01",
  "status": "pending",
  "tkauth-type": "atc",
  "token-authority": "https://ta.example.com"
}

Key authorization

tkauth-01 uses the standard key authorization formula: token.thumbprint where thumbprint is the base64url-encoded SHA-256 JWK thumbprint of the account key. The token field is not present in the challenge object; the thumbprint is used directly as the fingerprint check in the authority token’s atc claim.

The fingerprint field in the atc claim must be formatted as:

SHA256 XX:XX:XX:...

where XX:XX:XX:... is the colon-separated uppercase hex encoding of the raw SHA-256 JWK thumbprint bytes.

Identifier value format (JWTClaimConstraints)

For JWTClaimConstraints identifiers, the tkvalue in the atc claim and the ACME order identifier value must both be the base64url encoding of a DER-encoded JWTClaimConstraints structure as defined in RFC 8226 §3:

JWTClaimConstraints ::= SEQUENCE {
    mustInclude  [0] JWTClaimNames   OPTIONAL,
    permittedValues [1] JWTClaimValuesList OPTIONAL
}

The server validates both mustInclude (claim names that must be present in the JWT) and permittedValues (allowed values for specific claims). At least one of the two MUST be present.

Example: to require a specific Kerberos principal in the sub claim, encode:

JWTClaimConstraints {
    permittedValues [1]: [("sub", ["user@REALM"])]
}

The resulting DER bytes, base64url-encoded, become the identifier value.

Obtaining an authority token

The client contacts the Token Authority (identified by token-authority or by deployment convention) and requests an authority token for its identifier. The TA issues a compact JWT that must contain:

• Header: alg and one of:

  • x5c: inline certificate chain (array of base64-encoded DER certs); the leaf signs the JWT
  • x5u: URL from which the server fetches the signing certificate chain
  • kid: key identifier used to locate the signing public key in a JWKS endpoint

• Claims:

  • atc: an object with tktype (identifier type), tkvalue (identifier value, DER-encoded for JWTClaimConstraints), fingerprint (account key thumbprint in SHA256 XX:XX:... format), and optionally ca: false
  • jti: a unique token identifier (REQUIRED; enforces one-time use)
  • exp: expiry timestamp (REQUIRED)

Challenge response

POST to the challenge URL with the JWT in the tkauth field:

{
  "tkauth": "<compact-JWT>"
}

Example (header shown decoded):

{
  "alg": "ES256",
  "x5u": "https://ta.example.com/cert"
}

Validation steps

1. Decode the JWT header to determine the key resolution path:
   • x5c: parse the inline certificate chain directly
   • x5u: fetch the certificate chain from the URL (HTTPS only; SSRF guard applies)
   • kid: look up the signing public key from a JWKS endpoint (see JWKS trust below)
2. For x5c/x5u: validate the certificate chain against the configured trusted_ta_ca_files. For kid: the trust is established by the per-profile trust_jwks_urls list.
3. Verify the JWT signature using the resolved public key. The public key algorithm must match alg; supported algorithms include ES256/ES384/ES512 (ECDSA), RS256/RS384/RS512/PS256/PS384/PS512 (RSA), EdDSA (Ed25519), and ML-DSA-44/ML-DSA-65/ML-DSA-87.
4. Confirm exp has not elapsed and exp - now does not exceed max_validity_secs.
5. Check the atc claim: tktype matches the identifier type, tkvalue matches the identifier value, fingerprint matches the account key thumbprint.
6. For JWTClaimConstraints: parse the DER-encoded tkvalue and verify that the JWT’s own claims satisfy both mustInclude (all named claims are present) and permittedValues (each constrained claim’s value is in the allowed list).
7. Record the jti in the replay-prevention store; duplicate JTIs are rejected.

JWKS trust (kid-based tokens)

When the JWT header contains kid instead of x5c/x5u, the server looks up the signing public key from a JWKS endpoint. Trust is configured per profile:

[profiles.providers.local.profiles.my-profile]
description     = "Example profile"
ca_ids          = ["my-ca"]
trust_jwks_urls = [
    "https://idp.example.com/jwks",
    "http+unix://%2Frun%2Fekishib%2Fekishib.sock/jwks",
]

The trust_jwks_urls list is searched in order. The first JWKS that contains a key with a matching kid is used. If no profile has trust_jwks_urls set, kid-signed tokens are rejected.

JWKS responses are cached in memory for 5 minutes. Each URL is refreshed independently when the cache entry expires.

URL schemes:

The http+unix:// scheme is intended for co-located Token Authorities (e.g. Ekishib IdP running on the same host) where TLS is unnecessary.

Note: ML-DSA-44/ML-DSA-65/ML-DSA-87 keys are supported in JWKS entries (kty: "AKP"). This allows post-quantum Token Authorities to sign authority tokens without an X.509 certificate chain.

Certificate SAN injection (claim_encoders)

When the server issues a certificate for a JWTClaimConstraints identifier, it can inject Subject Alternative Names derived from the permittedValues of the validated token. This is controlled by the [[tkauth.claim_encoders]] configuration.

Each entry maps a JWT claim name to an encoder that knows how to produce an OtherName SAN:

[[tkauth.claim_encoders]]
claim   = "sub"
encoder = "krb5-kpn"   # Kerberos principal (id-pkinit-san OtherName, OID 1.3.6.1.5.2.2)

[[tkauth.claim_encoders]]
claim   = "upn"
encoder = "ms-upn"     # Microsoft UPN OtherName (OID 1.3.6.1.4.1.311.20.2.3)

[[tkauth.claim_encoders]]
claim   = "dns"
encoder = "dns-san"    # plain dNSName SAN; wildcards are rejected

Built-in encoders:

A permittedValues entry with exactly one value is injected as a SAN using the matching encoder. Entries with multiple permitted values are skipped (the server cannot determine which specific value the TA attested).

For dns-san, the DNS name from the token constraint is added alongside any DNS SANs already in the CSR. The ACME client must still include the name in its CSR — the encoder only grants permission to inject it from the token, it does not bypass the CSR.

Configuration

[tkauth]
enabled                 = true
trusted_ta_ca_files     = ["/etc/akamu/ta-root.pem"]
token_authority_url     = "https://ta.example.com"   # optional hint surfaced in challenge object
max_validity_secs       = 3600   # reject tokens with exp - now > this value
jti_prune_interval_secs = 3600   # how often to purge expired JTI records from the database

# SAN injection: map JWT claim names to OtherName encoders
[[tkauth.claim_encoders]]
claim   = "sub"
encoder = "krb5-kpn"

Per-profile JWKS trust (set in each profile that should accept kid-signed tokens):

[profiles.providers.local.profiles.kerberos-svc]
description     = "Kerberos service certificate"
ca_ids          = ["kerberos-ca"]
trust_jwks_urls = ["https://idp.example.com/jwks"]

[profiles.providers.local.profiles.ipa-ldap]
description     = "IPA LDAP server certificate"
ca_ids          = ["ipa-ca"]
# Co-located Ekishib IdP via Unix socket
trust_jwks_urls = ["http+unix://%2Frun%2Fekishib%2Fekishib.sock/jwks"]

Certificates

This chapter covers certificate issuance, retrieval, revocation, and the ACME Renewal Information (ARI) extension.

Issuance

Certificates are issued when an order is finalized. The client submits a PKCS#10 CSR (DER-encoded, base64url) to the finalize endpoint.

flowchart TD
    A(["POST /acme/order/ID/finalize<br/>csr = base64url DER"]) --> B[Decode + parse CSR]
    B --> C{"Self-signature<br/>valid?"}
    C -->|No| FAIL([400 badCSR])
    C -->|Yes| D{"BasicConstraints<br/>cA=FALSE?"}
    D -->|cA=TRUE found| FAIL
    D -->|OK| E{"SAN set equals<br/>order identifiers?"}
    E -->|Mismatch| FAIL
    E -->|Match| F["Resolve profile parameters<br/>(from requested profile, or server defaults)"]
    F --> AUTH{"Per-profile auth checks<br/>(patterns, hook, grants)"}
    AUTH -->|Denied| UNAUTH([401/403 unauthorized])
    AUTH -->|Permitted| G["Build end-entity certificate<br/>extensions from resolved profile"]
    G --> H[Sign with CA private key]
    H --> MTC{"issue_as = mtc?"}
    MTC -->|Yes| MTCB["Build MTC StandaloneCertificate<br/>DER; Content-Type: application/pkix-cert"]
    MTC -->|No| I["Store DER + PEM bundle<br/>in certificates table"]
    MTCB --> I
    I --> J["Update order: status=valid<br/>certificate_id set"]
    J --> K([Return order with certificate URL])
    K --> L(["Client: GET /acme/cert/ID<br/>Download certificate"])

    classDef ok   fill:#f0fdf4,stroke:#16a34a,color:#0f172a
    classDef fail fill:#fef2f2,stroke:#dc2626,color:#0f172a
    class K,L ok
    class FAIL,UNAUTH fail

The server:

1. Decodes and parses the CSR.
2. Verifies the CSR’s self-signature.
3. Checks that the CSR does not request CA authority (cA=TRUE in BasicConstraints is rejected).
4. Verifies that the CSR’s SubjectAlternativeName extension contains exactly the identifiers from the order — no more, no fewer.
5. Generates a random 16-byte serial number (positive two’s complement, high bit cleared).
6. Applies certificate parameters from the requested profile, or from the server’s default policy if no profile was specified.
7. Issues the certificate. When the resolved profile has issue_as = "mtc", a Merkle Tree Certificate StandaloneCertificate is built instead of a PEM chain; otherwise, a standard X.509 v3 certificate is issued. The extensions depend on the active profile:

The Subject Name from the CSR is copied verbatim into the issued certificate.

The validity period runs from the moment of issuance for validity_days days (default 90), or the profile-specific validity if a profile is active. See Certificate Profiles for how to configure per-profile extension content, MTC issuance, and per-profile authorization.

Downloading a certificate

Send a GET request to the certificate URL provided in the order’s certificate field:

GET /acme/cert/<cert-id>

No authentication is required. The response format depends on how the certificate was issued:

Standard X.509 certificate (Content-Type: application/pem-certificate-chain):

-----BEGIN CERTIFICATE-----
<base64-encoded end-entity certificate>
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
<base64-encoded CA certificate>
-----END CERTIFICATE-----

The bundle always contains the end-entity certificate followed by the CA certificate. No intermediate certificates are included (there are none in this single-tier CA architecture).

MTC StandaloneCertificate (Content-Type: application/pkix-cert):

When the order was finalized with a profile that sets issue_as = "mtc", the endpoint returns the raw DER-encoded StandaloneCertificate (§6.1 of draft-ietf-plants-merkle-tree-certs). The server detects MTC certificates automatically and sets the appropriate Content-Type. See Certificate Profiles — MTC certificate issuance for how to configure an MTC-issuing profile.

Certificate storage

The server stores both the DER and PEM representations of the issued certificate in the certificates database table, along with:

• The UUID used as the certificate ID in the download URL.
• The hex-encoded serial number.
• Validity window timestamps (Unix epoch).
• The MTC log leaf index (if MTC logging is enabled).
• The suggested renewal window (ARI; computed on first query if not set).

Revocation

To revoke a certificate, POST to /acme/revoke-cert with a JWS signed by either:

• The account key of the account that owns the certificate, or
• The private key that corresponds to the certificate’s subject public key.

The payload:

{
  "certificate": "<base64url-encoded-DER-certificate>",
  "reason": 1
}

The certificate field contains the DER-encoded end-entity certificate (not the PEM bundle).

The reason field is optional. When present, it must be a CRL reason code:

Codes 7 and values above 10 are invalid and rejected with badRevocationReason.

On success, the server returns HTTP 200 with no body. The certificate’s status is set to revoked in the database with the revocation timestamp and reason code.

Revoking an already-revoked certificate returns alreadyRevoked.

ACME Renewal Information (ARI)

Akāmu implements RFC 9773, which allows ACME clients to ask the server when to renew a certificate.

Endpoint

GET /acme/renewal-info/<cert-id>

No authentication required.

Response

{
  "suggestedWindow": {
    "start": "2026-04-01T00:00:00Z",
    "end":   "2026-04-09T00:00:00Z"
  }
}

Window computation

If the server has not explicitly set a renewal window for the certificate, it computes one as follows:

• Start: two-thirds of the way through the certificate’s validity period.
• End: 24 hours before the certificate expires.

For a 90-day certificate issued on January 1, 2026:

• Validity period: 90 days = 7,776,000 seconds
• Start: January 1 + 60 days = March 2, 2026
• End: April 1, 2026 (one day before April 2 expiry)

flowchart LR
    A(["Jan 1<br/>Issued"]) -->|"60 days"| B(["Mar 2<br/>Window opens"])
    B -->|"29 days"| C(["Apr 1<br/>Window closes"])
    C -->|"24 h"| D(["Apr 2<br/>Expires"])

    classDef ok   fill:#f0fdf4,stroke:#16a34a,color:#0f172a
    classDef fail fill:#fef2f2,stroke:#dc2626,color:#0f172a
    class B,C ok
    class D fail

RFC 9773 allows an optional explanationURL field pointing to a human-readable page explaining the renewal recommendation. Set ari_explanation_url in [server] to include it:

[server]
ari_explanation_url = "https://acme.example.com/docs/renewal-policy"

When absent, the field is omitted from the response.

Using ARI with certbot

Certbot 2.7 and later support ARI. It fetches the renewal window when deciding whether to renew:

certbot renew --server https://acme.example.com/acme/directory

If the current time falls within the suggestedWindow, certbot proceeds with renewal even if the certificate has more than 30 days remaining.

Certificate Profiles

Certificate profiles let Akāmu issue certificates with different extension sets, validity periods, and key usage policies depending on the use case. Without profiles every order gets the same default profile: digitalSignature KeyUsage, serverAuth EKU, and the validity and URL settings from [ca]. With profiles configured, clients can request a named policy at order time and the server enforces it at issuance.

Profiles implement draft-ietf-acme-profiles-01.

How it works

1. At startup Akāmu loads profile definitions from one or more providers (see below) and caches them in memory.
2. The directory endpoint advertises the available profiles in meta.profiles.
3. A client includes "profile": "<name>" in its newOrder request.
4. At finalize time the server resolves the profile’s CertificateParameters and issues the certificate with those extension values; Akāmu’s own CA always signs.
5. A background task refreshes the cache every refresh_interval_secs seconds (default: 3600).

If no profile is requested, or no providers are configured, the server falls back to CA defaults unchanged.

Configuration overview

[profiles]
refresh_interval_secs = 3600   # how often to reload from providers (default)

# ── Provider 1: inline TOML definitions ─────────────────────────────────────
[profiles.providers.local]
type = "builtin"

[profiles.providers.local.profiles.tlsserver]
description   = "Standard TLS server certificate"
validity_days = 90
key_usage     = ["digital_signature", "key_encipherment"]
eku           = ["server_auth"]

[profiles.providers.local.profiles.clientauth]
description   = "Client authentication certificate"
validity_days = 365
key_usage     = ["digital_signature"]
eku           = ["client_auth"]

# ── Provider 2: Dogtag PKI profile files ────────────────────────────────────
[profiles.providers.dogtag_prod]
type        = "dogtag"
profile_dir = "/etc/pki/pki-tomcat/ca/profiles/ca"
profiles    = ["caServerCert", "caIPAserviceCert"]   # empty = all

# ── Provider 3: FreeIPA/IPAThinCA via GSSAPI LDAP ───────────────────────────
[profiles.providers.ipa_prod]
type     = "ipa"
profiles = ["caIPAserviceCert", "IECUserRoles"]

[profiles.providers.ipa_prod.ldap]
uri     = "ldap://ipa.example.com:389"
base_dn = "o=ipaca"
gssapi  = true

Provider types

builtin — inline TOML

Define profiles directly in config.toml. No external system required.

[profiles.providers.local]
type = "builtin"

[profiles.providers.local.profiles.<profile-id>]
description   = "Human-readable description shown in meta.profiles"
validity_days = 90          # optional; inherits from [ca].validity_days
hash_alg      = "sha256"    # optional; inherits from [ca].hash_alg
key_usage     = ["digital_signature"]   # see table below
eku           = ["server_auth"]         # see table below
crl_url       = "http://crl.example.com/ca.crl"   # optional
ocsp_url      = "http://ocsp.example.com"          # optional
allowed_key_types = ["ec:P-256", "rsa:2048"]       # optional; empty = any
issue_as      = "mtc"       # optional; "mtc" or absent/"x509" for standard X.509

# Multi-CA restriction (optional; empty = available via all CAs)
ca_ids               = ["rsa", "ec"]              # restrict to specific CA IDs

# Per-profile authorization (all three checks are AND-combined)
allowed_identifiers  = ['^dns:.*\.example\.com$']  # optional; empty = no restriction
identifier_match     = "all"                        # "all" (default) or "any"
auth_hook            = "/etc/akamu/hooks/auth.sh"  # optional; path to executable
auth_hook_timeout_secs = 30                         # optional; default 30
require_account_grant  = false                      # optional; default false

[[profiles.providers.local.profiles.<profile-id>.certificate_policies]]
oid     = "2.23.140.1.2.1"                         # DV certificate
cps_uri = "https://example.com/cps"               # optional

key_usage names

eku names and dotted-decimal OIDs

crl_url / ocsp_url three-state semantics

dogtag — Dogtag PKI profile files

Load profiles from a Dogtag PKI .cfg file directory. Each file is named <profile-id>.cfg and uses the Dogtag Java-properties format.

[profiles.providers.dogtag_prod]
type        = "dogtag"
profile_dir = "/etc/pki/pki-tomcat/ca/profiles/ca"
profiles    = ["caServerCert", "caIPAserviceCert"]
# profiles = []   # empty = load all .cfg files in the directory

At least one of profile_dir or ldap must be set. When both are configured, ldap takes priority.

# LDAP source — simple bind, TLS via STARTTLS
[profiles.providers.dogtag_ldap]
type     = "dogtag"
profiles = ["caServerCert"]

[profiles.providers.dogtag_ldap.ldap]
uri                = "ldap://dogtag.example.com:389"
base_dn            = "dc=example,dc=com"
bind_dn            = "uid=admin,ou=people,dc=example,dc=com"
bind_password_file = "/etc/akamu/ldap-password"
tls_ca_cert_file   = "/etc/ssl/certs/ldap-ca.pem"   # triggers STARTTLS on ldap:// URIs

# LDAP source — multiple servers, GSSAPI
[profiles.providers.dogtag_ha]
type     = "dogtag"
profiles = ["caServerCert"]

[profiles.providers.dogtag_ha.ldap]
uris    = ["ldap://dogtag1.example.com:389", "ldap://dogtag2.example.com:389"]
base_dn = "dc=example,dc=com"
gssapi  = true

Supported Dogtag policy classes

Unrecognised policy class IDs are silently skipped.

ipa — FreeIPA / IPAThinCA

Load profiles from a FreeIPA or IPAThinCA instance. Profile .cfg files use the same Dogtag format. The standard location for IPA-embedded Dogtag is /etc/pki/pki-tomcat/ca/profiles/ca on the IPA server, and LDAP profiles are stored at ou=certificateProfiles,ou=ca,o=ipaca — accessible on the standard LDAP ports (389 for plain/STARTTLS, 636 for LDAPS).

# Filesystem source
[profiles.providers.ipa_prod]
type        = "ipa"
profile_dir = "/etc/pki/pki-tomcat/ca/profiles/ca"
profiles    = ["caIPAserviceCert"]

# LDAP source — single server, simple bind
[profiles.providers.ipa_ldap]
type     = "ipa"
profiles = ["caIPAserviceCert"]

[profiles.providers.ipa_ldap.ldap]
uri                = "ldap://ipa.example.com:389"
base_dn            = "o=ipaca"
bind_dn            = "uid=admin,cn=users,cn=accounts,dc=example,dc=com"
bind_password_file = "/etc/akamu/ipa-ldap-password"

# LDAP source — multiple servers (failover list), GSSAPI
[profiles.providers.ipa_ha]
type     = "ipa"
profiles = ["caIPAserviceCert"]

[profiles.providers.ipa_ha.ldap]
uris    = ["ldap://ipa1.example.com:389", "ldap://ipa2.example.com:389"]
base_dn = "o=ipaca"
gssapi  = true

# LDAP source — SRV-based discovery, GSSAPI
[profiles.providers.ipa_gssapi]
type     = "ipa"
profiles = ["caIPAserviceCert"]

[profiles.providers.ipa_gssapi.ldap]
srv_domain = "example.com"   # resolves _ldap._tcp.example.com SRV records
base_dn    = "o=ipaca"
gssapi     = true

LDAP server selection

At least one of uri, uris, or srv_domain must be set.

LDAP authentication options

Attribute name lowercasing: the akamu-ldap library normalises all LDAP attribute names to lower case in the returned entries. Profile lookup keys such as cn and certProfileConfig are matched in lower case internally; this is transparent to the operator.

Refresh behaviour

Akāmu loads all providers once at startup and caches the results. A background tokio task wakes every refresh_interval_secs seconds and re-loads all providers, atomically replacing the cache. Certificates being issued concurrently always see a consistent snapshot.

If a refresh fails (e.g., a .cfg file is temporarily unreadable), the previous cache is kept and a warning is logged. The server never stops serving because of a failed refresh.

The refresh task exits automatically when the server shuts down (it holds a weak reference to the registry).

[profiles]
refresh_interval_secs = 1800   # refresh every 30 minutes instead of 1 hour

Precedence when multiple providers list the same profile

If two providers both export a profile with the same ID, the first provider listed in config.toml wins. The second is silently ignored. This is determined by HashMap iteration order over [profiles.providers], which is non-deterministic in TOML. To avoid ambiguity, give each profile a unique ID across providers, or use a single canonical provider.

Requesting a profile from an ACME client

Include "profile" in the newOrder payload:

{
  "identifiers": [{ "type": "dns", "value": "example.com" }],
  "profile": "tlsserver"
}

The server:

1. Records the profile name on the order.
2. Validates the profile name at finalize time (rejects with invalidProfile if no longer loaded).
3. Runs per-profile authorization checks (see below).
4. Issues the certificate using the profile’s CertificateParameters.

The profile name is echoed back in every order response:

{
  "status": "valid",
  "profile": "tlsserver",
  "certificate": "https://acme.example.com/acme/cert/…"
}

CA restriction (ca_ids)

When ca_ids is set on a builtin profile, the profile is only offered via the ACME endpoints of the listed CAs. Requests for this profile via any other CA’s endpoint receive urn:ietf:params:acme:error:invalidProfile at finalize time.

[profiles.providers.local.profiles.rsa-only]
description = "Certificate restricted to the RSA CA"
ca_ids      = ["rsa"]

Config validation rejects ca_ids entries that do not match any configured CA id. When ca_ids is empty (the default), the profile is available via all configured CAs.

Per-profile authorization

Three independent checks are applied at finalize time. All configured checks must pass (AND logic) for issuance to proceed. Checks that are not configured are skipped.

1. Identifier patterns

allowed_identifiers is a list of regular expressions. Each order identifier is formatted as "type:value" (e.g. "dns:example.com", "dns:*.example.com") before being tested against the patterns.

[profiles.providers.local.profiles.internal]
description         = "Internal services only"
allowed_identifiers = ['^dns:.*\.internal\.example\.com$', '^dns:internal\.example\.com$']
identifier_match    = "all"   # "all" (default) or "any"

identifier_match controls how the patterns are applied:

When allowed_identifiers is empty (the default), no identifier restriction is applied.

An invalid regular expression in allowed_identifiers causes the finalize request to fail with invalidProfile.

2. External authorization hook

auth_hook is a path to an executable. The server spawns it at finalize time and sends a JSON object on stdin:

{
  "account_id": "abc123",
  "profile": "internal",
  "identifiers": [
    { "type": "dns", "value": "svc.internal.example.com" }
  ]
}

• Exit code 0: issuance proceeds.
• Non-zero exit code: issuance is denied. The hook’s standard output (trimmed) is forwarded to the ACME client as the denial reason.
• Standard error is discarded.

auth_hook_timeout_secs (default: 30) sets the maximum time the server waits for the hook to exit. If the hook times out, issuance is denied.

[profiles.providers.local.profiles.internal]
description            = "Internal services"
auth_hook              = "/etc/akamu/hooks/check-service.sh"
auth_hook_timeout_secs = 10

3. Account grants

require_account_grant = true means the account requesting the order must have this profile’s name in its profile_grants attribute.

[profiles.providers.local.profiles.privileged]
description           = "Privileged cert profile"
require_account_grant = true

Grants are managed two ways:

• Admin API: PUT /admin/account/{id}/profile-grants with body {"profile_grants":["privileged"]}. See Admin API below.
• EAB key inheritance: when an EAB key is provisioned with profile_grants, those grants are automatically copied to any account created using that key.

An account whose profile_grants is NULL (the default) is considered to have no grants. When require_account_grant is true, such an account is denied.

MTC certificate issuance (issue_as = "mtc")

A builtin profile can issue a Merkle Tree Certificate (MTC) StandaloneCertificate instead of a standard X.509 PEM chain by setting issue_as = "mtc":

[mtc]
log_path = "/var/lib/akamu/mtc.log"
enabled  = true

[mtc.signing_key]
key_file = "/var/lib/akamu/mtc-signing.key"

[profiles.providers.local]
type = "builtin"

[profiles.providers.local.profiles.mtc-tls]
description = "MTC TLS certificate"
validity_days = 90
key_usage   = ["digital_signature"]
eku         = ["server_auth"]
issue_as    = "mtc"

When issue_as = "mtc":

1. The finalize handler issues the certificate as usual (X.509 TBSCertificate).
2. The certificate is appended to the MTC log synchronously during finalization; the resulting leaf index is stored in the database.
3. A StandaloneCertificate (per §6.1 of draft-ietf-plants-merkle-tree-certs) is built from the TBSCertificate, a Merkle inclusion proof, and a signature from the MTC signing key.
4. The raw DER-encoded StandaloneCertificate is stored in the database and served at the certificate download URL with Content-Type: application/pkix-cert.

Requirements:

• [mtc] must be configured and enabled = true.
• [mtc.signing_key] must be configured (the standalone certificate requires a signature).
• If either condition is not met, finalization returns invalidProfile.

The download endpoint auto-detects MTC certificates by their PEM marker and switches the response Content-Type accordingly:

Admin API

The admin API is enabled by adding an [admin] section to config.toml with a listen_addr and at least one of ca_certs (for mTLS client certificates) or [admin.gssapi] (for Kerberos). See Configuration Reference — [admin] for all configuration keys.

Operators authenticate via mTLS client certificate or GSSAPI/Kerberos session token. A successful login returns a session_token that is passed as Authorization: Bearer <token> on subsequent requests. Each endpoint enforces a role-based access policy; see Admin API — Endpoint reference for the full role matrix.

When [admin] is absent from the configuration, the admin listener is not started and all admin endpoints are unreachable.

Account profile grants

GET /admin/account/{id}/profile-grants

Returns the current grants for the account:

{ "profile_grants": ["p1", "p2"] }

Returns {"profile_grants": null} when the account has no grants. Returns 404 when the account is not found.

PUT /admin/account/{id}/profile-grants

Replace the account’s grants entirely. Body:

{ "profile_grants": ["p1", "p2"] }

Send {"profile_grants": null} or {"profile_grants": []} to clear all grants (equivalent to NULL — account may use any profile). Returns 204 on success, 404 when not found.

DELETE /admin/account/{id}/profile-grants

Clear all grants for the account (set to NULL). Returns 204 on success, 404 when not found.

EAB key provisioning

POST /admin/eab

Provision a new EAB key with optional profile grants:

{
  "kid": "key-id-1",
  "hmac_key_b64u": "<base64url-encoded-HMAC-key>",
  "profile_grants": ["p1", "p2"]
}

profile_grants is optional; omit it or pass null for no restriction. When present, any account created with this EAB key will automatically inherit these grants at account creation time.

Returns 201 with {"kid": "key-id-1", "created": <unix-epoch>} on success. Returns 409 when the kid already exists.

To generate a suitable HMAC key:

openssl rand -base64 32 | tr '+/' '-_' | tr -d '='

S/MIME profile example

To issue S/MIME end-user certificates via the RFC 8823 email-reply-00 challenge, configure a profile with email_protection EKU and restrict it to email identifiers. Combine with [email_challenge] in the server configuration.

[email_challenge]
enabled             = true
from_address        = "acme-validation@example.com"
send_script         = "/etc/akamu/send-email.sh"
webhook_hmac_secret = "replace-with-output-of--openssl-rand-hex-32"

[profiles.providers.local]
type = "builtin"

[profiles.providers.local.profiles.smime]
description          = "S/MIME end-user certificate (RFC 8823)"
key_usage            = ["digital_signature", "non_repudiation", "key_encipherment"]
eku                  = ["email_protection"]
allowed_identifiers  = ['^email:.*$']
validity_days        = 365

The allowed_identifiers pattern '^email:.*$' restricts this profile to email identifier orders; it is rejected for DNS/IP orders. The non_repudiation bit is optional but commonly included for S/MIME signing certificates per CA/Browser Forum S/MIME Baseline Requirements.

The CSR submitted at finalize time must include an rfc822Name SAN and the emailProtection EKU. The server validates both before issuing. See email-reply-00 in the Challenges reference for the complete protocol.

Legacy [server.profiles]

Prior to the [profiles] subsystem, profile names were declared as a flat string map under [server]:

[server.profiles]
"tls-server-auth" = "https://acme.example.com/docs/profiles/tls-server-auth"

This still works for advertising profile names in the directory (the meta.profiles field). However, the map is a pure label registry — no actual certificate parameters are loaded from it, and any profile name is accepted at order time (no enforcement of key usage or EKU). Use the new [profiles] section for real per-profile issuance policy.

When [profiles] providers are configured, meta.profiles is populated from the registry; [server.profiles] is ignored.

CRL and OCSP

Akāmu supports both Certificate Revocation List (CRL) and Online Certificate Status Protocol (OCSP) to communicate revocation status to relying parties. Both protocols are served directly by Akāmu at built-in endpoints.

CRL — GET /ca/{ca_id}/crl and GET /ca/crl

Akāmu generates and serves a signed v2 CRL (RFC 5280) for each configured CA. In multi-CA deployments each CA has its own CRL endpoint:

GET /ca/{ca_id}/crl   # per-CA CRL
GET /ca/crl           # backward-compatible alias → default CA

The CRL is built on each request from the current revocation database. No caching or pre-generation is required for typical issuance volumes. The response uses Content-Type: application/pkix-crl.

Configuring the CRL URL

Set crl_url in each [[ca]] (or [ca]) entry to the public URL of that CA’s CRL endpoint. This URL is embedded in every issued end-entity certificate in the CRLDistributionPoints extension.

For a single-CA deployment the URL is typically the /ca/crl alias:

[ca]
crl_url = "http://acme.example.com/ca/crl"

For multi-CA deployments use the per-CA path so each CA’s certificates point to the correct revocation list:

[[ca]]
id      = "rsa"
crl_url = "http://acme.example.com/ca/rsa/crl"

[[ca]]
id      = "ec"
crl_url = "http://acme.example.com/ca/ec/crl"

Clients that check CRL status fetch this URL and verify the certificate’s serial number against the revocation list.

CRL validity window

The nextUpdate field in the CRL is set to the current time plus crl_next_update_secs (default: 86400 seconds, i.e. one day):

[ca]
crl_next_update_secs = 86400   # one day (default)

Adjust this value to match how frequently clients are expected to re-fetch the CRL.

What a CRL contains

Each CRL entry carries the certificate’s serial number, the revocation timestamp, and the reason code (if one was provided at revocation time). The CRL also includes a cRLNumber extension (RFC 5280 §5.2.3) derived from the current Unix timestamp.

CRL reason codes

Verifying the CRL manually

curl http://acme.example.com/ca/crl | openssl crl -inform DER -text -noout

OCSP — GET /ca/{ca_id}/ocsp/{request} and POST /ca/{ca_id}/ocsp

Akāmu includes a built-in OCSP responder (RFC 6960) for each configured CA. In multi-CA deployments each CA has its own OCSP endpoint:

POST /ca/{ca_id}/ocsp                  # per-CA OCSP (POST)
GET  /ca/{ca_id}/ocsp/{request}        # per-CA OCSP (GET)
POST /ca/ocsp                          # backward-compatible alias → default CA
GET  /ca/ocsp/{request}                # backward-compatible alias → default CA

The {request} path segment is the base64url-encoded DER OCSPRequest (RFC 6960 §A.1). Both endpoints return a signed OCSPResponse with Content-Type: application/ocsp-response. No authentication is required.

Both endpoints return a signed OCSPResponse with Content-Type: application/ocsp-response. No authentication is required — OCSP is a public protocol.

Configuring the OCSP URL

Set ocsp_url in each [[ca]] (or [ca]) entry to the public base URL of that CA’s OCSP endpoint. This URL is embedded in every issued end-entity certificate in the AuthorityInfoAccess extension.

For a single-CA deployment:

[ca]
ocsp_url = "http://acme.example.com/ca/ocsp"

For multi-CA deployments use the per-CA path:

[[ca]]
id       = "rsa"
ocsp_url = "http://acme.example.com/ca/rsa/ocsp"

[[ca]]
id       = "ec"
ocsp_url = "http://acme.example.com/ca/ec/ocsp"

Clients sending GET requests append the base64url-encoded request to this URL. Clients sending POST requests target the URL directly.

OCSP response behaviour

For each serial number in an OCSPRequest:

The response is signed with the CA key. The responder identity is set to byName using the CA’s subject DER.

The nextUpdate field in each SingleResponse is fixed at 24 hours after the response is produced.

Verifying OCSP manually

openssl ocsp -issuer ca.pem -cert issued.pem -url http://acme.example.com/ca/ocsp -text

Cross-certificates — GET /ca/{ca_id}/cross-certs

When cross-signing is used, the resulting cross-certificates are available at a public (unauthenticated) endpoint:

GET /ca/{ca_id}/cross-certs

This returns a JSON list of cross-certificates where {ca_id} is the subject (the CA whose public key was cross-signed). Relying parties and ACME clients can use this endpoint to discover cross-certificates for path building.

{
  "cross_certs": [
    {
      "id": "a1b2c3d4-…",
      "issuer_ca_id": "rsa",
      "not_before": "2026-05-06T12:00:00Z",
      "not_after": "2031-05-06T12:00:00Z"
    }
  ]
}

To download the cross-certificate PEM, use the admin API: GET /admin/cross-certs/{id} (see Admin API — CA management endpoints) or akamuctl cross-cert download <id>.

Checking revocation status from the database

To verify whether a specific certificate is currently marked as revoked in Akāmu’s database, query the certificates table by serial number. The serial number is printed in hex by most certificate inspection tools (for example, openssl x509 -serial -noout -in cert.pem):

SELECT serial_number, status, revoked_at, revocation_reason
FROM certificates
WHERE serial_number = '<hex-serial>';

A status value of revoked indicates the certificate has been revoked. revoked_at is a Unix timestamp of when revocation occurred, and revocation_reason is the numeric CRL reason code (or NULL if no reason was specified).

Merkle Tree Certificate Log

Akāmu integrates with a Merkle Tree Certificate (MTC) transparency log using the synta-mtc library. When enabled, each issued end-entity certificate is appended as a leaf to a disk-backed, append-only log.

What is an MTC log?

A Merkle Tree Certificate log is a tamper-evident, append-only data structure. Each leaf encodes an issued certificate in a way that allows efficient proofs of inclusion and consistency that third parties can verify independently.

This is analogous in concept to Certificate Transparency (CT) logs (RFC 6962) but uses a different data structure and encoding based on the synta-mtc specification.

Configuration

[mtc]
log_path = "/var/lib/akamu/mtc.log"
enabled  = true

When enabled = true:

• On startup, the server opens the existing log file at log_path, or creates a new one if the file does not exist.
• After each successful certificate issuance, the certificate is appended to the log. The append happens in a background task so it does not delay the issuance response.
• The resulting leaf index is stored in the certificates database table. If the append fails, a warning is logged but the certificate issuance response is not affected; the log index will be NULL for that certificate.

When enabled = false (the default):

• The log file is never written.
• The log_path must still be specified but is not used.

Issuing MTC certificates directly from a profile

When [mtc] is enabled and [mtc.signing_key] is configured, a builtin certificate profile can be set to issue a Merkle Tree Certificate StandaloneCertificate instead of a standard X.509 PEM chain. Set issue_as = "mtc" on the profile:

[mtc]
log_path = "/var/lib/akamu/mtc.log"
enabled  = true

[mtc.signing_key]
key_file = "/var/lib/akamu/mtc-signing.key"
key_type = "ec:P-256"

[profiles.providers.local]
type = "builtin"

[profiles.providers.local.profiles.mtc-tls]
description = "MTC TLS certificate"
validity_days = 90
key_usage   = ["digital_signature"]
eku         = ["server_auth"]
issue_as    = "mtc"

When a client finalizes an order with this profile, the finalize handler:

1. Issues the X.509 TBSCertificate as usual.
2. Appends the certificate to the MTC log synchronously (not in a background task, because the leaf index is needed immediately for the standalone certificate).
3. Builds a StandaloneCertificate embedding the TBSCertificate, a Merkle inclusion proof, and a signature from the MTC signing key.
4. Stores the DER-encoded StandaloneCertificate and returns the certificate URL to the client.

The certificate download endpoint (GET /acme/cert/{id}) detects MTC certificates and serves them as raw DER with Content-Type: application/pkix-cert.

If [mtc] is not enabled or [mtc.signing_key] is absent when a profile with issue_as = "mtc" is finalized, the server returns invalidProfile.

See Certificate Profiles — MTC certificate issuance for the full configuration reference.

Checkpoint signing

To enable periodic checkpoint production, add a [mtc.signing_key] section. The signing key must be distinct from the X.509 CA key (§5.5 of the MTC draft).

[mtc]
log_path                 = "/var/lib/akamu/mtc.log"
enabled                  = true
checkpoint_interval_secs = 3600    # default: 3600 (1 hour)
landmark_interval_secs   = 86400   # default: 86400 (1 day)
max_active_landmarks     = 100     # default: 100
hash_alg                 = "sha256"  # leaf hash algorithm: sha256 | sha384 | sha512 | sha3-256 | sha3-384 | sha3-512
log_number               = 1        # serial encoding: (log_number << 48) | entry_index
# tree_minimum_index     = 0        # §5.2.3 log pruning; absent = no pruning
# trust_anchor_id        = "1.3.6.1.4.1.44363.47.10.1"  # CA self-cosigner OID (§5.4)

[mtc.signing_key]
key_file = "/var/lib/akamu/mtc-signing.key"   # auto-generated if absent
key_type = "ec:P-256"                          # same values as [ca].key_type
hash_alg = "sha256"                            # sha256 | sha384 | sha512

Supported key_type values are the same set accepted for the CA key: ec:P-256, ec:P-384, ec:P-521, rsa:2048–rsa:4096, ed25519, ed448, ml-dsa-44, ml-dsa-65, ml-dsa-87. Per §5.4.2 of the draft, only ECDSA P-256/P-384, Ed25519, and ML-DSA are listed as valid cosigner signature algorithms; prefer EC or EdDSA for the MTC signing key.

When [mtc.signing_key] is present:

• At startup the server reads the PEM file at key_file, or auto-generates a new key of key_type and writes it there.
• A background task fires every checkpoint_interval_secs seconds. If the log has grown since the last checkpoint, it computes the Merkle root, constructs a signed checkpoint, and stores it in the database.
• Checkpoints are idempotent: if the tree size has not grown the task is a no-op.

When [mtc.signing_key] is absent, checkpoint production is disabled.

External cosigners

After each checkpoint, Akāmu can POST the checkpoint to external cosigner servers and embed their signatures in each StandaloneCertificate.

[[mtc.cosigners]]
url                  = "https://cosigner.example.com/sign"
cosigner_id_cert_pem = "/etc/akamu/cosigner1.pem"  # optional; path to cosigner X.509 cert PEM
trust_anchor_id      = "1.3.6.1.4.1.44363.47.10.1" # optional; expected TrustAnchorID OID

Multiple [[mtc.cosigners]] entries are supported. For each entry:

• Akāmu POSTs the DER-encoded checkpoint with Content-Type: application/octet-stream.
• The cosigner returns a DER-encoded signature with HTTP 200.
• Each request has a 30-second per-cosigner timeout.
• Failures are logged and skipped — partial success is acceptable; the standalone certificate is still built with whatever signatures arrive.

When cosigner_id_cert_pem is set, the PEM file is loaded at startup and added to the TLS trust store for that cosigner’s HTTPS connection, in addition to the system root CAs. The certificate’s public key is also used for cryptographic verification of received SubtreeSignature values. This allows cosigners whose TLS certificate chains to an operator-provisioned CA to be used without installing that CA system-wide.

When trust_anchor_id is set, the SubtreeSignature.cosigner OID in each response is compared against this value. Per draft-ietf-plants-merkle-tree-certs-04 §4.1, CosignerID is TrustAnchorID ::= OBJECT IDENTIFIER; a mismatch causes the signature to be rejected.

Security constraint: Setting trust_anchor_id without also setting cosigner_id_cert_pem is a hard startup error. OID-only verification provides no cryptographic assurance — anyone who knows the OID could forge a cosignature. Both fields must be set together to enable verified cosignature acceptance. When neither field is set, cosignatures are accepted without any verification and a warning is logged at startup.

Querying the log index

To find which MTC log slot a certificate occupies, query the database:

SELECT id, serial_number, mtc_log_index
FROM certificates
WHERE mtc_log_index IS NOT NULL
ORDER BY mtc_log_index;

A NULL index means the certificate was either issued before MTC logging was enabled, or the log append failed at issuance time.

HTTP API

The following read-only endpoints expose the log state. All return 404 when MTC is disabled (enabled = false).

GET /acme/mtc/tree-size

Returns the current number of leaves in the log.

{ "treeSize": 42 }

GET /acme/mtc/root

Returns the current tree size and the Merkle root hash as a lowercase hex string.

{ "treeSize": 42, "rootHash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" }

GET /acme/mtc/inclusion-proof/{cert_id}

Returns a Merkle inclusion proof for the certificate identified by cert_id (the internal UUID stored in the certificates table). Returns 404 if the certificate does not exist or has no log index.

{
  "leafIndex": 7,
  "treeSize": 42,
  "proof": [
    { "hash": "a1b2c3..." },
    { "hash": "d4e5f6..." }
  ]
}

Each element of proof is an object with a single "hash" field containing the sibling hash as a lowercase hex string. The proof is ordered from the leaf up to the root. The sibling position (left or right) is determined algorithmically from the leaf index and tree size, following the standard RFC 6962 Merkle audit proof construction; it is not encoded in the response.

GET /acme/mtc/cert/{cert_id}/standalone

Returns the DER-encoded standalone certificate (§6.1 of the MTC draft) for the given certificate, with Content-Type: application/octet-stream.

The standalone certificate embeds the certificate’s TBS data, a Merkle inclusion proof, and a signature from the MTC signing key. Relying parties can verify the certificate’s presence in the log without querying the CA.

Returns 404 when:

• MTC is disabled
• The certificate does not exist
• The certificate has no MTC log index (the log append failed at issuance)
• A checkpoint covering the certificate has not yet been produced (the standalone certificate is built during the next checkpoint cycle)

GET /acme/mtc/landmarks

Returns a JSON array of all allocated landmarks, ordered by sequence number ascending.

[
  { "sequenceNo": 0, "treeSize": 100, "createdAt": 1700000000 },
  { "sequenceNo": 1, "treeSize": 250, "createdAt": 1700086400 }
]

Returns 404 when MTC is disabled.

GET /acme/mtc/landmarks/{seq}/cert

Returns the DER-encoded landmark certificate (§6.3.1 of the MTC draft) for the landmark with sequence number seq, with Content-Type: application/octet-stream.

Returns 404 when:

• MTC is disabled
• No landmark with that sequence number exists
• The landmark certificate has not yet been built

GET /acme/mtc/consistency-proof?from={old_size}&to={new_size}

Returns the Merkle roots at two tree sizes so a monitor can verify that the tree at to extends the tree at from.

{
  "fromSize": 10,
  "toSize": 42,
  "fromRoot": "a1b2c3...",
  "toRoot": "d4e5f6..."
}

Both from and to must be positive integers with from < to and to <= current tree size. Returns 400 for invalid parameters.

GET /acme/mtc/subtree-root?start={start}&end={end}

Returns the Merkle root hash for the subtree [start, end). The subtree must satisfy the alignment constraint from draft-04 §4.3.1 (start is a multiple of BIT_CEIL(end - start)).

{
  "start": 0,
  "end": 256,
  "rootHash": "e3b0c442..."
}

GET /acme/mtc/revoked-ranges

Returns a JSON array of [start, end] pairs representing revoked log entry index ranges (draft-04 §5.6). Relying parties use these to reject standalone certificates whose serial number falls within a revoked range.

[[10, 15], [100, 120]]

Returns 404 when MTC is disabled.

C2SP tlog-tiles API

When [mtc.signing_key] is configured, three additional endpoints implement the C2SP tlog-tiles and C2SP signed-note specifications, enabling compatibility with transparency-log clients that speak the tlog-tiles protocol.

All three endpoints return 404 when MTC is disabled. GET /acme/mtc/tlog/checkpoint and GET /acme/mtc/tlog/cosignature additionally require a signing key to be configured; without one they return 503.

GET /acme/mtc/tlog/checkpoint

Returns the current tree as a C2SP signed-note checkpoint signed by the MTC signing key acting as the primary log operator.

• Ed25519 key: signature type 0x01.
• ECDSA key: signature type 0x02.

Response Content-Type is text/plain; charset=utf-8. The note body format is:

<log origin>
<tree_size>
<base64(root_hash)>

— <key_name> <base64(key_id || signature)>

GET /acme/mtc/tlog/tile/{*path}

Serves a C2SP hash tile. The path component encodes {level}/{tile_index_path}[.p/{width}]:

• level is 0 for leaf-hash tiles, or L > 0 for Merkle subtree roots (covering 256^L leaves each).
• tile_index_path is the C2SP multi-level decimal encoding (e.g. 000, x001/234).
• The optional .p/{width} suffix requests a partial tile with fewer than 256 entries.

Response Content-Type is application/octet-stream; each hash entry is 32, 48, or 64 bytes depending on the [mtc].hash_alg configured for the log (SHA-256/SHA3-256, SHA-384/SHA3-384, or SHA-512/SHA3-512 respectively).

Returns 404 when the tile is entirely beyond the current log size. Returns 501 for tile/entries/... paths because Akāmu stores only leaf hashes, not raw entry data.

GET /acme/mtc/tlog/cosignature

Returns a C2SP cosignature note for the current checkpoint, produced by the MTC signing key acting as a cosigner. The current POSIX timestamp is embedded in the signature blob.

• Ed25519 key: cosignature type 0x04 (cosignature/v1 signed-note format).
• ML-DSA-44 key: cosignature type 0x06 (subtree/v1 binary cosigned message).
• ECDSA key: uses the operator format (type 0x02) because no dedicated ECDSA cosignature type is defined by C2SP.

Response Content-Type is text/plain; charset=utf-8.

Landmark management

A landmark is a frozen snapshot of the tree size at a point in time. Relying parties use landmarks to anchor inclusion proofs across the log’s lifetime without tracking every checkpoint.

When [mtc.signing_key] is configured, a background task fires every landmark_interval_secs seconds (default: 86400 = 1 day). If the tree has grown since the last landmark, a new landmark is built and stored in the database. Rows beyond max_active_landmarks (default: 100) are pruned automatically, removing the oldest landmarks by sequence number.

Log integrity

The log is append-only by design. Once a leaf is appended it cannot be removed or modified without corrupting the file. A single Akāmu process is the exclusive writer. At startup, Akāmu acquires an exclusive advisory lock on <log_path>.lock; if another process already holds the lock the server exits immediately with a clear error rather than proceeding to corrupt the log.

For details on the internal log format, appending algorithm, checkpoint production, and concurrency model, see MTC Implementation in the Developer Guide.

MTC Cosigner Daemon

akamu-cosigner is a standalone binary that acts as an external MTC (Merkle Tree Certificate) cosigner. When the main akamu server produces a checkpoint, it POSTs the DER-encoded Checkpoint to each configured cosigner URL. akamu-cosigner signs the checkpoint with its own key and returns a DER-encoded SubtreeSignature. The signature is then embedded in every StandaloneCertificate produced from that checkpoint.

Operators who run an independent MTC log can expose akamu-cosigner as a public cosigning service. Operators who want additional signatures on their own log can run one or more cosigner instances as part of their infrastructure.

Binary

Build from source:

cargo build -p akamu-cosigner --release

The binary is placed at target/release/akamu-cosigner.

Run:

akamu-cosigner /etc/akamu/cosigner.toml

If no argument is given, the daemon looks for cosigner.toml in the current working directory.

Configuration file

akamu-cosigner reads a single TOML configuration file. All sections are described below.

Complete example

[server]
listen_addr = "0.0.0.0:8080"
base_url    = "https://cosigner.example.com"

[tls]
cert_file = "/etc/akamu/cosigner-tls.crt"
key_file  = "/etc/akamu/cosigner-tls.key"

[signing_key]
key_file = "/var/lib/akamu/cosigner-signing.key"
key_type = "ec:P-256"
hash_alg = "sha256"

[cosigner_id]
cert_file       = "/var/lib/akamu/cosigner-id.crt"
trust_anchor_id = "1.3.6.1.4.1.44363.47.10.1"

[acme_bootstrap]
server_url    = "https://acme.example.com/acme/directory"
account_email = "ops@example.com"
eab_kid       = "my-eab-key-id"
eab_hmac      = "c2VjcmV0LWhtYWMta2V5LWJ1ZmZlcg"
domain        = "cosigner.example.com"
challenge_type = "http-01"
cert_file     = "/var/lib/akamu/cosigner-tls.crt"
key_file      = "/var/lib/akamu/cosigner-tls.key"

[server]

listen_addr

Optional. Default: "0.0.0.0:8080".

Address the daemon binds to. Two forms are accepted:

[server]
listen_addr = "0.0.0.0:8443"

# Or, for a Unix domain socket behind a reverse proxy:
# listen_addr = "unix:/run/akamu/akamu-cosigner.sock"

The AKAMU_COSIGNER_LISTEN environment variable overrides this field:

AKAMU_COSIGNER_LISTEN=unix:/run/akamu/akamu-cosigner.sock akamu-cosigner /etc/akamu/cosigner.toml

Constraint: Unix domain sockets and [tls] are mutually exclusive. When listen_addr is a Unix path and a [tls] section is present (or [acme_bootstrap] is configured, which implies TLS), the daemon exits at startup with an error.

Systemd socket activation: The provided akamu-cosigner.socket unit pre-binds /run/akamu/akamu-cosigner.sock (mode 0660, user/group akamu-cosigner). Enable with systemctl enable --now akamu-cosigner.socket akamu-cosigner.service. When socket activation is active, listen_addr in the config file is ignored — the pre-bound socket is passed via LISTEN_FDS.

base_url

Required.

Public HTTPS base URL of the cosigner. Used as the dNSName SAN when auto-generating the self-signed cosigner-id certificate.

[server]
base_url = "https://cosigner.example.com"

[tls]

Optional. When present, the daemon serves HTTPS using the given certificate and key. When absent, the daemon listens on plain HTTP — only suitable behind a TLS-terminating reverse proxy.

When [acme_bootstrap] is configured and the [tls] section is absent, the daemon derives TLS configuration from the ACME-issued certificate and key paths specified in [acme_bootstrap].

cert_file

Required within [tls]. Path to the TLS server certificate PEM file (leaf + chain).

key_file

Required within [tls]. Path to the TLS server private key PEM file.

[tls]
cert_file = "/etc/akamu/cosigner-tls.crt"
key_file  = "/etc/akamu/cosigner-tls.key"

[signing_key]

The MTC signing key. This key must be distinct from any TLS certificate key. Its public half is embedded in the cosigner-id certificate so that relying parties can verify the SubtreeSignature.

key_file

Required. Path to the signing key PEM file. If the file does not exist, a new key of key_type is generated and written here on startup.

key_type

Optional. Default: "ec:P-256".

Key algorithm for auto-generation. Accepts the same values as [[ca]].key_type in akamu: "ec:P-256", "ec:P-384", "ec:P-521", "rsa:2048", "rsa:3072", "rsa:4096", "ed25519", "ed448".

hash_alg

Optional. Default: "sha256".

Hash algorithm for ECDSA/RSA signing: "sha256", "sha384", "sha512". Ignored for EdDSA keys.

[signing_key]
key_file = "/var/lib/akamu/cosigner-signing.key"
key_type = "ec:P-256"
hash_alg = "sha256"

[cosigner_id]

The cosigner identity configuration. Per draft-ietf-plants-merkle-tree-certs-04 §4.1, CosignerID is now TrustAnchorID ::= OBJECT IDENTIFIER. The trust_anchor_id OID is embedded in every SubtreeSignature.cosigner field so that akamu servers and relying parties can identify which cosigner produced the signature. The certificate file is retained for cryptographic verification by relying parties.

cert_file

Required. Path to the cosigner-id PEM certificate file.

• If the file exists, it is loaded as the identity certificate.
• If the file is absent and [acme_bootstrap] is configured and the bootstrap certificate exists, that certificate is used as the cosigner-id.
• Otherwise, a self-signed certificate is auto-generated from the [signing_key] and written to this path. The self-signed cert uses base_url’s hostname as its dNSName SAN and has 10-year validity.

trust_anchor_id

Required. The OID (dotted-decimal) that identifies this cosigner as a TrustAnchorID. This value is embedded in every SubtreeSignature.cosigner field. Operators must agree on this OID with log operators before deploying. Example: "1.3.6.1.4.1.44363.47.10.1".

[cosigner_id]
cert_file       = "/var/lib/akamu/cosigner-id.crt"
trust_anchor_id = "1.3.6.1.4.1.44363.47.10.1"

[acme_bootstrap]

Optional. When present, akamu-cosigner uses akamu-client to obtain a certificate from the configured ACME server at startup (if the certificate is absent or expiring within 30 days). The issued certificate is used as both the TLS server certificate and the source of the cosigner-id.

server_url

Required. ACME server directory URL, e.g. "https://acme.example.com/acme/directory".

account_email

Optional. Contact e-mail for the ACME account. The mailto: prefix is added automatically.

eab_kid

Required. External Account Binding key identifier provisioned by the CA.

eab_hmac

Required. EAB HMAC key, base64url-encoded without padding.

domain

Required. DNS name to certify. Must be publicly resolvable for the chosen challenge type.

challenge_type

Optional. Default: "http-01".

ACME challenge type to use: "http-01", "dns-01", "dns-persist-01", or "tls-alpn-01".

dns_hook

Optional. Shell command invoked for dns-01 DNS provisioning. Called with ACME_DOMAIN and ACME_TXT_VALUE environment variables set. An exit code of 0 indicates the record was provisioned. When absent and challenge_type = "dns-01", the daemon logs the required TXT record and exits with an error — the operator must set the record manually and restart.

dns_persist_hook

Optional. Shell command invoked for dns-persist-01 DNS provisioning. Called with the following environment variables:

An exit code of 0 indicates the record was provisioned.

cert_file

Required. Where to write the issued certificate PEM chain.

key_file

Required. Where to write the private key PEM for the issued certificate.

csr_key_type

Optional. Default: "ec:P-256".

Key type for the ACME CSR key. Accepts the same values as [signing_key].key_type.

[acme_bootstrap]
server_url     = "https://acme.example.com/acme/directory"
account_email  = "ops@example.com"
eab_kid        = "my-eab-key-id"
eab_hmac       = "c2VjcmV0LWhtYWMta2V5LWJ1ZmZlcg"
domain         = "cosigner.example.com"
challenge_type = "http-01"
cert_file      = "/var/lib/akamu/cosigner-tls.crt"
key_file       = "/var/lib/akamu/cosigner-tls.key"
csr_key_type   = "ec:P-256"

HTTP endpoints

akamu-cosigner exposes the following endpoints:

POST /sign

Accepts a DER-encoded Checkpoint (Content-Type: application/octet-stream). Returns a DER-encoded SubtreeSignature with HTTP 200.

The SubtreeSignature covers the full checkpoint range [0, tree_size) and is signed with the [signing_key]. The cosigner field in the response contains the TrustAnchorID OID configured in [cosigner_id].trust_anchor_id.

GET /.well-known/acme-challenge/:token

Serves http-01 challenge tokens during the ACME bootstrap phase. Only active while the bootstrap flow is running; this endpoint returns 404 at all other times.

Integrating with akamu

Add a [[mtc.cosigners]] entry in the akamu server configuration for each akamu-cosigner instance:

[[mtc.cosigners]]
url                  = "https://cosigner.example.com/sign"
cosigner_id_cert_pem = "/etc/akamu/cosigner-id.crt"
trust_anchor_id      = "1.3.6.1.4.1.44363.47.10.1"   # optional; must match cosigner's [cosigner_id].trust_anchor_id

See Configuration Reference — [[mtc.cosigners]] for the full field reference.

Startup sequence

On each startup, akamu-cosigner:

1. Loads and validates the configuration file.
2. Loads or generates the [signing_key].
3. Runs the ACME bootstrap if [acme_bootstrap] is configured and the certificate is absent or expiring within 30 days.
4. Loads or generates the cosigner-id certificate at [cosigner_id].cert_file.
5. Starts the HTTP (or HTTPS) server.

The daemon does not persist any state other than the key and certificate files on disk.

Logging

akamu-cosigner uses the tracing crate. Control log verbosity with the RUST_LOG environment variable:

RUST_LOG=info  akamu-cosigner /etc/akamu/cosigner.toml
RUST_LOG=debug akamu-cosigner /etc/akamu/cosigner.toml

Admin interface

akamu-cosigner includes its own admin HTTP listener. When the [admin] section is present in the configuration file, the daemon starts a second HTTPS server for operator access. The admin listener is independent of the signing endpoint and supports the same mTLS and session-token authentication model as the main akamu server.

When the [admin] section is absent, all admin endpoints return 401 Unauthorized and a warning is logged at startup.

Configuration

Add an [admin] section and one or more [[admin.operators]] entries to cosigner.toml:

[admin]
listen_addr    = "127.0.0.1:9444"
cert_file      = "/etc/akamu/cosigner-admin-tls.pem"
key_file       = "/etc/akamu/cosigner-admin-tls.key"
ca_certs       = ["/etc/akamu/operator-ca.pem"]
session_ttl_secs = 3600

[[admin.operators]]
name             = "alice"
role             = "administrator"
cert_fingerprint = "a3b4c5…"    # SHA-256 hex of the DER leaf cert

[[admin.operators]]
name             = "bob"
role             = "auditor"
cert_fingerprint = "b2c3d4…"

Operators are defined statically in the config file rather than in a database. Changes to the operator list require a daemon restart.

[admin] fields

[[admin.operators]] fields

Admin endpoints

POST /admin/session

Authenticate with a client certificate and receive a session token.

Response 200 OK:

{
  "session_token": "a4f1…64-hex-chars…",
  "role": "administrator",
  "expires_at": "2026-05-02T14:00:00Z"
}

DELETE /admin/session

Invalidate the current session token.

Response: 204 No Content.

GET /admin/status

Liveness check. All authenticated operators may call this endpoint.

Response 200 OK:

{ "status": "ok", "uptime_secs": 3600 }

GET /admin/stats

Return signing statistics.

Response 200 OK:

{
  "uptime_secs": 3600,
  "checkpoints_signed": 42,
  "last_checkpoint_at": "2026-05-02T13:45:00Z"
}

GET /admin/config

Return a redacted view of the running configuration: operator names, roles, and session TTL. Private key material and CA certificate paths are not included. Requires the administrator role.

Response 200 OK:

{
  "operators": [
    { "name": "alice", "role": "administrator" },
    { "name": "bob",   "role": "auditor" }
  ],
  "session_ttl_secs": 3600
}

Querying via akamuctl

The akamuctl cosigner subcommands target the cosigner’s admin listener. Configure the connection in the [cosigner] section of ~/.config/akamu/akamuctl.toml:

[cosigner]
url       = "https://cosigner.example.com:9444"
ca_cert   = "/etc/akamu/cosigner-admin-ca.pem"
cert_file = "/etc/akamu/operator.pem"
key_file  = "/etc/akamu/operator.key"

akamuctl cosigner status
akamuctl cosigner stats

See akamuctl — Cosigner administration for the full command reference.

TLS Configuration

By default Akāmu listens on a plain TCP socket and relies on an upstream reverse proxy (nginx, Caddy, HAProxy, …) for TLS termination. If you want a fully self-contained deployment without a proxy, set [tls] enabled = true and Akāmu will accept HTTPS connections directly.

Backward compatibility is strict: deployments without a [tls] section in config.toml see zero behavior change.

When to use native TLS vs. a reverse proxy

Deployment modes overview

flowchart TD
    A([Akāmu startup]) --> B{"tls section<br/>in config.toml?"}
    B -->|No| C["Mode 1 — Plain HTTP<br/>Bind plain TCP socket<br/>Upstream proxy handles TLS"]
    B -->|Yes, enabled=true| D{"cert_file AND<br/>key_file both exist?"}
    D -->|Neither exists| E["Mode 2 — Auto-generated TLS<br/>Generate server key + cert<br/>signed by Akāmu CA<br/>Write files for next start"]
    D -->|One missing| ERR["Error: both or neither required<br/>startup aborted"]
    D -->|Both exist| F{"tls.client_auth<br/>section present?"}
    F -->|No| G["Mode 3 — Native TLS<br/>Load externally-issued cert + key<br/>Serve HTTPS directly"]
    F -->|Yes| H["Mode 4 — Mutual TLS<br/>Require client certificate<br/>signed by configured CA<br/>Handshake fails for unknown clients"]
    C & E & G & H --> READY([Server ready])

    classDef ok   fill:#f0fdf4,stroke:#16a34a,color:#0f172a
    classDef fail fill:#fef2f2,stroke:#dc2626,color:#0f172a
    class READY ok
    class ERR fail

Deployment walkthroughs

The sections below walk through each of the four supported operating modes in order of increasing complexity. Pick the one that matches your environment.

Mode 1 — Plain HTTP behind a reverse proxy

This is the default and requires no [tls] section at all. Akāmu binds to a plain TCP socket — typically on a loopback or private address — and an upstream reverse proxy handles HTTPS termination and forwards requests over HTTP.

config.toml (no [tls] section)

listen_addr = "127.0.0.1:8080"
base_url    = "https://acme.example.com"

[database]
path = "/var/lib/akamu/akamu.db"

[ca]
key_file  = "/etc/akamu/ca.key.pem"
cert_file = "/etc/akamu/ca.cert.pem"

[mtc]
log_path = "/var/lib/akamu/mtc.log"
enabled  = false

base_url must be the external HTTPS URL that ACME clients use to reach the directory — not the internal loopback address. Akāmu embeds this value in every URL it returns to clients (account URLs, order URLs, certificate download URLs, etc.). If base_url points at 127.0.0.1 clients will receive unusable URLs.

nginx example

server {
    listen 443 ssl;
    server_name acme.example.com;

    ssl_certificate     /etc/nginx/tls/acme.example.com.crt;
    ssl_certificate_key /etc/nginx/tls/acme.example.com.key;

    location / {
        proxy_pass         http://127.0.0.1:8080;
        proxy_set_header   Host              $host;
        proxy_set_header   X-Real-IP         $remote_addr;
        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
    }
}

Caddy example

acme.example.com {
    reverse_proxy 127.0.0.1:8080
}

Caddy automatically obtains and renews its own TLS certificate for the public hostname; no extra TLS configuration is needed on the Akāmu side.

Mode 2 — Native TLS with auto-generated certificate (development / lab)

Use this when you want Akāmu to speak HTTPS directly without a proxy but you do not yet have an externally-issued certificate. Akāmu will generate a server certificate signed by its own CA on first start.

Step 1. Add a [tls] section with enabled = true and supply paths for cert_file and key_file. The files do not need to exist yet.

listen_addr = "0.0.0.0:8443"
base_url    = "https://akamu.internal:8443"

[tls]
enabled     = true
cert_file   = "/etc/akamu/server.crt"
key_file    = "/etc/akamu/server.key"
server_name = "akamu.internal"

listen_addr and base_url must agree on the port (8443 here). base_url is the URL clients will use; listen_addr is what the OS socket binds to. 0.0.0.0 binds on all interfaces; restrict to a specific IP if needed.

Step 2. Start Akāmu. Because cert_file and key_file are both absent, the server generates a TLS certificate automatically:

1. A fresh server key is generated using the bootstrap_key_type algorithm (default ec:P-256).
2. A server certificate for server_name is signed by the Akāmu CA.
3. The PEM chain (leaf + CA) is written to cert_file and the private key to key_file.

On every subsequent start the existing files are loaded without regeneration.

Step 3. Trust the Akāmu CA on the client. The auto-generated server certificate chains to the Akāmu CA — the same CA that signs ACME-issued certificates. Its PEM is at the path configured in [ca] cert_file. Pass it to curl with --cacert:

curl --cacert /etc/akamu/ca.cert.pem \
     https://akamu.internal:8443/acme/directory

ACME client software (certbot, acme.sh, …) typically has an equivalent option for specifying a custom CA bundle.

Mode 3 — Native TLS with an externally-issued certificate (production, no proxy)

Use this when ACME clients cannot be pre-configured to trust the Akāmu CA and a publicly-trusted TLS certificate is required for the ACME endpoint itself.

The Akāmu CA (which signs certificates issued to your ACME clients) is entirely separate from the TLS server certificate. Obtaining a public TLS cert for the ACME server hostname does not affect the CA or the certificates it issues.

Step 1. Obtain a certificate for the Akāmu server hostname from a public CA (Let’s Encrypt, ZeroSSL, your organisation’s PKI, etc.). You can use any ACME client pointed at a public CA — Akāmu itself does not need to be running yet for this step.

Step 2. Place the PEM certificate chain in cert_file (leaf first, then any intermediates) and the unencrypted private key in key_file.

Step 3. Configure Akāmu:

listen_addr = "0.0.0.0:8443"
base_url    = "https://acme.example.com:8443"

[tls]
enabled     = true
cert_file   = "/etc/akamu/server.crt"   # publicly-trusted chain, leaf first
key_file    = "/etc/akamu/server.key"   # unencrypted PKCS#8 or EC key
server_name = "acme.example.com"        # used only if cert/key are absent (bootstrap)

Because cert_file and key_file already exist when Akāmu starts, the bootstrap step is skipped entirely. server_name has no effect at runtime but is kept as documentation of the hostname and makes the config self-describing.

Step 4. When the public certificate is renewed, replace cert_file and key_file on disk and restart Akāmu (or send SIGHUP if live reload is supported by your deployment).

Mode 4 — Mutual TLS (mTLS)

Mutual TLS requires every connecting client to present a certificate signed by a trusted CA. This is useful for restricting access to the ACME server to known ACME agents or administrative tooling.

The TLS handshake enforces client authentication before any HTTP request is processed. A client that presents no certificate or an untrusted certificate receives a TLS handshake error — not an ACME-level error response.

Step 1. Decide on a client CA. This can be the Akāmu CA itself (so that only clients holding Akāmu-issued certificates may connect) or a separate private CA dedicated to client authentication. The CA certificate(s) must be available as PEM files on the Akāmu host.

Step 2. Add a [tls.client_auth] section. For a private PKI use profile = "rfc5280" to avoid CAB Forum restrictions that do not apply to internally-issued certificates.

listen_addr = "0.0.0.0:8443"
base_url    = "https://akamu.internal:8443"

[tls]
enabled   = true
cert_file = "/etc/akamu/server.crt"
key_file  = "/etc/akamu/server.key"

[tls.client_auth]
required = true
ca_files = ["/etc/akamu/client-ca.crt"]
profile  = "rfc5280"

Step 3. Test with curl, supplying both a CA bundle for server certificate verification and a client certificate with its key:

curl --cacert /etc/akamu/ca.cert.pem \
     --cert   client.crt \
     --key    client.key \
     https://akamu.internal:8443/acme/directory

Step 4. Understand the failure modes. When a client connects without a certificate or with a certificate that does not chain to the configured ca_files, the TLS handshake is aborted. The client sees a TLS alert (for example handshake failure or certificate required), not an HTTP 4xx response. Check the Akāmu log for client cert verification failed: … to diagnose chain or profile issues.

Minimal configuration

[tls]
enabled   = true
cert_file = "/etc/akamu/server.crt"   # PEM chain: leaf cert first, then intermediates/CA
key_file  = "/etc/akamu/server.key"   # PEM private key (PKCS#8 or SEC1, unencrypted)

If both cert_file and key_file are absent when the server starts, Akāmu auto-generates a server certificate signed by the Akāmu CA and writes both files. This makes the first-run experience zero-configuration: any client that already trusts the Akāmu CA will also trust the TLS channel.

If only one of the two files exists, startup fails with an explicit error.

Certificate and key format

• cert_file: PEM file with one or more -----BEGIN CERTIFICATE----- blocks. The leaf certificate must come first; intermediate and root certificates follow in order. When Akāmu generates the file it writes <leaf>\n<CA> automatically.

• key_file: PEM file with a single private key — -----BEGIN PRIVATE KEY----- (PKCS#8) or -----BEGIN EC PRIVATE KEY----- (SEC1). The file must be unencrypted (no passphrase). Akāmu never reads an encrypted key file.

Full [tls] field reference

[tls]
# Whether to enable native TLS.  Default: false.
enabled = true

# PEM file with the server certificate chain (leaf first).
cert_file = "/etc/akamu/server.crt"

# PEM file with the server private key (unencrypted PKCS#8 or SEC1).
key_file = "/etc/akamu/server.key"

# TLS protocol versions to accept.  Default: ["TLSv1.2", "TLSv1.3"].
protocols = ["TLSv1.3"]

# Hostname placed in CN and SAN of the auto-generated server certificate.
# Only used when cert_file/key_file are both absent.  Default: "localhost".
server_name = "akamu.internal"

# Key algorithm for the auto-generated server certificate.
# Accepted values: "ec:P-256", "ec:P-384", "ec:P-521",
#                  "rsa:2048", "rsa:3072", "rsa:4096", "ed25519", "ed448".
# Default: "ec:P-256".
bootstrap_key_type = "ec:P-256"

Mutual TLS client certificate authentication

[tls.client_auth] enables mTLS: Akāmu requests a client certificate and validates the chain against a configurable set of trusted CAs.

[tls.client_auth]
# Reject connections that present no client certificate.  Default: false.
required = true

# PEM files containing trusted root CA certificates.
# Each file may contain multiple PEM blocks.
ca_files = [
    "/etc/akamu/client-ca.crt",
]

# Validation profile: "webpki" (CAB Forum) or "rfc5280".  Default: "webpki".
profile = "webpki"

# Allow ML-DSA / composite post-quantum algorithms in client cert chains.
# Default: false.
allow_post_quantum = false

# Maximum certificate chain depth (leaf not counted).  Default: 8.
max_chain_depth = 8

# Minimum RSA modulus size in bits.  Default: 2048.
minimum_rsa_modulus = 2048

profile — CAB Forum vs RFC 5280

Post-quantum support (allow_post_quantum = true)

When enabled, Akāmu accepts:

• Pure ML-DSA certificate chains: verified via the OpenSSL backend.
• Composite ML-DSA+classical TLS 1.3 CertificateVerify signatures: provisional code points from draft-reddy-tls-composite-mldsa are advertised and verified.

Classical algorithms are always verified using a standard cryptographic backend. Composite schemes are TLS 1.3 only and never appear in a TLS 1.2 handshake.

Full annotated example with mTLS

[server]
listen_addr = "0.0.0.0:8443"
base_url    = "https://akamu.internal:8443"

[tls]
enabled             = true
cert_file           = "/etc/akamu/server.crt"
key_file            = "/etc/akamu/server.key"
protocols           = ["TLSv1.3"]
server_name         = "akamu.internal"
bootstrap_key_type  = "ec:P-384"

[tls.client_auth]
required           = true
ca_files           = ["/etc/akamu/client-ca.crt", "/etc/akamu/sub-ca.crt"]
profile            = "rfc5280"
allow_post_quantum = true
max_chain_depth    = 5
minimum_rsa_modulus = 3072

Known limitations

• Composite scheme code points: the TLS SignatureScheme code points for composite ML-DSA+classical schemes are provisional values from draft-reddy-tls-composite-mldsa (all TBD pending IANA allocation). The corresponding X.509 OIDs are defined in draft-ietf-lamps-pq-composite-sigs. If assigned code points differ from the provisional values used here, a code update will be required before deploying to production.

• Composite scheme support depends on the OpenSSL version: composite ML-DSA+classical CertificateVerify verification requires OpenSSL 3.5 or later with composite NID support. If the installed OpenSSL version does not support the required NIDs, verification will return an OpenSSL error at runtime.

• Pure ML-DSA TLS signature schemes: no IANA code points exist yet for standalone ML-DSA (non-composite) TLS schemes. Even with allow_post_quantum = true, only composite schemes are advertised.

• Client remote address: when native TLS is active, the client’s remote IP address is available to handlers through the standard axum connection-info mechanism.

Troubleshooting

Performance

This chapter covers issuance throughput and latency characteristics of Akāmu under load, with guidance on key type selection, connection pool tuning, and capacity planning.

All numbers were collected on a single host — Intel Core i7-12800H (14 cores / 20 threads, 63 GB RAM, Fedora Linux 6.15, OpenSSL 3.5.6) — using the acme-bench tool in two modes:

• Process mode (--spawn process): the server runs as a separate OS process with its own Tokio runtime, memory allocator, and SQLite :memory: database. This matches how a real deployment behaves. Heap allocation numbers reflect the client side only.
• Inprocess mode (default): server and clients share a single process. This mode enables SQLite backend, connection pool, and read-only pool split benchmarks that require shared-process access to the database layer. Heap allocation numbers include both client and server.

Audit events are written to a JSONL file (/tmp/akamu-bench-audit.jsonl) in both modes.

The benchmark runs full ACME workflows (new-order → authz → challenge validate → finalize → certificate download). Latency is end-to-end wall time from new-order through certificate download; account creation is amortised and excluded. Default configuration uses ec:P-256 client keys, ec:P-256 CA key, and http-01 challenge.

The full benchmark suite can be run with contrib/performance/run_benchmarks.sh, which writes newline-delimited JSON results to a file for post-processing. Set SPAWN_MODE="--spawn process" to run the suite in process mode.

Concurrency

With ec:P-256 certificates, http-01 validation, and SQLite :memory:, throughput peaks at 5–10 concurrent clients in both modes and degrades under higher concurrency as queue depth grows.

Process mode

Inprocess mode

Phase columns show mean milliseconds per ACME step.

Process mode peaks at c=5–10 (975–1,098 iss/s) with sub-9 ms mean latency, driven by read-only pool separation, crypto caching, and spawn_blocking for certificate signing. Inprocess mode peaks at c=5–25 (818–889 iss/s). Process mode shows lower download times (0.2 ms vs 1–6 ms) because certificate delivery bypasses the shared-process HTTP stack. Inprocess mode shows higher authz and download overhead at high concurrency due to Tokio task contention within the single runtime.

Client key type

The client key type is the largest single determinant of per-issuance latency. All runs use ec:P-256 CA; process mode uses 25 concurrent clients, inprocess mode uses 50.

Process mode

Inprocess mode

In process mode ed25519 and ec:P-256 are effectively tied (~33 ms, 556–561 iss/s). ML-DSA variants perform well: ML-DSA-44 at 523 iss/s is only 6% slower than ec:P-256. EC P-384 is consistently slower than ML-DSA-87 in both modes due to its heavier finalize cost.

RSA 2048 is 3.6–4.7× slower than ec:P-256; RSA 4096 at ~1,160 ms mean is dominated entirely by key generation.

RSA 4096 is strongly discouraged for ACME clients in multi-client deployments.

RSA 4096 saturation

RSA 4096 key generation is CPU-wall-limited. Adding concurrency barely improves throughput while latency grows linearly.

Process mode