Secsy PKI — enterprise documentation¶
Deployment and operations guides for the enterprise edition of secsy-pki: an HSM-backed X.509 and SSH certificate authority with envelope-based secret encryption, role-based access control, and a tamper-evident audit log.
The project README covers what secsy-pki is, how to build it,
and the secsy-ssh workflow. Everything below is the enterprise reference,
grouped into 12 sections. Each section folder has its own index with fuller
descriptions; this page is the map.
These pages are also published — with search and navigation — at https://blechschmidt.github.io/secsy-pki/, built from this tree by the documentation-site workflow.
Start here¶
| If you want to… | Go to |
|---|---|
| Copy a working setup | examples/ — whole use cases as a config plus the client-side glue: SSH PKI, keyless signing from GitHub Actions, ACME TLS automation, a private mTLS CA |
| Deploy for the first time | HSM configuration → Certificate authority → RBAC & audit |
| Add secret encryption | Password / secret encryption |
| Move to production | Production HSM migration → Key ceremony & DR → Observability |
| Run it on Kubernetes | Kubernetes deployment → Multi-replica coordination |
| Operate a live deployment | Operator runbook — keep it bookmarked |
| Respond to a key compromise | Incident response: mass revocation |
| Prepare for a WebTrust / CA-Browser-Forum audit | Certificate Policy / CPS and the compliance control mapping |
| Understand why it is built this way | Architecture overview and the decision records |
Documentation map¶
1. HSM & key management — hsm/¶
Where private keys live, and the proof they never leave.
| Page | Covers |
|---|---|
| HSM / PKCS#11 configuration | Key-provider abstraction, PKCS#11/HSM and SoftHSM setup, PIN sourcing |
| HSM high availability (multi-token failover) | Health-tracked failover across several PKCS#11 tokens |
| Cloud KMS backend (AWS / Azure / Google) | AWS KMS, Azure Key Vault and Google Cloud KMS backends |
| HashiCorp Vault Transit backend | Signing keys and KEKs in a Vault Transit engine; token/AppRole auth |
| Key ceremony, backup & DR | M-of-N key ceremony, key inventory, backup and disaster recovery |
| Production HSM migration | SoftHSM → real HSM (YubiHSM / network HSM) cutover |
| Remotely verifiable HSM audit log | Third-party-checkable proof that a given key signed nothing beyond what was published, and that the log came from the HSM whose serial it names |
| YubiHSM key attestation | Hardware-signed proof a key was born in the HSM and cannot be exported |
2. Certificate authority — ca/¶
Standing up CAs and running the certificate lifecycle.
| Page | Covers |
|---|---|
| CA setup & certificate lifecycle | Root and intermediate CAs, profiles, issue/renew/revoke, CRL and OCSP |
| Intermediate key rotation | Intermediate signing-key rollover with a dual-chain overlap window |
| Cross-signing & bridge CAs | Bridge CAs and root transitions through alternate trust chains |
| Externally-signed subordinate CA | A subordinate CA signed by an offline or third-party root |
| Importing existing keys & adopting a CA | Migrating a CA or signing key that already exists into the provider, without re-keying |
| SSH certificate authority | HSM-backed OpenSSH user and host certificates, KRL revocation |
| PKCS#12 (.p12/.pfx) export | Server-side key generation with password-protected bundle delivery |
| Chain / path validation | Validating a supplied chain: path building, revocation, policy, key strength |
| Certificate-inventory retention & archival | Bounding a high-volume inventory with a fail-safe age-out policy |
3. Issuance policy & pre-issuance gates — issuance/¶
What is checked before the HSM is ever asked to sign.
| Page | Covers |
|---|---|
| Issuance preview (dry-run) | Dry-run a would-be issuance through every gate without signing anything |
| Pre-issuance certificate linting | CA/Browser Forum Baseline Requirements lint gate, with optional zlint |
| CAA record checking (RFC 8659) | Fail-closed DNS authorization, incl. accounturi/validationmethods |
| Name Constraints & Certificate Policies (RFC 5280) | Permitted/excluded subtrees and policy OIDs on CAs and leaves |
| Weak-key & compromised-key gate | ROCA, RSA policy, the Debian blocklist and an operator SPKI denylist |
| Certificate Transparency (RFC 6962) | CT precertificate submission, SCT embedding and inclusion-proof monitoring |
4. Certificate types & profiles — certificates/¶
The specialized certificate shapes the CA can issue.
| Page | Covers |
|---|---|
| S/MIME e-mail protection | Mailbox validation, domain allowlists and the S/MIME BR lint rules |
| Smartcard-logon & Kerberos PKINIT | Windows smartcard logon and Kerberos PKINIT client certificates |
| eIDAS qualified certificates (ETSI EN 319 412-5) | QcCompliance/QcType/QcSSCD and the PSD2 QcStatement |
| SPIFFE SVID workload identity | Short-lived workload identities and the JWKS trust bundle |
| TLS Delegated Credentials (RFC 9345) | The delegationUsage extension; minting and verifying credentials |
| Post-quantum & hybrid certificates | Pure ML-DSA and catalyst-hybrid signatures, with interop caveats |
5. Enrollment protocols & integrations — protocols/¶
How clients and devices actually get their certificates.
| Page | Covers |
|---|---|
| ACME server (RFC 8555) | Challenges, EAB, ARI, client-selectable profiles, STAR, S/MIME |
| ACME Multi-Perspective Issuance Corroboration (SC-067) | Corroborating domain control from several network vantage points |
| SCEP & EST enrollment | Device, MDM and IoT enrollment with challenge or client-cert auth |
| BRSKI zero-touch onboarding (RFC 8995) | Voucher-based onboarding of factory-fresh devices through a MASA |
| Windows autoenrollment (MS-XCEP + MS-WSTEP) | GPO-driven autoenrollment for AD-joined machines, Kerberos-free |
| Host auto-enrollment agent (secsy-agent) | Declarative cert specs, ARI-driven renewal, atomic install and rollback |
| gRPC API | PKIService over gRPC, with reflection, health checks and mTLS |
6. Signing & timestamping services — signing/¶
Using the HSM to sign things that are not certificates.
| Page | Covers |
|---|---|
| Artifact / code signing | HSM-backed CMS/PKCS#7 code and artifact signing, CAdES B/T/LT |
| Time-stamping authority (RFC 3161) | Provisioning the TSA key, the /tsa endpoint, openssl ts interop |
| Trusted external time source (NTS / Roughtime) | Cross-checking the host clock before signing, and refusing on drift |
| Long-term preservation — Evidence Records (RFC 4998) | Renewable archive timestamps that outlive algorithm obsolescence |
7. Secret & password encryption — secrets/¶
The HSM-backed encryption service that sits alongside the PKI.
| Page | Covers |
|---|---|
| Password / secret encryption | Envelope encryption, escrow, KEK rotation, FPE and the crypto service |
8. Security, access control & governance — security/¶
Who may do what, and the evidence that they did it.
| Page | Covers |
|---|---|
| RBAC, audit logging & config | Roles, per-CA permissions, the hash-chained event log, centralized config |
| Operator authentication (SSO, mTLS, WebAuthn) | OIDC SSO, LDAP/AD, mTLS binding, WebAuthn step-up, scoped API tokens |
| Four-eyes / maker-checker approvals | Dual control over CA lifecycle, bulk revocation and issuance |
| Multi-tenant isolation | Serving several isolated organizations from one deployment |
| Rate limiting & abuse protection | Tiered rate limits and the bounded HSM concurrency guard |
| Audit log export to SIEM | Streaming the audit log to syslog/CEF/webhook, and offline verification |
| FIPS 140-3 mode | The GOFIPS140 build plus the fail-closed algorithm policy |
| Security review & hardening | Findings, fixes, residual risks, and how to re-verify them |
9. Deployment & scaling — deployment/¶
Getting it running, and running more than one of it.
| Page | Covers |
|---|---|
| The container image | The published image: tags, both architectures, what is inside, and verifying it |
| Kubernetes deployment | Container image, Helm chart, cert-manager issuer, kind/SoftHSM smoke test |
| Persistence backends (SQLite & PostgreSQL) | SQLite and PostgreSQL stores, pooling, and migration between them |
| Multi-replica coordination & HA | Multiple replicas with leader-elected singleton background jobs |
| Unix-domain-socket listeners | Serving HTTP/gRPC on a socket instead of a port, with filesystem permissions as the boundary |
| Self-managed serving-TLS certificate | Issuing the server's own HTTPS certificate from an internal CA |
10. Day-2 operations — operations/¶
Running it, watching it, and fixing it when it breaks.
| Page | Covers |
|---|---|
| Operator runbook | Day-2 procedures: incidents, outages, tuning, rotation, DR, diagnostics |
| Incident response: mass revocation | Key-compromise mass revocation against the CA/B 24-hour clock |
| Observability | Prometheus metrics, health/readiness probes, dashboards, alerts and SLOs |
| Distributed tracing (OpenTelemetry) | Request-to-HSM span trees over OTLP, with log↔trace correlation |
| Expiry monitoring & auto-renewal | Expiry scanning, notification sinks and automated renewal |
| Synthetic issuance canary | A probe that continuously proves the issuance path end to end |
| Scheduled encrypted backups | Leader-elected encrypted DR artifacts, and proving they restore |
| OCSP pre-signing & static publishing (CDN offload) | Taking the HSM off the public hot path; CRL/OCSP to a CDN |
| Outbound webhooks (eventing) | At-least-once delivery with HMAC signatures and dead-lettering |
| DANE TLSA & SSHFP DNS records | Zone-file pinning records for TLS services and SSH hosts |
| Operator web console | The embedded operator console and its CLI feature-parity map |
11. Compliance & audit readiness — compliance/¶
The documents a WebTrust or CA/Browser Forum audit asks for.
| Page | Covers |
|---|---|
| Certificate Policy / CPS (RFC 3647) | The audit-facing CP/CPS, all nine sections, from the code |
| Compliance control mapping | CA/B BR, S/MIME BR and WebTrust controls traced to implementing code |
12. Development, testing & release — development/¶
The quality gates a change has to clear.
| Page | Covers |
|---|---|
| Performance & load benchmarking | HSM hot-path benchmarks, session-pool tuning, the regression gate |
| Test-coverage measurement & ratchet gate | A committed baseline that coverage may only ratchet above |
| Fuzz & property testing | Native go test -fuzz targets over the untrusted-input parsers |
| Resilience & fault-injection testing | Deliberately breaking dependencies to prove the PKI fails closed |
| Authorization & tenant-isolation regression matrix | A pinned RBAC/tenant decision for every REST route and RPC |
| Releasing | The release guard, what a v* tag sets off, the release archives, and the dry run |
| Supply-chain security (SBOM, signing, SLSA) | SBOMs, cosign signing, SLSA provenance and the govulncheck gate |
| Documentation site (GitHub Pages) | How these pages are published, and how to build the site locally |
Architecture Decision Records — adr/¶
The load-bearing design decisions, and what they cost.
Key-provider abstraction · HSM non-extractability invariants · Fail-closed security gates · Dual-chain rotation overlap · PQC / hybrid algorithm choice · Four-eyes approval gate
Project-level documents¶
These live at the repository root, where contributors and tooling expect them:
| Document | Covers |
|---|---|
| README | What secsy-pki is, quick start, the secsy-ssh client, the REST API |
| ARCHITECTURE | Component map, request flows, and the feature-to-code index |
| TESTING | How to run every suite: unit, SoftHSM integration, e2e, race, lint |
examples/ |
Runnable end-to-end use-case recipes |
The tools at a glance¶
| Binary | Purpose | Build |
|---|---|---|
secsy-pki-server |
The HTTP server, web console, and API | go build -tags sqlite -o secsy-pki-server ./cmd/server |
secsy-ca |
CA setup and certificate lifecycle | go build -tags sqlite -o secsy-ca ./cmd/secsy-ca |
secsy-secret |
HSM-backed secret encryption | go build -tags sqlite -o secsy-secret ./cmd/secsy-secret |
secsy-agent |
Host auto-enrollment / renewal daemon | go build -o secsy-agent ./cmd/secsy-agent |
secsy-ssh |
OIDC SSH client wrapper | go build -o secsy-ssh ./cmd/secsy-ssh |
secsy-verify |
Offline HSM audit-log verifier | go build -o secsy-verify ./cmd/verify |
All CLIs accept -config config.yaml and share the server's configuration,
database, and key provider. Run any command with -h for its flags.