Certificates and PKI#

Audience: Operations Administrators, Security Professionals
Prerequisites: Understanding of PKI and certificate management
Outcome: Understand Kleidia’s PKI architecture and certificate lifecycle

Overview#

Kleidia uses OpenBao as a Certificate Authority (CA) or intermediate for signing YubiKey PIV certificates. The PKI system provides enterprise-grade certificate management with automatic signing and lifecycle management.

PKI Architecture#

Certificate Authority#

Root CA: Self-signed root certificate (10-year lifetime)
PKI Engine: Vault PKI secrets engine at pki/ mount
Certificate Signing: Automatic CSR signing via PKI role
Certificate Revocation: CRL support for certificate revocation

PKI Role Configuration#

The system uses a PKI role named kleidia with the following settings:

Setting	Value	Purpose
`allow_any_name`	`true`	Allows certificates with any common name
`enforce_hostnames`	`false`	Disables hostname validation
`allow_subdomains`	`true`	Permits subdomain certificates
`allow_localhost`	`true`	Allows localhost certificates
`allow_ip_sans`	`true`	Permits IP address SANs
`require_cn`	`true`	Requires Common Name in certificates
`key_type`	`rsa`	RSA key type (YubiKey standard)
`key_bits`	`2048`	2048-bit RSA keys
`max_ttl`	`8760h`	Maximum certificate lifetime (1 year)
`ttl`	`8760h`	Default certificate lifetime (1 year)

Certificate Lifecycle#

1. CSR Generation#

Location: User workstation (agent)
Process:

User requests certificate generation via web interface
Frontend calls agent: POST http://127.0.0.1:56123/piv/generate-csr
Agent generates CSR using YubiKey’s private key (slot 9a)
CSR includes:
- Common Name (CN)
- Subject Alternative Names (SANs)
- Key algorithm (RSA 2048-bit)
- Key usage extensions

Security: Private key never leaves YubiKey hardware

2. Certificate Signing#

Location: Backend server
Process:

Frontend sends CSR to backend: POST /api/yubikey/{serial}/sign-csr
Backend authenticates to Vault using AppRole
Backend submits CSR to Vault PKI: POST /v1/pki/sign/kleidia
Vault signs CSR using root CA
Backend receives signed certificate

Certificate Properties:

Issuer: Kleidia Root CA
Validity: 1 year (8760h, configurable via PKI role)
Key Usage: Digital signature, key encipherment
Extended Key Usage: Client authentication, email protection

3. Certificate Import#

Location: User workstation (agent)
Process:

Backend returns signed certificate to frontend
Frontend sends certificate to agent: POST http://127.0.0.1:56123/piv/import-certificate
Agent imports certificate to YubiKey PIV slot (9a, 9c, 9d, or 9e)
Certificate stored on YubiKey hardware

Security: Certificate stored securely on YubiKey hardware

4. Certificate Usage#

Certificates can be used for:

Client Authentication: TLS client certificates
Email Signing: S/MIME email signing
Code Signing: Application code signing
Document Signing: PDF and document signing

5. Certificate Revocation#

Process:

Admin revokes certificate via web interface
Backend calls Vault PKI: POST /v1/pki/revoke
Certificate serial number added to CRL
Certificate marked as revoked in database

CRL Distribution: CRL available at /v1/pki/crl

PKI Configuration#

Automatic Setup#

PKI is automatically configured during Helm deployment:

Enable PKI Engine: vault secrets enable -path=pki pki
Configure TTL: vault secrets tune -max-lease-ttl=8760h pki
Generate Root CA: Create self-signed root certificate
Configure URLs: Set issuing certificate and CRL URLs
Create PKI Role: Create kleidia role with appropriate settings

Certificate Operations#

Generate Certificate#

User Flow:

User logs into web interface
Navigates to YubiKey device
Selects “Generate Certificate”
Certificate details automatically configured (CN, SANs, etc.)
System generates CSR on YubiKey
System signs CSR via Vault PKI
System imports certificate to YubiKey
Certificate ready for use

View Certificates#