Chapter 9: Short-Lived PKI Certificates

Chapter contract

Persona: Application/workload user · orders-apiPhase: Applications and pipelinesEstimated time: 50 minutes

Prerequisites:

Chapter 7 complete, the PKI role created by bootstrap, and OpenSSL installed.

User-visible outcome:

orders-api can install and rotate a SAN-constrained certificate while keeping its private key opaque.

Objectives
Flow
Concepts
Lab
Failure drill
Break it / fix it
Quick check

Learning objectives

Request a certificate constrained by a Vault PKI role.
Verify SAN, issuer, and expiry without showing private key material.
Design atomic certificate-and-key reload.

Consumer flow

Ownership boundary

Owner	Consumer-facing responsibility
You own	Defines consumption, validation, reload, and stop-using behavior.
Platform team owns	Provides trusted runtime identity, protected delivery, network, and telemetry.
Vault owns	Operates auth mounts, policies, engines, audit, and recovery.

Core concepts

Issuer

The CA identity signing a certificate.

Role constraints

Allowed names, key types, usages, and maximum TTL.

SAN

The identity names a verifier actually checks.

Atomic replacement

A complete swap that never exposes mismatched partial files.

Commands and configuration

source learn-vault/.runtime/learner.env
cd learn-vault/labs/pki
./issue.sh orders-api.lockbox.internal
./inspect.sh
./rotate.sh orders-api.lockbox.internal

Secret-safety stop

Stop: Private keys are generated secrets. Never print, commit, attach, back up, or inspect their first lines.

Failure drill

Symptom	TLS fails after certificate rotation.
Likely causes	Cert and key swapped separately, SAN mismatch, untrusted issuer, expired chain, or reload failure.
Inspect safely	Compare fingerprint, SAN, issuer, validity, modes, and reload timestamp.
Do not print	Private key bytes, issuance response, or client credentials.

Break it / fix it

Break it: Request a name outside the allowed lockbox.internal domain.

Show diagnosis and fix

Fix it: Use the role-approved SAN and validate issuer, SAN, expiry, and key correspondence.

Escalate with time, endpoint, auth path, role, mount, namespace when relevant, status code, request ID, and sanitized error class. Never attach a credential or response body.

Try it

Bootstrap boundary

labs/bootstrap owns the disposable server, auth mounts, policies, roles, and engines; learner actions begin after setup.

Cost:

$0; local containers only

Starting state:

Run labs/bootstrap/setup.sh and source .runtime/learner.env unless the chapter lab says AppRole alone is sufficient.

User actions:

Issue to ignored storage, inspect public metadata, compare derived public-key digests, then rotate.

cd learn-vault/labs/pki
./issue.sh orders-api.lockbox.internal
./inspect.sh
./verify-pair.sh
old_serial=$(./serial.sh)
./rotate.sh orders-api.lockbox.internal
test "$old_serial" != "$(./serial.sh)"
./cleanup.sh

Success criteria:

Complete every item in the Verify section using metadata-only evidence; no secret value appears in terminal output or tracked files.

Troubleshooting:

Use the Failure drill and Break it / fix it evidence fields. Stop before broadening policy, weakening identity or TLS checks, or copying secret-bearing diagnostics.

Verify

SAN contains orders-api.lockbox.internal and expiry is finite.
Derived public keys match without exposing the private key.
Rotation changes serial and installs a complete bundle.

Evidence rule: retain only status, policy names, TTLs, versions, timestamps, fingerprints, and error classes. Never retain secret values.

Cleanup

Remove the runtime certificate directory. Use serial-based revocation when real incident policy requires it.

Project Lockbox increment

orders-api has a service identity with an explicit SAN, trust chain, and rotation deadline.

Quick check

Why is common name insufficient?

Modern TLS verification uses subject alternative names.

How verify a key pair safely?

Compare digests of derived public keys.

What makes a swap atomic?

Prepare complete files and rename within one filesystem.

Does short TTL eliminate revocation?

No. High-risk compromise can still require it.

Gotchas

Certificate renewal normally issues replacement bytes.
Leaf, chain, and key must remain consistent.
Clock skew consumes part of a short lifetime.

Recap and next

Short-lived PKI works when constraints, trust, atomic reload, and expiry telemetry are designed together.

Primary references

Continue →