Introduction

kipuka (Hawaiian) — an area of older land surrounded by younger lava flows; an island of stability in a landscape of constant change.

kipuka is a Rust-based EST (Enrollment over Secure Transport) server that issues and renews X.509 certificates at scale. It targets environments where compliance, high availability, and hardware-backed key protection are non-negotiable: government enclaves, regulated enterprise networks, IoT device fleets, and zero-trust architectures.

What kipuka does

• Certificate enrollment and renewal — full RFC 7030 EST implementation including /cacerts, /simpleenroll, /simplereenroll, /serverkeygen, /fullcmc, and /csrattrs.
• Multi-CA high availability — route enrollment requests to different Certificate Authorities based on EST labels, with automatic failover.
• HSM integration — PKCS #11 support via cryptoki for hardware-backed CA signing keys (Thales Luna, YubiHSM 2, SoftHSM, and others).
• One-time password enrollment — generate and validate OTPs through the admin API for initial device bootstrapping.
• Profile-based routing — EST labels map incoming requests to specific CA configurations, certificate profiles, and policy sets.
• Audit logging — structured, tamper-evident logs suitable for NIAP and CA/Browser Forum audit requirements.
• Dogtag PKI back-end — delegate signing to a Red Hat Certificate System / Dogtag PKI instance when full CA lifecycle management is needed.
• CoAP transport — constrained-device enrollment over RFC 7252 (CoAP) for IoT environments with limited bandwidth.

What kipuka does not do

• Full CA lifecycle management — kipuka is an enrollment front-end, not a complete CA. It delegates signing to local key material, an HSM, or a back-end CA such as Dogtag PKI. It does not manage CRL publication, OCSP responders, or CA key ceremonies.
• ACME — kipuka implements EST, not ACME (RFC 8555). Use a dedicated ACME server if your clients speak that protocol.
• Certificate transparency — kipuka does not submit pre-certificates to CT logs. Pair it with a CT-aware CA if your trust model requires it.
• End-entity key management — private keys for enrolled devices are generated client-side (or via /serverkeygen). kipuka never stores end-entity private keys beyond the lifetime of a single request.

Technology stack

Standards implemented

kipuka targets conformance with the following specifications:

Who this documentation is for

This book is organized for three audiences:

1. Operators — you deploy, configure, and maintain kipuka in production. Start with the Quick Start and then read the Operator Guide for the full configuration reference, HA setup, HSM integration, and audit logging.

2. API integrators — you write client software that enrolls certificates through kipuka. The API Reference documents every endpoint, request format, and response code. The Your First Certificate walkthrough gives you a working example in five minutes.

3. Contributors — you want to build kipuka from source, run the test suite, or submit patches. The Developer Guide covers the workspace layout, architecture decisions, database migrations, and contribution process.

Quick navigation

Installation

This page covers every way to get kipuka running: pulling a pre-built container image, building from source, and installing as a systemd service.

Prerequisites

Container (fastest)

Pre-built images are published to quay.io for both x86_64 and aarch64:

# x86_64 (default)
podman pull quay.io/kipuka/kipuka:latest

# Apple Silicon / ARM servers
podman pull quay.io/kipuka/kipuka:latest-arm64

Run the container with a bind-mounted configuration directory:

podman run -d \
  --name kipuka \
  -p 9443:9443 \
  -v /etc/kipuka:/etc/kipuka:ro \
  -v /var/lib/kipuka:/var/lib/kipuka:rw \
  quay.io/kipuka/kipuka:latest \
  kipuka --config /etc/kipuka/kipuka.toml

The container image ships a minimal filesystem. All state lives in /var/lib/kipuka (database, OTP records) and all configuration is read from /etc/kipuka. TLS certificates and CA key material are expected under /etc/kipuka/tls/ and /etc/kipuka/ca/ respectively.

Tip: For Kubernetes or OpenShift deployments, mount the configuration as a ConfigMap and secrets (TLS keys, CA keys) as Secret volumes.

Building from source

Clone the repository and build in release mode:

git clone https://codeberg.org/czinda/kipuka.git
cd kipuka
cargo build --release

The workspace contains six crates:

The final binary is at target/release/kipuka.

OS-specific build dependencies

Fedora / RHEL / CentOS Stream

sudo dnf install openssl-devel clang cmake pkg-config

Debian / Ubuntu

sudo apt install libssl-dev clang cmake pkg-config

macOS

brew install openssl cmake
export OPENSSL_DIR=$(brew --prefix openssl)

Installing the binary

Copy the release binary to a location on $PATH:

sudo cp target/release/kipuka /usr/local/bin/
sudo chmod 755 /usr/local/bin/kipuka

Verify the installation:

kipuka --version

systemd service

Create a dedicated service account:

sudo useradd -r -s /sbin/nologin -d /var/lib/kipuka kipuka
sudo mkdir -p /var/lib/kipuka /var/log/kipuka /etc/kipuka
sudo chown kipuka:kipuka /var/lib/kipuka /var/log/kipuka

Install the unit file at /etc/systemd/system/kipuka.service:

[Unit]
Description=kipuka EST enrollment server
Documentation=https://codeberg.org/czinda/kipuka
After=network-online.target
Wants=network-online.target

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

# Security hardening
PrivateTmp=true
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectControlGroups=true
ReadWritePaths=/var/lib/kipuka /var/log/kipuka
CapabilityBoundingSet=CAP_NET_BIND_SERVICE
AmbientCapabilities=CAP_NET_BIND_SERVICE

# Logging
StandardOutput=journal
StandardError=journal
SyslogIdentifier=kipuka

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable --now kipuka
sudo systemctl status kipuka

Note: The CAP_NET_BIND_SERVICE capability allows kipuka to bind to port 443 without running as root. If you run on a high port (e.g., 9443) you can remove both CapabilityBoundingSet and AmbientCapabilities lines.

Running tests

The full test suite runs against an in-memory SQLite database and does not require any external services:

cargo test

To run tests for a specific crate:

cargo test -p kipuka-est
cargo test -p kipuka-hsm

Integration tests that require a running EST server are gated behind a feature flag:

cargo test --features integration

Next: First Run walks you through creating a minimal configuration and starting the server.

First Run

This guide takes you from a freshly installed kipuka binary to a running EST server responding to /cacerts requests. By the end you will have a working server with a self-signed CA suitable for development and testing.

Step 1: Create directories and service account

sudo mkdir -p /etc/kipuka/{tls,ca}
sudo mkdir -p /var/lib/kipuka
sudo mkdir -p /var/log/kipuka
sudo useradd -r -s /sbin/nologin -d /var/lib/kipuka kipuka
sudo chown kipuka:kipuka /var/lib/kipuka /var/log/kipuka

Step 2: Generate test certificates

The repository includes a helper script that creates a complete test PKI:

./contrib/local-dev/setup-ca.sh

This generates a root CA, a server TLS certificate, and a client certificate under contrib/local-dev/pki/. Copy the relevant files:

sudo cp contrib/local-dev/pki/ca.pem /etc/kipuka/ca/ca.pem
sudo cp contrib/local-dev/pki/ca-key.pem /etc/kipuka/ca/ca-key.pem
sudo cp contrib/local-dev/pki/server.pem /etc/kipuka/tls/server.pem
sudo cp contrib/local-dev/pki/server-key.pem /etc/kipuka/tls/server-key.pem

Manual certificate generation

If you prefer to create certificates by hand:

# Root CA
openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:P-256 \
  -keyout /etc/kipuka/ca/ca-key.pem \
  -out /etc/kipuka/ca/ca.pem \
  -days 3650 -nodes \
  -subj "/CN=kipuka Test CA"

# Server TLS certificate
openssl req -newkey ec -pkeyopt ec_paramgen_curve:P-256 \
  -keyout /etc/kipuka/tls/server-key.pem \
  -out /tmp/server.csr -nodes \
  -subj "/CN=localhost"

openssl x509 -req -in /tmp/server.csr \
  -CA /etc/kipuka/ca/ca.pem \
  -CAkey /etc/kipuka/ca/ca-key.pem \
  -CAcreateserial \
  -out /etc/kipuka/tls/server.pem \
  -days 365 \
  -extfile <(printf "subjectAltName=DNS:localhost,IP:127.0.0.1")

rm /tmp/server.csr

Set restrictive permissions on key material:

sudo chmod 600 /etc/kipuka/ca/ca-key.pem /etc/kipuka/tls/server-key.pem
sudo chown kipuka:kipuka /etc/kipuka/ca/* /etc/kipuka/tls/*

Step 3: Write a minimal configuration

Create /etc/kipuka/kipuka.toml:

[server]
listen = "0.0.0.0:9443"

[tls]
cert = "/etc/kipuka/tls/server.pem"
key = "/etc/kipuka/tls/server-key.pem"

[tls.client_auth]
# Trust anchor for EST client certificate authentication.
# Clients presenting a certificate signed by this CA are
# permitted to re-enroll without an OTP.
trust_anchors = ["/etc/kipuka/ca/ca.pem"]

[db]
# SQLite for development.  Use a PostgreSQL URL for production.
url = "sqlite:///var/lib/kipuka/kipuka.db?mode=rwc"

[[ca]]
id = "default"
cert = "/etc/kipuka/ca/ca.pem"
key = "/etc/kipuka/ca/ca-key.pem"

# Optional: restrict which subject names this CA will sign.
# allowed_subjects = ["CN=*"]

# Optional: set a default certificate validity period.
# validity_days = 365

Production note: For production deployments, replace the [db] URL with a PostgreSQL connection string and store CA keys in an HSM. See the Configuration Reference for the full set of options.

Step 4: Run database migrations

kipuka manages its own schema. Run the migration command before the first start:

sudo -u kipuka kipuka migrate --config /etc/kipuka/kipuka.toml

Expected output:

Applied 3 migrations to sqlite:///var/lib/kipuka/kipuka.db

Step 5: Start the server

Start kipuka in the foreground to verify everything works:

sudo -u kipuka kipuka --config /etc/kipuka/kipuka.toml

You should see log output similar to:

2026-06-24T12:00:00.000Z  INFO kipuka::server: kipuka v0.1.0 starting
2026-06-24T12:00:00.001Z  INFO kipuka::tls: TLS configured, client auth enabled
2026-06-24T12:00:00.002Z  INFO kipuka::ca: Loaded CA "default" (CN=kipuka Test CA)
2026-06-24T12:00:00.003Z  INFO kipuka::db: Database connected (sqlite)
2026-06-24T12:00:00.004Z  INFO kipuka::server: Listening on 0.0.0.0:9443

Press Ctrl+C to stop. For long-running deployments, use the systemd service instead.

Step 6: Verify the EST endpoint

The /cacerts endpoint returns the CA certificate(s) without requiring client authentication. Use it to confirm the server is responding:

curl -sk https://localhost:9443/.well-known/est/cacerts \
  | base64 -d \
  | openssl pkcs7 -inform DER -print_certs

You should see the PEM-encoded CA certificate:

subject=CN = kipuka Test CA
issuer=CN = kipuka Test CA
-----BEGIN CERTIFICATE-----
MIIBkTCB+...
-----END CERTIFICATE-----

If this works, your server is ready to issue certificates.

Logging

kipuka uses Rust’s tracing framework. Control verbosity with the RUST_LOG environment variable:

To set the log level when running directly:

RUST_LOG=debug kipuka --config /etc/kipuka/kipuka.toml

For the systemd service, add an environment override:

sudo systemctl edit kipuka

[Service]
Environment="RUST_LOG=debug"

Next: Your First Certificate walks through the complete enrollment flow — generating an OTP, submitting a CSR, and extracting the signed certificate.

Your First Certificate

This guide walks through a complete EST enrollment cycle: generating a one-time password, creating a certificate signing request, enrolling through the EST endpoint, and verifying the result. By the end you will have a signed X.509 certificate issued by your kipuka server.

Prerequisites: A running kipuka instance from the First Run guide and the CA certificate saved as ca.pem.

Step 1: Generate a one-time password

kipuka authenticates initial enrollment requests with a one-time password (OTP). Generate one through the admin API:

curl -sk -X POST https://localhost:9443/admin/otp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"entity_id": "test-device"}'

Response:

{
  "entity_id": "test-device",
  "otp": "a1b2c3d4e5f6",
  "expires_at": "2026-06-25T12:00:00Z"
}

Save the OTP value:

OTP="a1b2c3d4e5f6"

Note: The admin API bearer token is configured in kipuka.toml under [admin]. See the Admin API Reference for details on token management.

Step 2: Generate a CSR

Create an EC P-256 key pair and a certificate signing request:

openssl req -new \
  -newkey ec -pkeyopt ec_paramgen_curve:P-256 \
  -keyout client.key \
  -out client.csr \
  -nodes \
  -subj "/CN=test-device"

This produces two files:

Tip: For production IoT devices, generate the key pair in a secure element or TPM and export only the CSR.

Step 3: Enroll with OTP

Submit the CSR to the EST /simpleenroll endpoint, authenticating with the entity ID and OTP as HTTP Basic credentials:

curl -sk \
  --cacert ca.pem \
  -u "test-device:${OTP}" \
  --data-binary @client.csr \
  -H "Content-Type: application/pkcs10" \
  -o cert.p7 \
  https://localhost:9443/.well-known/est/simpleenroll

The server returns a PKCS #7 (CMS) envelope containing the signed certificate in DER format, saved here as cert.p7.

If enrollment succeeds, the HTTP response code is 200. Common error codes:

Step 4: Extract the certificate

Convert the PKCS #7 envelope to PEM:

openssl pkcs7 -inform DER -in cert.p7 -print_certs -out client.pem

You now have the signed certificate in client.pem.

Step 5: Verify the certificate

Inspect the certificate details:

openssl x509 -in client.pem -text -noout

Expected output (abbreviated):

Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number: ...
        Signature Algorithm: ecdsa-with-SHA256
        Issuer: CN = kipuka Test CA
        Validity
            Not Before: Jun 24 12:00:00 2026 GMT
            Not After : Jun 24 12:00:00 2027 GMT
        Subject: CN = test-device
        Subject Public Key Info:
            Public Key Algorithm: id-ecPublicKey
                Public-Key: (256 bit)
                ...

Verify the certificate chains back to your CA:

openssl verify -CAfile ca.pem client.pem

client.pem: OK

Re-enrollment

Once a device holds a valid certificate, it can renew without an OTP by authenticating with TLS client certificate authentication. The EST /simplereenroll endpoint accepts the same CSR format:

# Generate a new CSR (optionally with a new key pair)
openssl req -new \
  -newkey ec -pkeyopt ec_paramgen_curve:P-256 \
  -keyout client-new.key \
  -out client-new.csr \
  -nodes \
  -subj "/CN=test-device"

# Re-enroll using the existing certificate for authentication
curl -sk \
  --cacert ca.pem \
  --cert client.pem \
  --key client.key \
  --data-binary @client-new.csr \
  -H "Content-Type: application/pkcs10" \
  -o cert-new.p7 \
  https://localhost:9443/.well-known/est/simplereenroll

Extract the renewed certificate:

openssl pkcs7 -inform DER -in cert-new.p7 -print_certs -out client-new.pem

Key rotation: The example above generates a fresh key pair during re-enrollment. This is recommended practice. If your use case requires keeping the same key, omit -newkey and pass the existing key with -key client.key.

EST labels: profile-based routing

kipuka supports EST labels (also called path segments) to route enrollment requests to different CA configurations or certificate profiles. The label appears in the URL path between /.well-known/est/ and the operation name.

For example, if you configure a label called iot-devices that maps to a dedicated CA and profile:

[[ca]]
id = "iot"
cert = "/etc/kipuka/ca/iot-ca.pem"
key = "/etc/kipuka/ca/iot-ca-key.pem"
label = "iot-devices"
validity_days = 90

Clients enroll against the labeled path:

curl -sk \
  --cacert iot-ca.pem \
  -u "sensor-001:${OTP}" \
  --data-binary @sensor.csr \
  -H "Content-Type: application/pkcs10" \
  -o sensor-cert.p7 \
  https://localhost:9443/.well-known/est/iot-devices/simpleenroll

The /cacerts endpoint also respects labels, returning only the CA certificate(s) for that label:

curl -sk https://localhost:9443/.well-known/est/iot-devices/cacerts \
  | base64 -d \
  | openssl pkcs7 -inform DER -print_certs

Labels are a powerful mechanism for multi-tenant and multi-profile deployments. See EST Labels in the Operator Guide for the complete configuration reference.

Summary

You have completed a full EST enrollment lifecycle:

1. Generated a one-time password via the admin API
2. Created a CSR with an EC P-256 key pair
3. Enrolled through /simpleenroll with OTP authentication
4. Extracted and verified the signed certificate
5. Learned how to re-enroll with certificate-based authentication
6. Explored label-based routing for multi-CA deployments

Next steps:

• Configuration Reference — explore every kipuka.toml option
• Authentication — configure client certificate auth policies
• HSM Integration — move CA keys into hardware
• Admin API Reference — full OTP and management API documentation

Configuration Reference

This document provides a complete reference for kipuka.toml, the main configuration file for the kipuka EST server.

Configuration Sections

[server]

Core server settings for HTTP/HTTPS listeners and runtime behavior.

[tls]

TLS configuration for the main EST endpoint.

[tls.client_auth]

Mutual TLS (mTLS) client authentication settings.

[db]

Database connection settings.

[[ca]]

Certificate Authority (CA) definitions. Multiple [[ca]] sections define multiple CAs.

[est]

EST protocol feature flags and global settings.

[[est.label]]

EST label definitions for CA-specific endpoints. Multiple [[est.label]] sections define multiple labels.

[hsm]

Hardware Security Module (HSM) configuration.

[otp]

One-Time Password (OTP) authentication for initial enrollment.

[audit]

Audit logging configuration.

[ha]

High Availability configuration for CA failover.

[[ha.group]]

HA groups for label-specific CA failover. Multiple [[ha.group]] sections define multiple groups.

[admin]

Administrative API configuration.

Configuration Examples

Minimal Configuration

A basic single-CA deployment with one EST label.

[server]
listen = "0.0.0.0:8443"

[tls]
cert = "/etc/kipuka/server.pem"
key = "/etc/kipuka/server-key.pem"

[tls.client_auth]
trust_anchors = "/etc/kipuka/client-ca.pem"
mode = "required"

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

[[ca]]
id = "main-ca"
name = "Main CA"
cert = "/etc/kipuka/ca.pem"
key = "/etc/kipuka/ca-key.pem"
validity_days = 365
max_validity_days = 398

[est]
base_path = "/.well-known/est"

[[est.label]]
name = "default"
ca_id = "main-ca"
require_san = true

Production Configuration

A realistic production deployment with HSM, HA, audit logging, admin API, OTP, and multiple CAs.

[server]
listen = "0.0.0.0:8443"
admin_listen = "127.0.0.1:9443"
workers = 8
max_body_size = "2MB"
shutdown_timeout = "60s"

[tls]
cert = "/etc/kipuka/certs/server.pem"
key = "/etc/kipuka/certs/server-key.pem"
min_version = "1.3"

[tls.client_auth]
trust_anchors = "/etc/kipuka/certs/client-ca-bundle.pem"
mode = "required"

[db]
url = "postgres://kipuka:[email protected]/kipuka?sslmode=require"
max_connections = 20
connect_timeout = "10s"
auto_migrate = true

[hsm]
library = "/usr/lib/softhsm/libsofthsm2.so"
slot = 0
token_label = "kipuka-prod"
pin_env = "KIPUKA_HSM_PIN"

[[ca]]
id = "root-ca"
name = "Production Root CA"
cert = "/etc/kipuka/ca/root-ca.pem"
key = "pkcs11:object=root-ca-key"
chain = "/etc/kipuka/ca/root-chain.pem"
validity_days = 365
max_validity_days = 398
default_key_usage = ["digitalSignature", "keyEncipherment"]
default_ext_key_usage = ["serverAuth", "clientAuth"]
hsm_slot = 0

[[ca]]
id = "backup-ca"
name = "Production Backup CA"
cert = "/etc/kipuka/ca/backup-ca.pem"
key = "pkcs11:object=backup-ca-key"
chain = "/etc/kipuka/ca/backup-chain.pem"
validity_days = 365
max_validity_days = 398
default_key_usage = ["digitalSignature", "keyEncipherment"]
default_ext_key_usage = ["serverAuth", "clientAuth"]
hsm_slot = 1

[[ca]]
id = "iot-ca"
name = "IoT Device CA"
cert = "/etc/kipuka/ca/iot-ca.pem"
key = "pkcs11:object=iot-ca-key"
validity_days = 180
max_validity_days = 180
default_key_usage = ["digitalSignature"]
default_ext_key_usage = ["clientAuth"]
hsm_slot = 2

[est]
base_path = "/.well-known/est"
cacerts = true
simpleenroll = true
simplereenroll = true
fullcmc = false
serverkeygen = false
csrattrs = true
csr_attributes = ["2.5.4.3", "2.5.4.11"]
retry_after = 120

[[est.label]]
name = "servers"
ca_id = "root-ca"
allowed_key_types = ["rsa-2048", "rsa-4096", "ecdsa-p256"]
required_ext_key_usage = ["serverAuth"]
max_validity_days = 398
require_san = true
subject_pattern = "^CN=.*\\.example\\.com$"

[[est.label]]
name = "clients"
ca_id = "root-ca"
allowed_key_types = ["ecdsa-p256", "ecdsa-p384"]
required_ext_key_usage = ["clientAuth"]
max_validity_days = 365
require_san = true

[[est.label]]
name = "iot"
ca_id = "iot-ca"
allowed_key_types = ["ecdsa-p256"]
required_ext_key_usage = ["clientAuth"]
max_validity_days = 180
require_san = false

[otp]
enabled = true
token_length = 20
default_ttl = "24h"
max_uses = 1
hash_algorithm = "argon2id"
max_failures = 5
failure_window = "15m"
lockout_duration = "30m"

[audit]
file = "/var/log/kipuka/audit.jsonl"
syslog = "tcp+tls://syslog.example.com:6514"
syslog_facility = "local0"
events = ["enroll", "renew", "reject", "revoke"]
include_cert_data = false

[ha]
enabled = true
strategy = "active-passive"
check_interval = "10s"
failure_threshold = 3
recovery_timeout = "60s"
check_timeout = "5s"

[[ha.group]]
name = "production"
ca_ids = ["root-ca", "backup-ca"]
strategy = "active-passive"

[[ha.group]]
name = "iot"
ca_ids = ["iot-ca"]
strategy = "active-passive"

[admin]
enabled = true
auth = "both"
trust_anchors = "/etc/kipuka/certs/admin-ca.pem"
bearer_token_env = "KIPUKA_ADMIN_TOKEN"

Notes

• Security: Never commit kipuka.toml with plaintext secrets to version control. Use environment variables or HSM-backed keys.
• Validation: kipuka validates the configuration at startup and reports errors for missing required fields or invalid values.
• Reloading: Configuration changes require a server restart. Plan maintenance windows for production deployments.
• HSM Keys: When using HSM-backed CA keys, specify key as a PKCS#11 URI (e.g., pkcs11:object=my-key) and ensure hsm_slot matches the token slot.
• NIAP Compliance: For NIAP Common Criteria compliance, ensure otp.token_length >= 16, tls.min_version = "1.3", and ca.max_validity_days <= 398.

Certificate Authorities

kipuka supports multiple Certificate Authorities (CAs) through its [[ca]] array configuration. This architecture enables operators to serve different trust domains, key algorithms, and PKI hierarchies from a single EST server instance.

Multi-CA Architecture

Each CA in kipuka is defined by a unique id field used to bind EST labels to specific certificate authorities. Multiple CAs are configured in kipuka.toml:

[[ca]]
id = "internal-rsa"
cert = "/etc/kipuka/ca/internal-rsa-ca.crt"
key = "/etc/kipuka/ca/internal-rsa-ca.key"
chain = "/etc/kipuka/ca/internal-rsa-chain.pem"
max_validity_days = 90

[[ca]]
id = "external-ecdsa"
cert = "/etc/kipuka/ca/external-ecdsa-ca.crt"
key = "/etc/kipuka/ca/external-ecdsa-ca.key"
chain = "/etc/kipuka/ca/external-ecdsa-chain.pem"
max_validity_days = 90

Use Cases for Multiple CAs

Separate Trust Domains: Internal infrastructure certificates from one CA, external-facing services from another. This isolation prevents compromise of one domain from affecting the other.

Algorithm Migration: Run both RSA and ECDSA CAs simultaneously to support legacy clients while transitioning to modern algorithms.

Tiered Assurance Levels: Different CAs for different assurance requirements (standard validation vs. extended validation, different key sizes).

Geographic or Organizational Boundaries: Separate CAs for different regions or business units within an organization.

Development vs. Production: Dedicated CAs for testing environments prevent accidental trust of development certificates in production.

CA Lifecycle

Creating a Root CA

Generate a self-signed root CA private key and certificate:

# RSA 4096-bit root CA
openssl genrsa -out root-ca.key 4096
openssl req -new -x509 -days 7300 -key root-ca.key -out root-ca.crt \
  -subj "/C=US/O=Example Corp/CN=Example Root CA"

# ECDSA P-384 root CA
openssl ecparam -name secp384r1 -genkey -noout -out root-ca.key
openssl req -new -x509 -days 7300 -key root-ca.key -out root-ca.crt \
  -subj "/C=US/O=Example Corp/CN=Example Root CA"

Root CAs typically have 10-20 year validity periods and are kept offline. The root private key should be stored in secure offline storage (HSM, encrypted media in a safe).

Creating an Intermediate CA

Generate an intermediate CA signed by the root:

# Generate intermediate CA private key
openssl ecparam -name prime256v1 -genkey -noout -out intermediate-ca.key

# Create CSR for intermediate CA
openssl req -new -key intermediate-ca.key -out intermediate-ca.csr \
  -subj "/C=US/O=Example Corp/CN=Example Issuing CA"

# Sign intermediate CSR with root CA (5 year validity)
openssl x509 -req -in intermediate-ca.csr -CA root-ca.crt -CAkey root-ca.key \
  -CAcreateserial -out intermediate-ca.crt -days 1825 \
  -extensions v3_ca -extfile openssl-ca.cnf

The openssl-ca.cnf must include intermediate CA extensions:

[v3_ca]
basicConstraints = critical,CA:TRUE,pathlen:0
keyUsage = critical,keyCertSign,cRLSign
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always

Building the Certificate Chain

The chain file contains certificates from the issuing CA up to (but typically not including) the root:

# Create chain file (intermediate only, root excluded)
cat intermediate-ca.crt > chain.pem

# If there are multiple intermediates, order from issuing CA to root:
# cat issuing-intermediate.crt sub-intermediate.crt > chain.pem

Chain ordering is critical: the first certificate in the chain must be the issuer of the end-entity certificate, and each subsequent certificate must be the issuer of the previous one.

Configuring kipuka to Use the Intermediate

[[ca]]
id = "prod-issuing-ca"
cert = "/etc/kipuka/ca/intermediate-ca.crt"
key = "/etc/kipuka/ca/intermediate-ca.key"
chain = "/etc/kipuka/ca/chain.pem"
max_validity_days = 90

The /cacerts endpoint returns the intermediate certificate plus the chain (but not the root). Clients must have the root CA in their trust store independently.

Key Types and Recommendations

RSA Keys

# RSA 2048-bit (legacy compatibility)
openssl genrsa -out ca-rsa2048.key 2048

# RSA 3072-bit (transitional strength)
openssl genrsa -out ca-rsa3072.key 3072

# RSA 4096-bit (high assurance, slower)
openssl genrsa -out ca-rsa4096.key 4096

RSA 2048: Minimum for legacy compatibility. Acceptable for short-lived certificates (under 100 days). Avoid for new deployments.

RSA 3072: Equivalent security to AES-128. Reasonable choice for transitional deployments.

RSA 4096: Equivalent security to AES-256. Use for long-lived root CAs. Performance penalty for signing and verification operations.

ECDSA Keys

# NIST P-256 (secp256r1, prime256v1)
openssl ecparam -name prime256v1 -genkey -noout -out ca-p256.key

# NIST P-384 (secp384r1)
openssl ecparam -name secp384r1 -genkey -noout -out ca-p384.key

# NIST P-521 (secp521r1)
openssl ecparam -name secp521r1 -genkey -noout -out ca-p521.key

P-256 (prime256v1): Recommended for general use. Equivalent security to AES-128. Wide client support, fast operations, small certificate size.

P-384: Equivalent security to AES-192. Use for high-assurance environments. Moderate performance impact.

P-521: Equivalent security to AES-256. Use for maximum security requirements. Larger certificates and slower operations than P-256.

Algorithm Selection Guidance

For new deployments, prefer ECDSA P-256 unless specific requirements dictate otherwise:

• Smaller key and certificate sizes reduce bandwidth
• Faster signing and verification operations
• Equivalent or better security than RSA 2048
• Supported by all modern clients (TLS 1.2+, most TLS 1.3 implementations)

Use RSA 2048 only when legacy client compatibility is required (older embedded devices, Windows XP, ancient Java versions).

Use P-384 or RSA 4096 for root CAs in high-assurance environments where the performance penalty is acceptable.

HSM-Backed vs File-Based Keys

File-Based Keys

File-based keys are stored as PEM-encoded files on the filesystem:

[[ca]]
id = "file-based-ca"
cert = "/etc/kipuka/ca/ca.crt"
key = "/etc/kipuka/ca/ca.key"
chain = "/etc/kipuka/ca/chain.pem"
max_validity_days = 90

Advantages:

• Simple configuration and operation
• No additional hardware or drivers required
• Easy backup and disaster recovery
• Standard OpenSSL tooling for key generation

Disadvantages:

• Private key exists in cleartext on disk (even if file permissions are restrictive)
• Key compromise if filesystem is breached
• No audit trail for key usage
• Key can be copied without detection

Security Measures for File-Based Keys:

• Store keys on encrypted filesystems
• Use file permissions to restrict access (mode 0400, root-owned)
• Consider encrypted key files with passphrase protection (requires manual unlock on service start)
• Implement filesystem integrity monitoring (AIDE, Tripwire)
• Regular key rotation

HSM-Backed Keys

HSM-backed keys reference a PKCS#11 token and slot instead of filesystem paths:

[hsm]
module = "/usr/lib64/libsofthsm2.so"
pin = "1234"

[[ca]]
id = "hsm-backed-ca"
cert = "/etc/kipuka/ca/ca.crt"
hsm_slot = 0
chain = "/etc/kipuka/ca/chain.pem"
max_validity_days = 90

Advantages:

• Private key never leaves the HSM hardware
• Tamper-resistant hardware with physical security controls
• Audit logging of all key usage operations
• FIPS 140-2/140-3 compliance available
• Key backup and recovery through HSM vendor mechanisms

Disadvantages:

• Additional hardware cost and complexity
• PKCS#11 driver setup and maintenance
• Potential performance bottleneck for high-volume signing
• Vendor lock-in for key backup/recovery
• Operational complexity (HSM initialization, token management, PIN management)

HSM Selection Considerations:

Network HSMs (Thales Luna, Entrust nShield) provide centralized key management and high availability but introduce network dependencies.

USB HSMs (YubiHSM, Nitrokey HSM) offer lower cost and simpler deployment but limited performance and single points of failure.

Software HSMs (SoftHSM) provide PKCS#11 API compatibility for testing but offer no security advantage over file-based keys.

For production issuing CAs, network HSMs are recommended. For offline root CAs, USB HSMs stored in physically secure locations are acceptable.

Certificate Chain Configuration

The chain parameter provides the certificate chain from the issuing CA to the root (root typically excluded). This chain is returned via the /cacerts endpoint.

Chain File Format

Chain files are PEM-encoded, containing one or more certificates. Order matters:

-----BEGIN CERTIFICATE-----
[Issuing Intermediate CA Certificate]
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
[Sub-Intermediate CA Certificate, if any]
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
[Root CA Certificate - optional, often excluded]
-----END CERTIFICATE-----

Chain Ordering Rules

1. First certificate is the issuer of the end-entity certificates that the CA signs
2. Each subsequent certificate is the issuer of the previous certificate
3. Last certificate is either the root CA or the certificate directly issued by the root
4. Root CA is often excluded from the chain (clients must have it in their trust store)

Why Exclude the Root CA

Most TLS/PKI implementations expect clients to have the root CA in their local trust store. Including the root in the chain:

• Increases bandwidth unnecessarily
• May cause validation issues with strict clients
• Violates some certificate profile specifications

However, some closed environments include the root in the chain for convenience. kipuka supports both approaches.

Verifying Chain Correctness

# Verify the intermediate can be validated against the root
openssl verify -CAfile root-ca.crt intermediate-ca.crt

# Verify the complete chain
openssl verify -CAfile root-ca.crt -untrusted chain.pem end-entity.crt

Multiple Intermediate Levels

For deep hierarchies (root -> policy CA -> issuing CA):

# Build chain with two intermediates
cat issuing-ca.crt policy-ca.crt > chain.pem

# Root CA is still excluded

kipuka returns the issuing CA certificate concatenated with the chain file contents via /cacerts.

CA/B Forum Validity Limits

The CA/Browser Forum mandates maximum validity periods for publicly-trusted certificates. These limits progressively shorten:

Configuring max_validity_days

The max_validity_days parameter in each [[ca]] section enforces these limits:

[[ca]]
id = "public-ca-2026"
cert = "/etc/kipuka/ca/ca.crt"
key = "/etc/kipuka/ca/ca.key"
chain = "/etc/kipuka/ca/chain.pem"
max_validity_days = 200  # Ready for March 2026 limit

kipuka rejects CSRs requesting validity beyond max_validity_days. Clients must request shorter lifetimes or accept the CA’s default.

Planning for Shorter Lifetimes

March 2026 (200 days): Transition to quarterly certificate renewal cycles. Most organizations can adapt existing manual processes.

March 2027 (100 days): Manual renewal becomes impractical. EST-based automation is essential. Plan for 90-day certificate lifetimes to allow renewal buffer.

March 2029 (47 days): Monthly or bi-weekly renewal cycles. Full automation required. No manual certificate issuance workflows can scale.

Why Shorter Lifetimes Drive EST Adoption

Reduced Blast Radius: Compromised keys have limited validity windows. Stolen certificates expire quickly.

Faster Cryptographic Agility: Transitioning to new algorithms (post-quantum cryptography) becomes operationally feasible when certificates renew frequently.

Improved Revocation Handling: Short lifetimes reduce reliance on CRL and OCSP infrastructure. Expired certificates are automatically untrusted.

Forcing Automation: Organizations must build robust certificate lifecycle management. This operational maturity pays dividends in incident response and compliance.

EST as the Solution: Manual CSR generation, approval workflows, and certificate installation cannot scale to 47-day lifetimes. EST provides:

• Automated enrollment via /simpleenroll
• Automated renewal via /simplereenroll
• Automated trust anchor updates via /cacerts
• Standard protocol implemented by network equipment, IoT devices, operating systems

Operational Recommendations

Set max_validity_days to 90 days for new CAs. This provides:

• Compliance with current and near-term CA/B Forum limits
• 30-day renewal buffer (renew at 60 days remaining)
• Operational experience with short-lived certificates before 47-day limit

For existing CAs, plan a staged reduction:

• 2026: 180 days
• 2027: 90 days
• 2029: 45 days

Use monitoring to track certificate expiration across your fleet. Alert when certificates are not renewed on schedule. EST’s /simplereenroll should be triggered automatically when 1/3 of the validity period remains.

Internal vs. Publicly-Trusted CAs

CA/B Forum limits apply only to publicly-trusted CAs (trust anchors in browser and OS trust stores). Internal CAs can use longer lifetimes:

[[ca]]
id = "internal-ca"
cert = "/etc/kipuka/ca/internal-ca.crt"
key = "/etc/kipuka/ca/internal-ca.key"
chain = "/etc/kipuka/ca/chain.pem"
max_validity_days = 365  # Internal CA, not subject to CA/B Forum

However, adopting short lifetimes even for internal CAs provides operational benefits (automation, reduced compromise windows) and prepares infrastructure for future regulatory requirements.

EST Labels

EST labels provide a powerful mechanism for operating multiple certificate profiles from a single EST server instance. This chapter covers label configuration, policy enforcement, and practical deployment patterns.

What Are EST Labels

RFC 7030 Section 3.2.2 defines EST path segments that enable certificate profile selection. The URL pattern for enrollment operations follows this structure:

/.well-known/est/<label>/simpleenroll
/.well-known/est/<label>/simplereenroll

When a client makes a request without a label (e.g., /.well-known/est/simpleenroll), the EST server applies its default certificate profile. Labels allow a single EST server to issue different types of certificates with different policies, CA issuers, and validation rules.

Common use cases include:

• Certificate purpose separation: Different labels for TLS server certificates, client authentication certificates, and code signing certificates
• Policy enforcement: Distinct labels enforcing different validity periods, key requirements, or subject naming constraints
• Multi-tenant operation: Separate labels for different organizational units or trust boundaries
• CA hierarchy management: Different labels issuing from different intermediate CAs within the same PKI

Label Configuration

Each [[est.label]] section in kipuka.toml defines a named profile. Labels are bound to specific CAs and enforce policy constraints on certificate issuance.

Full Label Syntax

[[est.label]]
# Unique label name used in EST URLs
name = "server-tls"

# CA ID reference (must match a [[ca]] entry)
ca_id = "intermediate-tls"

# Allowed CSR key types (optional)
# If omitted, all key types are accepted
allowed_key_types = ["ecdsaP256", "ecdsaP384", "rsa2048", "rsa3072"]

# Required Extended Key Usage OIDs (optional)
# Forces these EKUs into all issued certificates
required_ext_key_usage = ["serverAuth"]

# Maximum certificate validity in days (optional)
# Overrides CA default if set
max_validity_days = 398

# Require Subject Alternative Names (default: true)
require_san = true

# Subject DN validation regex (optional)
# CSRs must match this pattern to be accepted
subject_pattern = "^CN=[a-z0-9-]+\\.example\\.com(,.*)?$"

All fields except name and ca_id are optional. Without constraints, the label inherits behavior from the referenced CA.

CA Binding

Every label must reference a CA through ca_id. This CA identifier must match the id field of a [[ca]] entry defined elsewhere in kipuka.toml.

Multiple Labels, Same CA

Different labels can reference the same CA to provide different policy enforcement while using the same issuer:

[[ca]]
id = "corp-intermediate"
cert_path = "/etc/kipuka/pki/intermediate.crt"
key_path = "/etc/kipuka/pki/intermediate.key"
default_validity_days = 365

[[est.label]]
name = "server"
ca_id = "corp-intermediate"
required_ext_key_usage = ["serverAuth"]
max_validity_days = 398

[[est.label]]
name = "client"
ca_id = "corp-intermediate"
required_ext_key_usage = ["clientAuth"]
max_validity_days = 90
require_san = false

Both labels issue certificates from the same intermediate CA but enforce different EKUs, validity periods, and SAN requirements.

Multiple Labels, Different CAs

Labels can reference different CAs to support complex PKI hierarchies:

[[ca]]
id = "public-tls-ca"
cert_path = "/etc/kipuka/pki/public-tls-intermediate.crt"
key_path = "/etc/kipuka/pki/public-tls-intermediate.key"

[[ca]]
id = "internal-device-ca"
cert_path = "/etc/kipuka/pki/internal-device-intermediate.crt"
key_path = "/etc/kipuka/pki/internal-device-intermediate.key"

[[est.label]]
name = "public-server"
ca_id = "public-tls-ca"
required_ext_key_usage = ["serverAuth"]

[[est.label]]
name = "iot-device"
ca_id = "internal-device-ca"
required_ext_key_usage = ["clientAuth"]
max_validity_days = 30

This configuration issues public TLS certificates from one CA and private IoT device certificates from another.

Key Type Restrictions

The allowed_key_types field restricts which cryptographic key algorithms are accepted in certificate signing requests. This prevents weak key types or enforces organizational cryptographic policies.

Supported Key Type Values

allowed_key_types = [
    "rsa2048",    # RSA with 2048-bit modulus
    "rsa3072",    # RSA with 3072-bit modulus
    "rsa4096",    # RSA with 4096-bit modulus
    "ecdsaP256",  # ECDSA with NIST P-256 curve
    "ecdsaP384",  # ECDSA with NIST P-384 curve
    "ecdsaP521",  # ECDSA with NIST P-521 curve
]

If allowed_key_types is omitted, the label accepts any supported key type. An empty array [] rejects all requests.

Example: ECDSA-Only Label

[[est.label]]
name = "modern-tls"
ca_id = "tls-ca"
allowed_key_types = ["ecdsaP256", "ecdsaP384"]

This configuration rejects all RSA CSRs and only accepts P-256 or P-384 ECDSA keys.

EKU Constraints

The required_ext_key_usage field forces specific Extended Key Usage OIDs into all certificates issued under this label. This ensures certificates are only used for their intended purpose.

Common EKU Values

required_ext_key_usage = [
    "serverAuth",        # TLS server authentication (1.3.6.1.5.5.7.3.1)
    "clientAuth",        # TLS client authentication (1.3.6.1.5.5.7.3.2)
    "emailProtection",   # S/MIME email (1.3.6.1.5.5.7.3.4)
    "codeSigning",       # Code signing (1.3.6.1.5.5.7.3.3)
]

You can specify multiple EKUs for dual-purpose certificates. If the field is omitted, the label does not enforce EKU requirements (though the CA may still add EKUs based on its own policy).

Example: Mutual TLS Label

[[est.label]]
name = "mtls"
ca_id = "corp-ca"
required_ext_key_usage = ["serverAuth", "clientAuth"]

Certificates issued under this label can be used for both server and client authentication.

SAN Requirements

The require_san field enforces the presence of Subject Alternative Names in certificate signing requests. This follows CA/Browser Forum Baseline Requirements, which mandate SAN extensions for publicly trusted TLS certificates.

require_san = true   # Default: reject CSRs without SAN
require_san = false  # Accept CSRs without SAN

When require_san = true, the EST server rejects any CSR that does not contain at least one SAN entry (DNS name, IP address, email, or URI).

When to Disable SAN Requirements

Set require_san = false for:

• Client authentication certificates: User certificates often have meaningful Subject DNs but no SAN
• Legacy device certificates: Older systems may not support SAN extension generation
• Internal PKI: Private infrastructures may rely solely on Subject DN for identification

[[est.label]]
name = "user-cert"
ca_id = "user-ca"
required_ext_key_usage = ["clientAuth", "emailProtection"]
require_san = false  # Allow subject-only certificates

Subject DN Patterns

The subject_pattern field validates the Subject Distinguished Name of incoming CSRs using regular expressions. This prevents clients from requesting certificates with arbitrary subject fields.

Pattern Syntax

# Exact CN match
subject_pattern = "^CN=server\\.example\\.com$"

# Domain restriction with variable hostname
subject_pattern = "^CN=[a-z0-9-]+\\.example\\.com$"

# Multiple RDN components
subject_pattern = "^CN=[^,]+,O=Example Corp,C=US$"

# Flexible ordering (less restrictive)
subject_pattern = "CN=[a-z0-9-]+\\.example\\.com"

The regex engine is Rust’s regex crate, which supports standard PCRE-like syntax. Patterns are case-sensitive by default.

Example: Locked-Down Production Label

[[est.label]]
name = "prod-server"
ca_id = "prod-ca"
subject_pattern = "^CN=(www|api|mail)\\.example\\.com(,O=Example Corp)?(,C=US)?$"
required_ext_key_usage = ["serverAuth"]
allowed_key_types = ["ecdsaP256", "ecdsaP384"]

This pattern only allows CSRs with CN values of www.example.com, api.example.com, or mail.example.com, with optional Organization and Country fields.

Practical Examples

Server TLS Label

Configuration for public-facing TLS server certificates following CA/B Forum requirements:

[[ca]]
id = "public-tls-ca"
cert_path = "/etc/kipuka/pki/tls-intermediate.crt"
key_path = "/etc/kipuka/pki/tls-intermediate.key"
default_validity_days = 365

[[est.label]]
name = "server-tls"
ca_id = "public-tls-ca"
allowed_key_types = ["ecdsaP256", "ecdsaP384", "rsa2048", "rsa3072"]
required_ext_key_usage = ["serverAuth"]
max_validity_days = 398  # CA/B Forum 398-day limit
require_san = true
subject_pattern = "^CN=[a-z0-9-]+\\.example\\.com$"

Client enrollment:

# Generate CSR with SAN
openssl req -new -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 \
  -nodes -keyout server-key.pem -out server-csr.pem \
  -subj "/CN=web.example.com" \
  -addext "subjectAltName=DNS:web.example.com,DNS:www.example.com"

# Enroll via EST
curl --cacert ca.pem --cert client.pem --key client-key.pem \
  --data-binary @server-csr.pem \
  -H "Content-Type: application/pkcs10" \
  -o server-cert.p7 \
  https://est.example.com/.well-known/est/server-tls/simpleenroll

# Extract certificate from PKCS#7
openssl pkcs7 -in server-cert.p7 -inform DER -print_certs -out server.pem

Client Authentication Label

Configuration for mutual TLS client certificates with shorter validity and relaxed SAN requirements:

[[ca]]
id = "client-ca"
cert_path = "/etc/kipuka/pki/client-intermediate.crt"
key_path = "/etc/kipuka/pki/client-intermediate.key"

[[est.label]]
name = "client-auth"
ca_id = "client-ca"
allowed_key_types = ["ecdsaP256", "rsa2048"]
required_ext_key_usage = ["clientAuth"]
max_validity_days = 90
require_san = false
subject_pattern = "^CN=[a-z]+\\.[a-z]+@example\\.com$"

Client enrollment:

# Generate CSR (no SAN required)
openssl req -new -newkey rsa:2048 -nodes \
  -keyout client-key.pem -out client-csr.pem \
  -subj "/[email protected]"

# Enroll via EST
curl --cacert ca.pem --cert bootstrap.pem --key bootstrap-key.pem \
  --data-binary @client-csr.pem \
  -H "Content-Type: application/pkcs10" \
  -o client-cert.p7 \
  https://est.example.com/.well-known/est/client-auth/simpleenroll

# Extract certificate
openssl pkcs7 -in client-cert.p7 -inform DER -print_certs -out client.pem

Device Identity Label

Configuration for IoT device certificates with strict key type enforcement and short validity:

[[ca]]
id = "device-ca"
cert_path = "/etc/kipuka/pki/device-intermediate.crt"
key_path = "/etc/kipuka/pki/device-intermediate.key"

[[est.label]]
name = "device"
ca_id = "device-ca"
allowed_key_types = ["ecdsaP256"]  # P-256 only for embedded devices
required_ext_key_usage = ["clientAuth"]
max_validity_days = 30
require_san = true
subject_pattern = "^CN=device-[0-9a-f]{8}$"

Device enrollment:

# Generate CSR with device-specific CN and SAN
DEVICE_ID="device-a1b2c3d4"
openssl req -new -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 \
  -nodes -keyout device-key.pem -out device-csr.pem \
  -subj "/CN=${DEVICE_ID}" \
  -addext "subjectAltName=URI:urn:uuid:a1b2c3d4-e5f6-7890-abcd-ef1234567890"

# Enroll via EST
curl --cacert ca.pem --cert device-bootstrap.pem --key device-bootstrap-key.pem \
  --data-binary @device-csr.pem \
  -H "Content-Type: application/pkcs10" \
  -o device-cert.p7 \
  https://est.example.com/.well-known/est/device/simpleenroll

# Extract certificate
openssl pkcs7 -in device-cert.p7 -inform DER -print_certs -out device.pem

Label Selection Strategy

When designing your EST label architecture, consider:

1. Certificate Purpose Separation: Create distinct labels for server authentication, client authentication, email protection, and code signing. Never mix purposes in a single label.

2. Security Posture: Use restrictive labels for production workloads (subject_pattern, strict allowed_key_types) and permissive labels for development environments.

3. Validity Period: Match max_validity_days to certificate rotation cadence. Short-lived certificates (30-90 days) for automated systems, longer validity for manually managed certificates.

4. CA Hierarchy Mapping: Map labels to CAs based on trust requirements. Public-facing services may require certificates from a different CA than internal infrastructure.

5. Client Capabilities: Consider what key types and extensions your clients can generate. Legacy systems may require require_san = false and broader allowed_key_types.

Label Discovery

Clients can discover available labels through the EST /csrattrs endpoint:

curl --cacert ca.pem --cert client.pem --key client-key.pem \
  https://est.example.com/.well-known/est/server-tls/csrattrs

However, RFC 7030 does not define a standard mechanism for enumerating all labels. Operators should document available labels and their intended purposes in client onboarding documentation.

Validation Behavior

When a client submits a CSR to a labeled endpoint, kipuka performs validation in this order:

1. Key type validation: If allowed_key_types is set, reject CSRs with non-matching key algorithms
2. SAN validation: If require_san = true, reject CSRs without SAN extension
3. Subject DN validation: If subject_pattern is set, reject CSRs with non-matching Subject DN
4. EKU injection: Add required_ext_key_usage OIDs to the issued certificate (does not validate CSR EKUs)
5. Validity enforcement: Apply max_validity_days limit, overriding CA default if stricter

If any validation step fails, the EST server returns HTTP 400 Bad Request with an error message indicating which constraint was violated.

Performance Considerations

Label lookups occur on every EST request. For deployments with hundreds of labels, ensure kipuka.toml is stored on fast local storage. Label matching is O(n) in the number of configured labels.

If you anticipate very large numbers of labels (>100), consider deploying multiple kipuka instances, each serving a subset of labels, behind a reverse proxy that routes based on URL path.

Authentication

kipuka supports multiple authentication methods to accommodate different enrollment scenarios and enterprise environments. This chapter covers the three primary authentication mechanisms available for EST endpoints.

Authentication Methods

mTLS (Mutual TLS) Authentication

Mutual TLS is the primary authentication method for EST as defined in RFC 7030. The client presents a certificate during the TLS handshake, which the server validates against a configured trust store.

Configuration

mTLS is configured in the [tls.client_auth] section:

[tls]
# ... other TLS settings ...

[tls.client_auth]
# Path to CA bundle containing trusted client certificate issuers
trust_anchors = "/etc/kipuka/client-ca-bundle.pem"

# Client certificate verification mode
mode = "required"  # required | optional | none

Mode Options:

• required: All EST endpoints require a valid client certificate. The TLS handshake fails if no certificate is presented or if the certificate is not signed by a trusted CA.
• optional: Client certificate is verified if presented, but clients without certificates can still connect. This mode allows fallback to OTP or GSSAPI for initial enrollment.
• required_for_reenroll: Enrollment optionally requires a client certificate, but reenrollment is only possible using an existing client certificate.
• none: No client certificate verification. Not recommended for production environments.

Trust Anchors:

The trust_anchors file should contain one or more PEM-encoded CA certificates. These CAs define which client certificates are accepted for authentication.

# Example: concatenate multiple CA certificates
cat corporate-ca.pem partner-ca.pem > /etc/kipuka/client-ca-bundle.pem

Re-enrollment Workflow

For re-enrollment (/simplereenroll), the client typically uses its previously-issued certificate as the client certificate:

1. Client initiates TLS connection with its current certificate
2. Server validates certificate against trust anchors
3. Client submits CSR for new certificate
4. Server issues new certificate

Example: Initial Enrollment with mTLS

For clients that already have a certificate (e.g., issued by a different CA or manually installed):

curl --cert client.crt --key client.key \
     --cacert est-server-ca.pem \
     -H "Content-Type: application/pkcs10" \
     --data-binary @request.csr \
     https://est.example.com:8443/.well-known/est/simpleenroll

Example: Re-enrollment

# Use the previously-issued certificate for authentication
curl --cert current.crt --key current.key \
     --cacert est-server-ca.pem \
     -H "Content-Type: application/pkcs10" \
     --data-binary @renewal.csr \
     https://est.example.com:8443/.well-known/est/simplereenroll

OTP (One-Time Password) Authentication

OTP authentication is designed for initial enrollment scenarios where the client does not yet have a certificate. The administrator generates a token via the Admin API, delivers it to the client through a secure out-of-band channel, and the client uses it for authentication.

Configuration

[otp]
# Enable OTP authentication
enabled = true

# Hash algorithm for token storage
# Options: argon2id (recommended), bcrypt, sha256-hmac
hash_algorithm = "argon2id"

# Minimum token length (NIAP PP requires >= 16)
token_length = 20

# Single-use or multi-use tokens
max_uses = 1

# Rate limiting configuration
max_failures = 5
failure_window = 300  # 5 minutes
lockout_duration = 900  # 15 minutes

Hash Algorithms:

• argon2id (recommended): NIAP-compliant, memory-hard algorithm resistant to GPU attacks
• bcrypt: Industry-standard password hashing
• sha256-hmac: Fast but less secure; use only for low-security environments

All implementations use timing-safe comparison to prevent timing attacks.

Rate Limiting:

• max_failures: Maximum authentication failures before lockout
• failure_window: Time window (seconds) for counting failures
• lockout_duration: How long (seconds) the client is locked out after exceeding max_failures

OTP Workflow

1. Token Generation: Administrator calls the Admin API to generate an OTP token
2. Out-of-Band Delivery: Token is securely delivered to the client (email, SMS, secure portal, etc.)
3. Client Authentication: Client uses the token in HTTP Basic authentication
4. Certificate Issuance: Server validates token and issues certificate
5. Future Renewals: Client uses mTLS with the issued certificate

Generating OTP Tokens

Tokens are generated via the Admin API:

# Generate a single-use OTP token for a client
curl -X POST https://est.example.com:8443/admin/otp \
     -H "Authorization: Bearer <admin-token>" \
     -H "Content-Type: application/json" \
     -d '{
       "client_id": "workstation-42",
       "max_uses": 1,
       "expires_at": "2026-06-30T23:59:59Z"
     }'

Response:

{
  "token": "xK9mP2vL8qR5wN3jT7fY",
  "client_id": "workstation-42",
  "created_at": "2026-06-24T10:15:00Z",
  "expires_at": "2026-06-30T23:59:59Z",
  "max_uses": 1
}

Using OTP for Enrollment

The client sends the OTP token as the password in HTTP Basic authentication. The username is ignored but should be provided for RFC compliance:

# Enroll using OTP authentication
curl -u ":xK9mP2vL8qR5wN3jT7fY" \
     --cacert est-server-ca.pem \
     -H "Content-Type: application/pkcs10" \
     --data-binary @request.csr \
     https://est.example.com:8443/.well-known/est/simpleenroll

After successful enrollment, the client stores the issued certificate and uses mTLS for all future operations, including re-enrollment.

NIAP PP Compliance

For NIAP Protection Profile compliance:

• Set token_length >= 16
• Use hash_algorithm = "argon2id"
• Configure appropriate rate limiting
• Enable audit logging for OTP generation and usage

GSSAPI/Kerberos Authentication

GSSAPI authentication provides enterprise Single Sign-On (SSO) integration using Kerberos tickets. This is particularly useful in Active Directory and FreeIPA environments.

Configuration

[gssapi]
# Enable GSSAPI/Kerberos authentication
enabled = true

# Path to server's keytab file
keytab = "/etc/kipuka/kipuka.keytab"

# Service principal name
# Format: HTTP/hostname@REALM
service_principal = "HTTP/[email protected]"

# Principal to certificate subject mapping
# Maps Kerberos principal to X.509 subject DN
[gssapi.principal_mapping]
"[email protected]" = "CN=User,OU=People,DC=example,DC=com"
"[email protected]" = "CN=Admin,OU=Admins,DC=example,DC=com"

# Default mapping template (optional)
# {principal} is replaced with the authenticated Kerberos principal
default_template = "CN={principal},OU=Users,DC=example,DC=com"

Server Setup

The EST server must have a keytab containing credentials for the HTTP service principal:

# On Active Directory or FreeIPA KDC, create the service principal
# and export the keytab

# FreeIPA example:
ipa service-add HTTP/est.example.com
ipa-getkeytab -s ipaserver.example.com \
              -p HTTP/est.example.com \
              -k /etc/kipuka/kipuka.keytab

# Set appropriate permissions
chown kipuka:kipuka /etc/kipuka/kipuka.keytab
chmod 600 /etc/kipuka/kipuka.keytab

Client Authentication

Clients use SPNEGO (RFC 4559) to send Kerberos tickets via the Negotiate HTTP authentication scheme:

# Obtain Kerberos ticket
kinit [email protected]

# Enroll using GSSAPI authentication
curl --negotiate -u : \
     --cacert est-server-ca.pem \
     -H "Content-Type: application/pkcs10" \
     --data-binary @request.csr \
     https://est.example.com:8443/.well-known/est/simpleenroll

The server:

1. Receives the Negotiate header with Kerberos ticket
2. Validates the ticket against the KDC
3. Extracts the authenticated principal name
4. Maps the principal to a certificate subject DN using the configured mapping rules
5. Issues a certificate with the mapped subject

Authentication Modes

kipuka supports two GSSAPI authentication modes controlled by the require_crypto_verification setting:

Cryptographic Verification (default, recommended)

When require_crypto_verification = true (the default), kipuka uses libgssapi to perform full cryptographic verification of Kerberos tickets. This requires:

• A valid keytab file or gssproxy configuration
• The gssapi compile-time feature flag enabled
• Network connectivity to the KDC for ticket validation

[gssapi]
enabled = true
keytab = "/etc/kipuka/kipuka.keytab"
service_principal = "HTTP/[email protected]"
require_crypto_verification = true

Structural Parsing Mode (development only)

When require_crypto_verification = false, kipuka performs structural parsing of the SPNEGO token without cryptographic verification. The service name (sname) is extracted from the cleartext portion of the ticket, but:

• No cryptographic verification is performed
• The client identity cannot be authenticated
• This mode is not suitable for production

This mode is intended only for development, logging, or environments where TLS client certificates provide the primary authentication and GSSAPI is used only for identity hint extraction.

[gssapi]
enabled = true
require_crypto_verification = false  # WARNING: development only

Security Warning: Never set require_crypto_verification = false in production. Without cryptographic verification, any client can forge a SPNEGO token with an arbitrary principal name.

Credential Management

kipuka supports two mutually exclusive credential management strategies:

Keytab file (traditional):

[gssapi]
keytab = "/etc/kipuka/kipuka.keytab"

gssproxy (recommended for containerized deployments):

[gssapi]
gssproxy = true  # Uses gssproxy socket instead of keytab

gssproxy separates credential management from the application, allowing kipuka to run without direct access to the keytab file. This is particularly useful in container environments where mounting keytab files is operationally complex.

Principal Mapping

The principal_mapping table defines explicit mappings from Kerberos principals to certificate subject DNs. If no explicit mapping exists, the default_template is used (if configured).

Example: Principal [email protected] with default template "CN={principal},OU=Users,DC=example,DC=com" results in subject [email protected],OU=Users,DC=example,DC=com.

Authentication per Endpoint

Different EST endpoints have different authentication requirements:

Admin Endpoint Authentication

Admin endpoints (OTP generation, certificate revocation, etc.) use separate authentication configured in the [admin] section:

[admin]
# mTLS for admin endpoints
[admin.tls]
trust_anchors = "/etc/kipuka/admin-ca-bundle.pem"
mode = "required"

# Bearer token authentication (alternative or in addition to mTLS)
[admin.bearer_token]
enabled = true
tokens = [
    { token_hash = "sha256:...", description = "CI/CD automation" },
    { token_hash = "sha256:...", description = "Admin portal" }
]

Admin authentication is independent of EST endpoint authentication. You can require mTLS for admin operations even if EST endpoints accept OTP or GSSAPI.

Authentication Precedence

When multiple authentication methods are enabled, kipuka evaluates them in the following order:

1. mTLS: If a client certificate is presented (and mode != "none"), it is validated first
2. GSSAPI: If no valid client certificate and Negotiate header is present, GSSAPI is attempted
3. OTP: If no valid client certificate and Authorization: Basic header is present, OTP is checked

A request succeeds if any enabled method authenticates successfully. For endpoints requiring mTLS (e.g., /simplereenroll), only mTLS is evaluated.

Security Best Practices

• Production environments: Use mode = "required" for mTLS and disable OTP after initial enrollment
• Initial enrollment: Use mode = "optional" with OTP enabled, then migrate to mode = "required" after all devices are enrolled
• Token delivery: Never send OTP tokens over the same channel as enrollment (e.g., do not email a token to an address that auto-forwards to the EST client)
• Token entropy: Use token_length >= 20 for high-security environments
• Keytab protection: Store GSSAPI keytabs with restrictive permissions (600) and limit access to the kipuka service account
• Audit logging: Enable audit logs for all authentication events to detect suspicious activity

Troubleshooting

mTLS Issues

Error: “client certificate required”

• Verify mode is set to optional or none if client does not have a certificate
• Check that the client is sending a certificate (--cert and --key in curl)

Error: “certificate signed by unknown authority”

• Ensure the client certificate is signed by a CA in trust_anchors
• Verify the CA bundle is readable and contains valid PEM data

OTP Issues

Error: “invalid OTP token”

• Check token expiration (expires_at)
• Verify token has not exceeded max_uses
• Ensure token is sent as password in Basic auth (username can be empty or any value)

Error: “too many failures, locked out”

• Wait for lockout_duration to expire
• Review rate limiting configuration (max_failures, failure_window)

GSSAPI Issues

Error: “GSSAPI authentication failed”

• Verify client has a valid Kerberos ticket (klist)
• Check server’s keytab is readable and contains the correct principal
• Ensure clocks are synchronized between client, server, and KDC (Kerberos requires time sync within 5 minutes)

Error: “principal not mapped”

• Add an explicit mapping in [gssapi.principal_mapping] or configure default_template
• Check that the authenticated principal name matches the expected format

TLS Configuration

This guide covers TLS configuration for the kipuka EST server, including certificate requirements, protocol versions, cipher suites, client authentication modes, and production deployment scenarios.

Server Certificate Requirements

RFC 7030 Section 3.3.2 mandates that EST server certificates include the id-kp-cmcRA Extended Key Usage (EKU) with OID 1.3.6.1.5.5.7.3.28. This EKU identifies the server as an authorized Registration Authority (RA) for certificate enrollment operations.

Without this EKU, compliant EST clients may reject the server certificate, even if it is otherwise valid. In production deployments, include both:

• id-kp-cmcRA (1.3.6.1.5.5.7.3.28) - Required for EST protocol compliance
• id-kp-serverAuth (1.3.6.1.5.5.7.3.1) - Standard server authentication for web browser compatibility

Generating a Server Certificate with cmcRA EKU

Create an OpenSSL configuration file (est-server.cnf) with the required extensions:

[ req ]
default_bits       = 2048
distinguished_name = req_distinguished_name
req_extensions     = v3_req
prompt             = no

[ req_distinguished_name ]
CN = est.example.com
O  = Example Organization
C  = US

[ v3_req ]
keyUsage           = critical, digitalSignature, keyEncipherment
extendedKeyUsage   = serverAuth, 1.3.6.1.5.5.7.3.28
subjectAltName     = @alt_names

[ alt_names ]
DNS.1 = est.example.com
DNS.2 = kipuka.example.com

[ v3_ca ]
subjectKeyIdentifier   = hash
authorityKeyIdentifier = keyid:always,issuer
basicConstraints       = critical, CA:true
keyUsage               = critical, keyCertSign, cRLSign

Generate the server private key and CSR:

# Generate private key
openssl genrsa -out est-server-key.pem 2048

# Generate certificate signing request
openssl req -new -key est-server-key.pem \
    -out est-server.csr \
    -config est-server.cnf

# Sign with your CA (replace ca-cert.pem and ca-key.pem)
openssl x509 -req -in est-server.csr \
    -CA ca-cert.pem -CAkey ca-key.pem \
    -CAcreateserial -out est-server-cert.pem \
    -days 365 -sha256 \
    -extensions v3_req -extfile est-server.cnf

# Verify the cmcRA EKU is present
openssl x509 -in est-server-cert.pem -text -noout | grep -A1 "Extended Key Usage"

Expected output should include:

X509v3 Extended Key Usage:
    TLS Web Server Authentication, 1.3.6.1.5.5.7.3.28

Self-Signed Certificate for Development

For development and testing only:

# Generate self-signed certificate with cmcRA EKU
openssl req -x509 -newkey rsa:2048 -nodes \
    -keyout est-server-key.pem \
    -out est-server-cert.pem \
    -days 365 -sha256 \
    -config est-server.cnf \
    -extensions v3_req

Warning: Self-signed certificates should never be used in production. Always obtain certificates from a trusted CA.

TLS Version Configuration

The min_version parameter in the [tls] section controls the minimum TLS protocol version accepted by the server.

[tls]
min_version = "1.2"  # or "1.3"

Supported Values

• "1.2" (default): Accept TLS 1.2 and TLS 1.3 connections. This is the minimum version required for RFC 7030 compliance and maintains compatibility with older EST clients.
• "1.3": Accept only TLS 1.3 connections. Recommended for new deployments where all clients support TLS 1.3, as it provides improved security and performance.

TLS 1.0 and TLS 1.1 are not supported, as they have been deprecated by RFC 8996 and are considered insecure.

Recommendation

For production environments deployed after 2024, set min_version = "1.3" unless you have specific legacy client requirements. TLS 1.3 removes obsolete cryptographic algorithms, reduces handshake latency, and encrypts more of the handshake metadata.

Cipher Suite Configuration

The cipher_suites array in the [tls] section specifies the allowed cipher suites. If omitted, kipuka uses a secure default set that excludes weak ciphers.

[tls]
cipher_suites = [
    "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384",
    "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
    "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256",
    "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
]

TLS 1.2 Cipher Suites

The default cipher suite list for TLS 1.2 connections includes:

cipher_suites = [
    "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384",
    "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
    "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256",
    "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
    "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256",
    "TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256",
]

All suites provide:

• Forward Secrecy via ECDHE key exchange
• AEAD encryption (GCM or ChaCha20-Poly1305)
• Strong hash functions (SHA-256 or SHA-384)

TLS 1.3 Cipher Suites

TLS 1.3 defines only three mandatory cipher suites, which are always enabled when min_version = "1.3":

• TLS_AES_256_GCM_SHA384
• TLS_AES_128_GCM_SHA256
• TLS_CHACHA20_POLY1305_SHA256

The cipher_suites configuration parameter does not affect TLS 1.3, as the protocol specification mandates these suites.

NIAP and FIPS Compliance

For systems requiring NIAP Common Criteria or FIPS 140-2/3 compliance, disable ChaCha20-Poly1305 cipher suites, as they are not FIPS-approved algorithms:

[tls]
cipher_suites = [
    "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384",
    "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
    "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256",
    "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
]

Consult your organization’s security policy for approved cipher suites.

Client Authentication Modes

The mode parameter in the [tls.client_auth] section controls whether and how client certificates are verified.

[tls.client_auth]
mode = "optional"
trust_anchors = "/etc/kipuka/client-ca.pem"

Available Modes

mode = "required"

All TLS connections must present a valid client certificate. The certificate must:

• Chain to a CA in the trust_anchors file
• Not be expired or revoked
• Have valid signatures

Use this mode when:

• All clients have existing certificates (e.g., re-enrollment only)
• Initial enrollment is performed via a separate out-of-band mechanism
• Maximum security is required

Note: With mode = "required", clients cannot perform initial enrollment unless they already possess a certificate. You must provision initial certificates through another channel (e.g., manual issuance, SCEP, or ACME).

mode = "optional"

Client certificates are verified if presented, but connections are allowed without a certificate. This mode supports:

• mTLS re-enrollment: Clients with existing certificates use them for authentication
• OTP-based enrollment: Clients without certificates authenticate with a one-time password (OTP) during initial enrollment

This is the recommended mode for production EST deployments, as it supports the full enrollment lifecycle.

[tls.client_auth]
mode = "optional"
trust_anchors = "/etc/kipuka/client-ca.pem"

[enrollment]
require_proof_of_possession = true  # Enforce PoP for OTP enrollments

mode = "none"

No client certificate verification is performed. Connections are accepted without client authentication.

This mode is for development and testing only. Do not use in production, as it disables a critical security layer.

Trust Anchors

The trust_anchors parameter specifies a PEM file containing the CA certificates trusted for client authentication. This file may contain multiple concatenated certificates.

# Example trust_anchors file with two CAs
cat ca1-cert.pem ca2-cert.pem > /etc/kipuka/client-ca.pem

kipuka validates client certificates against this trust anchor bundle. Ensure the file is readable by the kipuka process user.

Separate Admin API TLS Configuration

The administrative API runs on a separate TCP port (default 9443) and can use independent TLS settings. This allows you to:

• Bind the admin API to a management network interface
• Use separate client authentication for administrative operations
• Restrict admin access to authorized systems only

Basic Admin API Configuration

[server]
listen = "0.0.0.0:8443"        # EST API (client-facing)
admin_listen = "127.0.0.1:9443" # Admin API (localhost only)

[tls]
cert = "/etc/kipuka/est-server-cert.pem"
key = "/etc/kipuka/est-server-key.pem"

[tls.client_auth]
mode = "optional"
trust_anchors = "/etc/kipuka/client-ca.pem"

[admin.client_auth]
mode = "required"
trust_anchors = "/etc/kipuka/admin-ca.pem"  # Separate CA for admin certs

In this example:

• EST API on port 8443 accepts optional client certificates from end-user devices
• Admin API on localhost port 9443 requires client certificates from administrator systems
• Admin certificates are issued by a separate CA (admin-ca.pem)

Binding to Management Networks

For multi-homed systems, bind the admin API to a dedicated management network interface:

[server]
listen = "0.0.0.0:8443"           # EST API on all interfaces
admin_listen = "10.0.1.100:9443"  # Admin API on management VLAN

Configure firewall rules to restrict access to the management network. For example, using iptables:

# Allow admin API only from management subnet
iptables -A INPUT -p tcp --dport 9443 -s 10.0.1.0/24 -j ACCEPT
iptables -A INPUT -p tcp --dport 9443 -j DROP

Localhost-Only Admin Access

For single-host deployments or when using a reverse proxy, bind the admin API to localhost:

[server]
admin_listen = "127.0.0.1:9443"

Administrators can access the API via SSH port forwarding:

ssh -L 9443:localhost:9443 [email protected]
curl --cert admin-cert.pem --key admin-key.pem \
     https://localhost:9443/admin/health

Practical Configuration Examples

Development Setup with Self-Signed Certificate

For local testing and development:

[server]
listen = "127.0.0.1:8443"
admin_listen = "127.0.0.1:9443"

[tls]
cert = "/home/dev/kipuka/dev-cert.pem"
key = "/home/dev/kipuka/dev-key.pem"
min_version = "1.2"

[tls.client_auth]
mode = "none"  # Accept all connections for testing

[enrollment]
require_proof_of_possession = false  # Simplified for dev

Generate the development certificate:

openssl req -x509 -newkey rsa:2048 -nodes \
    -keyout dev-key.pem -out dev-cert.pem \
    -days 365 -sha256 \
    -subj "/CN=localhost" \
    -addext "subjectAltName=DNS:localhost,IP:127.0.0.1" \
    -addext "extendedKeyUsage=serverAuth,1.3.6.1.5.5.7.3.28"

Production Setup with Internal CA

For enterprise deployments with an internal PKI:

[server]
listen = "0.0.0.0:8443"
admin_listen = "10.0.1.100:9443"

[tls]
cert = "/etc/kipuka/certs/est-server-cert.pem"
key = "/etc/kipuka/private/est-server-key.pem"
min_version = "1.2"
cipher_suites = [
    "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384",
    "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
    "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256",
    "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
]

[tls.client_auth]
mode = "optional"
trust_anchors = "/etc/kipuka/ca/device-ca-bundle.pem"

[admin.client_auth]
mode = "required"
trust_anchors = "/etc/kipuka/ca/admin-ca.pem"

[enrollment]
require_proof_of_possession = true
allowed_key_types = ["rsa2048", "rsa4096", "ecdsa256", "ecdsa384"]

Certificate generation workflow:

# 1. Generate server private key
openssl genrsa -out est-server-key.pem 2048
chmod 600 est-server-key.pem

# 2. Create CSR with cmcRA EKU
openssl req -new -key est-server-key.pem \
    -out est-server.csr \
    -config est-server.cnf

# 3. Submit CSR to internal CA for signing
# (Process varies by CA implementation)

# 4. Install signed certificate
install -m 644 est-server-cert.pem /etc/kipuka/certs/
install -m 600 est-server-key.pem /etc/kipuka/private/
chown kipuka:kipuka /etc/kipuka/certs/est-server-cert.pem
chown kipuka:kipuka /etc/kipuka/private/est-server-key.pem

# 5. Verify cmcRA EKU
openssl x509 -in /etc/kipuka/certs/est-server-cert.pem -text -noout \
    | grep -A1 "Extended Key Usage"

High-Security Setup with TLS 1.3 Only

For environments requiring maximum security (e.g., classified networks, financial services):

[server]
listen = "10.0.1.50:8443"
admin_listen = "127.0.0.1:9443"

[tls]
cert = "/etc/kipuka/certs/est-server-cert.pem"
key = "/etc/kipuka/private/est-server-key.pem"
min_version = "1.3"  # TLS 1.3 only

# Note: cipher_suites parameter has no effect in TLS 1.3
# The following suites are always enabled:
# - TLS_AES_256_GCM_SHA384
# - TLS_AES_128_GCM_SHA256
# - TLS_CHACHA20_POLY1305_SHA256

[tls.client_auth]
mode = "required"  # All connections must present client cert
trust_anchors = "/etc/kipuka/ca/device-ca-bundle.pem"

[admin.client_auth]
mode = "required"
trust_anchors = "/etc/kipuka/ca/admin-ca.pem"

[enrollment]
require_proof_of_possession = true
allowed_key_types = ["ecdsa384"]  # P-384 only
max_validity_days = 365
require_san = true

Additional hardening:

# Restrict file permissions
chmod 700 /etc/kipuka/private
chmod 600 /etc/kipuka/private/*.pem
chmod 644 /etc/kipuka/certs/*.pem

# Run as unprivileged user
useradd -r -s /bin/false -d /var/lib/kipuka kipuka
chown -R kipuka:kipuka /etc/kipuka

# Enable mandatory access control (SELinux/AppArmor)
# Example SELinux policy (adjust for your distribution)
semanage fcontext -a -t cert_t "/etc/kipuka/certs(/.*)?"
semanage fcontext -a -t cert_t "/etc/kipuka/ca(/.*)?"
semanage fcontext -a -t cert_t "/etc/kipuka/private(/.*)?"
restorecon -R /etc/kipuka

FIPS-Compliant Configuration

For systems requiring FIPS 140-2/3 compliance:

[server]
listen = "0.0.0.0:8443"
admin_listen = "10.0.1.100:9443"

[tls]
cert = "/etc/kipuka/certs/est-server-cert.pem"
key = "/etc/kipuka/private/est-server-key.pem"
min_version = "1.2"

# Disable ChaCha20 (not FIPS-approved)
cipher_suites = [
    "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384",
    "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
    "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256",
    "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
]

[tls.client_auth]
mode = "required"
trust_anchors = "/etc/kipuka/ca/device-ca-bundle.pem"

[enrollment]
allowed_key_types = ["rsa2048", "rsa4096", "ecdsa256", "ecdsa384"]
allowed_signature_algorithms = ["sha256", "sha384", "sha512"]

Ensure the underlying operating system is running in FIPS mode:

# RHEL/CentOS
fips-mode-setup --enable
reboot

# Verify FIPS mode
cat /proc/sys/crypto/fips_enabled  # Should output: 1

Troubleshooting

Client Rejects Server Certificate

Symptom: EST client fails with “server certificate verification failed” or similar.

Cause: Server certificate missing the id-kp-cmcRA EKU.

Solution: Verify the EKU is present:

openssl x509 -in est-server-cert.pem -text -noout | grep -A1 "Extended Key Usage"

Expected output:

X509v3 Extended Key Usage:
    TLS Web Server Authentication, 1.3.6.1.5.5.7.3.28

If 1.3.6.1.5.5.7.3.28 is missing, regenerate the certificate using the instructions in “Server Certificate Requirements.”

TLS Handshake Failure

Symptom: Connection fails during TLS handshake with “no shared cipher” or “protocol version mismatch.”

Cause: Client and server have no common cipher suites or TLS versions.

Solution: Enable TLS 1.2 support if clients do not support TLS 1.3:

[tls]
min_version = "1.2"

Check client cipher suite support and add compatible suites to cipher_suites.

Admin API Unreachable

Symptom: Cannot connect to admin API on port 9443.

Cause: Admin API bound to wrong interface or blocked by firewall.

Solution: Verify admin_listen binding:

[server]
admin_listen = "0.0.0.0:9443"  # Listen on all interfaces

Check firewall rules:

# List firewall rules
iptables -L -n -v | grep 9443

# Allow admin API port
iptables -A INPUT -p tcp --dport 9443 -j ACCEPT

For localhost-only access, use SSH port forwarding:

ssh -L 9443:localhost:9443 [email protected]

Security Best Practices

1. Use TLS 1.3 for new deployments: Set min_version = "1.3" to eliminate legacy protocol weaknesses.
2. Restrict cipher suites: Use the default list or a more restrictive set. Avoid CBC-mode ciphers and weak hashes.
3. Require client authentication for re-enrollment: Set mode = "required" if all clients have certificates.
4. Separate admin and client CAs: Use distinct trust anchors for administrative and end-user certificates.
5. Bind admin API to management networks: Limit exposure of administrative endpoints.
6. Rotate certificates before expiration: Monitor certificate expiry and renew at least 30 days in advance.
7. Protect private keys: Store keys on encrypted filesystems or HSMs. Use chmod 600 and restrict access to the kipuka process user.
8. Enable OCSP or CRL checking: Configure revocation checking for client certificates (see enrollment configuration documentation).
9. Audit TLS configuration regularly: Use tools like testssl.sh or sslyze to verify cipher suite and protocol configuration.
10. Follow your organization’s security policy: Consult internal PKI and cryptography standards before deployment.

References

• RFC 7030: Enrollment over Secure Transport (EST)
• RFC 8996: Deprecating TLS 1.0 and TLS 1.1
• RFC 8446: The Transport Layer Security (TLS) Protocol Version 1.3
• NIST SP 800-52 Rev. 2: Guidelines for the Selection, Configuration, and Use of TLS
• NIAP Protection Profile for Network Devices: Common Criteria requirements for TLS configuration

HSM Integration

kipuka supports Hardware Security Modules (HSMs) and software HSMs through the PKCS#11 (Cryptoki) standard. HSM integration ensures that CA private keys never leave the secure hardware boundary, with all signing operations delegated to the HSM.

PKCS#11 Overview

kipuka uses the PKCS#11 API to interface with HSMs. The integration model follows these principles:

• The [hsm] section in kipuka.toml configures the PKCS#11 provider library and authentication
• CA definitions reference HSM-stored keys using the hsm_slot parameter in the [[ca]] section
• Private keys remain on the HSM at all times—signing operations are performed by the HSM
• When hsm_slot is set for a CA, the key parameter is ignored

This architecture ensures that sensitive key material never exists in kipuka’s process memory or on the filesystem.

Supported Vendors and Library Paths

kipuka works with any PKCS#11-compliant HSM. The following table lists common vendors and their typical library paths:

Consult your HSM vendor documentation for the exact library path on your system.

PIN Management

kipuka supports three methods for providing the HSM PIN, evaluated in the following priority order:

Environment Variable (RECOMMENDED)

Set pin_env to the name of an environment variable containing the PIN:

[hsm]
library = "/usr/lib/softhsm/libsofthsm2.so"
token_label = "kipuka"
pin_env = "KIPUKA_HSM_PIN"

Then start kipuka with the PIN in the environment:

export KIPUKA_HSM_PIN="your-pin-here"
kipuka

For systemd services, use EnvironmentFile:

[Service]
EnvironmentFile=/etc/kipuka/hsm.env
ExecStart=/usr/local/bin/kipuka

Where /etc/kipuka/hsm.env contains:

KIPUKA_HSM_PIN=your-pin-here

Set restrictive permissions on the environment file:

chmod 0400 /etc/kipuka/hsm.env
chown kipuka:kipuka /etc/kipuka/hsm.env

PIN File

Set pin_file to a path containing only the PIN:

[hsm]
library = "/usr/lib/softhsm/libsofthsm2.so"
token_label = "kipuka"
pin_file = "/etc/kipuka/hsm.pin"

Secure the PIN file:

echo "your-pin-here" > /etc/kipuka/hsm.pin
chmod 0400 /etc/kipuka/hsm.pin
chown kipuka:kipuka /etc/kipuka/hsm.pin

Plaintext PIN (NOT RECOMMENDED)

For development only, the PIN can be stored directly in the configuration:

[hsm]
library = "/usr/lib/softhsm/libsofthsm2.so"
token_label = "kipuka"
pin = "1234"

Never use this method in production. The PIN will be visible in the configuration file and process listings.

Slot Configuration

PKCS#11 tokens are identified by either slot number or token label.

By Slot Number

Reference the HSM token by its numeric slot identifier:

[hsm]
library = "/usr/lib/softhsm/libsofthsm2.so"
slot = 0
pin_env = "KIPUKA_HSM_PIN"

By Token Label

Reference the HSM token by its label:

[hsm]
library = "/usr/lib/softhsm/libsofthsm2.so"
token_label = "kipuka"
pin_env = "KIPUKA_HSM_PIN"

Using token_label is generally more portable across HSM reconfigurations.

Discovering Slots

Use pkcs11-tool to list available slots:

pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so --list-slots

Example output:

Available slots:
Slot 0 (0x1d6d28f6): SoftHSM slot ID 0x1d6d28f6
  token label        : kipuka
  token manufacturer : SoftHSM project
  token model        : SoftHSM v2
  token flags        : login required, rng, token initialized, PIN initialized
  hardware version   : 2.6
  firmware version   : 2.6
  serial num         : 4c8e0a766d6d28f6
  pin min/max        : 4/255

The token label from this output can be used as the token_label value.

Key Generation Examples

Before configuring kipuka to use HSM-stored keys, you must generate key pairs on the HSM. The following examples use pkcs11-tool from the OpenSC package.

Generate RSA 2048-bit Key Pair

pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so \
  --login \
  --pin 1234 \
  --keypairgen \
  --key-type rsa:2048 \
  --id 01 \
  --label "kipuka-ca-rsa-2048"

Generate RSA 4096-bit Key Pair

pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so \
  --login \
  --pin 1234 \
  --keypairgen \
  --key-type rsa:4096 \
  --id 02 \
  --label "kipuka-ca-rsa-4096"

Generate ECDSA P-256 Key Pair

pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so \
  --login \
  --pin 1234 \
  --keypairgen \
  --key-type EC:prime256v1 \
  --id 03 \
  --label "kipuka-ca-ec-p256"

Generate ECDSA P-384 Key Pair

pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so \
  --login \
  --pin 1234 \
  --keypairgen \
  --key-type EC:secp384r1 \
  --id 04 \
  --label "kipuka-ca-ec-p384"

List HSM Objects

Verify key generation by listing objects on the token:

pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so \
  --login \
  --pin 1234 \
  --list-objects

Example output:

Public Key Object; RSA 2048 bits
  label:      kipuka-ca-rsa-2048
  ID:         01
  Usage:      encrypt, verify, wrap
Private Key Object; RSA
  label:      kipuka-ca-rsa-2048
  ID:         01
  Usage:      decrypt, sign, unwrap

The ID field value is used as the hsm_slot parameter in kipuka’s CA configuration.

Development Setup with Kryoptic

Kryoptic is a Rust-based software PKCS#11 implementation suitable for development and testing. It provides a lightweight alternative to hardware HSMs.

Installation

Install Kryoptic from crates.io:

cargo install kryoptic

Or build from source:

git clone https://github.com/latchset/kryoptic.git
cd kryoptic
cargo build --release

The PKCS#11 library will be at target/release/libkryoptic_pkcs11.so (Linux) or target/release/libkryoptic_pkcs11.dylib (macOS).

Initialize a Token

Create a Kryoptic configuration directory:

mkdir -p ~/.config/kryoptic

Initialize a token using pkcs11-tool:

pkcs11-tool --module target/release/libkryoptic_pkcs11.so \
  --init-token \
  --label "kipuka-dev" \
  --so-pin 12345678

Set the user PIN:

pkcs11-tool --module target/release/libkryoptic_pkcs11.so \
  --init-pin \
  --so-pin 12345678 \
  --pin 1234

Generate Development Keys

Generate an RSA 2048-bit key pair:

pkcs11-tool --module target/release/libkryoptic_pkcs11.so \
  --login \
  --pin 1234 \
  --keypairgen \
  --key-type rsa:2048 \
  --id 01 \
  --label "kipuka-dev-ca"

Configure kipuka

Update kipuka.toml to use the Kryoptic library:

[hsm]
library = "/home/user/kryoptic/target/release/libkryoptic_pkcs11.so"
token_label = "kipuka-dev"
pin_env = "KIPUKA_HSM_PIN"

[[ca]]
id = "dev-ca"
name = "Development CA"
cert = "/etc/kipuka/ca/dev-ca.pem"
hsm_slot = 1
validity_days = 365

Generate the CA certificate (the private key remains on Kryoptic):

export KIPUKA_HSM_PIN=1234

# Generate a self-signed CA certificate using the HSM key
openssl req -new -x509 \
  -engine pkcs11 \
  -keyform engine \
  -key "pkcs11:token=kipuka-dev;id=%01;type=private" \
  -out /etc/kipuka/ca/dev-ca.pem \
  -days 3650 \
  -subj "/CN=kipuka Development CA"

Start kipuka:

kipuka

kipuka will now use the Kryoptic HSM for all signing operations for the dev-ca CA.

Full Configuration Example

The following example shows a complete HSM configuration with multiple CAs:

# HSM configuration
[hsm]
library = "/usr/lib/pkcs11/libkryoptic_pkcs11.so"
token_label = "kipuka"
pin_env = "KIPUKA_HSM_PIN"

# Server configuration
[server]
listen = "0.0.0.0:8443"
tls_cert = "/etc/kipuka/server.pem"
tls_key = "/etc/kipuka/server-key.pem"

# RSA CA using HSM key
[[ca]]
id = "hsm-rsa-ca"
name = "HSM-Protected RSA CA"
cert = "/etc/kipuka/ca/hsm-rsa-ca.pem"
hsm_slot = 1
validity_days = 365
key_usage = ["digitalSignature", "keyCertSign", "cRLSign"]

# ECDSA CA using HSM key
[[ca]]
id = "hsm-ec-ca"
name = "HSM-Protected ECDSA CA"
cert = "/etc/kipuka/ca/hsm-ec-ca.pem"
hsm_slot = 3
validity_days = 365
key_usage = ["digitalSignature", "keyCertSign", "cRLSign"]

Key points:

• The hsm_slot parameter references the object ID assigned during key generation
• When hsm_slot is set, the key parameter must be omitted—the private key exists only on the HSM
• Multiple CAs can share the same HSM by using different slot identifiers
• The CA certificate in the cert parameter is the public certificate; the private key remains on the HSM

Troubleshooting

Library Not Found

If kipuka reports that the PKCS#11 library cannot be loaded, verify:

• The library path is correct for your system
• The library file has appropriate read and execute permissions
• Required dependencies are installed (consult HSM vendor documentation)

Authentication Failures

If kipuka reports authentication failures:

• Verify the PIN is correct using pkcs11-tool --login
• Check that the token is not locked due to failed login attempts
• Ensure the environment variable or PIN file is readable by the kipuka process user

Key Not Found

If kipuka reports that the key cannot be found in the HSM:

• List objects with pkcs11-tool --list-objects and verify the key exists
• Ensure the hsm_slot value matches the key’s ID field
• Check that the token label or slot number is correct

Performance Considerations

HSM signing operations have higher latency than software signing. For high-throughput deployments:

• Use hardware HSMs with dedicated crypto acceleration
• Consider load balancing across multiple kipuka instances
• Monitor HSM session limits and adjust max_sessions if supported by your HSM

High Availability

kipuka provides multi-CA high availability at the application layer. When a Certificate Authority backend becomes unavailable—whether due to HSM failure, Dogtag server downtime, or certificate expiration—kipuka can automatically failover to an alternate CA. This ensures continuous certificate enrollment even when individual CA components fail.

High availability is configured through [ha] and [[ha.group]] sections in the configuration file.

Overview

Traditional PKI deployments often rely on infrastructure-level HA (load balancers, database replication) for a single CA. kipuka takes a different approach: it treats each CA as an independent backend and implements application-layer failover logic. This allows:

• Heterogeneous CA backends: Mix HSM-backed CAs with file-based CAs, or Dogtag with other implementations
• Gradual migration: Route a percentage of traffic to a new CA while maintaining the old one
• Geographic distribution: Route requests to the nearest or fastest CA
• Independent failure domains: HSM failure doesn’t take down file-based backup CAs

When a CA fails, kipuka’s circuit breaker immediately stops routing requests to it and redistributes traffic to healthy CAs in the same group. When the failed CA recovers, kipuka automatically reintegrates it based on the configured strategy.

Failover Strategies

kipuka supports four failover strategies, selectable globally via [ha] or per-group via [[ha.group]]:

active-passive

The primary CA handles all requests. If it fails, the secondary takes over. When the primary recovers, traffic automatically returns to it.

Use when:

• You have a clear primary CA (e.g., HSM-backed) and want a hot standby
• You need predictable CA assignment for audit or compliance
• Your CAs have different trust levels or security characteristics

Behavior:

• All requests routed to the first healthy CA in the group
• On failure, immediately switch to the next CA
• On recovery, immediately switch back to the primary

round-robin

Requests are distributed evenly across all healthy CAs in the group. Any failure removes that CA from rotation until it recovers.

Use when:

• All CAs in the group have equivalent capacity and trust
• You want to distribute load across multiple CAs
• You need to maximize utilization of all CA backends

Behavior:

• Each request goes to the next CA in a circular list
• Failed CAs are skipped in the rotation
• Load is balanced evenly across all healthy CAs

weighted

Requests are distributed according to configured weights (e.g., 80% to CA1, 20% to CA2). Allows proportional load distribution.

Use when:

• CAs have different capacities (e.g., HSM vs. software)
• You’re migrating from one CA to another gradually
• You want to test a new CA with a small percentage of traffic

Behavior:

• Each CA receives traffic proportional to its weight
• Weights are specified per-CA in the group configuration
• If a CA fails, its weight is redistributed to remaining CAs

Configuration:

[[ha.group]]
name = "primary"
ca_ids = ["hsm-ca", "file-ca"]
strategy = "weighted"
weights = { "hsm-ca" = 80, "file-ca" = 20 }

latency-based

Requests are routed to the CA with the lowest recent response time. Self-optimizing for geographically distributed CAs.

Use when:

• CAs are in different geographic locations
• Network latency varies significantly between CAs
• You want automatic optimization without manual tuning

Behavior:

• kipuka tracks rolling average latency for each CA
• Each request goes to the CA with the lowest average latency
• Latency is measured from health checks and actual signing operations
• Failed CAs are assigned infinite latency

Circuit Breaker Pattern

kipuka implements a circuit breaker to prevent cascading failures and automatically recover from transient issues. The circuit breaker prevents the system from repeatedly attempting to use a failing CA, which could delay client requests or exhaust resources.

States

The circuit breaker transitions through five states:

Healthy: CA is responding normally. All requests are routed to it according to the failover strategy.

Degraded: CA has experienced some failures but remains below the failure threshold. Requests continue to be routed, but the CA is monitored more closely. This state provides early warning of potential issues.

Unhealthy: Failure count exceeds failure_threshold within the check window. The CA is immediately removed from rotation to prevent client impact.

CircuitOpen: After transitioning to Unhealthy, the circuit opens. No requests are sent to this CA. A timer starts for recovery_timeout seconds to allow the CA time to recover.

Recovering: After recovery_timeout expires, a single probe request is sent. If it succeeds, the CA transitions back to Healthy and rejoins rotation. If it fails, the circuit returns to CircuitOpen with an extended timeout (exponential backoff).

State Transitions

Healthy --> Degraded --> Unhealthy --> CircuitOpen --> Recovering --> Healthy
   ^                                      |               |
   |                                      +-------<-------+
   +------------------<-------------------+

• Healthy → Degraded: First failure detected
• Degraded → Unhealthy: Failure count exceeds threshold
• Unhealthy → CircuitOpen: Immediate transition; timer starts
• CircuitOpen → Recovering: After recovery_timeout expires
• Recovering → Healthy: Probe succeeds; CA rejoins rotation
• Recovering → CircuitOpen: Probe fails; extended timeout begins
• Degraded → Healthy: CA recovers before hitting threshold
• CircuitOpen → Healthy: Manual operator override (health check passes)

Configuration

Circuit breaker behavior is tuned via [ha]:

[ha]
check_interval = "10s"        # How often to probe each CA
failure_threshold = 3          # Consecutive failures before marking unhealthy
recovery_timeout = "60s"       # Wait time before probing a failed CA
check_timeout = "5s"           # Max time to wait for health check response

• check_interval: Frequency of active health checks. Shorter intervals detect failures faster but increase CA load.
• failure_threshold: Number of consecutive failures before removing a CA from rotation. Lower values improve responsiveness but may cause flapping; higher values increase tolerance for transient failures.
• recovery_timeout: How long to wait before attempting recovery. This gives the CA time to fully restart or for transient issues to resolve. kipuka uses exponential backoff: if the first probe fails, the next timeout is doubled.
• check_timeout: Maximum time to wait for a health check response. Should be shorter than check_interval to avoid overlapping checks.

HA Groups

HA groups define sets of CAs that provide redundancy for each other. All CAs in a group should issue from the same root (or cross-certified roots) so clients trust all issuers.

Configuration

[[ha.group]]
name = "primary"               # Unique group name
ca_ids = ["hsm-ca", "file-ca"] # Array of [[ca]] id values
strategy = "active-passive"    # Optional: override global strategy

• name: Unique identifier for this group. Used in logs and metrics.
• ca_ids: Array of CA identifiers. Must reference valid [[ca]] sections. Order matters for active-passive strategy.
• strategy: Optional override of the global [ha] strategy. Allows different strategies for different groups.

EST Label Integration

EST labels reference individual CAs via their id. When the primary CA in a group fails, the HA system automatically routes requests to the next healthy CA in the group. From the client’s perspective, the EST label remains the same—failover is transparent.

Example:

[[ca]]
id = "hsm-ca"
backend = "dogtag"
# ... HSM configuration ...

[[ca]]
id = "file-ca"
backend = "file"
# ... file configuration ...

[[ha.group]]
name = "production"
ca_ids = ["hsm-ca", "file-ca"]
strategy = "active-passive"

[[est.label]]
name = "device-cert"
ca_id = "hsm-ca"  # References the group leader
profile = "deviceCert"

If hsm-ca fails, requests to the device-cert label automatically use file-ca until hsm-ca recovers.

Health Check Configuration

kipupa performs active health checks to detect CA failures and recoveries. Health checks are lightweight signing operations that verify the CA is fully functional—not just network-reachable.

Health Check Behavior

1. Every check_interval seconds, kipuka sends a test signing request to each CA
2. If the CA responds successfully within check_timeout, the check passes
3. If the CA fails to respond or returns an error, the check fails
4. After failure_threshold consecutive failures, the CA is marked Unhealthy
5. After recovery_timeout seconds, kipuka sends a single probe to the failed CA
6. If the probe succeeds, the CA returns to Healthy; if it fails, the timeout doubles

Tuning Recommendations

Low-latency environment (local CAs):

[ha]
check_interval = "5s"
failure_threshold = 2
recovery_timeout = "30s"
check_timeout = "2s"

High-latency environment (geographically distributed CAs):

[ha]
check_interval = "30s"
failure_threshold = 5
recovery_timeout = "120s"
check_timeout = "10s"

Production (balanced):

[ha]
check_interval = "10s"
failure_threshold = 3
recovery_timeout = "60s"
check_timeout = "5s"

Example Configurations

Two-CA Active-Passive with HSM Primary

A production deployment with an HSM-backed primary CA and a file-based backup. Normal traffic uses the HSM; if it fails, the file-based CA provides continuity.

[ha]
strategy = "active-passive"
check_interval = "10s"
failure_threshold = 3
recovery_timeout = "60s"
check_timeout = "5s"

[[ca]]
id = "hsm-ca"
backend = "dogtag"
[ca.dogtag]
url = "https://pki.example.com:8443"
ca_cert = "/etc/kipuka/pki-ca.pem"
auth_cert = "/etc/kipuka/ra-agent.pem"
auth_key = "pkcs11:token=HSM;object=ra-key"

[[ca]]
id = "backup-ca"
backend = "file"
[ca.file]
ca_cert = "/etc/kipuka/backup-ca.pem"
ca_key = "/etc/kipuka/backup-ca-key.pem"

[[ha.group]]
name = "production"
ca_ids = ["hsm-ca", "backup-ca"]

[[est.label]]
name = "device"
ca_id = "hsm-ca"  # HA group leader
profile = "deviceCert"

Expected behavior:

• All requests use hsm-ca under normal conditions
• If the HSM or Dogtag server fails, traffic immediately switches to backup-ca
• When hsm-ca recovers, traffic returns to it within one check_interval
• Clients see no difference—the device label works throughout

Three-CA Round-Robin for Load Distribution

Three identical CAs in different datacenters. Traffic is distributed evenly to maximize utilization and provide geographic redundancy.

[ha]
strategy = "round-robin"
check_interval = "15s"
failure_threshold = 3
recovery_timeout = "90s"
check_timeout = "7s"

[[ca]]
id = "ca-east"
backend = "dogtag"
[ca.dogtag]
url = "https://pki-east.example.com:8443"
ca_cert = "/etc/kipuka/ca.pem"
auth_cert = "/etc/kipuka/ra-east.pem"
auth_key = "/etc/kipuka/ra-east-key.pem"

[[ca]]
id = "ca-west"
backend = "dogtag"
[ca.dogtag]
url = "https://pki-west.example.com:8443"
ca_cert = "/etc/kipuka/ca.pem"
auth_cert = "/etc/kipuka/ra-west.pem"
auth_key = "/etc/kipuka/ra-west-key.pem"

[[ca]]
id = "ca-central"
backend = "dogtag"
[ca.dogtag]
url = "https://pki-central.example.com:8443"
ca_cert = "/etc/kipuka/ca.pem"
auth_cert = "/etc/kipuka/ra-central.pem"
auth_key = "/etc/kipuka/ra-central-key.pem"

[[ha.group]]
name = "global"
ca_ids = ["ca-east", "ca-west", "ca-central"]

[[est.label]]
name = "iot"
ca_id = "ca-east"  # Any CA in the group; round-robin applies
profile = "iotDevice"

Expected behavior:

• Requests are distributed 33/33/33 across the three CAs
• If ca-east fails, traffic is redistributed 50/50 to ca-west and ca-central
• When ca-east recovers, it rejoins the rotation
• Each CA operates independently; no shared state required

Geographic HA with Latency-Based Routing

Two CAs in different regions. kipuka automatically routes requests to the CA with the lowest latency, optimizing performance for geographically distributed clients.

[ha]
strategy = "latency-based"
check_interval = "20s"
failure_threshold = 4
recovery_timeout = "120s"
check_timeout = "10s"

[[ca]]
id = "ca-us"
backend = "dogtag"
[ca.dogtag]
url = "https://pki-us.example.com:8443"
ca_cert = "/etc/kipuka/ca.pem"
auth_cert = "/etc/kipuka/ra-us.pem"
auth_key = "/etc/kipuka/ra-us-key.pem"

[[ca]]
id = "ca-eu"
backend = "dogtag"
[ca.dogtag]
url = "https://pki-eu.example.com:8443"
ca_cert = "/etc/kipuka/ca.pem"
auth_cert = "/etc/kipuka/ra-eu.pem"
auth_key = "/etc/kipuka/ra-eu-key.pem"

[[ha.group]]
name = "global"
ca_ids = ["ca-us", "ca-eu"]

[[est.label]]
name = "vpn"
ca_id = "ca-us"  # HA group leader; latency-based routing applies
profile = "vpnCert"

Expected behavior:

• kipuka measures latency to both CAs during health checks
• Requests are automatically routed to the faster CA (e.g., ca-us for US clients, ca-eu for EU clients)
• If latency increases for one CA (network congestion, overload), traffic shifts to the other
• If one CA fails completely, all traffic uses the remaining CA
• No manual configuration required—self-optimizing based on network conditions

Weighted Migration from Old to New CA

Gradual migration from an existing CA to a new one. Start with 90% traffic on the old CA, gradually shift to 100% on the new CA, then decommission the old CA.

[ha]
strategy = "weighted"
check_interval = "10s"
failure_threshold = 3
recovery_timeout = "60s"
check_timeout = "5s"

[[ca]]
id = "old-ca"
backend = "dogtag"
[ca.dogtag]
url = "https://pki-old.example.com:8443"
ca_cert = "/etc/kipuka/old-ca.pem"
auth_cert = "/etc/kipuka/ra-old.pem"
auth_key = "/etc/kipuka/ra-old-key.pem"

[[ca]]
id = "new-ca"
backend = "dogtag"
[ca.dogtag]
url = "https://pki-new.example.com:8443"
ca_cert = "/etc/kipuka/new-ca.pem"
auth_cert = "/etc/kipuka/ra-new.pem"
auth_key = "/etc/kipuka/ra-new-key.pem"

[[ha.group]]
name = "migration"
ca_ids = ["old-ca", "new-ca"]
strategy = "weighted"
weights = { "old-ca" = 90, "new-ca" = 10 }

[[est.label]]
name = "server"
ca_id = "old-ca"
profile = "serverCert"

Migration procedure:

1. Start with weights = { "old-ca" = 100, "new-ca" = 0 } (new CA online but unused)
2. Update to weights = { "old-ca" = 90, "new-ca" = 10 } (10% canary traffic)
3. Monitor logs and metrics; if no issues, increase to 80/20, 50/50, 20/80
4. Finish with weights = { "old-ca" = 0, "new-ca" = 100 } (full cutover)
5. Remove old-ca from the configuration once fully decommissioned

No client reconfiguration required—weights can be adjusted without restarting kipuka.

Database Backends

kipuka uses a database to store issued certificates, audit logs, OTP tokens, and certificate authority state. Three backend options are supported: SQLite, PostgreSQL, and MariaDB. The database backend is configured via the [db] section in kipuka.toml.

SQLite

SQLite is the default backend and requires zero configuration. It is ideal for single-node deployments, development environments, and small to medium workloads.

URL Format

[db]
url = "sqlite:///var/lib/kipuka/kipuka.db"
auto_migrate = true

For in-memory testing:

[db]
url = "sqlite://:memory:"

Features and Characteristics

• Write-Ahead Logging (WAL): kipuka enables WAL mode by default, allowing concurrent reads while a write transaction is in progress.
• File Permissions: The database file should be owned by the kipuka service user with mode 0600 to prevent unauthorized access.
• Single-Writer: SQLite supports only one concurrent writer. This is not a limitation for single-node deployments but makes it unsuitable for high-availability configurations with shared state.
• No Network Access: The database must be on the local filesystem. Network-mounted filesystems (NFS, SMB) are not recommended due to locking and performance issues.

Backup

SQLite databases can be backed up using:

• File copy: While the WAL is checkpointed (kipuka handles this automatically), the database file can be copied. Use a consistent snapshot method to avoid corruption.

• sqlite3 .backup: The SQLite command-line tool provides a .backup command for online backups:

  sqlite3 /var/lib/kipuka/kipuka.db ".backup /backup/kipuka-$(date +%Y%m%d).db"
  

Best For

• Single-node deployments
• Development and testing
• Small to medium workloads (< 1000 requests/minute)
• Scenarios where operational simplicity is prioritized

Limitations

• Single writer (not suitable for multi-node HA with shared state)
• No network access (cannot be shared across nodes)
• Limited to local filesystem performance

PostgreSQL

PostgreSQL is the recommended backend for production multi-node deployments. It provides robust support for concurrent writes, network access, replication, and point-in-time recovery.

URL Format

[db]
url = "postgres://kipuka:[email protected]:5432/kipuka?sslmode=require"
max_connections = 20
connect_timeout = "5s"
auto_migrate = true

Features and Characteristics

• Concurrent Writes: Multiple kipuka nodes can write to the database simultaneously.
• Network Access: The database can be accessed over the network, enabling multi-node deployments.
• Replication: PostgreSQL supports streaming replication for read replicas and high availability.
• Point-in-Time Recovery (PITR): WAL archiving enables recovery to any point in time.
• Connection Pooling: kipuka maintains a connection pool sized by max_connections.

Connection Pool Tuning

The max_connections setting controls the size of kipuka’s connection pool to PostgreSQL:

• Default: 5 (suitable for low-load scenarios)
• Formula: Start with workers * 2 and adjust based on monitoring.
• Too Low: Connection pool exhaustion under load, causing requests to queue.
• Too High: Unnecessary resource consumption; may exceed PostgreSQL’s max_connections limit (default 100).

Monitor pool utilization via the Admin API endpoint /admin/health, which reports connection pool statistics.

PostgreSQL Configuration

Ensure max_connections in postgresql.conf is set higher than the sum of all kipuka nodes’ max_connections. Leave headroom for other applications and administrative connections.

# postgresql.conf
max_connections = 100

SSL Connections

Append ?sslmode=require to the URL to enforce SSL/TLS connections:

url = "postgres://kipuka:${DB_PASSWORD}@db.example.com:5432/kipuka?sslmode=require"

Best For

• Production environments
• High-availability deployments (with replication)
• High-throughput scenarios (> 1000 requests/minute)
• Multi-node clusters with shared state

MariaDB

MariaDB is an alternative to PostgreSQL and supports Galera Cluster for synchronous multi-master replication. It is well-suited for organizations already standardized on MariaDB or requiring Galera-based high availability.

URL Format

[db]
url = "mysql://kipuka:[email protected]:3306/kipuka"
max_connections = 20
connect_timeout = "5s"
auto_migrate = true

Features and Characteristics

• Galera Cluster: Provides synchronous multi-master replication, allowing writes to any node in the cluster.
• Concurrent Writes: Multiple kipuka nodes can write to the database simultaneously.
• Network Access: The database can be accessed over the network.

Galera Considerations

• Replication Format: Use ROW-based replication (binlog_format=ROW) for deterministic replication.
• Synchronous Reads: Set wsrep_sync_wait=1 to ensure reads reflect writes from all nodes (reads-after-writes consistency).

# MariaDB Galera configuration
wsrep_sync_wait=1
binlog_format=ROW

Best For

• Organizations standardized on MariaDB
• Galera Cluster-based high availability
• Multi-master replication requirements

Connection URL Formats Summary

Migrations

kipuka uses versioned, idempotent migrations to manage database schema changes. Migrations can be applied automatically on startup or run manually as a separate step.

Automatic Migrations

Set auto_migrate = true (the default) to apply pending migrations on startup:

[db]
auto_migrate = true

This is convenient for development and single-node deployments, but may not be suitable for production environments where migrations should be reviewed and tested before deployment.

Manual Migrations

Set auto_migrate = false to disable automatic migrations:

[db]
auto_migrate = false

Then run migrations manually using the kipuka migrate command:

# Show pending migrations
kipuka migrate status

# Apply pending migrations
kipuka migrate run

Best Practices

• Production: Run migrations as a separate step before starting the server. This allows you to review migrations, test them in a staging environment, and coordinate downtime if necessary.
• Development: Use auto_migrate = true for convenience.
• Idempotency: Migrations are idempotent and can be re-run safely. If a migration is interrupted, re-running it will complete the operation.

max_connections Tuning

The max_connections setting controls the size of kipuka’s database connection pool. Tuning this parameter is critical for balancing resource utilization and performance.

Default

The default is 5, which is suitable for SQLite and small deployments with low concurrency.

Tuning Formula

Start with the formula:

max_connections = workers * 2

Adjust based on monitoring and observed load. For example, if kipuka is configured with 4 workers, start with max_connections = 8.

Symptoms of Incorrect Settings

• Too Low: Connection pool exhaustion under load. Requests will queue waiting for an available connection, increasing latency.
• Too High: Unnecessary resource consumption (memory, file descriptors). May exceed the database’s max_connections limit, causing connection failures.

Monitoring

Use the Admin API endpoint /admin/health to monitor connection pool utilization:

curl http://localhost:8080/admin/health

The response includes metrics such as active connections, idle connections, and pool size.

PostgreSQL Configuration

Ensure PostgreSQL’s max_connections setting is higher than the sum of all kipuka nodes’ max_connections. For example:

• 3 kipuka nodes, each with max_connections = 20 → 60 total
• PostgreSQL max_connections = 100 → 40 connections available for other applications and administrative tasks

Credential Security

Database connection URLs often contain sensitive credentials (usernames and passwords). Follow these best practices to protect credentials:

Environment Variable Substitution

kipuka supports environment variable substitution in the url field using the ${ENV_VAR} syntax:

[db]
url = "postgres://kipuka:${DB_PASSWORD}@db.example.com:5432/kipuka"

Set the environment variable before starting kipuka:

export DB_PASSWORD="your-secure-password"
kipuka run

Or use a systemd service file with EnvironmentFile:

[Service]
EnvironmentFile=/etc/kipuka/db.env
ExecStart=/usr/bin/kipuka run

Never Commit Passwords

Never commit plaintext passwords to version control. Use:

• Environment variables (as shown above)
• Secret management systems (e.g., HashiCorp Vault, AWS Secrets Manager)
• Encrypted configuration files with restricted file permissions

Example: Secrets Manager Integration

For production deployments, consider integrating with a secrets manager:

# Fetch password from secrets manager
export DB_PASSWORD=$(vault kv get -field=password secret/kipuka/db)

# Start kipuka
kipuka run

This ensures credentials are never written to disk in plaintext and can be rotated without modifying configuration files.

Audit Logging

kipuka implements comprehensive audit logging designed to meet NIAP Protection Profile for Certification Authorities requirements, specifically FAU_GEN.1 (Audit Data Generation). All security-relevant events are recorded with sufficient detail for forensic analysis and compliance verification.

NIAP FAU_GEN.1 Compliance

kipuka’s audit logging implementation satisfies the following FAU_GEN.1 requirements:

• Completeness: All security-relevant events are recorded, including certificate issuance, revocation, authentication attempts, and administrative actions.
• Sufficient Detail: Each audit record contains timestamp (UTC), event type, outcome (success/failure), subject identity, source IP address, and event-specific data necessary for forensic analysis.
• Tamper Evidence: Audit records are append-only. The database audit tables permit only INSERT operations; UPDATE and DELETE operations are prohibited at the schema level.
• Reliability: Audit records are written synchronously to the database, with optional asynchronous replication to file and syslog destinations.

Audit Event Types

kipuka records 22 distinct event types across four categories:

Audit Destinations

kipuka supports three audit destinations that operate independently. The database destination is always active; file and syslog destinations are optional.

Database (Always Active)

All audit events are written to the audit_log table in the kipuka database. This destination is always active and cannot be disabled.

Characteristics:

• INSERT-only: The database schema enforces that audit records can only be inserted, never updated or deleted.
• Queryable: Audit records can be retrieved via the Admin API for compliance reporting and forensic analysis.
• Persistent: Records remain in the database until explicitly purged by an administrator through documented procedures.

File (Append-Only JSON)

When configured, kipuka writes audit events to a file in JSON Lines format (one JSON object per line). The file is opened with the O_APPEND flag to ensure records cannot be overwritten.

Configuration:

[audit]
file = "/var/log/kipuka/audit.json"

Rotation: Use logrotate with the copytruncate option or equivalent log rotation tools. Example logrotate configuration:

/var/log/kipuka/audit.json {
    daily
    rotate 90
    compress
    delaycompress
    copytruncate
    missingok
    notifempty
}

Example JSON Record:

{
  "timestamp": "2026-06-24T14:32:10.123456Z",
  "event_type": "cert.issued",
  "outcome": "success",
  "subject": "CN=server.example.com",
  "source_ip": "192.0.2.45",
  "serial": "4A:3F:21:8C:09:77:34:2B",
  "issuer": "CN=Example CA",
  "not_before": "2026-06-24T14:32:00Z",
  "not_after": "2027-06-24T14:32:00Z"
}

Syslog (RFC 5424, Optional TLS)

kipuka can forward audit events to a remote syslog server using RFC 5424 format. UDP, TCP, and TLS-encrypted TCP are supported.

Configuration:

[audit]
syslog = "tcp+tls://syslog.example.com:6514"
syslog_facility = "local0"

Supported URL Schemes:

• udp://host:port - Unencrypted UDP (not recommended for production)
• tcp://host:port - Unencrypted TCP
• tcp+tls://host:port - TLS-encrypted TCP (recommended for NIAP compliance)

Syslog Facilities: The syslog_facility option accepts local0 through local7. Default is local0.

Structured Data: Audit events are encoded as RFC 5424 structured data elements. Example syslog message:

<134>1 2026-06-24T14:32:10.123456Z server1 kipuka 12345 cert.issued [audit event_type="cert.issued" outcome="success" subject="CN=server.example.com" source_ip="192.0.2.45" serial="4A:3F:21:8C:09:77:34:2B"]

Event Filtering

The events array in the [audit] section controls which events are forwarded to file and syslog destinations. The database always records all events regardless of this filter.

Default Behavior: If the events array is omitted or empty, all event types are forwarded to file and syslog.

Filtering Example: To log only security-critical events to file/syslog:

[audit]
file = "/var/log/kipuka/audit.json"
events = [
    "cert.issued",
    "cert.denied",
    "cert.revoked",
    "auth.otp.failure",
    "auth.otp.lockout",
    "auth.mtls.failure",
    "admin.access",
]

In this configuration, successful routine operations (e.g., enroll.success, auth.otp.success) are recorded only in the database, reducing file and syslog volume while maintaining complete audit trail in the database for compliance queries.

Certificate Data in Audit Records

By default, audit records for certificate lifecycle events include metadata (serial number, subject, issuer, validity dates) but not the full certificate. The include_cert_data option controls whether the complete PEM-encoded certificate is included.

Default (include_cert_data = false):

{
  "timestamp": "2026-06-24T14:32:10.123456Z",
  "event_type": "cert.issued",
  "serial": "4A:3F:21:8C:09:77:34:2B",
  "subject": "CN=server.example.com",
  "issuer": "CN=Example CA",
  "not_before": "2026-06-24T14:32:00Z",
  "not_after": "2027-06-24T14:32:00Z"
}

With Full Certificate Data (include_cert_data = true):

{
  "timestamp": "2026-06-24T14:32:10.123456Z",
  "event_type": "cert.issued",
  "serial": "4A:3F:21:8C:09:77:34:2B",
  "subject": "CN=server.example.com",
  "issuer": "CN=Example CA",
  "not_before": "2026-06-24T14:32:00Z",
  "not_after": "2027-06-24T14:32:00Z",
  "certificate": "-----BEGIN CERTIFICATE-----\nMIIDXTCCAkWgAwIBAgIJAEo/IYwJdzQr...\n-----END CERTIFICATE-----"
}

Trade-offs:

• Enabling include_cert_data significantly increases audit log size (typical certificate is 1-2 KB).
• Required by some compliance frameworks (e.g., certain government PKI policies) for complete certificate lifecycle tracking.
• Useful for forensic analysis when the original certificate is no longer available in the database.

Configuration Examples

Minimal Configuration (File Only)

[audit]
file = "/var/log/kipuka/audit.json"

This configuration writes all audit events to a local file with default settings.

Production Configuration (File + Syslog over TLS)

[audit]
file = "/var/log/kipuka/audit.json"
syslog = "tcp+tls://syslog.example.com:6514"
syslog_facility = "local1"
events = [
    "cert.issued",
    "cert.denied",
    "cert.revoked",
    "auth.otp.failure",
    "auth.otp.lockout",
    "auth.mtls.failure",
    "admin.access",
    "otp.created",
    "server.startup",
    "server.shutdown",
]

This configuration:

• Logs all events to the database (always active).
• Logs security-critical events to both file and remote syslog over TLS.
• Reduces file and syslog volume by filtering routine successful operations.

NIAP-Compliant Configuration

[audit]
file = "/var/log/kipuka/audit.json"
syslog = "tcp+tls://syslog.example.com:6514"
syslog_facility = "local0"
include_cert_data = true
# events array omitted: all events forwarded to file and syslog

This configuration:

• Logs all 22 event types to database, file, and syslog.
• Uses TLS-encrypted syslog for confidentiality and integrity.
• Includes full certificate data in audit records for complete lifecycle tracking.
• Meets NIAP FAU_GEN.1 requirements for completeness, detail, and tamper evidence.

Note: Enabling include_cert_data will substantially increase storage requirements. Plan for approximately 2-5 KB per certificate lifecycle event (issuance, renewal, revocation).

Admin API

The Admin API provides privileged endpoints for server management, monitoring, OTP provisioning, and certificate lifecycle operations. It runs on a separate port from the EST service to enable network-level access control and is disabled by default for security.

Enabling the Admin API

The Admin API is disabled by default. To enable it, configure both the [admin] section and the admin_listen address in [server].

The Admin API runs on a separate port (default 9443) to allow network-level access control. Bind to 127.0.0.1 for localhost-only access, or to a management VLAN IP for remote administration:

[server]
admin_listen = "127.0.0.1:9443"

[admin]
enabled = true
auth = "mtls"
trust_anchors = "/etc/kipuka/admin-ca.pem"

Authentication Methods

The Admin API supports three authentication modes configured via the auth parameter:

mTLS Authentication

Admin clients must present a certificate signed by the admin trust anchors CA. This is the most secure option and recommended for production environments.

[admin]
enabled = true
auth = "mtls"
trust_anchors = "/etc/kipuka/admin-ca.pem"

Bearer Token Authentication

Admin clients provide a bearer token in the Authorization header. The token value is loaded from the environment variable specified by bearer_token_env.

[admin]
enabled = true
auth = "bearer"
bearer_token_env = "KIPUKA_ADMIN_TOKEN"

Clients authenticate using:

curl -H "Authorization: Bearer $KIPUKA_ADMIN_TOKEN" \
  https://localhost:9443/admin/health

Both Authentication

Either mTLS or bearer token accepted. Useful during migration periods or for mixed tooling environments.

[admin]
enabled = true
auth = "both"
trust_anchors = "/etc/kipuka/admin-ca.pem"
bearer_token_env = "KIPUKA_ADMIN_TOKEN"

Endpoints Overview

OTP Provisioning Workflow

The OTP provisioning workflow enables secure initial enrollment for devices that do not yet have certificates.

Step 1: Admin Generates OTP

The administrator creates a new OTP token with specified constraints:

curl -s --cert admin.pem --key admin-key.pem \
  --cacert admin-ca.pem \
  -X POST https://localhost:9443/admin/otp \
  -H "Content-Type: application/json" \
  -d '{"label": "device-42", "ttl": "24h", "max_uses": 1}'

Response:

{
  "token_id": "01234567-89ab-cdef-0123-456789abcdef",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires": "2026-06-25T14:30:00Z",
  "label": "device-42",
  "max_uses": 1
}

Parameters:

• label: Human-readable identifier for the token (for audit logs)
• ttl: Time-to-live (e.g., “24h”, “7d”, “1h30m”)
• max_uses: Maximum number of times the token can be used (typically 1)

Step 2: Admin Delivers Token to Client Operator

The token value must be delivered out-of-band through a secure channel:

• Encrypted email
• Ticketing system
• Secure messaging platform
• In-person handoff

Never transmit OTP tokens over unencrypted channels.

Step 3: Client Uses OTP for Initial Enrollment

The client operator uses the OTP token for initial EST enrollment:

curl --cacert ca.pem \
  -u ":eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  --data-binary @csr.pem \
  -H "Content-Type: application/pkcs10" \
  -o cert.p7 \
  https://est.example.com/.well-known/est/simpleenroll

Note the colon prefix in the -u flag: HTTP Basic Auth uses username:password format, and OTP tokens are submitted as the password with an empty username.

Step 4: OTP Consumed After Successful Enrollment

After successful enrollment, the OTP is marked as consumed if max_uses=1. Subsequent attempts to use the same token will be rejected.

Step 5: Future Renewals Use Certificate-Based mTLS

Once the device has a certificate, all future operations (reenrollment, renewal) use the issued certificate for mTLS authentication. The OTP is no longer required.

CA Status Monitoring

List All CAs

curl --cert admin.pem --key admin-key.pem \
  --cacert admin-ca.pem \
  https://localhost:9443/admin/ca

Response:

[
  {
    "id": "primary-ca",
    "name": "Primary Issuing CA",
    "status": "healthy",
    "last_check": "2026-06-24T12:34:56Z",
    "cert_not_after": "2028-12-31T23:59:59Z",
    "certs_issued_today": 42,
    "certs_issued_total": 15234
  },
  {
    "id": "backup-ca",
    "name": "Backup Issuing CA",
    "status": "healthy",
    "last_check": "2026-06-24T12:34:56Z",
    "cert_not_after": "2029-06-30T23:59:59Z",
    "certs_issued_today": 0,
    "certs_issued_total": 0
  }
]

Status values:

• healthy: CA is operational and passing all health checks
• degraded: CA is operational but experiencing issues (e.g., approaching expiration)
• unhealthy: CA is not operational (e.g., expired, HSM unreachable)

Get Specific CA Details

curl --cert admin.pem --key admin-key.pem \
  --cacert admin-ca.pem \
  https://localhost:9443/admin/ca/primary-ca

This endpoint provides detailed status for a single CA, including backend-specific health information.

Get CA Certificate Chain

curl --cert admin.pem --key admin-key.pem \
  --cacert admin-ca.pem \
  https://localhost:9443/admin/ca/primary-ca/chain

Returns the CA certificate chain in PEM format. This is useful for distributing trust anchors to clients.

Aggregate Health Status

curl --cert admin.pem --key admin-key.pem \
  --cacert admin-ca.pem \
  https://localhost:9443/admin/health

Response:

{
  "status": "healthy",
  "components": {
    "database": "healthy",
    "cas": {
      "primary-ca": "healthy",
      "backup-ca": "healthy"
    },
    "hsm": "healthy"
  },
  "uptime": "3d 14h 22m"
}

Use this endpoint for monitoring dashboards and alerting. Aggregate status reflects the worst status of any component:

• All components healthy: healthy
• Any component degraded: degraded
• Any component unhealthy: unhealthy

Kubernetes Probes

For Kubernetes deployments, use the dedicated probe endpoints:

Readiness probe (server is ready to accept traffic):

curl https://localhost:9443/admin/health/ready

Liveness probe (server is running):

curl https://localhost:9443/admin/health/live

Configure in your Deployment manifest:

livenessProbe:
  httpGet:
    path: /admin/health/live
    port: 9443
    scheme: HTTPS
  initialDelaySeconds: 10
  periodSeconds: 30

readinessProbe:
  httpGet:
    path: /admin/health/ready
    port: 9443
    scheme: HTTPS
  initialDelaySeconds: 5
  periodSeconds: 10

Certificate Management

List Issued Certificates

List certificates with optional filtering and pagination:

curl --cert admin.pem --key admin-key.pem \
  --cacert admin-ca.pem \
  "https://localhost:9443/admin/certs?status=active&ca=primary-ca&page=1&per_page=50"

Query parameters:

• status: Filter by certificate status (active, revoked, expired)
• ca: Filter by issuing CA ID
• subject: Filter by subject DN (substring match)
• page: Page number (1-indexed)
• per_page: Results per page (default 50, max 1000)

Response:

{
  "certs": [
    {
      "serial": "1a2b3c4d5e6f7890",
      "subject": "CN=device-42.example.com",
      "issuer": "CN=Primary Issuing CA",
      "not_before": "2026-06-24T00:00:00Z",
      "not_after": "2027-06-24T23:59:59Z",
      "status": "active",
      "ca_id": "primary-ca"
    }
  ],
  "total": 15234,
  "page": 1,
  "per_page": 50
}

Get Certificate Details

Retrieve detailed information for a specific certificate by serial number:

curl --cert admin.pem --key admin-key.pem \
  --cacert admin-ca.pem \
  https://localhost:9443/admin/certs/1a2b3c4d5e6f7890

Response includes full certificate details, issuance metadata, and audit trail.

Revoke a Certificate

Revoke a certificate by serial number with a reason code:

curl --cert admin.pem --key admin-key.pem \
  --cacert admin-ca.pem \
  -X POST https://localhost:9443/admin/certs/1a2b3c4d5e6f7890/revoke \
  -H "Content-Type: application/json" \
  -d '{"reason": "keyCompromise"}'

Valid reason codes (per RFC 5280):

• unspecified: Default reason
• keyCompromise: Private key compromise
• caCompromise: CA key compromise
• affiliationChanged: Subject changed affiliation
• superseded: Certificate replaced
• cessationOfOperation: Certificate no longer needed
• privilegeWithdrawn: Certificate privileges revoked

Response:

{
  "serial": "1a2b3c4d5e6f7890",
  "status": "revoked",
  "revocation_time": "2026-06-24T14:30:00Z",
  "revocation_reason": "keyCompromise"
}

The certificate is immediately marked as revoked in the database and will appear in the next CRL update.

Audit Log Queries

Query the audit log for security analysis and compliance:

curl --cert admin.pem --key admin-key.pem \
  --cacert admin-ca.pem \
  "https://localhost:9443/admin/audit?action=enroll&start=2026-06-01&end=2026-06-24&page=1&per_page=100"

Query parameters:

• action: Filter by action type (enroll, reenroll, serverkeygen, revoke, otp_generate, otp_use)
• subject: Filter by certificate subject DN
• ca: Filter by CA ID
• start: Start timestamp (ISO 8601)
• end: End timestamp (ISO 8601)
• page: Page number (1-indexed)
• per_page: Results per page (default 100, max 1000)

Response:

{
  "events": [
    {
      "timestamp": "2026-06-24T10:15:30Z",
      "action": "enroll",
      "subject": "CN=device-42.example.com",
      "ca_id": "primary-ca",
      "result": "success",
      "client_ip": "10.0.1.42",
      "auth_method": "otp",
      "serial": "1a2b3c4d5e6f7890"
    }
  ],
  "total": 1523,
  "page": 1,
  "per_page": 100
}

Metrics

The Admin API exposes Prometheus-format metrics for monitoring:

curl --cert admin.pem --key admin-key.pem \
  --cacert admin-ca.pem \
  https://localhost:9443/admin/metrics

Key metrics include:

• kipuka_enrollments_total: Counter of enrollment operations by CA and result
• kipuka_reenrollments_total: Counter of reenrollment operations by CA and result
• kipuka_revocations_total: Counter of revocation operations by CA and reason
• kipuka_otp_generated_total: Counter of OTP tokens generated
• kipuka_otp_consumed_total: Counter of OTP tokens consumed
• kipuka_request_duration_seconds: Histogram of request durations by endpoint
• kipuka_active_certificates: Gauge of currently active certificates by CA
• kipuka_ca_health: Gauge of CA health status (1=healthy, 0=unhealthy)

Configure Prometheus to scrape the Admin API endpoint with appropriate mTLS credentials.

Dogtag PKI Integration

Overview

kipuka can use Red Hat Certificate System (Dogtag PKI) as a backend CA instead of, or alongside, file-based or HSM-backed local CAs. This integration enables organizations already running Dogtag/RHCS to add EST enrollment capabilities without modifying their existing PKI infrastructure.

Architecture:

• Dogtag provides a full-featured PKI with REST API, comprehensive audit logging, HSM support, and complete certificate lifecycle management
• kipuka acts as an EST frontend (Registration Authority) to Dogtag’s CA subsystem
• The integration preserves all Dogtag policies, approval workflows, and certificate profiles while exposing EST protocol endpoints

Benefits:

• Leverage existing Dogtag infrastructure and operational expertise
• Maintain centralized certificate policy enforcement in Dogtag profiles
• Benefit from Dogtag’s enterprise features: HSM integration, audit trails, approval workflows, Key Recovery Authority (KRA)
• Add EST enrollment to IoT devices, network equipment, and mobile endpoints without deploying new CA infrastructure

REST API Client

kipuka communicates with Dogtag exclusively via its REST API, typically exposed at https://dogtag.example.com:8443/ca/rest/certrequests.

Authentication

kipuka authenticates to Dogtag using a client certificate (agent cert) that has enrollment privileges. This certificate must be issued by the Dogtag CA itself and associated with an agent user in the Dogtag database.

Obtaining an agent certificate:

1. On the Dogtag server, create an agent user (if not already present):

   pki -d /var/lib/pki/pki-tomcat/alias -c <password> \
       ca-user-add kipuka-agent --fullName "kipuka EST RA"
   

2. Generate a certificate request and submit it for the agent certificate:

   pki -d /var/lib/pki/pki-tomcat/alias -c <password> \
       client-cert-request "CN=kipuka EST RA,O=Example Corp" \
       --profile caAgentServerCert
   

3. Approve and issue the certificate via the Dogtag web UI or CLI

4. Export the agent certificate and key for use by kipuka

Configuration

Configure Dogtag as a CA entry with type = "dogtag":

[[ca]]
id = "dogtag-ca"
name = "Dogtag Enterprise CA"
type = "dogtag"

# Dogtag instance URL (without /ca/rest suffix)
url = "https://dogtag.example.com:8443"

# Agent certificate for authenticating to Dogtag
agent_cert = "/etc/kipuka/dogtag/agent.pem"
agent_key = "/etc/kipuka/dogtag/agent-key.pem"

# Dogtag CA certificate chain for TLS verification
ca_cert = "/etc/kipuka/dogtag/ca-chain.pem"

# Default certificate profile for this CA
profile = "caServerCert"

# Optional: Request timeout (default: 30s)
timeout = "30s"

# Optional: Enable certificate caching to reduce Dogtag load
cache_certificates = true
cache_ttl = "1h"

File formats:

• agent_cert and ca_cert: PEM-encoded X.509 certificates
• agent_key: PEM-encoded RSA or EC private key (can be encrypted; kipuka will prompt for passphrase)

Enrollment

When kipuka receives an EST /simpleenroll request, it translates the PKCS#10 CSR into a Dogtag certificate enrollment request and submits it to the Dogtag REST API.

Profile Mapping

Dogtag uses certificate profiles (e.g., caServerCert, caUserCert, caTPSCert) to define certificate content, extensions, and policy constraints. kipuka maps EST labels to Dogtag profiles:

[[est.label]]
name = "server-tls"
ca_id = "dogtag-ca"
dogtag_profile = "caServerCert"

[[est.label]]
name = "client-auth"
ca_id = "dogtag-ca"
dogtag_profile = "caUserCert"

[[est.label]]
name = "token-signing"
ca_id = "dogtag-ca"
dogtag_profile = "caTPSCert"

Default profile: If no label is provided in the EST request, the profile specified in the [[ca]] entry is used.

Enrollment Flow

1. Client sends EST /simpleenroll request with PKCS#10 CSR
2. kipuka validates the CSR and authenticates the client (via HTTP Basic or TLS client cert)
3. kipuka determines the Dogtag profile based on the EST label
4. kipuka submits the CSR to Dogtag: POST /ca/rest/certrequests
5. Dogtag processes the request according to the profile policy:
   • If auto-approval is enabled in the profile, the certificate is issued immediately
   • If approval is required, the request enters pending state
6. kipuka polls Dogtag until the certificate is issued (or timeout expires)
7. kipuka returns the issued certificate to the EST client in PKCS#7 format

Manual Approval Workflow

If the Dogtag profile requires manual approval (common for high-assurance certificates):

1. The enrollment request remains in Dogtag’s pending queue
2. An agent approves the request via Dogtag web UI or CLI:

   pki ca-cert-request-review <request_id> --action approve
   

3. kipuka’s next poll retrieves the issued certificate
4. The EST client receives the certificate (this may take seconds to minutes depending on poll interval)

Polling configuration:

[[ca]]
id = "dogtag-ca"
type = "dogtag"
# ... other config ...

# Poll interval for pending certificate requests (default: 5s)
poll_interval = "5s"

# Maximum time to wait for approval (default: 5m)
approval_timeout = "5m"

If approval_timeout expires before the certificate is issued, kipuka returns an HTTP 202 response to the client with a retry-after header.

Revocation

kipuka’s Admin API revocation calls are forwarded to Dogtag’s revocation endpoint.

Revoke via Admin API

curl -X POST https://kipuka.example.com/admin/revoke \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "serial": "0x1A2B3C4D",
    "reason": "keyCompromise"
  }'

Revocation Flow

1. kipuka receives the revocation request via Admin API
2. kipuka maps the serial number to the issuing CA (in this case, dogtag-ca)
3. kipuka submits a revocation request to Dogtag: POST /ca/rest/agent/certs/<serial>/revoke
4. Dogtag revokes the certificate and updates its internal database
5. Dogtag automatically updates CRLs and OCSP responder (if enabled)
6. kipuka returns success to the caller

Revocation Reason Mapping

kipuka maps its revocation reason codes to Dogtag’s reason codes per RFC 5280:

Note: Dogtag does not support removeFromCRL (un-hold) via the REST API for certificates revoked with certificateHold. Use the Dogtag CLI for un-hold operations.

KRA Server-Side Key Generation

EST’s /serverkeygen endpoint can use Dogtag’s Key Recovery Authority (KRA) subsystem for server-side key generation and archival.

Overview

When server-side key generation is requested:

1. kipuka forwards the request to Dogtag with the KRA archival flag enabled
2. Dogtag’s KRA subsystem generates the key pair server-side
3. The private key is encrypted and archived in the KRA database
4. Dogtag issues the certificate using the generated public key
5. kipuka receives both the certificate and the encrypted private key
6. The private key is returned to the EST client as a PKCS#8 EncryptedPrivateKeyInfo wrapped in the EST response

Prerequisites

• Dogtag KRA subsystem must be installed and configured
• The KRA must be configured to communicate with the CA subsystem
• The agent certificate used by kipuka must have key archival privileges

Configuration

[[ca]]
id = "dogtag-ca"
type = "dogtag"
url = "https://dogtag.example.com:8443"

# KRA endpoint (often same host as CA)
kra_url = "https://dogtag.example.com:8443"

# KRA agent credentials (may be same as CA agent or separate)
kra_agent_cert = "/etc/kipuka/dogtag/kra-agent.pem"
kra_agent_key = "/etc/kipuka/dogtag/kra-agent-key.pem"

# ... other CA config ...

If kra_url is not specified, server-side key generation is disabled for this CA.

EST Request

curl -X POST https://kipuka.example.com/.well-known/est/serverkeygen \
  --user client:password \
  --cacert ca.pem \
  -H "Content-Type: application/pkcs10" \
  --data-binary @csr.p10 \
  -o response.p7

The response is a PKCS#7 structure containing:

• The issued certificate
• The encrypted private key (PKCS#8 EncryptedPrivateKeyInfo)
• Optional additional CA certificates

Client-side decryption: The client must decrypt the private key using the password provided during enrollment (passed in the CSR’s challenge password attribute, or via out-of-band key).

Key Recovery

If a client loses their private key, authorized users can recover it from the KRA:

pki kra-key-recover --keyID <key_id> --output recovered-key.p12

This operation requires dual approval from KRA agents (depending on KRA policy).

Supported Key Algorithms

The KRA supports server-side generation of the following key types:

The key algorithm is determined by the Dogtag certificate profile. When the EST client’s CSR specifies a key algorithm via the csrattrs response, kipuka maps it to the appropriate KRA parameter.

CMC Passthrough Details

When Full CMC passthrough is enabled (est.fullcmc = true), kipuka acts as a transparent CMC gateway between EST clients and Dogtag. The CMC message format is preserved end-to-end:

1. Request path: Client -> EST /fullcmc -> kipuka -> Dogtag /ca/rest/certrequests/cmc
2. Response path: Dogtag CMC response -> kipuka -> EST client

kipuka validates the outer CMS SignedData wrapper but does not modify the inner CMC PKIData payload. This enables:

• Batch enrollment: Multiple certificate requests in a single CMC transaction
• Key recovery: CMC-wrapped key recovery requests forwarded to KRA
• Revocation: CMC revocation requests processed by Dogtag’s RA
• TPS integration: Token Processing System operations over EST transport

The synta-cmc crate handles CMC message parsing and construction, providing full RFC 5272/5273/5274 compliance.

Multi-CA Pool with Circuit Breaker

Multiple Dogtag instances can be configured as separate CA entries to provide high availability and load distribution.

Configuration

[[ca]]
id = "dogtag-primary"
type = "dogtag"
url = "https://dogtag1.example.com:8443"
agent_cert = "/etc/kipuka/dogtag/agent.pem"
agent_key = "/etc/kipuka/dogtag/agent-key.pem"
ca_cert = "/etc/kipuka/dogtag/ca-chain.pem"
profile = "caServerCert"

[[ca]]
id = "dogtag-secondary"
type = "dogtag"
url = "https://dogtag2.example.com:8443"
agent_cert = "/etc/kipuka/dogtag/agent.pem"
agent_key = "/etc/kipuka/dogtag/agent-key.pem"
ca_cert = "/etc/kipuka/dogtag/ca-chain.pem"
profile = "caServerCert"

[ha]
enabled = true
strategy = "active-passive"

[[ha.group]]
name = "dogtag-pool"
ca_ids = ["dogtag-primary", "dogtag-secondary"]

# Health check interval
health_check_interval = "30s"

# Circuit breaker thresholds
failure_threshold = 3
success_threshold = 2
timeout = "10s"

Failover Behavior

Active-Passive Strategy:

• All requests are routed to dogtag-primary
• If dogtag-primary fails health checks (3 consecutive failures), the circuit breaker trips
• Traffic is routed to dogtag-secondary while dogtag-primary is unavailable
• Once dogtag-primary passes health checks (2 consecutive successes), traffic is restored to primary

Active-Active Strategy (future):

[ha]
enabled = true
strategy = "active-active"

[[ha.group]]
name = "dogtag-pool"
ca_ids = ["dogtag-primary", "dogtag-secondary"]
load_balancing = "round-robin"  # or "least-connections"

Health Checks

kipuka performs health checks against each Dogtag instance:

GET /ca/rest/certs/ca HTTP/1.1
Host: dogtag1.example.com:8443

A successful response (HTTP 200 with the CA certificate) indicates the instance is healthy.

Monitoring endpoint:

curl https://kipuka.example.com/health/ca

Response:

{
  "dogtag-primary": {
    "status": "healthy",
    "last_check": "2026-06-24T10:30:00Z",
    "consecutive_failures": 0
  },
  "dogtag-secondary": {
    "status": "circuit_open",
    "last_check": "2026-06-24T10:30:00Z",
    "consecutive_failures": 5
  }
}

Full CMC Passthrough (RFC 5272)

When fullcmc = true in the [est] configuration, kipuka can pass Full CMC (Certificate Management over CMS) requests directly to Dogtag.

Overview

Full CMC (RFC 5272/5273/5274) supports complex certificate management operations beyond simple enrollment:

• Batch enrollment (multiple certificates in a single request)
• Certificate update/renewal
• Key recovery requests
• Revocation requests
• Get certificate/CRL operations

Dogtag is one of the few CAs that fully implements RFC 5272/5273/5274, making it ideal for enterprise CMC deployments.

Configuration

[est]
enabled = true
fullcmc = true

# Optional: CMC-specific settings
[est.cmc]
# Maximum CMC message size (default: 10MB)
max_message_size = "10MB"

# Allow unsigned CMC requests (default: false)
allow_unsigned = false

CMC Request Flow

1. Client constructs a Full CMC request (typically using CMCRequest tool or smart card management software)
2. Client submits the CMC request to kipuka’s EST endpoint: POST /.well-known/est/fullcmc
3. kipuka validates the CMC request structure and authenticates the client
4. kipuka forwards the CMC payload to Dogtag: POST /ca/rest/certrequests/cmc
5. Dogtag processes the CMC request according to its internal policies
6. Dogtag returns a CMC Full PKI Response
7. kipuka returns the CMC response to the EST client

Example: Batch Enrollment via CMC

# Create a CMC request with multiple CSRs
CMCRequest \
  -d /path/to/nssdb \
  -i csr1.pem \
  -i csr2.pem \
  -i csr3.pem \
  -o batch-request.cmc

# Submit to kipuka
curl -X POST https://kipuka.example.com/.well-known/est/fullcmc \
  --user agent:password \
  --cacert ca.pem \
  -H "Content-Type: application/pkcs7-mime" \
  --data-binary @batch-request.cmc \
  -o batch-response.cmc

# Parse the response
CMCResponse -d /path/to/nssdb -i batch-response.cmc

Token Processing System (TPS) Integration

Dogtag’s Token Processing System (TPS) uses Full CMC for smart card lifecycle management:

• Format and enroll smart cards
• Update certificates on existing tokens
• Recover keys from KRA to re-provision tokens

kipuka acts as a CMC gateway, enabling TPS to operate over EST endpoints. This is particularly useful for remote TPS operations where direct Dogtag access is restricted by firewall policy.

TPS configuration example:

[[ca]]
id = "dogtag-ca"
type = "dogtag"
url = "https://dogtag.example.com:8443"
kra_url = "https://dogtag.example.com:8443"
tps_url = "https://dogtag.example.com:8443"
# ... agent certs ...

[est.cmc]
# TPS may send large CMC messages with multiple key recovery requests
max_message_size = "50MB"

# TPS operations require signed CMC requests
allow_unsigned = false

Prerequisites

Before configuring kipuka with Dogtag integration, ensure:

1. Dogtag PKI Installation:

   • Dogtag PKI 10.x or 11.x (RHEL 7/8/9: Red Hat Certificate System 9.x or 10.x)
   • Fedora: Dogtag PKI 11.x available via dnf
   • CA subsystem installed and operational

2. Agent Certificate:

   • Agent certificate issued by the Dogtag CA with enrollment privileges
   • For KRA integration: separate agent cert with key archival/recovery privileges
   • Agent user configured in Dogtag database and added to appropriate groups

3. Network Connectivity:

   • kipuka must reach Dogtag REST API port (default: 8443)
   • If using Dogtag behind a load balancer, ensure session affinity for approval workflows
   • Firewall rules permit bidirectional HTTPS between kipuka and Dogtag

4. TLS Certificates:

   • Dogtag CA certificate chain for TLS verification
   • If Dogtag uses a private CA, install the root and intermediate certificates on kipuka host

5. Optional: KRA Subsystem:

   • KRA installed and configured if server-side key generation is required
   • KRA transport certificate and storage certificate properly configured
   • KRA connector enabled in CA subsystem

6. Profiles:

   • Ensure the certificate profiles referenced in kipuka configuration exist in Dogtag
   • Verify profile policies match your security requirements
   • Test profile submission via Dogtag CLI before configuring kipuka

Verification

Test Dogtag connectivity from the kipuka host:

# Verify CA REST API is accessible
curl -k https://dogtag.example.com:8443/ca/rest/certs/ca

# Submit a test certificate request using agent cert
curl -k https://dogtag.example.com:8443/ca/rest/certrequests \
  -X POST \
  --cert /etc/kipuka/dogtag/agent.pem \
  --key /etc/kipuka/dogtag/agent-key.pem \
  -H "Content-Type: application/json" \
  -d '{
    "ProfileID": "caServerCert",
    "Renewal": false,
    "Input": [{
      "Name": "cert_request_type",
      "Value": "pkcs10"
    }, {
      "Name": "cert_request",
      "Value": "<base64-encoded-csr>"
    }]
  }'

A successful response indicates the agent certificate is configured correctly and has enrollment privileges.

See Also

• High Availability Configuration for general HA strategies
• Admin API Reference for revocation endpoints
• Certificate Profiles for mapping EST labels to CA profiles
• Red Hat Certificate System documentation: https://access.redhat.com/documentation/en-us/red_hat_certificate_system/
• Dogtag PKI wiki: https://www.dogtagpki.org/wiki/PKI_Main_Page

CMP Protocol Configuration

The Certificate Management Protocol (CMP) is defined in RFC 4210 and updated in RFC 9810 (CMP v3). kipuka implements CMP as an alternative to EST for certificate lifecycle operations, providing stronger cryptographic protection options and more granular control over request types.

Overview

CMP vs EST

While EST provides a simpler REST-based API over HTTP, CMP offers:

• Stronger authentication: MAC-based or signature-based protection of all messages
• Fine-grained request control: Enable/disable specific operations (initial enrollment, renewal, revocation)
• Standardized error handling: Well-defined error codes and failure messages
• Vendor interoperability: Widely implemented in enterprise PKI systems

CMP runs alongside EST on the same server. The endpoint is located at:

/.well-known/cmp

Configuration

Enable CMP in your kipuka.toml configuration file:

[cmp]
enabled = true

# Request types allowed
allow_ir = true      # Initialization Request (initial enrollment)
allow_cr = true      # Certification Request (enrollment with existing cert)
allow_kur = true     # Key Update Request (renewal/rekey)
allow_rr = false     # Revocation Request (certificate revocation)

# Protection mechanisms
allow_mac_protection = true
mac_algorithm = "hmac-sha256"  # Options: hmac-sha256, hmac-sha384, hmac-sha512

# Certificate profile for new enrollments
reference_cert_profile = "server-cert"

# MAC shared secrets for authentication
[[cmp.mac_secrets]]
reference = "device-001"
secret_hex = "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

[[cmp.mac_secrets]]
reference = "device-002"
secret_hex = "f1e2d3c4b5a69788796a5b4c3d2e1f0"

Configuration Options

Protection Mechanisms

CMP supports two message protection modes:

MAC-Based Protection

MAC-based protection uses a pre-shared secret between the client and server. This is suitable for automated enrollment scenarios where devices are provisioned with shared secrets.

Advantages:

• No existing certificate required for initial enrollment
• Simpler client implementation
• Suitable for IoT and embedded devices

Configuration:

[[cmp.mac_secrets]]
reference = "fleet-alpha"
secret_hex = "00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff"

The reference field matches the sender field in the CMP message header. The secret_hex must be a hex-encoded value (even number of characters).

Signature-Based Protection

Signature-based protection uses an existing certificate to sign CMP messages. This provides stronger authentication when the client already possesses a valid certificate.

Advantages:

• Stronger cryptographic binding to identity
• No pre-shared secrets to manage
• Required for CR and KUR operations in high-security environments

Configuration:

Signature-based protection is automatically available when allow_mac_protection = true is not the only protection method configured. Clients provide their certificate chain in the extraCerts field.

Request Types

IR (Initialization Request)

Used for first-time enrollment when the client has no existing certificate.

Requirements:

• allow_ir = true
• MAC protection or administrator-approved request
• Valid proof-of-possession (POP) in the request

Example curl command (using MAC protection):

# Note: CMP uses binary ASN.1 encoding; this is a conceptual example
# Real CMP clients use libraries like OpenSSL, Bouncy Castle, or CMP-native tools

openssl cmp -cmd ir \
  -server https://est.example.com/.well-known/cmp \
  -ref "device-001" \
  -secret "pass:a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" \
  -newkey device-key.pem \
  -certout device-cert.pem

CR (Certification Request)

Used for enrollment when the client already has a certificate (possibly from another CA).

Requirements:

• allow_cr = true
• Signature-based protection using existing certificate
• Valid proof-of-possession

KUR (Key Update Request)

Used for certificate renewal or rekey operations.

Requirements:

• allow_kur = true
• Signature-based protection using current certificate
• New public key (for rekey) or same key (for renewal)

Example curl command:

openssl cmp -cmd kur \
  -server https://est.example.com/.well-known/cmp \
  -cert current-cert.pem \
  -key current-key.pem \
  -newkey new-key.pem \
  -certout renewed-cert.pem

RR (Revocation Request)

Used to revoke a certificate.

Requirements:

• allow_rr = true (disabled by default for security)
• Signature-based protection
• Authorization check against certificate ownership

Security Note: Revocation requests should be carefully controlled. Consider keeping allow_rr = false and using the administrative API for revocations instead.

Security Considerations

MAC Secret Management

1. Generate strong secrets: Use at least 32 bytes (256 bits) of cryptographically random data

   openssl rand -hex 32
   

2. Unique secrets per device: Never reuse MAC secrets across multiple devices

3. Rotation: Plan for periodic secret rotation. Update both server configuration and device provisioning.

4. Storage: Protect kipuka.toml with appropriate file permissions (0600). Consider using environment variables or secret management systems for production deployments.

Algorithm Selection

The default hmac-sha256 provides 256-bit security strength, suitable for most deployments. Use stronger algorithms for high-security environments:

mac_algorithm = "hmac-sha384"  # 384-bit security
mac_algorithm = "hmac-sha512"  # 512-bit security

Ensure clients support the selected algorithm.

Request Type Restrictions

Disable unused request types to reduce attack surface:

# Production configuration for renewal-only deployment
allow_ir = false   # Initial enrollment via EST only
allow_cr = false   # No cross-CA enrollment
allow_kur = true   # Renewal enabled
allow_rr = false   # Revocation via admin API only

Troubleshooting

Client reports “MAC verification failed”

Cause: Mismatch between client and server shared secret, or incorrect reference number.

Solution:

1. Verify the reference field in the client configuration matches a [[cmp.mac_secrets]] entry
2. Confirm the shared secret is identical (case-sensitive hex string)
3. Check server logs for the reference number received

“Request type not allowed” error

Cause: The requested operation (IR, CR, KUR, RR) is disabled in server configuration.

Solution:

1. Check allow_ir, allow_cr, allow_kur, allow_rr settings
2. Enable the required request type or use an alternative enrollment method (EST)

Certificate profile errors

Cause: reference_cert_profile points to a non-existent profile.

Solution:

1. Verify the profile name matches an entry in the [cert_profiles] section
2. Remove reference_cert_profile to use the default profile
3. Check server logs for available profile names

Performance issues with many devices

Solution:

• Consider using signature-based protection for high-volume deployments (eliminates MAC secret storage per device)
• Implement client-side caching of CA certificates
• Use HTTP/2 connection pooling

Integration Examples

IoT Device Provisioning

Provision devices with unique MAC secrets during manufacturing:

[[cmp.mac_secrets]]
reference = "sensor-{{ DEVICE_SERIAL }}"
secret_hex = "{{ PROVISIONED_SECRET }}"

Use template expansion in your provisioning system to generate unique entries.

Enterprise PKI Integration

Allow CMP for renewals, EST for initial enrollment:

[cmp]
enabled = true
allow_ir = false   # Use EST for initial enrollment
allow_kur = true   # CMP for renewals
allow_mac_protection = false  # Signature-based only

Air-Gapped Environments

Combine CMP with CMS-EST for disconnected operations:

[cmp]
enabled = true
allow_mac_protection = true

[cms_est]
enabled = true
require_signed_requests = true

See CMS-EST Configuration for details on offline enrollment workflows.

CMS-EST Configuration

CMS-EST (Cryptographic Message Syntax for EST) extends the Enrollment over Secure Transport protocol with CMS wrapping, as defined in RFC 8295. This enables EST operations in disconnected, air-gapped, or store-and-forward scenarios where direct HTTPS connectivity is unavailable.

Overview

CMS-EST vs Plain EST

Plain EST (RFC 7030) requires a direct HTTPS connection between client and server. CMS-EST allows:

• Offline enrollment: Generate CMS-wrapped requests on disconnected systems
• Store-and-forward: Transport requests via removable media, email, or batch processing
• Enhanced security: Mandatory message signing and optional encryption
• Air-gapped operations: No network connectivity required during request generation

The trade-off is increased complexity and message size due to CMS envelope overhead.

Use Cases

Air-Gapped Manufacturing

Enroll devices in a secure manufacturing facility without internet access:

1. Device generates CSR and wraps it in CMS on the factory floor
2. Operator transfers CMS file to network-connected workstation via USB
3. Workstation submits to kipuka CMS-EST endpoint
4. Signed certificate response is transferred back via USB
5. Device imports certificate

Batch Processing

Process enrollment requests from hundreds of devices simultaneously:

1. Devices generate CMS-wrapped enrollment requests during off-peak hours
2. Requests are queued on a management server
3. Batch submission to kipuka during maintenance window
4. Encrypted responses are distributed back to devices

Disconnected Field Operations

Military, maritime, or remote infrastructure scenarios:

1. Field technicians generate enrollment requests locally
2. Requests are stored until network connectivity is available
3. Periodic sync transfers requests to headquarters
4. Responses are synced back during next connectivity window

Frozen Device Enrollment During PQC Migration

As organizations migrate from classical cryptography (RSA/ECC) to post-quantum algorithms (ML-DSA, ML-KEM), some devices cannot migrate — sealed hardware, regulatory-locked platforms (FDA 510(k), Common Criteria EAL4+), and long-lifecycle embedded systems (20-30 year weapon platforms, industrial SCADA controllers). These “frozen devices” will continue using classical certificates for their entire remaining service life.

CMS-EST is the enrollment protocol for frozen devices because these systems typically:

• Operate behind air gaps or data diodes with no direct CA connectivity
• Cannot run ACME clients (constrained protocol stacks)
• Require offline enrollment that survives network outages spanning weeks or months
• Need certificate renewal without firmware updates

Enrollment workflow for frozen devices:

1. Frozen device generates a CSR using its existing classical key (RSA/ECC)
2. CSR is wrapped in CMS SignedData for integrity and optionally EnvelopedData for confidentiality
3. CMS-wrapped request crosses the air gap via removable media, data diode, or courier
4. Operator submits to kipuka’s CMS-EST endpoint on the connected network
5. kipuka processes the request against the Dogtag CA, which issues a classical certificate per the device’s certificate profile
6. Signed certificate response is CMS-wrapped and carried back across the air gap
7. Device imports the certificate

MTC transparency integration:

When combined with Merkle Tree Certificate transparency logging, every classical certificate issued to a frozen device is recorded in a tamper-evident log. An independent monitor validates each issuance against a frozen device registry:

• Authorized: The device identity, issuing CA, and algorithm match the frozen device record → issuance proceeds normally
• Unauthorized identity: A classical certificate is requested for an entity not in the frozen device registry → alert (potential attack or misconfiguration)
• Wrong CA: A classical certificate for a known frozen device is issued by an unexpected CA → alert (CA compromise)
• Wrong algorithm: A classical certificate uses a weaker algorithm than authorized (e.g., RSA-1024 instead of RSA-2048) → alert (downgrade)
• Expired authorization: A classical certificate is requested after the frozen device record’s expiry date → alert (device should have been migrated or decommissioned)

This turns frozen devices from an unmonitored security blind spot into an audited, policy-controlled exception within the broader PQC migration.

Configuration for frozen device profiles:

[cms_est]
enabled = true
require_signed_requests = true
encrypt_responses = true

# Frozen device certificate profiles restrict algorithm and validity
# These are enforced by the Dogtag CA certificate profile, not kipuka
# kipuka passes the enrollment request to the CA, which applies profile constraints

The Dogtag CA certificate profile for frozen devices should enforce:

• Classical algorithms only (RSA-2048, RSA-3072, or ECDSA-P256 per device capability)
• Maximum validity period aligned with the device’s remaining service life
• Key usage restrictions appropriate to the device’s function
• Extended key usage limiting the certificate’s applicability

Configuration

Enable CMS-EST in your kipuka.toml configuration:

[cms_est]
enabled = true

# Message protection requirements
require_signed_requests = true     # Mandate digital signatures on all requests
encrypt_responses = true           # Encrypt all response messages

# Encryption algorithms (in preference order)
allowed_content_encryption = [
    "AES-256-GCM",   # Preferred: AEAD with 256-bit key
    "AES-128-GCM",   # Fallback: AEAD with 128-bit key
    "AES-256-CBC"    # Legacy support (avoid if possible)
]

Configuration Options

Content Encryption Algorithms

kipuka supports three encryption algorithms for CMS-EST responses:

AES-256-GCM (Recommended)

Authenticated Encryption with Associated Data (AEAD) providing both confidentiality and integrity. Requires clients support GCM mode.

Advantages:

• Single operation provides encryption and authentication
• No padding oracle vulnerabilities
• Faster than CBC for hardware-accelerated platforms

Configuration:

allowed_content_encryption = ["AES-256-GCM"]

AES-128-GCM

Similar to AES-256-GCM but with 128-bit key length. Suitable for resource-constrained devices.

Use when:

• Client hardware lacks 256-bit AES support
• Regulatory requirements mandate AES-128 minimum
• Performance constraints require smaller key sizes

AES-256-CBC (Legacy)

Cipher Block Chaining mode with 256-bit key. Included for backward compatibility with older CMS implementations.

Considerations:

• Requires separate HMAC for integrity protection
• Vulnerable to padding oracle attacks if improperly implemented
• Slower than GCM on modern hardware

Only use if:

• Interoperating with legacy systems that don’t support GCM
• Regulatory compliance requires CBC mode specifically

Request/Response Flow

CMS-Wrapped Enrollment Request

1. Client generates CSR:

   openssl req -new -key device-key.pem -out device.csr
   

2. Client wraps CSR in CMS:

   # Sign the CSR with client's existing certificate
   openssl cms -sign \
     -in device.csr \
     -out device-cms-request.p7s \
     -signer client-cert.pem \
     -inkey client-key.pem \
     -outform DER \
     -binary \
     -nodetach
   

3. Submit CMS request to kipuka:

   curl -X POST \
     --data-binary @device-cms-request.p7s \
     -H "Content-Type: application/pkcs7-mime" \
     -o device-cms-response.p7c \
     https://est.example.com/.well-known/est/simpleenroll
   

4. Client unwraps CMS response:

   # Decrypt the response (if encrypted)
   openssl cms -decrypt \
     -in device-cms-response.p7c \
     -recip client-cert.pem \
     -inkey client-key.pem \
     -out device-cert.pem
   

CMS-Wrapped Reenrollment

For certificate renewal, the flow is similar but uses the current certificate:

# 1. Generate new CSR
openssl req -new -key new-key.pem -out renew.csr

# 2. Sign with current certificate
openssl cms -sign \
  -in renew.csr \
  -out renew-cms-request.p7s \
  -signer current-cert.pem \
  -inkey current-key.pem \
  -outform DER \
  -binary

# 3. Submit to reenroll endpoint
curl -X POST \
  --data-binary @renew-cms-request.p7s \
  -H "Content-Type: application/pkcs7-mime" \
  -o renew-cms-response.p7c \
  https://est.example.com/.well-known/est/simplereenroll

# 4. Decrypt response
openssl cms -decrypt \
  -in renew-cms-response.p7c \
  -recip current-cert.pem \
  -inkey current-key.pem \
  -out renewed-cert.pem

Security Considerations

Signature Verification

When require_signed_requests = true, kipuka performs these checks on incoming CMS requests:

1. Signature validity: Cryptographic signature must verify against signer’s certificate
2. Certificate chain: Signer’s certificate must chain to a trusted root
3. Certificate status: Signer’s certificate must not be revoked (OCSP/CRL check)
4. Timestamp validation: CMS signature timestamp must be within acceptable window

Recommendation: Always enable require_signed_requests in production. Unsigned requests bypass authentication and should only be allowed in isolated test environments.

Response Encryption

When encrypt_responses = true, kipuka encrypts the certificate response using the public key from the signer’s certificate. This ensures:

• Confidentiality: Certificate is only readable by the requesting device
• Binding: Response is cryptographically bound to the request
• Non-repudiation: Requester cannot claim they didn’t receive the certificate

Recommendation: Enable encryption unless all CMS-EST operations occur over physically secure channels.

Algorithm Selection

Order allowed_content_encryption from strongest to weakest:

allowed_content_encryption = [
    "AES-256-GCM",   # Try first
    "AES-128-GCM",   # Fallback for compatibility
]
# Omit AES-256-CBC unless required for legacy interop

kipuka selects the first algorithm supported by both client and server.

Transport Security

CMS-EST still requires HTTPS transport when used over a network. The CMS wrapping provides:

• Protection of request/response content during offline storage
• End-to-end security spanning disconnected segments
• Defense against transport-layer downgrade attacks

Do not transmit CMS-EST messages over unencrypted HTTP.

Example Workflows

Air-Gapped Device Enrollment

On disconnected device:

# Generate key and CSR
openssl genpkey -algorithm RSA -out device-key.pem -pkeyopt rsa_keygen_bits:2048
openssl req -new -key device-key.pem -out device.csr \
  -subj "/CN=device-12345/O=Example Corp"

# Create self-signed temp cert for CMS signing (if no existing cert)
openssl req -x509 -key device-key.pem -out temp-cert.pem -days 1 \
  -subj "/CN=device-12345/O=Example Corp"

# Sign CSR with temp cert
openssl cms -sign -in device.csr -out device-cms-request.p7s \
  -signer temp-cert.pem -inkey device-key.pem -outform DER -binary

# Transfer device-cms-request.p7s to USB drive

On network-connected workstation:

# Submit to kipuka
curl -X POST \
  --data-binary @/media/usb/device-cms-request.p7s \
  -H "Content-Type: application/pkcs7-mime" \
  -o /media/usb/device-cms-response.p7c \
  https://est.example.com/.well-known/est/simpleenroll

Back on disconnected device:

# Extract certificate from response
openssl cms -decrypt \
  -in device-cms-response.p7c \
  -recip temp-cert.pem \
  -inkey device-key.pem \
  -out device-cert.pem

# Verify certificate
openssl x509 -in device-cert.pem -text -noout

Batch Processing Script

#!/bin/bash
# batch-cms-enroll.sh - Process multiple CMS requests

REQUEST_DIR="/var/cms-est/requests"
RESPONSE_DIR="/var/cms-est/responses"
EST_URL="https://est.example.com/.well-known/est/simpleenroll"

for request in "$REQUEST_DIR"/*.p7s; do
    base=$(basename "$request" .p7s)
    echo "Processing $base..."
    
    curl -X POST \
      --data-binary @"$request" \
      -H "Content-Type: application/pkcs7-mime" \
      -o "$RESPONSE_DIR/${base}.p7c" \
      -w "HTTP %{http_code}\n" \
      "$EST_URL"
    
    if [ $? -eq 0 ]; then
        echo "  ✓ Response saved to $RESPONSE_DIR/${base}.p7c"
        mv "$request" "$REQUEST_DIR/processed/"
    else
        echo "  ✗ Failed to process $base"
    fi
done

Troubleshooting

“CMS signature verification failed”

Cause: Signer’s certificate doesn’t chain to a trusted root, or the signature is invalid.

Solution:

1. Verify the signer’s certificate chains to a CA trusted by kipuka
2. Check that the private key used for signing matches the certificate
3. Ensure the signer’s certificate is not expired or revoked
4. Inspect server logs for detailed verification errors

“Unsupported content encryption algorithm”

Cause: Client requested an encryption algorithm not in allowed_content_encryption.

Solution:

1. Add the algorithm to the server configuration:

   allowed_content_encryption = ["AES-256-GCM", "AES-128-GCM", "AES-256-CBC"]
   

2. Or update the client to request a supported algorithm
3. Check client and server logs for algorithm negotiation details

Response decryption fails

Cause: Response was encrypted for a different recipient certificate.

Solution:

1. Ensure the certificate used for decryption matches the one used to sign the request
2. Verify the decryption key corresponds to the certificate’s public key
3. Check for corruption during file transfer (verify file hash)

Large message sizes

Cause: CMS envelope overhead adds significant size to requests/responses.

Solution:

• Use binary DER encoding instead of PEM (saves ~33% space)
• Minimize certificate chain length by using direct trust anchors
• Compress CMS files during transport (CMS content is not compressible, but envelope metadata is)
• Consider plain EST for high-volume, connected deployments

Integration Examples

Python Client

#!/usr/bin/env python3
from cryptography import x509
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import rsa
from cryptography.hazmat.backends import default_backend
import requests

# Generate key
private_key = rsa.generate_private_key(
    public_exponent=65537,
    key_size=2048,
    backend=default_backend()
)

# Create CSR
csr = x509.CertificateSigningRequestBuilder().subject_name(
    x509.Name([
        x509.NameAttribute(x509.NameOID.COMMON_NAME, "device-67890"),
        x509.NameAttribute(x509.NameOID.ORGANIZATION_NAME, "Example Corp"),
    ])
).sign(private_key, hashes.SHA256(), default_backend())

# Wrap in CMS (requires python-cms library)
# ... CMS signing code ...

# Submit to kipuka
response = requests.post(
    "https://est.example.com/.well-known/est/simpleenroll",
    data=cms_request,
    headers={"Content-Type": "application/pkcs7-mime"}
)

# Unwrap CMS response
# ... CMS decryption code ...

Performance Considerations

CMS-EST operations are slower than plain EST due to:

• Signature verification: ~10-50ms per request depending on key size
• Encryption/decryption: ~5-20ms per response
• Certificate validation: ~50-200ms including OCSP/CRL checks

For high-throughput deployments:

1. Cache trusted certificates to reduce chain validation overhead
2. Use OCSP stapling to eliminate outbound OCSP requests
3. Consider hardware acceleration for AES-GCM operations
4. Batch multiple enrollment requests when possible

Typical throughput: 100-500 CMS-EST enrollments per second on modern server hardware.

STAR Certificates Configuration

Short-Term, Automatically Renewed (STAR) certificates are defined in RFC 8739. kipuka implements STAR to address the industry-wide shift toward short-lived certificates mandated by the CA/Browser Forum’s 47-day maximum validity requirement.

Overview

Why STAR?

Traditional certificate management with multi-year validity periods creates operational challenges:

• Revocation complexity: Long-lived certificates require reliable OCSP/CRL infrastructure
• Compromise risk: Stolen private keys remain valid until detected and revoked
• Manual renewal: Annual or multi-year renewals are error-prone and disruptive

The CA/Browser Forum now mandates maximum 47-day validity for publicly trusted certificates. STAR automates this at scale.

How STAR Works

Instead of manually renewing every 47 days, STAR:

1. Order creation: Client requests a STAR certificate with desired lifetime (e.g., 1 year)
2. Automatic issuance: kipuka issues the first 47-day certificate immediately
3. Automatic renewal: kipuka generates and publishes new certificates before expiration
4. Client polling: Client periodically fetches the latest certificate from the STAR endpoint
5. Lifecycle management: Order runs until max lifetime or cancellation

STAR vs Traditional EST

Configuration

Enable STAR in your kipuka.toml configuration:

[star]
enabled = true

# Renewal intervals (seconds)
min_renewal_interval_secs = 3600       # 1 hour (minimum allowed)
max_renewal_interval_secs = 604800     # 7 days (maximum allowed)
default_renewal_interval_secs = 86400  # 1 day (default when not specified)

# Lifecycle limits
max_lifetime_days = 365                # Maximum order lifetime
max_active_orders = 10000              # Resource exhaustion protection

# Renewal timing
pre_renewal_factor = 0.5               # Renew at 50% of certificate lifetime

Configuration Options

Renewal Timing

The pre_renewal_factor controls when kipuka generates the next certificate:

renewal_time = (certificate_validity * pre_renewal_factor)

Examples:

• pre_renewal_factor = 0.5 (default): Renew 47-day cert after 23.5 days
• pre_renewal_factor = 0.75: Renew 47-day cert after 35.25 days
• pre_renewal_factor = 0.25: Renew 47-day cert after 11.75 days

Recommendations:

• High-reliability: 0.25-0.33 — More frequent renewals, longer grace period
• Balanced (default): 0.5 — Reasonable renewal frequency and grace period
• Resource-constrained: 0.75-0.8 — Fewer renewals, minimal grace period

Lower values increase server load but provide more time to recover from renewal failures.

STAR Endpoints

Create Order

POST /.well-known/est/{label}/star-create
Content-Type: application/pkcs10

Request body: PKCS#10 CSR (DER-encoded)

Response:

{
  "order_id": "7f3b9c2a-1e4d-4c8b-9a2e-6d5c8b7a3f1e",
  "status": "pending",
  "lifetime_days": 365,
  "renewal_interval_secs": 86400,
  "certificate_validity_days": 47,
  "fetch_url": "https://est.example.com/.well-known/est/prod/star/7f3b9c2a-1e4d-4c8b-9a2e-6d5c8b7a3f1e"
}

Fetch Certificate

GET /.well-known/est/{label}/star/{order-id}

Response: Current certificate (PEM-encoded)

Clients should poll this endpoint based on renewal_interval_secs to fetch renewed certificates.

Cancel Order (Admin API)

DELETE /admin/api/v1/star/{order-id}
Authorization: Bearer <admin-token>

Immediately cancels the order and stops automatic renewals.

Order Lifecycle

          ┌────────┐
          │ Create │
          │ Order  │
          └───┬────┘
              │
              ▼
        ┌──────────┐
        │ pending  │◄──────────────┐
        └────┬─────┘               │
             │                     │
             │ Initial cert        │
             │ issued              │
             ▼                     │
        ┌──────────┐               │
        │  active  │               │
        └────┬─────┘               │
             │                     │
             │ Renewal timer       │
             │ fires               │
             ├─────────────────────┘
             │
             │ Lifetime expired
             │ or cancelled
             ▼
        ┌──────────┐
        │ expired  │
        │cancelled │
        └──────────┘

Status States

pending

Order created but initial certificate not yet issued. Typical duration: <1 second.

Transitions to:

• active — Initial certificate issued successfully
• expired — Order creation failed or timed out

active

Certificate issued and automatic renewals enabled. Server generates new certificates based on pre_renewal_factor.

Transitions to:

• expired — Lifetime exceeded max_lifetime_days
• cancelled — Admin or client cancellation request

expired

Order lifetime exceeded. No further renewals will be issued.

Final state: Order cannot return to active.

cancelled

Order cancelled by administrator or client. Immediate termination.

Final state: Order cannot return to active.

Client Implementation

Python Example

#!/usr/bin/env python3
import time
import requests
from cryptography import x509
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import rsa
from cryptography.hazmat.backends import default_backend

# Configuration
EST_SERVER = "https://est.example.com"
EST_LABEL = "prod"
RENEWAL_CHECK_INTERVAL = 86400  # 1 day

# Generate key pair
private_key = rsa.generate_private_key(
    public_exponent=65537,
    key_size=2048,
    backend=default_backend()
)

# Create CSR
csr = x509.CertificateSigningRequestBuilder().subject_name(
    x509.Name([
        x509.NameAttribute(x509.NameOID.COMMON_NAME, "www.example.com"),
    ])
).sign(private_key, hashes.SHA256(), default_backend())

# Submit STAR order
response = requests.post(
    f"{EST_SERVER}/.well-known/est/{EST_LABEL}/star-create",
    data=csr.public_bytes(serialization.Encoding.DER),
    headers={"Content-Type": "application/pkcs10"}
)

order = response.json()
order_id = order["order_id"]
fetch_url = order["fetch_url"]
print(f"STAR order created: {order_id}")

# Polling loop
while True:
    # Fetch current certificate
    cert_response = requests.get(fetch_url)
    
    if cert_response.status_code == 200:
        cert_pem = cert_response.text
        cert = x509.load_pem_x509_certificate(
            cert_pem.encode(), 
            default_backend()
        )
        
        print(f"Certificate valid until: {cert.not_valid_after}")
        
        # Install certificate
        with open("/etc/ssl/certs/server.crt", "w") as f:
            f.write(cert_pem)
        
        # Reload web server (example: nginx)
        import subprocess
        subprocess.run(["systemctl", "reload", "nginx"])
        
    elif cert_response.status_code == 404:
        print("Order expired or cancelled")
        break
    
    # Wait before next poll
    time.sleep(RENEWAL_CHECK_INTERVAL)

Systemd Timer

Run the polling script as a systemd service:

# /etc/systemd/system/star-cert-renew.service
[Unit]
Description=STAR Certificate Renewal
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/star-renew.py
Restart=always
RestartSec=3600

[Install]
WantedBy=multi-user.target

# /etc/systemd/system/star-cert-renew.timer
[Unit]
Description=STAR Certificate Renewal Timer

[Timer]
OnBootSec=5min
OnUnitActiveSec=1d

[Install]
WantedBy=timers.target

Enable:

systemctl enable --now star-cert-renew.timer

Resource Exhaustion Protection

The max_active_orders setting prevents resource exhaustion attacks:

max_active_orders = 10000

When this limit is reached:

1. New STAR order requests return HTTP 429 (Too Many Requests)
2. Existing orders continue renewing normally
3. Orders transition to expired or cancelled states free up capacity

Monitoring:

# Check active STAR order count
curl -H "Authorization: Bearer <admin-token>" \
  https://est.example.com/admin/api/v1/star/stats

# Response:
# {
#   "active_orders": 8567,
#   "max_orders": 10000,
#   "capacity_percent": 85.67
# }

Capacity Planning:

• Small deployment (<100 devices): max_active_orders = 1000
• Medium deployment (100-1000 devices): max_active_orders = 5000
• Large deployment (1000-10000 devices): max_active_orders = 25000
• Enterprise deployment (>10000 devices): max_active_orders = 100000

Each order consumes ~1KB of memory for metadata storage.

Security Considerations

Order ID Entropy

Order IDs are generated using cryptographically secure random UUIDs (128 bits of entropy). This prevents:

• Enumeration attacks: Guessing valid order IDs
• Prediction: Deriving order IDs from observable data
• Collisions: Duplicate order IDs across the system

Fetch URL Authorization

The fetch endpoint (/.well-known/est/{label}/star/{order-id}) requires:

1. Knowledge of order ID: Only clients with the UUID can fetch certificates
2. TLS transport security: Prevents interception of fetch requests
3. No additional authentication: Order ID serves as bearer token

Implications:

• Protect order IDs like API keys
• Don’t log order IDs in publicly accessible logs
• Use HTTPS for all fetch operations
• Rotate orders if order ID is compromised (cancel old, create new)

Cancellation Authorization

Only authenticated administrators can cancel STAR orders via the admin API. This prevents:

• Unauthorized service disruption
• Denial-of-service through order cancellation
• Client-initiated cancellation (clients must contact admin)

Monitoring and Observability

Metrics

kipuka exposes Prometheus metrics for STAR operations:

# Total active STAR orders
star_active_orders{label="prod"} 8567

# Orders by status
star_orders_by_status{label="prod",status="active"} 8560
star_orders_by_status{label="prod",status="pending"} 7
star_orders_by_status{label="prod",status="expired"} 0
star_orders_by_status{label="prod",status="cancelled"} 0

# Renewal operations
star_renewals_total{label="prod",result="success"} 156234
star_renewals_total{label="prod",result="failure"} 12

# Fetch operations
star_fetches_total{label="prod",http_code="200"} 298765
star_fetches_total{label="prod",http_code="404"} 45

Logging

STAR operations generate structured logs:

{
  "timestamp": "2026-06-25T14:32:01Z",
  "level": "INFO",
  "event": "star_order_created",
  "order_id": "7f3b9c2a-1e4d-4c8b-9a2e-6d5c8b7a3f1e",
  "lifetime_days": 365,
  "renewal_interval_secs": 86400,
  "subject": "CN=www.example.com"
}

{
  "timestamp": "2026-06-25T15:00:00Z",
  "level": "INFO",
  "event": "star_certificate_renewed",
  "order_id": "7f3b9c2a-1e4d-4c8b-9a2e-6d5c8b7a3f1e",
  "serial": "3a:b2:c4:d5:e6:f7:a8:b9",
  "not_before": "2026-06-25T15:00:00Z",
  "not_after": "2026-08-11T15:00:00Z"
}

Health Checks

Monitor STAR renewal health:

# Check for failed renewals in the last hour
curl -s https://est.example.com/admin/api/v1/star/health | jq '.failed_renewals_1h'

# Alert if > 0

Troubleshooting

Certificates not renewing

Symptoms:

• Client fetches return expired certificates
• star_renewals_total{result="failure"} metric increasing

Causes:

1. CA backend unavailable
2. CA policy rejecting renewals
3. HSM communication failure

Diagnosis:

# Check renewal logs
journalctl -u kipuka -g "star_certificate_renewal_failed" --since "1 hour ago"

# Check CA backend health
curl https://est.example.com/admin/api/v1/ca/health

Solution:

• Verify CA backend connectivity
• Check CA audit logs for rejection reasons
• Ensure HSM is accessible and responsive

High fetch failure rate

Symptoms:

• star_fetches_total{http_code="404"} increasing rapidly

Causes:

1. Clients polling cancelled or expired orders
2. Order IDs leaked or mistyped
3. Mass order expiration event

Diagnosis:

# List recently expired orders
curl -H "Authorization: Bearer <admin-token>" \
  https://est.example.com/admin/api/v1/star/orders?status=expired&limit=100

Solution:

• Notify clients to recreate orders
• Investigate mass expiration (check max_lifetime_days configuration)
• Audit for unauthorized cancellations

Resource exhaustion

Symptoms:

• HTTP 429 responses on order creation
• star_active_orders metric at max_active_orders limit

Causes:

1. Legitimate growth exceeding capacity
2. Order creation abuse
3. Orders not expiring (configuration issue)

Solution:

# Increase capacity
# Edit kipuka.toml:
# max_active_orders = 50000

# Restart kipuka
systemctl restart kipuka

# Or cancel stale orders
curl -X DELETE -H "Authorization: Bearer <admin-token>" \
  https://est.example.com/admin/api/v1/star/orders/cleanup?older_than_days=400

Integration with Existing PKI

Hybrid Deployment

Run STAR alongside traditional EST for gradual migration:

# EST for initial enrollment
[est]
enabled = true

# STAR for automated renewals
[star]
enabled = true
max_lifetime_days = 365

Workflow:

1. Clients perform initial enrollment via EST /simpleenroll
2. Clients create STAR order for automatic renewals
3. Clients cancel STAR order when device is decommissioned

Certificate Revocation

STAR orders don’t require revocation because:

1. Short validity: 47-day certificates have limited exposure window
2. Cancellation: Stop renewals by cancelling the order
3. Immediate effect: Next fetch returns HTTP 404

Comparison to OCSP/CRL:

When to use traditional revocation:

• Certificates issued outside STAR workflow
• Compliance requirements mandate OCSP/CRL
• Legacy clients don’t support STAR

Performance Tuning

Renewal Batch Processing

Group renewals to reduce database load:

# Increase renewal interval to reduce frequency
default_renewal_interval_secs = 259200  # 3 days

# Higher pre_renewal_factor = later renewals
pre_renewal_factor = 0.75

Client Polling Optimization

Instruct clients to use HTTP conditional requests:

# Fetch with If-Modified-Since
curl -H "If-Modified-Since: Wed, 25 Jun 2026 14:00:00 GMT" \
  https://est.example.com/.well-known/est/prod/star/{order-id}

# Server returns 304 Not Modified if cert unchanged

Database Indexing

Ensure database has indexes on:

• order_id (primary key)
• status (for querying active orders)
• next_renewal_time (for renewal scheduling)

Future Enhancements

Planned features in future kipuka releases:

• Multi-certificate orders: Single order for multiple domains (SAN certificates)
• Client-initiated cancellation: Allow clients to cancel their own orders
• Renewal notifications: Webhook or email alerts before renewal
• Order transfer: Migrate orders between EST labels
• Analytics dashboard: Web UI for STAR order visualization

OCSP Configuration

The Online Certificate Status Protocol (OCSP) is defined in RFC 6960. kipuka implements OCSP checking to verify the revocation status of client certificates during mutual TLS authentication for EST enrollment operations.

Overview

OCSP in EST Context

EST enrollment requires client authentication via mutual TLS (mTLS). kipuka validates client certificates by:

1. Chain verification: Certificate chains to a trusted root
2. Validity period: Certificate is not expired
3. Revocation status: Certificate has not been revoked (via OCSP or CRL)

OCSP checking happens during the TLS handshake before EST operations are processed. Revoked certificates are rejected at the transport layer.

OCSP vs CRL

kipuka prefers OCSP for real-time revocation checking but falls back to CRL when OCSP is unavailable.

Configuration

Enable OCSP in your kipuka.toml configuration:

[ocsp]
enabled = true

# OCSP responder URL (optional, overrides AIA extension)
responder_url = "http://ocsp.example.com"

# Caching and performance
cache_ttl_secs = 300       # Cache OCSP responses for 5 minutes
timeout_secs = 10          # OCSP request timeout

# Security settings
require_nonce = true       # Require OCSP nonce (RFC 6960 §4.4.1)
soft_fail = false          # Reject clients if OCSP check fails

Configuration Options

OCSP Responder URL

kipuka determines the OCSP responder URL using this priority:

1. Configuration override: responder_url if set
2. AIA extension: OCSP URL from certificate’s Authority Information Access extension
3. Fail: Reject certificate if neither is available (unless soft_fail = true)

When to use responder_url override:

• All certificates use the same OCSP responder
• AIA extension points to an internal URL not reachable from kipuka’s network
• Testing with a local OCSP responder

Example:

# Override for all certificates
responder_url = "http://ocsp.internal.example.com:8080"

When to omit responder_url:

• Certificates from multiple CAs with different OCSP responders
• AIA extensions are correctly configured and reachable
• Production environments (prefer AIA for proper PKI hygiene)

Soft-Fail vs Hard-Fail

The soft_fail setting determines behavior when OCSP checking encounters errors.

Hard-Fail Mode (Default)

soft_fail = false

Behavior:

• OCSP responder unreachable → Reject client certificate
• OCSP response timeout → Reject client certificate
• OCSP response invalid → Reject client certificate
• Certificate has no AIA extension → Reject client certificate

Use when:

• Security is paramount (zero-trust environments)
• OCSP infrastructure is highly available (99.9%+ uptime)
• Network connectivity to OCSP responders is reliable

Risks:

• Service outage if OCSP responder fails
• Denial of service if network connectivity is lost

Soft-Fail Mode

soft_fail = true

Behavior:

• OCSP responder unreachable → Allow client certificate, log warning
• OCSP response timeout → Allow client certificate, log warning
• OCSP response invalid → Allow client certificate, log warning
• Certificate explicitly revoked → Reject client certificate
• Certificate has no AIA extension → Allow client certificate, log warning

Use when:

• Availability is more important than absolute security
• OCSP infrastructure has known reliability issues
• Gradual OCSP deployment (monitoring before enforcement)

Risks:

• Revoked certificates may be accepted if OCSP is down
• Increased attack surface during OCSP outages

Recommendation: Start with soft_fail = true in development, transition to soft_fail = false in production after verifying OCSP infrastructure reliability.

Nonce Requirements

RFC 6960 §4.4.1 recommends using nonces to prevent OCSP response replay attacks.

Nonce Enabled (Default)

require_nonce = true

Behavior:

• kipuka includes a random nonce in OCSP requests
• OCSP responder must echo the nonce in the response
• Responses without matching nonce are rejected

Security benefit:

• Prevents attacker from replaying old “good” responses for revoked certificates
• Ensures response freshness

Compatibility:

• All modern OCSP responders support nonces
• Some legacy responders may not support nonces

Nonce Disabled

require_nonce = false

Use when:

• OCSP responder doesn’t support nonces
• Interoperating with legacy PKI infrastructure
• OCSP responses are pre-generated and cached (can’t include unique nonces)

Security implication:

• Attacker could replay old OCSP responses during the cache window
• Mitigation: Use shorter cache_ttl_secs (e.g., 60 seconds)

Cache Behavior

kipuka caches OCSP responses in memory to reduce load on OCSP responders and improve performance.

Cache Mechanics

1. Cache key: SHA-256 hash of certificate serial + issuer DN
2. Cache value: OCSP response (Good, Revoked, Unknown) + timestamp
3. TTL: cache_ttl_secs from time of OCSP response receipt
4. Eviction: LRU (Least Recently Used) when cache size limit reached

Cache Tuning

# High-throughput deployment (many unique clients)
cache_ttl_secs = 600      # 10 minutes
cache_size_entries = 100000

# Low-latency deployment (few clients, strict freshness)
cache_ttl_secs = 60       # 1 minute
cache_size_entries = 1000

Trade-offs:

Recommendation: Use 300-600 seconds for production environments. This balances OCSP responder load with reasonable revocation detection latency.

Cache Invalidation

kipuka automatically invalidates cache entries when:

• TTL expires
• Certificate status changes from Good to Revoked (received from OCSP)
• Cache size limit exceeded (LRU eviction)
• kipuka restart (cache is not persisted to disk)

Manual cache invalidation:

# Clear OCSP cache via admin API
curl -X POST -H "Authorization: Bearer <admin-token>" \
  https://est.example.com/admin/api/v1/ocsp/cache/clear

CRL Fallback

When OCSP is unavailable or disabled, kipuka automatically falls back to Certificate Revocation Lists (CRL).

Fallback Scenarios

OCSP → CRL fallback occurs when:

1. ocsp.enabled = false (CRL-only mode)
2. OCSP responder unreachable and soft_fail = true
3. OCSP response timeout and soft_fail = true
4. Certificate has no AIA extension for OCSP

CRL Configuration

[crl]
enabled = true
cache_ttl_secs = 3600       # Cache CRL for 1 hour
download_timeout_secs = 30  # CRL download timeout
max_crl_size_mb = 100       # Reject CRLs larger than 100 MB

CRL URLs are extracted from the certificate’s CRL Distribution Points (CDP) extension.

OCSP + CRL Combined

Best practice is to enable both:

[ocsp]
enabled = true
soft_fail = true   # Fallback to CRL on OCSP failure

[crl]
enabled = true

This provides:

• Fast path: OCSP for real-time revocation checking
• Fallback: CRL when OCSP is unavailable
• Redundancy: Multiple revocation mechanisms

Performance Tuning

Latency Analysis

OCSP checking adds latency to the TLS handshake:

High-Throughput Optimization

For deployments with >1000 concurrent connections:

[ocsp]
enabled = true
cache_ttl_secs = 600           # Longer cache = fewer OCSP requests
timeout_secs = 5               # Shorter timeout = faster failure
soft_fail = true               # Avoid blocking on OCSP outages

# Connection pooling to OCSP responder
http_max_idle_connections = 100
http_max_connections_per_host = 50

Network Optimization

Reduce OCSP latency by:

1. Deploying local OCSP responders: Place responders near kipuka instances
2. Using HTTP/2: Modern OCSP responders support HTTP/2 multiplexing
3. Enabling OCSP stapling: Clients provide OCSP responses during TLS handshake (future kipuka feature)

Security Considerations

OCSP Response Validation

kipuka performs these checks on OCSP responses:

1. Signature verification: Response signed by trusted OCSP responder
2. Nonce match: Response nonce matches request nonce (if require_nonce = true)
3. Timestamp freshness: Response producedAt within acceptable window
4. Responder authorization: Responder certificate authorized to sign OCSP responses

OCSP Responder Trust

OCSP responders must be trusted via:

• Delegated responder: Responder certificate issued by the same CA that issued the client certificate
• CA-signed responder: Responder certificate has the id-kp-OCSPSigning extended key usage

kipuka validates the responder certificate chain and EKU before accepting responses.

Replay Attack Prevention

Even with nonces, OCSP responses can be replayed within the cache window. Mitigate by:

• Using shorter cache_ttl_secs in high-security environments
• Enabling require_nonce = true
• Monitoring for unusual OCSP response patterns (same serial queried repeatedly)

Privacy Considerations

OCSP requests reveal which certificates are being checked to the OCSP responder. This has privacy implications:

• User tracking: OCSP responder can track certificate usage patterns
• Surveillance: Network observers see OCSP queries

Mitigations:

• Use OCSP responders operated by trusted entities
• Consider CRL for privacy-sensitive deployments (queries are anonymous)
• Future: OCSP stapling (clients cache and provide their own responses)

Monitoring and Observability

Metrics

kipuka exposes Prometheus metrics for OCSP operations:

# OCSP check results
ocsp_checks_total{result="good"} 156234
ocsp_checks_total{result="revoked"} 12
ocsp_checks_total{result="unknown"} 3
ocsp_checks_total{result="error"} 45

# Cache performance
ocsp_cache_hits_total 298765
ocsp_cache_misses_total 5432
ocsp_cache_size_entries 8765

# Response times
ocsp_request_duration_seconds{quantile="0.5"} 0.025
ocsp_request_duration_seconds{quantile="0.9"} 0.089
ocsp_request_duration_seconds{quantile="0.99"} 0.156

Logging

OCSP operations generate structured logs:

{
  "timestamp": "2026-06-25T14:32:01Z",
  "level": "INFO",
  "event": "ocsp_check_success",
  "serial": "3a:b2:c4:d5:e6:f7:a8:b9",
  "issuer": "CN=Example CA",
  "status": "good",
  "cache_hit": true,
  "duration_ms": 0.8
}

{
  "timestamp": "2026-06-25T14:35:12Z",
  "level": "WARN",
  "event": "ocsp_check_revoked",
  "serial": "1a:2b:3c:4d:5e:6f:7a:8b",
  "issuer": "CN=Example CA",
  "status": "revoked",
  "revocation_time": "2026-06-20T10:00:00Z",
  "revocation_reason": "keyCompromise"
}

{
  "timestamp": "2026-06-25T14:40:00Z",
  "level": "ERROR",
  "event": "ocsp_check_failed",
  "serial": "9a:8b:7c:6d:5e:4f:3a:2b",
  "issuer": "CN=Example CA",
  "error": "timeout",
  "responder_url": "http://ocsp.example.com",
  "soft_fail": true
}

Alerting Rules

Example Prometheus alerting rules:

groups:
  - name: ocsp
    interval: 30s
    rules:
      - alert: OCSPHighErrorRate
        expr: |
          rate(ocsp_checks_total{result="error"}[5m]) > 0.1
        for: 5m
        annotations:
          summary: "High OCSP error rate"
          description: "OCSP checks failing at {{ $value }} errors/sec"

      - alert: OCSPResponderDown
        expr: |
          ocsp_checks_total{result="error"} > 0
        for: 2m
        annotations:
          summary: "OCSP responder appears down"
          description: "OCSP errors detected, responder may be unreachable"

      - alert: RevokedCertificateDetected
        expr: |
          increase(ocsp_checks_total{result="revoked"}[1m]) > 0
        annotations:
          summary: "Revoked certificate detected"
          description: "A revoked certificate attempted authentication"

Troubleshooting

OCSP timeout errors

Symptoms:

• ocsp_checks_total{result="error"} increasing
• Logs show “timeout” error

Causes:

1. OCSP responder slow or overloaded
2. Network connectivity issues
3. Firewall blocking OCSP traffic

Diagnosis:

# Test OCSP responder manually
openssl ocsp \
  -issuer ca-cert.pem \
  -cert client-cert.pem \
  -url http://ocsp.example.com \
  -resp_text

# Check network connectivity
curl -I http://ocsp.example.com

Solution:

• Increase timeout_secs if responder is consistently slow
• Enable soft_fail = true temporarily to avoid service disruption
• Contact CA to report OCSP responder performance issues
• Deploy local OCSP responder replica

High OCSP load on responder

Symptoms:

• OCSP responder CPU/bandwidth saturation
• Slow OCSP responses

Causes:

• cache_ttl_secs too low
• Many unique client certificates (low cache hit rate)

Solution:

# Increase cache TTL to reduce OCSP queries
cache_ttl_secs = 600   # 10 minutes instead of 5

# Increase cache size to accommodate more certificates
cache_size_entries = 50000

Monitor ocsp_cache_hits_total / (ocsp_cache_hits_total + ocsp_cache_misses_total) — aim for >80% cache hit rate.

Revoked certificate accepted

Symptoms:

• Known revoked certificate successfully authenticates

Causes:

1. OCSP response cached before revocation
2. soft_fail = true and OCSP responder down
3. Clock skew between kipuka and OCSP responder

Diagnosis:

# Check cache status
curl -H "Authorization: Bearer <admin-token>" \
  https://est.example.com/admin/api/v1/ocsp/cache/lookup?serial=3a:b2:c4:d5:e6:f7:a8:b9

# Force cache clear
curl -X POST -H "Authorization: Bearer <admin-token>" \
  https://est.example.com/admin/api/v1/ocsp/cache/clear

Solution:

• Clear OCSP cache to force fresh check
• Reduce cache_ttl_secs for faster revocation propagation
• Verify system clocks are synchronized (NTP)
• Switch to soft_fail = false to enforce strict checking

No OCSP URL in certificate

Symptoms:

• Logs show “No AIA extension found” or “No OCSP URL”
• ocsp_checks_total{result="error"} increasing

Causes:

• Certificate lacks Authority Information Access extension
• AIA extension present but missing OCSP URL

Diagnosis:

# Check for AIA extension
openssl x509 -in client-cert.pem -text -noout | grep -A4 "Authority Information Access"

# Expected output:
# Authority Information Access:
#     OCSP - URI:http://ocsp.example.com

Solution:

• Configure CA to include AIA extension in issued certificates
• Set responder_url to provide fallback OCSP URL:

  responder_url = "http://ocsp.example.com"
  

• Enable CRL fallback:

  [crl]
  enabled = true
  

Integration Examples

Python OCSP Client

#!/usr/bin/env python3
from cryptography import x509
from cryptography.x509 import ocsp
from cryptography.hazmat.backends import default_backend
from cryptography.hazmat.primitives import hashes
import requests

# Load certificate to check
with open("client-cert.pem", "rb") as f:
    cert = x509.load_pem_x509_certificate(f.read(), default_backend())

# Load issuer certificate
with open("issuer-cert.pem", "rb") as f:
    issuer = x509.load_pem_x509_certificate(f.read(), default_backend())

# Build OCSP request
builder = ocsp.OCSPRequestBuilder()
builder = builder.add_certificate(cert, issuer, hashes.SHA256())
req = builder.build()

# Send to OCSP responder
response = requests.post(
    "http://ocsp.example.com",
    data=req.public_bytes(serialization.Encoding.DER),
    headers={"Content-Type": "application/ocsp-request"}
)

# Parse OCSP response
ocsp_resp = ocsp.load_der_ocsp_response(response.content)

# Check status
if ocsp_resp.response_status == ocsp.OCSPResponseStatus.SUCCESSFUL:
    status = ocsp_resp.certificate_status
    if status == ocsp.OCSPCertStatus.GOOD:
        print("Certificate is GOOD")
    elif status == ocsp.OCSPCertStatus.REVOKED:
        print(f"Certificate REVOKED at {ocsp_resp.revocation_time}")
    else:
        print("Certificate status UNKNOWN")
else:
    print(f"OCSP error: {ocsp_resp.response_status}")

OpenSSL OCSP Query

# Query OCSP responder for certificate status
openssl ocsp \
  -issuer ca-cert.pem \
  -cert client-cert.pem \
  -url http://ocsp.example.com \
  -header "Host" "ocsp.example.com" \
  -resp_text

# Output:
# OCSP Response Data:
#     OCSP Response Status: successful (0x0)
#     Response Type: Basic OCSP Response
#     ...
#     Cert Status: good
#     This Update: Jun 25 14:00:00 2026 GMT
#     Next Update: Jun 25 15:00:00 2026 GMT

Best Practices

1. Enable both OCSP and CRL:

   [ocsp]
   enabled = true
   soft_fail = true
   
   [crl]
   enabled = true
   

2. Use reasonable cache TTLs: 300-600 seconds balances performance and freshness

3. Monitor cache hit rate: Target >80% to minimize OCSP responder load

4. Start with soft-fail: Deploy with soft_fail = true, transition to hard-fail after stability verification

5. Require nonces: Keep require_nonce = true for security unless compatibility issues arise

6. Set appropriate timeouts: timeout_secs = 10 is reasonable for most networks

7. Monitor revocation events: Alert on ocsp_checks_total{result="revoked"} for security incidents

8. Test OCSP infrastructure: Periodically verify OCSP responder availability and performance

9. Plan for OCSP outages: Document incident response procedures for OCSP responder failures

10. Keep clocks synchronized: Use NTP to prevent timestamp-related OCSP validation failures

CoAP Transport

kipuka supports EST-over-CoAP (RFC 9483) for constrained IoT devices. This enables lightweight certificate enrollment over UDP with DTLS protection, reducing overhead compared to HTTP/TLS while maintaining security.

Overview

CoAP (Constrained Application Protocol, RFC 7252) is designed for resource-constrained devices with limited power, memory, and bandwidth. EST-over-CoAP adapts the EST protocol to CoAP’s request/response model, making it suitable for:

• IoT sensors and actuators
• Embedded devices with limited RAM (< 1 MB)
• Low-power wireless networks (LoRaWAN, NB-IoT, 802.15.4)
• Environments where TCP overhead is prohibitive

The kipuka-coap crate implements the full RFC 9483 specification with DTLS 1.2/1.3 support, block-wise transfer for large payloads (critical for post-quantum certificates), and session resumption.

Implementation Architecture

The CoAP transport is implemented across two layers:

• kipuka-coap crate – Contains the CoapDtlsServer that manages the UDP listener and DTLS sessions (via OpenSSL), parses CoAP messages, handles block-wise transfer reassembly, and dispatches EST operations through the EstHandler trait.
• CoapEstHandler (in the main kipuka-est crate) – Implements the EstHandler trait, bridging parsed CoAP requests to the same CA signing, CSR validation, and certificate issuance logic used by the HTTPS transport. This ensures both transports produce identical certificates and audit records.

When CoAP is enabled, CoapDtlsServer::run() is called at startup alongside the axum HTTP server. Both listeners share the same AppState, CA configurations, and database connections.

Currently supported EST operations over CoAP:

Configuration

Enable CoAP in kipuka.toml under the [coap] section:

[coap]
enabled = true
listen_addr = "0.0.0.0:5684"
dtls_enabled = true
block_size = 512
max_payload = 65536
session_timeout_secs = 300
max_sessions = 1024

Configuration Parameters

Security Note: Always enable dtls_enabled = true in production. Plain CoAP exposes CSRs and certificates in cleartext over the network.

DTLS Setup

kipuka supports DTLS 1.2 (RFC 6347) and DTLS 1.3 (RFC 9147) for encrypted CoAP transport. DTLS provides:

• Encryption and integrity protection equivalent to TLS
• UDP-friendly handshake with retransmission
• Session resumption to reduce handshake overhead
• Client authentication via PSK or certificates (mTLS)

DTLS Configuration

DTLS shares TLS certificates from the main [tls] section:

[tls]
cert_chain = "/path/to/server-chain.pem"
private_key = "/path/to/server-key.pem"
ca_bundle = "/path/to/trusted-cas.pem"

For PSK-based DTLS (pre-shared key authentication):

[coap]
dtls_psk_enabled = true
dtls_psk_identity = "IoTDevice001"
dtls_psk_key_hex = "deadbeef..."  # Hex-encoded shared secret

Session Resumption

DTLS session resumption cache reduces handshake latency for returning clients:

• Session ID-based resumption (DTLS 1.2)
• Ticket-based resumption (DTLS 1.3, RFC 8446)
• Cache expires after session_timeout_secs

EST Path Mapping

RFC 9483 section 5.1 defines CoAP path segments for EST operations. kipuka maps standard EST endpoints to shortened CoAP paths:

Example: To enroll a device, send a POST to coaps://est.example.com:5684/sen with the CSR in PKCS#10 format.

Content-Format IDs

CoAP uses numeric Content-Format IDs instead of MIME strings. RFC 9483 section 5.4 assigns:

Request and response payloads use these IDs in the CoAP Content-Format option.

Block-Wise Transfer

CoAP message size is limited by UDP MTU (typically 1280 bytes for IPv6). Block-wise transfer (RFC 7959) splits large payloads across multiple CoAP messages using Block1 (request) and Block2 (response) options.

Why Block Transfer Matters

Post-quantum certificates (ML-DSA-87 signatures) can exceed 7 KB. A typical PQC certificate chain:

• Root CA cert: ~3 KB (ML-DSA-87 signature)
• Intermediate CA cert: ~3.5 KB
• End-entity cert: ~4 KB
• Total: ~10.5 KB → requires ~21 blocks at 512-byte block size

Configuration

Set block_size to match your network’s MTU constraints:

• 16-64 bytes: Very constrained links (802.15.4)
• 128-256 bytes: Low-power WAN (NB-IoT, LoRa)
• 512 bytes (default): General IoT deployments
• 1024 bytes: High-bandwidth local networks

Trade-off: Larger blocks reduce round trips but increase packet loss impact.

Example Flow

Client requests /cacerts with Block2 option:

1. Client: GET /cacerts, Block2: 0/0/512 (request 512-byte blocks)
2. Server: 2.05 Content, Block2: 0/1/512 (block 0, more blocks follow)
3. Client: GET /cacerts, Block2: 1/0/512 (request next block)
4. Server: 2.05 Content, Block2: 1/1/512 (block 1, more blocks)
5. …
6. Server: 2.05 Content, Block2: 20/0/512 (final block)

Example with coap-client

Install libcoap tools:

# Fedora/RHEL
sudo dnf install libcoap

# Ubuntu/Debian
sudo apt install libcoap2-bin

Fetch CA certificates

coap-client -m get \
  coaps://est.example.com:5684/cacerts \
  -u Client001 -k deadbeef... \
  -B 512 \
  -o cacerts.p7

• -m get: GET method
• -u/-k: DTLS PSK identity and key (hex)
• -B 512: Request 512-byte blocks
• -o: Save response to file

Simple enrollment

# Generate CSR
openssl req -new -newkey rsa:2048 -nodes \
  -keyout device.key -out device.csr

# Convert CSR to DER
openssl req -in device.csr -outform DER -out device.csr.der

# Send enrollment request
coap-client -m post \
  coaps://est.example.com:5684/sen \
  -u Client001 -k deadbeef... \
  -f device.csr.der \
  -t application/pkcs10 \
  -B 512 \
  -o device-cert.p7

• -f: Request payload file
• -t: Content-Type (use MIME string; libcoap translates to ID 285)

Troubleshooting

DTLS handshake fails

Symptom: Client timeout or “DTLS handshake failed” error.

Causes:

• Firewall blocking UDP port 5684
• Mismatched PSK identity or key
• Client doesn’t support DTLS 1.2/1.3
• Certificate verification failure (mTLS mode)

Debug:

# Enable verbose logging
coap-client -v 9 ...

# Check kipuka logs
journalctl -u kipuka -f | grep -i dtls

Block transfer incomplete

Symptom: Partial payload received, transfer hangs.

Causes:

• Network packet loss exceeds retransmission limits
• block_size too large for MTU
• max_payload too small for certificate chain

Fix:

• Reduce block_size to 256 or 128
• Increase max_payload to 131072 (128 KB)
• Check network MTU: ip link show | grep mtu

Session timeout errors

Symptom: “Session expired” after idle period.

Cause: Client inactive for > session_timeout_secs.

Fix:

• Increase session_timeout_secs to 600 (10 minutes)
• Implement session resumption in client
• Send periodic keepalive messages

Max sessions exceeded

Symptom: New clients refused with “Too many sessions”.

Cause: max_sessions limit reached (zombie sessions).

Fix:

• Increase max_sessions to 2048
• Reduce session_timeout_secs to 120 (2 minutes)
• Restart kipuka to clear session cache

Performance Considerations

Memory Usage

Each DTLS session consumes ~10-20 KB RAM:

• DTLS 1.2 state: ~8 KB
• DTLS 1.3 state: ~12 KB
• Session resumption cache: ~2 KB per session

1024 sessions → ~12-24 MB RAM overhead.

Throughput

CoAP throughput is limited by:

• UDP round-trip time (RTT)
• Block-wise transfer overhead
• DTLS cryptographic processing

Example: 10 KB certificate chain, 512-byte blocks, 50ms RTT:

• 20 blocks × 1 round trip each = 20 RTT
• Total time: 20 × 50ms = 1 second

Larger block sizes reduce latency but require higher MTU.

Security Recommendations

1. Always enable DTLS (dtls_enabled = true)
2. Use strong PSK keys (≥ 128 bits entropy)
3. Rotate PSK keys regularly (monthly for IoT)
4. Limit session lifetime (session_timeout_secs ≤ 600)
5. Monitor session count (alert on max_sessions threshold)
6. Validate client certificates (mTLS mode) or OTP (EST enrollment)
7. Use firewall rules to restrict CoAP port 5684 to authorized subnets
8. Enable audit logging for all enrollment requests

Deployment Notes

UDP Port and Firewall

The IANA-assigned port for CoAP over DTLS is 5684. Ensure your firewall allows inbound UDP on this port:

# firewalld (Fedora/RHEL)
sudo firewall-cmd --permanent --add-port=5684/udp
sudo firewall-cmd --reload

# iptables
sudo iptables -A INPUT -p udp --dport 5684 -j ACCEPT

Container Deployment

When running kipuka in a container, expose both the HTTPS and CoAP/DTLS ports:

podman run --rm \
  -v ./kipuka.toml:/etc/kipuka/kipuka.toml:ro \
  -v ./certs:/etc/kipuka/certs:ro \
  -p 9443:9443 \
  -p 5684:5684/udp \
  quay.io/kipuka/kipuka:latest

Note the /udp suffix on port 5684 – without it, only TCP is exposed.

DTLS Certificate and Key

The CoAP/DTLS listener shares the TLS certificate and private key from the [tls] section. No separate certificate configuration is needed:

[tls]
cert_chain = "/etc/kipuka/certs/server-chain.pem"
private_key = "/etc/kipuka/certs/server-key.pem"
ca_bundle = "/etc/kipuka/certs/trusted-cas.pem"

[coap]
enabled = true
listen_addr = "0.0.0.0:5684"
dtls_enabled = true

Full Configuration Example

A minimal configuration enabling both HTTPS and CoAP transports:

[server]
listen_addr = "0.0.0.0:9443"

[tls]
cert_chain = "/etc/kipuka/certs/server-chain.pem"
private_key = "/etc/kipuka/certs/server-key.pem"
ca_bundle = "/etc/kipuka/certs/trusted-cas.pem"

[[ca]]
id = "iot-ca"
cert = "/etc/kipuka/certs/iot-ca.pem"
key = "/etc/kipuka/certs/iot-ca-key.pem"
chain = "/etc/kipuka/certs/iot-ca-chain.pem"
validity_days = 365

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

[coap]
enabled = true
listen_addr = "0.0.0.0:5684"
dtls_enabled = true
block_size = 512
max_payload = 65536
session_timeout_secs = 300
max_sessions = 1024

References

• RFC 9483: Constrained Application Protocol (CoAP) over DTLS for EST
• RFC 7252: The Constrained Application Protocol (CoAP)
• RFC 7959: Block-Wise Transfers in CoAP
• RFC 6347: Datagram Transport Layer Security (DTLS) 1.2
• RFC 9147: The Datagram Transport Layer Security (DTLS) 1.3
• RFC 7030: Enrollment over Secure Transport (EST)

RFC Support Reference

This page documents every standards specification that kipuka implements, which sections are covered, and any caveats relevant to conformance testing.

Core Enrollment Standards

RFC 7030 – Enrollment over Secure Transport (EST)

RFC 8951 – Clarifications for EST

RFC 8951 addresses ambiguities in RFC 7030. kipuka incorporates all clarifications that affect server behavior:

RFC 5272 – Certificate Management over CMS (Full CMC)

The /fullcmc endpoint accepts a Full PKI Request (a ContentInfo containing a PKIData structure) and returns a Full PKI Response.

RFC 8739 – Short-Term, Automatically Renewed Certificates (STAR)

kipuka implements the server-side portion of STAR for short-lived certificate management. The kipuka::star module tracks renewal orders and issues replacement certificates before expiry.

Transport

RFC 7252 – Constrained Application Protocol (CoAP)

The kipuka-coap crate implements EST-over-CoAP for resource-constrained devices (IoT sensors, embedded controllers) that cannot maintain persistent TCP connections.

RFC 4210 / RFC 9810 – Certificate Management Protocol (CMP)

The CMP endpoint at /.well-known/cmp provides a comprehensive certificate lifecycle protocol with its own ASN.1 message format, independent of the EST transport.

RFC 8295 – EST with CMS-Level Security (CMS-EST)

CMS-EST wraps EST messages in CMS SignedData and EnvelopedData structures, providing message-level security independent of the TLS transport.

RFC 9483 – EST over CoAP (EST-coaps)

Extends the RFC 7252 CoAP transport entry above with EST-specific path mapping and content-format negotiation.

RFC 7959 – Block-Wise Transfers in CoAP

Composite Post-Quantum Signatures

Certificate Policy

CA/Browser Forum Baseline Requirements

kipuka enforces the CA/B Forum Baseline Requirements for TLS server certificates when configured to issue publicly-trusted certificates. See CA/B Forum Baseline Requirements for the full mapping.

NIAP Common Criteria – CA Protection Profile v2.0

kipuka is designed to satisfy the Security Functional Requirements (SFRs) of the NIAP CA Protection Profile. See NIAP CA Protection Profile for the full SFR-by-SFR mapping.

Cryptographic Standards

FIPS 140-3 – Cryptographic Module Validation

kipuka does not itself hold a FIPS 140-3 certificate. FIPS compliance is achieved by delegating all cryptographic operations to a validated PKCS#11 HSM module.

When kipuka operates with a software-only key (no HSM), it uses the Synta crate’s software implementations. These are suitable for testing and non-FIPS environments but do not carry a FIPS validation.

FIPS 204 – ML-DSA (Post-Quantum Digital Signatures)

kipuka supports ML-DSA (formerly CRYSTALS-Dilithium) signing via two paths:

ML-DSA support is experimental. CA certificates and end-entity certificates can use ML-DSA key pairs, but client and browser ecosystem support is limited as of 2026.

FIPS 203 – ML-KEM (Post-Quantum Key Encapsulation)

ML-KEM (formerly CRYSTALS-Kyber) is supported for key encapsulation in hybrid key exchange scenarios. The kipuka_hsm::key module defines MlKemLevel variants L1, L3, and L5 corresponding to ML-KEM-512, ML-KEM-768, and ML-KEM-1024 respectively.

ML-KEM is primarily relevant for /serverkeygen responses where the server encrypts the generated private key for transport to the client.

Summary Matrix

RFC 9908 – CSR Attributes Template

The /csrattrs endpoint supports the RFC 9908 CertificationRequestInfoTemplate attribute alongside the traditional OID-list mode (backward compatible).

Configuration

[est.csr_template]
key_algorithm = "ec:P-256"
required_extensions = ["2.5.29.17"]

[[est.csr_template.subject]]
oid = "2.5.4.10"
value = "Example Corp"

[[est.csr_template.subject]]
oid = "2.5.4.3"
# No value — client must supply commonName

draft-ietf-lamps-est-renewal-info – EST Renewal Information

The GET /.well-known/est/renewal-info/{cert_id} endpoint returns a JSON object with a suggested renewal window for the identified certificate.

Conformance Test Suite

kipuka ships a wire-format conformance test suite in contrib/conformance/ that validates protocol compliance beyond HTTP status codes. Each suite uses openssl asn1parse, openssl pkcs7, openssl x509, and xxd for DER-level assertion.

./contrib/conformance/run-all.sh           # against running server
./contrib/conformance/run-all.sh --deploy  # full lifecycle

NIAP CA Protection Profile

This page maps kipuka capabilities to the Security Functional Requirements (SFRs) defined in the NIAP Certificate Authority Protection Profile v2.0. The mapping is intended for evaluation teams preparing a Common Criteria assessment and for operators who need to verify that their deployment satisfies the Protection Profile.

Note: A Common Criteria evaluation requires an accredited evaluation facility. This document describes how kipuka addresses each SFR at the implementation level; it does not constitute a certified Security Target.

Audit (FAU)

FAU_GEN.1 – Audit Data Generation

Requirement: The TOE shall generate an audit record for each auditable event, including the date/time, event type, subject identity, and outcome.

How kipuka satisfies it:

The kipuka::audit module records structured audit events through the AuditEvent struct. Every event includes:

• Timestamp (UTC, microsecond precision)
• Event type (AuditEventType enum)
• Subject identity (client certificate DN, OTP identifier, or GSSAPI principal)
• Outcome (success or failure with reason)
• Source IP address and EST label

The following event types are audited:

Implementation location: kipuka::audit::record() is called from every EST handler and authentication layer.

Evaluation notes: The event set covers all “minimum audit events” listed in Table 5 of the Protection Profile. Additional events (OTP lifecycle, HA health changes) exceed the minimum.

FAU_GEN.2 – User Identity Association

Requirement: The TOE shall associate each auditable event with the identity of the user that caused the event.

How kipuka satisfies it:

The AuditEvent struct contains a subject field populated from the authenticated identity:

• mTLS: Subject DN and serial number of the client certificate.
• OTP: The OTP identifier (opaque token ID, not the secret).
• GSSAPI: The Kerberos principal name.
• CMS: The signer DN from the CMS SignerInfo.
• Unauthenticated (/cacerts): Recorded as "anonymous" with the source IP.

FAU_STG.1 – Protected Audit Trail Storage

Requirement: The TOE shall protect the stored audit records from unauthorized deletion.

How kipuka satisfies it:

Audit records are written through two channels, both designed for append-only semantics:

1. Database – Audit records are INSERT-only. The database schema does not expose UPDATE or DELETE operations on the audit table. When using PostgreSQL, row-level security policies can further restrict modification.

2. File – When audit.file is configured, events are appended to a JSON Lines file. kipuka opens the file in append-only mode (O_APPEND). File-system permissions should restrict the audit file to the kipuka service account.

3. Syslog – When audit.syslog is configured, events are forwarded to a remote syslog server over TLS, placing the audit trail outside the TOE boundary.

Evaluation notes: The Protection Profile requires that “the TSF shall be able to prevent unauthorized deletion of the stored audit records.” Operators must ensure that file-system permissions and database RBAC are configured to prevent the kipuka process from deleting its own audit records. Shipping audit events to a remote syslog server (channel 3) provides the strongest protection.

Cryptographic Support (FCS)

FCS_CKM.1 – Cryptographic Key Generation

Requirement: The TOE shall generate asymmetric cryptographic keys in accordance with a specified key generation algorithm and key sizes.

How kipuka satisfies it:

Serial numbers are 160 bits (20 bytes) from a CSPRNG, exceeding the CA/B Forum minimum of 64 bits and the NIAP requirement for unpredictable serial numbers.

Implementation location: kipuka_hsm::key::HsmKeyPair for CA keys; kipuka_est::serverkeygen for end-entity keys generated via /serverkeygen.

FCS_CKM.2 – Cryptographic Key Distribution

Requirement: The TOE shall distribute cryptographic keys in accordance with a specified key distribution method.

How kipuka satisfies it:

• CA certificate distribution – The /cacerts endpoint returns the CA certificate chain as a PKCS#7 certs-only message. Distribution is over TLS (FCS_TLSS_EXT.1).

• Server-generated key distribution – When /serverkeygen is enabled, the generated private key is encrypted to the client using PKCS#7 EnvelopedData:

  • AES-256 key wrapping with the content-encryption key wrapped to the client’s public key via RSA-OAEP or ECDH-ES.
  • The wrapped key and signed certificate are returned as a single multipart MIME response.

Implementation location: kipuka_est::serverkeygen for key wrapping; kipuka_est::cacerts for CA chain distribution.

FCS_COP.1 – Cryptographic Operation

Requirement: The TOE shall perform cryptographic operations in accordance with specified algorithms and key sizes.

How kipuka satisfies it:

Implementation location: kipuka_hsm::sign dispatches to sign_rsa_pkcs1, sign_rsa_pss, sign_ecdsa, or sign_ml_dsa depending on the CA key type.

FCS_RBG_EXT.1 – Random Bit Generation

Requirement: The TOE shall use a DRBG that is seeded by an entropy source.

How kipuka satisfies it:

• With HSM: Random bytes are obtained via PKCS#11 C_GenerateRandom, which invokes the HSM’s FIPS-validated DRBG.
• Without HSM: Random bytes are obtained from the operating system’s CSPRNG via getrandom(2) on Linux or the equivalent on other platforms.

Serial number generation always uses whichever RBG is active.

FCS_TLSS_EXT.1 – TLS Server

Requirement: The TOE shall implement TLS 1.2 and/or TLS 1.3 as a server.

How kipuka satisfies it:

kipuka uses rustls for TLS termination.

Implementation location: kipuka::tls module configures rustls::ServerConfig.

Identification and Authentication (FIA)

FIA_AFL.1 – Authentication Failure Handling

Requirement: The TOE shall detect when a configurable number of unsuccessful authentication attempts occur and take action.

How kipuka satisfies it:

The OTP authentication subsystem implements rate limiting and lockout:

When the threshold is reached:

1. An AuthFailure audit event is recorded with reason "lockout".
2. Subsequent authentication attempts for that OTP identifier return HTTP 403 until the lockout expires.
3. If the lockout is triggered by mTLS (invalid client cert), the TLS handshake fails before the HTTP layer is reached; the audit event records the client IP and certificate serial number.

Implementation location: kipuka::auth::otp for OTP lockout; kipuka::auth::mtls for mTLS failure logging.

FIA_UAU.1 – Timing of Authentication

Requirement: The TOE shall allow only the retrieval of CA certificates before the user is authenticated.

How kipuka satisfies it:

• /cacerts – Unauthenticated. No client credential is required.
• All other endpoints (/simpleenroll, /simplereenroll, /fullcmc, /serverkeygen, /csrattrs) – Require authentication via at least one configured method (mTLS, OTP, GSSAPI, or CMS signature).

The EstAuth extractor in kipuka::auth enforces this policy. The OptionalAuth extractor is used only for /cacerts and returns AuthMethod::None when no credential is presented.

Implementation location: kipuka::auth::EstAuth and kipuka::auth::OptionalAuth.

FIA_UAU.5 – Multiple Authentication Mechanisms

Requirement: The TOE shall provide multiple authentication mechanisms.

How kipuka satisfies it:

kipuka supports five authentication methods, selectable per EST label:

Security Management (FMT)

FMT_SMR.1 – Security Roles

Requirement: The TOE shall maintain the roles of operator and user.

How kipuka satisfies it:

kipuka defines two distinct roles:

The admin API listens on a separate address and port (server.admin_listen, default 127.0.0.1:9443) with independent TLS configuration. No EST client credential grants access to the admin API, and no admin credential grants access to EST endpoints on behalf of a client.

Implementation location: kipuka::routes::admin for operator endpoints; kipuka::routes::est for user endpoints.

FMT_SMF.1 – Management Functions

Requirement: The TOE shall provide management functions for authorized operators.

How kipuka satisfies it:

The admin API provides:

Trusted Path (FTP)

FTP_TRP.1 – Trusted Path

Requirement: The TOE shall provide a communication path between itself and remote users that is logically distinct from other paths and provides assured identification of its endpoints.

How kipuka satisfies it:

• EST over TLS – All enrollment communication uses TLS with server certificate authentication and (for authenticated endpoints) mutual TLS. The server certificate identifies the kipuka instance; the client certificate identifies the enrolling device.

• Admin on separate TLS – The admin API uses an independent TLS listener with its own certificate and trust anchors. This provides logical separation between the user-facing EST path and the operator-facing management path.

• DTLS for CoAP – CoAP enrollment uses DTLS 1.2 for the trusted path, providing the same endpoint authentication guarantees over UDP.

Implementation location: kipuka::tls for EST and admin TLS; kipuka_coap::dtls for DTLS.

SFR Coverage Summary

CA/B Forum Baseline Requirements

This page documents compliance with the CA/Browser Forum Baseline Requirements for the Issuance and Management of Publicly-Trusted TLS Server Certificates, Version 2.2.8 (16-Jun-2026). Operators issuing certificates under a publicly-trusted root must configure kipuka and the issuing CA to satisfy these requirements jointly; operators running private PKI may relax constraints through configuration.

Responsibility Boundary

kipuka is a Registration Authority (RA) and enrollment server. It validates CSRs and enforces certificate profile constraints, but it does not perform domain validation, CAA checking, or revocation services. Those responsibilities belong to the issuing Certification Authority.

The following table maps each BR area to the specific software component that owns it. When deploying under a publicly-trusted root, all affected components must be configured correctly.

kipuka (RA) Responsibilities