vca
Zero-Trust X.509 v3 PKI, OpenSSH CA, OIDC Workload Broker & Merkle CT Engine

vca — Unified Zero-Trust X.509 v3 PKI & OpenSSH Certificate Authority

vca — Cryptographic Certificate Authority & Trust Engine

Overview

vca is a self-contained, zero-external-dependency Private Public Key Infrastructure (PKI), X.509 v3 Certificate Authority, OpenSSH User & Host Certificate Authority, RFC 6962 Merkle Certificate Transparency (CT) Log, RFC 3161 Timestamp Authority (TSA), Private ACME v2 Server, and OIDC 1.0 Workload Identity Minter. Distributed as a single native executable for Windows, Linux, and macOS, vca unifies short-lived TLS/mTLS workload certificates, zero-standing-privilege SSH access, keyless code signing, and cryptographic auditability under one policy plane.

AUTHORITY TOPOLOGY

vca End-to-End Zero-Trust X.509 v3 PKI, OpenSSH CA, OIDC Federation & Merkle CT Architecture

Click any component node to inspect how vca evaluates workload identity, signs certificates, and appends transparency proofs.

Interactive SVG • Click any node (6 components)
1. WORKLOADS & OPERATORS CLI / ACME v2 / OIDC / Web Studio 2. POLICY & SIGNING AUTHORITY CORE ABAC + X.509 v3 DER + OpenSSH CA 3. TRANSPARENCY & SEALED VAULT RFC 6962 Merkle CT + Sharded MVCC CSR / OIDC MFA / ZSP X.509 Policy SSH Policy CT + WAL CT + KRL Relying Clients Workloads & CI Runners CSR, SSH PubKey, ACME & OIDC Principals Operators & End Users 4-Workspace PKI Web Studio Policy Engine OIDC & ABAC Policy Gate S256 PKCE + Option P3 Compiler PKI Engine X.509 v3 DER Authority Root / Scoped Int / OCSP / CRL SSH Engine OpenSSH Cert Authority User/Host Certs + Binary SSHKRL Transparency & State Merkle CT & Sealed Vault RFC 6962 STH + AES-256-GCM WAL
Components:
Relying Clients
Workloads & CI Runners
Zero-Escrow Enrollment ACME v2
Component 1 of 6
Architectural Role & Purpose

Services, TLS ingress proxies, SSH bastions, and CI pipelines requesting short-lived cryptographic identities.

Contextual Description & System Interaction

Guarantees zero private-key escrow on standard enrollment flows while eliminating long-lived static secrets.

Core Functionality & Security Mechanics
  • Generates private keys locally and submits signed PKCS#10 CSRs or OpenSSH public keys
  • Automates zero-touch TLS certificate renewal over Private ACME v2 directory flows
  • Exchanges OIDC S256 PKCE or workload tokens for keyless 10-minute signing certificates
Principals
Operators & End Users
Role-Separated Web Studio CLI
Component 2 of 6
Architectural Role & Purpose

Developers minting ZSP bundles and administrators governing CA hierarchies, Shamir ceremonies, and ABAC profiles.

Contextual Description & System Interaction

Separates self-service credential workflows (/ui/portal) from scoped (/ui/delegated) and global (/ui/admin) governance.

Core Functionality & Security Mechanics
  • Enrolls RFC 6238 TOTP MFA via offline ISO 18004 SVG QR codes
  • Mints atomic Triple-Credential ZSP bundles (X.509 mTLS + OpenSSH User Cert + Mesh Token)
  • Executes Shamir M-of-N unseal ceremonies, cross-signing rollovers, and wire inspections
Policy Engine
OIDC & ABAC Policy Gate
OIDC Verifier Option P3 ABAC Engine
Component 3 of 6
Architectural Role & Purpose

Authenticates principals and compiles conjunctive ABAC profile constraints prior to any signing operation.

Contextual Description & System Interaction

Acts as a fail-closed zero-trust gate preventing unauthorized SANs, privilege escalation, or excessive TTLs.

Core Functionality & Security Mechanics
  • Verifies EdDSA JWT signatures, S256 PKCE challenges, step-up MFA claims, and vca_enroll_ tokens
  • Enforces allowed SAN wildcard patterns, permitted DNS subtrees, and SSH principal whitelists
  • Clamps requested certificate lifetimes strictly to the matched profile max_ttl_seconds ceiling
PKI Engine
X.509 v3 DER Authority
ITU-T X.690 DER Multi-Tier X.509 v3
Component 4 of 6
Architectural Role & Purpose

Constructs, validates, and signs canonical X.509 v3 certificates, RFC 5280 CRLs, OCSP responses, and TSA tokens.

Contextual Description & System Interaction

Implements definite-length ASN.1 DER encoding and decoding natively with zero external crypto library dependencies.

Core Functionality & Security Mechanics
  • Supports Ed25519, Jacobian ECDSA-P256, blinded RSA-2048/3072/4096, and X25519 key agreement
  • Enforces critical BasicConstraints (pathLenConstraint) and Intermediate NameConstraints subtrees
  • Strips untrusted PKCS#10 CSR extensions and serves live CRL v2 and OCSP revocation status
SSH Engine
OpenSSH Cert Authority
OpenSSH Wire Codec SSHKRL Engine
Component 5 of 6
Architectural Role & Purpose

Signs short-lived OpenSSH user and host certificates, binary SSHKRL lists, and Git/artifact allowed_signers.

Contextual Description & System Interaction

Replaces static ~/.ssh/authorized_keys files and TOFU host prompts with short-lived cryptographic certificates.

Core Functionality & Security Mechanics
  • Issues ssh-ed25519-cert-v01, ecdsa-sha2-nistp256-cert-v01, and rsa-sha2-256/512-cert-v01
  • Sorts critical_options (source-address, force-command) and extensions lexicographically
  • Generates raw SSHKRL binary revocation artifacts for sshd RevokedKeys enforcement
Transparency & State
Merkle CT & Sealed Vault
RFC 6962 CT Log Sharded MVCC Vault
Component 6 of 6
Architectural Role & Purpose

Seals CA keys in AES-256-GCM envelopes, records Merkle CT proofs, and persists sharded MVCC + CRC32 WAL state.

Contextual Description & System Interaction

Provides cryptographic non-repudiation for every issued credential and tamper-evident authority durability.

Core Functionality & Security Mechanics
  • Protects Master KEK with GF(2^8) Shamir M-of-N shares and instant RAM zeroization on seal
  • Appends every issued certificate to the RFC 6962 Merkle tree with O(log N) inclusion proofs
  • Persists Ed25519-signed hash-chained RFC 5424 audit logs across MVCC WAL, cluster, or SQLite

Core Capabilities

Audience Capability Operational Value
Developers & Engineers Zero-Standing-Privilege SSH & mTLS (/ui/portal) Sign client-generated PKCS#10 CSRs and ~/.ssh/id_*.pub keys without private key escrow, mint atomic Triple-Credential ZSP bundles (X.509 v3 + OpenSSH + vnet_tok_), and obtain 10-minute Fulcio-style keyless OIDC code-signing certificates.
Workload & Mesh Operators Automated ACME v2, SPIFFE & Enrollment Tokens Automate TLS and service-mesh certificate lifecycle via stateful RFC 8555 Private ACME v2 (/acme/v2/directory), RFC 8693 OAuth 2.0 Token Exchange, and SAN-scoped machine bootstrap tokens (vca_enroll_* and vca_pat_*).
Delegated Org Operators Scoped Organizational Unit Governance (/ui/delegated) Manage principals, scoped issuance profiles, enrollment tokens, and immediate certificate revocations strictly within assigned Organizational Unit boundaries (org_id).
PKI Administrators Multi-Tier CA Hierarchy, Shamir Quorum & Rollover (/ui/admin) Govern Root CAs, RFC 5280 NameConstraints-scoped Intermediate CAs, and OpenSSH User/Host CAs protected by NIST SP 800-38D AES-256-GCM sealing, GF(2^8) M-of-N Shamir threshold ceremonies, and zero-downtime Root CA cross-signing.
Security & Compliance Teams Merkle CT Log, Live CRL/OCSP/SSHKRL & SOAR Verify O(log N) RFC 6962 Merkle inclusion proofs and Ed25519 Signed Tree Heads (STH), query live CRL v2 / RFC 6960 OCSP / binary SSHKRL, trigger closed-loop vsight SOAR containment, and export signed SOC2 / ISO 27001 compliance dossiers.

Live PKI Studio Preview

Identity & TOTP Authentication Gate (/ui/auth)

vca Identity & TOTP Authentication Gate

Self-Service Credentials, ISO 18004 MFA Pairing & Inventory (/ui/portal)

vca Self-Service Principal Profile, ISO 18004 TOTP QR & Issued Credentials


End-User Documentation Suite

  1. Overview & Readme — Product overview, zero-trust PKI capabilities, Web Studio preview, and quickstart commands.
  2. How-To Guide — Step-by-step recipes for offline Root + online Intermediate CA hierarchies, mTLS issuance, OpenSSH host/user signing, CT inclusion proof verification, and CRL/OCSP/SSHKRL revocation.
  3. End-User Guide — Developer and workload workflows, Web Studio navigation, zero-escrow CSR submission, SSH certificate login, and ASN.1 DER / SSH wire inspection.
  4. Administrator Guide — PKI hierarchy governance, Shamir M-of-N key ceremonies, zero-downtime Root rollover, ABAC issuance profiles, OIDC federation rules, encrypted backups, and WAL recovery.
  5. Operations & Use Cases — Production runbooks for zero-standing-privilege SSH bastions, service-mesh mTLS automation, CT log auditing, and incident SOAR revocation.
  6. Configuration & CLI Reference — Complete CLI subcommand and flag catalog, vca.conf and environment variables, policy JSON schemas, and OpenAPI 3.1 REST endpoints.
  7. Performance & Capacity Guide — Cryptographic signing throughput across Ed25519/ECDSA-P256/RSA, ASN.1 DER latency, Merkle CT append/proof latency, and WAL recovery metrics.
  8. Master User Handbook — Single-volume consolidated compendium combining all End-User, How-To, Administrator, Operations, CLI, and Performance guides.

Quickstart

Run vca using the prebuilt native binary for your platform (vca.exe on Windows or ./vca on Linux and macOS):

BASH
# Display semantic version and cryptographic engine summary
./vca version

# Start the HTTP/1.1 OpenAPI Control Plane & 4-Workspace PKI Studio
./vca serve 127.0.0.1:8444 --data-dir data/vca --issuer http://127.0.0.1:8444

# Provision a NameConstraints-scoped Intermediate X.509 v3 CA
./vca ca init-intermediate \
  --cn "VCA Edge TLS Intermediate Authority" \
  --ca-id ca-int-edge \
  --domains ".corp.internal" \
  --out-chain edge_ca_chain.pem \
  --data-dir data/vca

# Issue a 3-tier X.509 v3 workload certificate chain (Leaf + Intermediate + Root)
./vca cert issue-x509 \
  --cn gateway.corp.internal \
  --san "gateway.corp.internal,api.corp.internal" \
  --ca-id ca-int-edge \
  --out-cert gateway_fullchain.pem \
  --out-key gateway.key \
  --data-dir data/vca

# Sign a short-lived OpenSSH user certificate without private key escrow
./vca ssh sign \
  --pubkey ~/.ssh/id_ed25519.pub \
  --principal "alice,sre-admin" \
  --type user \
  --ttl 28800 \
  --out ~/.ssh/id_ed25519-cert.pub \
  --data-dir data/vca

Open http://127.0.0.1:8444/ui/auth in your browser to access the Authentication Gate, Self-Service Portal, Delegated Operations Console, and Global Administrator Console.

vca — Step-by-Step How-To Guide

vca — Cryptographic Certificate Authority & Trust Engine

1. Bootstrapping an Offline Root & Online Scoped Intermediate CA Hierarchy

Production PKI deployments isolate the Root X.509 v3 trust anchor from daily leaf certificate signing by issuing Scoped Intermediate CAs restricted with RFC 5280 NameConstraints.

Step 1.1: Initialize the Authority Store and Root Hierarchy

Starting vca against a clean --data-dir automatically generates a 256-bit Master Key Encryption Key (master.kek), splits it into 2-of-3 GF(2^8) Shamir shares, and provisions sealed X.509 v3 Root (ca-root-x509), OpenSSH User (ca-user-ssh), and OpenSSH Host (ca-host-ssh) authorities under NIST SP 800-38D AES-256-GCM envelopes (ENC[vca-v2-gcm:...]).

BASH
./vca serve 127.0.0.1:8444 --data-dir ./data --issuer https://pki.corp.internal

Step 1.2: Provision Domain-Scoped Online Intermediate CAs

Create dedicated Intermediate CAs for public edge gateways and internal service-mesh workloads. Each Intermediate CA sets basicConstraints: critical, CA:TRUE, pathLenConstraint: 0 and enforces permittedSubtrees DNS boundaries:

BASH
# Edge TLS Intermediate CA (Ed25519) constrained to .corp.internal
./vca ca init-intermediate \
  --cn "VCA Edge TLS Intermediate Authority" \
  --ca-id ca-int-edge \
  --domains ".corp.internal" \
  --alg Ed25519 \
  --out-chain ./certs/ca-int-edge-chain.pem \
  --data-dir ./data

# Service-Mesh mTLS Intermediate CA (ECDSA-P256) constrained to .mesh.corp.internal
./vca ca init-intermediate \
  --cn "VCA Workload mTLS Intermediate Authority" \
  --ca-id ca-int-mtls \
  --domains ".mesh.corp.internal" \
  --alg ECDSA-P256 \
  --out-chain ./certs/ca-int-mtls-chain.pem \
  --data-dir ./data

You can also provision Intermediate CAs live via the REST API or Global Administrator Console (/ui/admin):

BASH
curl -sS -X POST http://127.0.0.1:8444/api/v1/ca/intermediate \
  -H "Authorization: Bearer ${ADMIN_JWT}" \
  -H "Content-Type: application/json" \
  -d '{
    "ca_id": "ca-int-edge",
    "display_name": "VCA Edge TLS Intermediate Authority",
    "permitted_dns_domains": ".corp.internal",
    "algorithm": "Ed25519"
  }'

Multi-Tier Root, Scoped Intermediate & OpenSSH CA Hierarchy


2. Issuing mTLS Workload Certificates (CLI & Zero-Escrow CSR API)

Recipe 2.1: Direct CLI Issuance with Full 3-Tier PEM Chain

Issue a short-lived workload certificate signed by ca-int-mtls. vca appends an RFC 6962 Signed Certificate Timestamp (SCT) extension, logs the certificate in the Merkle CT tree, and writes the complete Leaf + Intermediate + Root PEM chain:

BASH
./vca cert issue-x509 \
  --cn payments.mesh.corp.internal \
  --san "payments.mesh.corp.internal,ledger.mesh.corp.internal" \
  --alg ECDSA-P256 \
  --ttl 14400 \
  --ca-id ca-int-mtls \
  --out-cert ./certs/mesh/payments-fullchain.pem \
  --out-key ./certs/mesh/payments.key \
  --data-dir ./data

Recipe 2.2: Zero-Private-Key-Escrow PKCS#10 CSR Signing via REST API

Generate the private key locally on the workload host so private key material never crosses the network, then submit only the PKCS#10 CSR using either an interactive Bearer JWT or a SAN-scoped enrollment token (vca_enroll_...):

BASH
# 1. Mint a single-use machine enrollment token scoped to *.mesh.corp.internal
ENROLL_TOK=$(curl -sS -X POST http://127.0.0.1:8444/api/v1/tokens/enroll \
  -H "Authorization: Bearer ${ADMIN_JWT}" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "prof-zsp-triple",
    "allowed_sans": "*.mesh.corp.internal",
    "max_uses": 1,
    "ttl_secs": 3600
  }')

# 2. Submit client-generated PKCS#10 CSR for zero-escrow signing
curl -sS -X POST http://127.0.0.1:8444/api/v1/self/x509-sign \
  -H "Authorization: Bearer vca_enroll_..." \
  -H "Content-Type: application/json" \
  -d '{
    "ca_id": "ca-int-mtls",
    "csr_pem": "-----BEGIN CERTIFICATE REQUEST-----\n...\n-----END CERTIFICATE REQUEST-----",
    "dns_names": ["orders.mesh.corp.internal"],
    "requested_ttl": 3600
  }'

vca verifies the CSR Proof-of-Possession signature, strips all untrusted client CSR extensions, enforces RFC 6125 single-label wildcard SAN rules and Intermediate NameConstraints, and returns certificate_pem, certificate_chain_pem, serial_hex, and sct_leaf_hash.


3. Signing Short-Lived OpenSSH User & Host Certificates

vca implements OpenSSH PROTOCOL.certkeys across ssh-ed25519-cert-v01@openssh.com, rsa-sha2-256-cert-v01@openssh.com, and ecdsa-sha2-nistp256-cert-v01@openssh.com without ever escrowing SSH private keys.

Step 3.1: Configure OpenSSH Daemons & Clients to Trust vca

BASH
# Export TrustedUserCAKeys and @cert-authority known_hosts entries
curl -sS http://127.0.0.1:8444/api/v1/ssh/ca-keys

On target Linux servers (./config/ssh/sshd_config), trust the vca User SSH CA and install its host certificate:

TEXT
TrustedUserCAKeys ./certs/ssh/vca_user_ca.pub
HostKey ./certs/ssh/ssh_host_ed25519_key
HostCertificate ./certs/ssh/ssh_host_ed25519_key-cert.pub
RevokedKeys ./certs/ssh/vca_revoked.krl

Step 3.2: Sign an OpenSSH Host Certificate (cert_type = 2)

BASH
./vca ssh sign \
  --pubkey ./certs/ssh/ssh_host_ed25519_key.pub \
  --principal "bastion01.corp.internal,10.20.0.10" \
  --type host \
  --ttl 2592000 \
  --out ./certs/ssh/ssh_host_ed25519_key-cert.pub \
  --data-dir ./data

Step 3.3: Sign a Short-Lived Developer OpenSSH User Certificate (cert_type = 1)

BASH
# Via CLI
./vca ssh sign \
  --pubkey ~/.ssh/id_ed25519.pub \
  --principal "alice,sre-admin" \
  --type user \
  --ttl 28800 \
  --out ~/.ssh/id_ed25519-cert.pub \
  --data-dir ./data

# Or via Zero-Escrow REST API
curl -sS -X POST http://127.0.0.1:8444/api/v1/self/ssh-sign \
  -H "Authorization: Bearer ${USER_JWT}" \
  -H "Content-Type: application/json" \
  -d '{
    "ssh_public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl alice@laptop",
    "cert_type": "user",
    "principals": ["alice", "sre-admin"],
    "requested_ttl": 3600
  }'

4. Verifying Certificate Transparency (CT) Merkle Inclusion Proofs

Every X.509 v3 certificate issued by vca (standard CSR, Triple-Credential ZSP bundle, ACME v2 finalize, or Keyless OIDC signing) is appended to an RFC 6962 SHA-256 Merkle binary tree.

BASH
# 1. Fetch the Ed25519-signed Merkle Signed Tree Head (STH)
curl -sS http://127.0.0.1:8444/api/v1/ct/v1/get-sth

# 2. Request and verify an O(log N) Merkle inclusion proof for leaf index 1
curl -sS "http://127.0.0.1:8444/api/v1/ct/v1/get-proof-by-index?index=1"

Example inclusion proof response:

JSON
{
  "leaf_index": 1,
  "tree_size": 5,
  "leaf_hash_hex": "d56833378df9c6ef25cd9cb1139d7671bdeba1e153dc39d2ea5a1acb80bae4f5",
  "root_hash_hex": "994cb99522cd3a7291eac3d115c510c680481403533a3d41dc5fba34e7eac2d0",
  "audit_path": [
    "a09903b8b2c5ab86b534de8a88b5340dfab970c59c7e2915d73b6bf1de7f21f3",
    "180c7eaa882a79e0899e044a0cf853d3465d543cdff3b41912eef14d6f1cfce6",
    "608e1655eb4ee1b276f0164da83a2a97aed2098715e3f3adc7b9f0ac56443f31"
  ],
  "verified": true
}

Merkle Certificate Transparency Inclusion Proof in Dark Mode


5. Revoking Compromised Credentials via CRL v2, OCSP & OpenSSH KRL

When a workload key or developer laptop is compromised, revoke the credential immediately by cert_id with an RFC 5280 revocation reason (keyCompromise, cessationOfOperation, superseded, or privilegeWithdrawn):

BASH
# 1. Revoke the certificate immediately
curl -sS -X POST http://127.0.0.1:8444/api/v1/certificates/revoke \
  -H "Authorization: Bearer ${ADMIN_JWT}" \
  -H "Content-Type: application/json" \
  -d '{
    "cert_id": "xcert_012ea21fee4e6431",
    "reason": "keyCompromise"
  }'

# 2. Query real-time RFC 6960 OCSP status ("good", "revoked", or "unknown")
curl -sS -X POST http://127.0.0.1:8444/api/v1/x509/ocsp \
  -H "Content-Type: application/json" \
  -d '{"serial_hex": "3ea3a5f60"}'

# 3. Export signed PEM X.509 CRL v2 for TLS proxies and edge load balancers
./vca crl --out ./certs/vca_revoked.crl.pem --data-dir ./data
curl -sS "http://127.0.0.1:8444/api/v1/x509/crl?format=pem" -o ./certs/vca_revoked.crl.pem

# 4. Export binary OpenSSH Key Revocation List (SSHKRL) for sshd RevokedKeys
./vca krl --out ./certs/ssh/vca_revoked.krl --data-dir ./data
curl -sS "http://127.0.0.1:8444/api/v1/ssh/krl?format=raw" -o ./certs/ssh/vca_revoked.krl

6. Native HTTPS / mTLS Serving & EST / SCEP Device Enrollment

Step 6.1: Serve vca Natively over HTTPS or Mutual TLS (mTLS)

Start vca directly over TLS without an external reverse proxy using either explicit PEM files or an ephemeral auto-provisioned ECDSA-P256 bundle:

BASH
# Quick native HTTPS with an auto-provisioned ECDSA-P256 certificate
./vca serve 0.0.0.0:8444 --tls-auto --data-dir ./data

# Production mTLS enforcing client certificates signed by your CA bundle
./vca serve 0.0.0.0:8444 \
  --tls-cert ./certs/vca_server.pem \
  --tls-key ./certs/vca_server.key \
  --tls-client-ca ./certs/vca_root_ca.pem \
  --data-dir ./data

Step 6.2: Automated Network & MDM Device Enrollment via EST (RFC 7030) and SCEP (RFC 8894)

BASH
# 1. Fetch the RFC 7030 EST PKCS#7 certs-only CA bundle
curl -sS https://pki.corp.internal/.well-known/est/cacerts -o cacerts.p7b.b64

# 2. Enroll a network appliance via EST simpleenroll (HTTP Basic or Bearer / vca_enroll_* token)
curl -sS -X POST https://pki.corp.internal/.well-known/est/simpleenroll \
  -u "alice:vca-secret-2026" \
  -H "Content-Type: application/pkcs10" \
  --data-binary @device.csr.b64 \
  -o device.p7b.b64

# 3. Query SCEP capabilities and CA certificate for MDM / router clients
curl -sS "https://pki.corp.internal/scep?operation=GetCACaps"
curl -sS "https://pki.corp.internal/scep?operation=GetCACert" -o ca.der

vca — End-User & Developer Guide

vca — Cryptographic Certificate Authority & Trust Engine

1. Navigating the Role-Separated PKI Web Studio

vca provides four role-separated browser workspaces served directly by the authority daemon (http://127.0.0.1:8444/ui/*). Each workspace defaults to crisp Institutional Light Mode (data-theme="light") with a persistent 1-click Dark Mode toggle in the top header bar:

Workspace Path Target Persona Primary Capabilities
/ui/auth All Principals Username + PBKDF2 password + 6-digit RFC 6238 TOTP sign-in, plus OIDC 1.0 + PKCE and ACME v2 endpoint discovery.
/ui/portal Developers & Workloads (member) Triple-Credential ZSP bundles, zero-escrow PKCS#10 CSR and SSH .pub signing, keyless OIDC code-signing, RFC 3161 timestamping, ASN.1 DER / SSH wire inspection, TOTP QR pairing, and personal credential renewal/revocation.
/ui/delegated OrgUnit Leads (delegated_admin) Scoped certificate inventory, OrgUnit principal provisioning, and SAN-locked machine enrollment token minting within the caller's org_id.
/ui/admin PKI Governors (super_admin, global_admin) Multi-tier Root/Intermediate/SSH CA topology, Shamir M-of-N seal/unseal ceremonies, ABAC policy profiles, Merkle CT log proofs, live CRL/OCSP/SSHKRL, vsight SOAR containment, and encrypted backups.

2. Signing In & Pairing TOTP Multi-Factor Authentication

  1. Open /ui/auth in your browser.
  2. Enter your username, password, and (when MFA is enabled on your account) the current 6-digit TOTP verification code from your authenticator app, then click Sign In & Mint EdDSA Session.
  3. Navigate to Self-Service Portal -> My Credentials & MFA and click Refresh Profile & Credentials to view your verified SPIFFE ID (spiffe://<trust-domain>/ns/<org>/sa/<user>) and scan your offline ISO/IEC 18004 vector SVG QR code.

Authentication & TOTP MFA Sign-In Gate

Principal Profile, ISO 18004 QR Code & Personal Credential Inventory


3. Minting Atomic Triple-Credential ZSP Bundles

Instead of juggling separate mTLS certificates, static SSH keys, and VPN configurations, developers can mint a short-lived Triple-Credential Zero-Standing-Privilege (ZSP) Bundle from /ui/portal (Triple-Credential ZSP tab):

  1. Set the Target vgate Zero-Trust Mesh Network (for example, prod-mesh) and Requested Lease TTL (for example, 3600 seconds).
  2. Select one or more authorized OpenSSH Principals (alice, sre-admin, deploy) using the multi-select chip selector.
  3. Click Mint Triple-Credential Bundle.

Minting an Atomic Triple-Credential ZSP Bundle in the Self-Service Portal

The Lightbox modal displays a single JSON bundle containing:

  • x509_certificate_pem — Short-lived X.509 v3 mTLS client certificate bound to your SPIFFE URI and ABAC claims (OID 1.3.6.1.4.1.59999.1.1) with an embedded Merkle CT SCT.
  • ssh_authorized_cert — Short-lived OpenSSH User certificate (ssh-ed25519-cert-v01@openssh.com) carrying your approved principals and permit-pty / permit-port-forwarding extensions.
  • vnet_token — HMAC-authenticated vnet_tok_... mesh session token accepted by vgate zero-trust gateways.

4. Submitting Zero-Escrow CSRs & Logging In with OpenSSH Certificates

4.1 Zero-Escrow PKCS#10 CSR Submission

When your private key must remain on your workstation, HSM, or container volume:

  1. Generate an Ed25519, ECDSA-P256, or RSA-2048/4096 keypair and PKCS#10 CSR locally.
  2. Open Self-Service Portal -> Zero-Escrow CSR & SSH Sign.
  3. Enter your requested DNS Subject Alternative Names (for example, workload.corp.internal), paste the -----BEGIN CERTIFICATE REQUEST----- block, and click Sign PKCS#10 CSR.
  4. Save the returned 3-tier certificate_chain_pem alongside your local private key.

4.2 Zero-Escrow OpenSSH Certificate Login Workflow

  1. Copy the contents of your local public key (~/.ssh/id_ed25519.pub)—never your private key.
  2. In Zero-Escrow CSR & SSH Sign, paste the .pub line, keep User Certificate (SSH_CERT_TYPE_USER = 1) selected, and click Sign OpenSSH Public Key (or run vca ssh sign --pubkey ~/.ssh/id_ed25519.pub --principal alice --out ~/.ssh/id_ed25519-cert.pub).
  3. Write the authorized_cert_line to ~/.ssh/id_ed25519-cert.pub next to ~/.ssh/id_ed25519.
  4. Connect directly with standard OpenSSH:
BASH
# Inspect your issued certificate validity, serial, principals, and CA fingerprint
ssh-keygen -L -f ~/.ssh/id_ed25519-cert.pub

# Connect to any host trusting the vca OpenSSH User CA
ssh alice@bastion01.corp.internal

OpenSSH automatically presents ~/.ssh/id_ed25519-cert.pub alongside ~/.ssh/id_ed25519 without requiring any static ~/.ssh/authorized_keys entry on the remote host.


5. Keyless OIDC Signing, RFC 3161 Timestamping & Wire Inspection

5.1 Keyless OIDC Ephemeral Code Signing & allowed_signers

Open Keyless OIDC & TSA in /ui/portal:

  • Click Mint 10-Minute Keyless X.509 v3 Cert to exchange your active OIDC session for a Fulcio-style ephemeral signing certificate bound to your SPIFFE identity and logged permanently in the Merkle CT tree.
  • Click Issue RFC 3161 Timestamp Token over any 64-character SHA-256 release artifact digest (POST /api/v1/tsa/timestamp) so verifiers can prove the signature existed while the 10-minute ephemeral certificate was valid.
  • Click Export OpenSSH allowed_signers (GET /api/v1/ssh/allowed-signers) to verify Git tags and release bundles using ssh-keygen -Y verify.

5.2 Visual ASN.1 DER & OpenSSH Wire Byte-Tree Inspector

Open ASN.1 & SSH Wire Inspector in /ui/portal (or run ./vca inspect <file>):

  • Paste any X.509 PEM certificate, PKCS#10 CSR, RFC 3161 Timestamp Token, or OpenSSH *-cert-v01@openssh.com line and click Inspect Byte-Tree in Lightbox.
  • Review exact byte offsets, definite-length TLV lengths, nesting depths, OIDs, SANs, or OpenSSH PROTOCOL.certkeys wire fields before deploying credentials to production.

6. Renewing & Revoking Personal Credentials

In My Credentials & MFA, every active credential owned by your principal lists two one-click actions:

  • Renew (POST /api/v1/self/renew) — Re-evaluates policy and re-signs the public key with a fresh cryptographic serial number and updated validity window while preserving historical immutability of the prior certificate record.
  • Revoke (POST /api/v1/certificates/revoke) — Marks the credential revoked immediately across live OCSP, CRL v2, and OpenSSH KRL endpoints.

vca — PKI Administrator Guide

vca — Cryptographic Certificate Authority & Trust Engine

1. PKI Hierarchy Governance & Role Separation

vca enforces strict three-tier Role-Based Access Control (RBAC) combined with Organizational Unit (org_id) tenancy boundaries:

Role Scope Permitted Governance Actions
super_admin / global_admin Global Authority Provision Scoped Intermediate CAs, execute Root CA cross-signing, trigger RAM seal / Shamir M-of-N unseal ceremonies, manage all OrgUnits/profiles/users, run SOAR quarantines, export encrypted VCA_BACKUP_V2 snapshots, and generate SOC2 dossiers.
delegated_admin / org_admin Assigned org_id Only View OrgUnit certificates, create users and ABAC profiles strictly within their own org_id (cannot promote any user to global_admin), mint scoped enrollment tokens, and revoke OrgUnit certificates.
member Reflexive Self-Service Mint personal/workload certificates permitted by ABAC profiles, inspect artifacts, and renew or revoke only certificates they personally own.

2. Managing Root, Intermediate & OpenSSH Authorities

Navigate to /ui/admin (Multi-Tier CAs & Rollover tab) to inspect active signing authorities:

  1. Root X.509 v3 Authority (x509_root) — Trust anchor with CA:TRUE, pathLenConstraint: 2, sealed at rest using NIST SP 800-38D AES-256-GCM (ENC[vca-v2-gcm:<iv>:<tag>:<ciphertext>]).
  2. Scoped Intermediate X.509 v3 Authorities (x509_intermediate) — Signed by the Root CA with CA:TRUE, pathLenConstraint: 0 and critical RFC 5280 NameConstraints (permittedSubtrees), ensuring an edge Intermediate CA scoped to .corp.internal can never issue certificates for .prod.payments or external domains.
  3. OpenSSH User & Host Authorities (ssh_user_ca, ssh_host_ca) — Separate signing authorities for human/automation SSH user principals (cert_type = 1) and server host identities (cert_type = 2). Note that issuing an OpenSSH Host certificate requires an administrative role or a pre-authorized host enrollment token.

Multi-Tier CA Topology & Rollover Governance Console


3. Shamir M-of-N Key Ceremonies & Zero-Downtime Root Rotation

3.1 Master KEK Protection & On-Demand RAM Sealing

On initial bootstrap, vca generates a 32-byte CSPRNG master.kek and splits it into 2-of-3 Shamir Secret Shares over $\text{GF}(2^8)$ (x^8 + x^4 + x^3 + x + 1). Distribute each vca_share_2of3_<idx>_<hex> token to a separate key custodian.

During a security incident or maintenance window, seal the authority in RAM immediately:

BASH
# Zero the 256-bit Master KEK and unsealed CA key cache in RAM
curl -sS -X POST http://127.0.0.1:8444/api/v1/ca/seal \
  -H "Authorization: Bearer ${ADMIN_JWT}"

While sealed ("is_sealed": true on /api/v1/health), all signing endpoints fail closed with 503 Service Unavailable. Reconstruct master.kek in memory by submitting threshold shares via /ui/admin (Shamir M-of-N Seal & Unseal tab) or the API:

BASH
curl -sS -X POST http://127.0.0.1:8444/api/v1/ceremonies/unseal \
  -H "Content-Type: application/json" \
  -d '{
    "shares": [
      "vca_share_2of3_1_...",
      "vca_share_2of3_2_..."
    ]
  }'

3.2 Zero-Downtime Root CA Rollover Cross-Signing

When rotating from Root Generation 1 (G1) to Root Generation 2 (G2), issue a Cross-Signed Bridge Certificate (POST /api/v1/ca/cross-sign) whose Subject and SubjectPublicKeyInfo belong to G2 while Issuer and signature belong to G1:

BASH
curl -sS -X POST http://127.0.0.1:8444/api/v1/ca/cross-sign \
  -H "Authorization: Bearer ${ADMIN_JWT}" \
  -H "Content-Type: application/json" \
  -d '{
    "new_common_name": "VCA Root X.509 Authority G2",
    "algorithm": "Ed25519"
  }'

Legacy clients trusting G1 validate chains signed by G2 seamlessly during the transition window without Simultaneous Flag-Day trust store updates.


4. Issuance Policy Profiles & ABAC Expression Governance

In /ui/admin (ABAC Policy Compiler tab), administrators define CertProfile templates governing TTL ceilings, allowed SAN wildcard patterns, MFA enforcement, cryptographic algorithms (Ed25519, ECDSA-P256, RSA-2048, RSA-4096, X25519), and fail-closed ABAC predicates:

ABAC Policy Compiler & Configured Certificate Profiles

BASH
curl -sS -X POST http://127.0.0.1:8444/api/v1/profiles \
  -H "Authorization: Bearer ${ADMIN_JWT}" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "prof-prod-bastion",
    "org_id": "org-platform",
    "max_ttl_secs": 14400,
    "require_mfa": true,
    "allowed_san_patterns": "*.prod.corp.internal",
    "abac_expression": "dept==Platform && group_in:sre"
  }'

Fail-Closed Policy Evaluation Rules

  1. Unrecognized ABAC Clauses Fail Closed: Any unknown attribute key or malformed operator immediately denies issuance (403 Forbidden).
  2. RFC 6125 Single-Label Wildcard Enforcement: A pattern of *.corp.internal matches api.corp.internal (true), but strictly rejects multi-label subdomains such as deep.api.corp.internal (false) and bare apex corp.internal (false).
  3. Cryptographic Claims Compilation: Approved principal attributes (org_id, department, groups, entitlements) are compiled directly into X.509 v3 extension OID 1.3.6.1.4.1.59999.1.1 and OpenSSH certificate extension vca-abac-claims@vca.internal so downstream proxies verify authorization offline.

5. OIDC 1.0 Federation & External PDP Integration

  1. Built-In OIDC 1.0 + PKCE (S256) & RFC 8693 STS:
    • Relying parties discover endpoints via GET /.well-known/openid-configuration and Ed25519 public keys (OKP) via GET /.well-known/jwks.json.
    • Workloads holding a valid OIDC JWT can call POST /api/v1/oidc/token with grant_type = "urn:ietf:params:oauth:grant-type:token-exchange" to obtain short-lived X.509 v3 certificates bound to their spiffe_id claim.
  2. Upstream vwarden Policy Decision Point (--vwarden-pdp):
    • Configure vwarden_pdp_url = https://vwarden.corp.internal in vca.conf (or --vwarden-pdp) so vca consults POST /access/v1/evaluate on central vwarden clusters before minting privileged production credentials.
  3. Closed-Loop vsight SIEM & SOAR (--vsight-syslog):
    • Configure vsight_syslog_addr = 10.10.0.25:6514 to stream Ed25519-signed RFC 5424 audit lines over TCP, and allow vsight to invoke POST /api/v1/soar/quarantine authenticated via constant-time X-Vsight-Signature HMAC-SHA256 headers.

6. Encrypted Authority Backups, WAL Durability & Disaster Recovery

6.1 Segmented WAL, Sparse Indexes & LZ4 Checkpoints

In default vprevail mode, vca persists mutations across 64 FNV-1a shards with {org_id} hash-tag co-location into segmented 32-byte IEEE CRC32 binary write-ahead logs (00000000000000000000.log), 24-byte .idx sparse indexes, and LZ4-compressed .snap checkpoints. On cold start or crash recovery:

  • vca loads the latest verified .snap checkpoint, replays subsequent .log frames, automatically truncates any torn trailing bytes, and rolls back any uncommitted TX_BEGIN frame lacking a matching TX_COMMIT.
  • Merkle CT leaves (ct_leaf_0..N) are deterministically rehydrated so tree hashes remain continuous across restarts.

6.2 Exporting & Restoring Lossless VCA_BACKUP_V2 Snapshots

Export a complete AES-256-GCM encrypted backup containing all CAs (with sealed private keys), users, OrgUnits, ABAC profiles, quorum ceremonies, and issued/revoked certificate records:

BASH
# Export encrypted VCA_BACKUP_V2 snapshot via CLI or REST API
./vca backup --out ./backups/vca-$(date +%F).backup.json --data-dir ./data

# Restore encrypted envelope onto a recovery node sharing the same master.kek
curl -sS -X POST http://127.0.0.1:8444/api/v1/admin/restore \
  -H "Authorization: Bearer ${ADMIN_JWT}" \
  -H "Content-Type: application/json" \
  -d '{"encrypted_envelope": "ENC[vca-v2-gcm:...]"}'

6.3 Generating Signed Compliance Dossiers & OpenMetrics

BASH
# Export signed SOC2 / ISO 27001 auditor dossier (CA counts, CT STH signature, verified audit chain)
./vca compliance --out ./backups/vca-compliance-dossier.json --data-dir ./data

# Scrape authenticated Prometheus / OpenMetrics certificate expiry horizon buckets (24h, 7d, 30d)
curl -sS http://127.0.0.1:8444/api/v1/metrics -H "Authorization: Bearer ${ADMIN_JWT}"

7. Production Deployment & Hardening Checklist

Before exposing vca in production environments, enable strict startup validation (--prod), sealed-on-boot custody (--start-sealed), and native TLS/mTLS termination:

BASH
export VCA_PROD=true
export VCA_START_SEALED=true
export VCA_SOAR_SECRET="<random-32-byte-hex>"
export VCA_MESH_SECRET="<random-32-byte-hex>"
export VCA_BOOTSTRAP_ADMIN_PASSWORD="<strong-admin-passphrase>"

./vca serve 0.0.0.0:8444 \
  --prod \
  --start-sealed \
  --max-conns 256 \
  --tls-cert /etc/vca/tls/tls.crt \
  --tls-key /etc/vca/tls/tls.key \
  --tls-client-ca /etc/vca/tls/client_ca.pem \
  --data-dir ./data

Reference deployment templates are bundled under deploy/:

  • deploy/vca.service: Hardened systemd unit (NoNewPrivileges, ProtectSystem=strict, PrivateTmp, CAP_NET_BIND_SERVICE).
  • deploy/Containerfile: Non-root (uid 10001) minimal runtime image with healthcheck.
  • deploy/k8s-deployment.yaml: Kubernetes Deployment with readinessProbe and livenessProbe targeting HTTPS /api/v1/health and Secret-backed VCA_* credentials.

vca — Operations, Production Runbooks & Use Cases

vca — Cryptographic Certificate Authority & Trust Engine

Runbook 1: Zero-Standing-Privilege (ZSP) SSH Bastion & Mesh Access

Operational Scenario

Platform engineers require on-demand interactive shell access (sre-admin) to production Linux hosts behind a vgate zero-trust bastion without leaving permanent public keys in ~/.ssh/authorized_keys or long-lived VPN credentials on laptops.

Step-by-Step Execution

  1. Configure Target Hosts Once: Distribute the vca User SSH CA public key (GET /api/v1/ssh/ca-keys) to ./certs/ssh/vca_user_ca.pub and configure ./config/ssh/sshd_config with TrustedUserCAKeys ./certs/ssh/vca_user_ca.pub and RevokedKeys ./certs/ssh/vca_revoked.krl.
  2. Authenticate with MFA: Engineer authenticates against vca (POST /api/v1/auth/login with 6-digit TOTP code) or via federated OIDC 1.0 PKCE (POST /api/v1/oidc/authorize -> POST /api/v1/oidc/token).
  3. Mint Atomic Triple-Credential Lease:
BASH
curl -sS -X POST https://pki.corp.internal/api/v1/self/mint-bundle \
  -H "Authorization: Bearer ${ENGINEER_JWT}" \
  -H "Content-Type: application/json" \
  -d '{
    "network_id": "prod-mesh",
    "requested_ttl": 3600,
    "principals": ["alice", "sre-admin"]
  }' > ./tmp/zsp_bundle.json

Atomic Triple-Credential ZSP Bundle Minting

  1. Connect & Auto-Expire: The engineer presents vnet_token to vgate, establishes mTLS using x509_certificate_pem, and connects via ssh -i ~/.ssh/id_ed25519 sre-admin@db01.corp.internal. After 3600 seconds, all three credentials expire cryptographically with zero cleanup scripts required.

Runbook 2: Service-Mesh mTLS & Private ACME v2 Automation

Operational Scenario

Edge ingress proxies (vgate, vsite) and internal microservices require automated X.509 v3 certificate provisioning and zero-downtime renewal without human intervention or private key escrow.

Option A: Stateful Private ACME v2 Workflow (RFC 8555)

BASH
# 1. Obtain fresh anti-replay nonce and register ACME client account
NONCE_JSON=$(curl -sS https://pki.corp.internal/acme/v2/new-nonce)
curl -sS -X POST https://pki.corp.internal/acme/v2/new-acct \
  -H "Content-Type: application/json" \
  -d '{"contact": "mailto:platform-ops@corp.internal"}'

# 2. Submit certificate order (unauthenticated orders start in "pending" state)
ORDER_JSON=$(curl -sS -X POST https://pki.corp.internal/acme/v2/new-order \
  -H "Content-Type: application/json" \
  -d '{"domains": ["ingress01.corp.internal"]}')

# 3. Validate domain ownership challenge (transitions order to "ready")
curl -sS -X POST https://pki.corp.internal/acme/v2/chall \
  -H "Content-Type: application/json" \
  -d '{"order_id": "ord_...", "challenge_token": "chall_..."}'

# 4. Finalize with local PKCS#10 CSR (CN must match ordered domain) & fetch PEM chain
FINAL_JSON=$(curl -sS -X POST https://pki.corp.internal/acme/v2/finalize \
  -H "Content-Type: application/json" \
  -d '{"order_id": "ord_...", "csr_pem": "-----BEGIN CERTIFICATE REQUEST-----\n..."}')

curl -sS "https://pki.corp.internal/acme/v2/cert?cert_id=xcert_..." -o ../vgate/certs/fullchain.pem

Option B: Workload Bootstrap via Scoped Enrollment Token (vca_pat_*)

For headless sidecars that cannot answer external HTTP challenges, mint a SAN-locked reusable machine PAT (max_uses: 50) restricted to *.mesh.corp.internal and invoke POST /api/v1/self/x509-sign on startup and POST /api/v1/self/renew at 70% of TTL.


Runbook 3: Certificate Transparency Auditing & Supply-Chain Notarization

Operational Scenario

Security auditors and CI/CD release pipelines (vstore, vllm, vvm, vkbm) require mathematical proof that every signing certificate is recorded in an append-only Merkle tree and that release artifacts were signed while the ephemeral certificate was valid.

Step-by-Step Execution

BASH
# 1. CI runner exchanges OIDC workload JWT for a 10-minute keyless signing certificate + SCT
curl -sS -X POST https://pki.corp.internal/api/v1/self/keyless-sign \
  -H "Authorization: Bearer ${CI_OIDC_JWT}" > keyless_cert.json

# 2. Stamp the compiled release binary SHA-256 with an RFC 3161 TSTInfo Timestamp Token
./vca tsa sign \
  --file release/app-linux-x64.tar.gz \
  --nonce 20261114cafe \
  --out release/app-linux-x64.tsr.pem \
  --data-dir ./data

# 3. Downstream consumers verify the RFC 3161 Timestamp Token offline/online
./vca tsa verify \
  --token release/app-linux-x64.tsr.pem \
  --file release/app-linux-x64.tar.gz \
  --data-dir ./data

# 4. Auditors verify the Ed25519 Signed Tree Head (STH) and O(log N) Merkle inclusion proof
curl -sS https://pki.corp.internal/api/v1/ct/v1/get-sth
curl -sS "https://pki.corp.internal/api/v1/ct/v1/get-proof-by-index?index=0"

Merkle CT Log Signed Tree Head & Inclusion Proof Verification


Runbook 4: Incident Containment, SOAR Quarantine & Emergency Sealing

Operational Scenario

vsight Endpoint Detection & Response (EDR) detects anomalous lateral movement originating from principal usr-alice, or operators detect an active intrusion targeting a regional PKI node.

Step-by-Step Containment

  1. Automated Closed-Loop Principal Quarantine (POST /api/v1/soar/quarantine):

vsight dispatches an HMAC-SHA256 authenticated webhook (X-Vsight-Signature) or an administrator triggers quarantine from /ui/admin (vsight SOAR & RFC 5424 Audit tab):

BASH
curl -sS -X POST https://pki.corp.internal/api/v1/soar/quarantine \
  -H "Authorization: Bearer ${ADMIN_JWT}" \
  -H "Content-Type: application/json" \
  -d '{
    "target_user_id": "usr-alice",
    "reason": "vsight_edr_compromise_containment"
  }'

vca atomically revokes every active X.509 v3 and OpenSSH credential issued to usr-alice, updates live OCSP/CRL/SSHKRL responders, appends an Ed25519-signed SHA-256 hash-chained audit event, and emits an RFC 5424 syslog alert.

  1. Propagate Revocation Lists Immediately:

Edge gateways refresh GET /api/v1/x509/crl?format=pem and SSH bastions refresh GET /api/v1/ssh/krl?format=raw.

  1. Verify Audit Ledger Integrity:
BASH
curl -sS https://pki.corp.internal/api/v1/audit \
  -H "Authorization: Bearer ${ADMIN_JWT}"

Confirm "chain_integrity_verified": true across all rolling SHA-256 event hashes and Ed25519 non-repudiation signatures.

  1. Emergency Host Seal (If Authority Host Is Threatened):

Invoke POST /api/v1/ca/seal to zero master.kek and all cached CA signing keys in RAM immediately until incident responders complete forensic verification and conduct a 2-of-3 Shamir unseal ceremony.

vca — Configuration, CLI & REST API Reference

vca — Cryptographic Certificate Authority & Trust Engine

1. CLI Subcommand & Flag Reference

Invoke vca (vca.exe on Windows, ./vca on Linux and macOS) with any of the server, governance, or workload subcommands below.

1.1 Server, Governance & Diagnostic Subcommands

Subcommand Arguments & Flags Description
serve / start [listen_addr] --config <file> --addr <host:port> --issuer <url> --data-dir <dir> --mode <backend> --vprevail-addr <host:port> --sqlite-path <file> --vsight-syslog <host:port> --vwarden-pdp <url> Starts the concurrent HTTP/1.1 OpenAPI 3.1 Control Plane and 4-Workspace PKI Studio (default 127.0.0.1:8444).
openapi [issuer_url] --issuer <url> Outputs the complete OpenAPI 3.1.0 JSON specification to standard output.
discovery [issuer_url] --issuer <url> Outputs authority OIDC, ACME v2, and CT log discovery metadata JSON.
init-store [vprevail|vprevail_cluster|sqlite] Verifies authority store initialization in the selected storage backend.
verify-id <identifier> Validates a resource identifier against [a-zA-Z0-9._:-]{1,96} and traversal rules.
audit (none) Executes static cyclomatic complexity and security rule verification.
version -v, --version Prints semantic version (0.1.0) and supported capability summary.
help -h, --help Prints full CLI subcommand and flag usage summary.

1.2 PKI, OpenSSH, Timestamp & Operator Subcommands

Subcommand Supported Flags Output & Behavior
ca init-intermediate --cn <name> --ca-id <id> --domains <csv> --alg <Ed25519|ECDSA-P256|RSA-2048|RSA-4096> --out-chain <file> --data-dir <dir> Provisions an RFC 5280 NameConstraints-scoped Intermediate X.509 v3 CA signed by ca-root-x509, persists sealed keys, writes Intermediate + Root PEM to --out-chain, and prints JSON summary.
cert issue-x509 --cn <cn> --san <csv> --alg <alg> --ttl <secs> --ca-id <id> --user <uid> --out-cert <file> --out-key <file> --data-dir <dir> Generates a keypair, signs an X.509 v3 leaf certificate with embedded Merkle CT SCT, writes the 3-tier PEM chain (Leaf + Intermediate + Root) to --out-cert and PKCS#8 private key to --out-key.
ssh sign --pubkey <file_or_line> --principal <csv> --type <user|host> --ttl <secs> --user <uid> --out <file> --data-dir <dir> Zero-escrow signs an OpenSSH .pub key (ssh-ed25519, ssh-rsa, ecdsa-sha2-nistp256) into a User (type = 1) or Host (type = 2) certificate.
tsa sign --file <path_or_sha256_hex> --nonce <hex> --user <uid> --out <file> --data-dir <dir> Signs an RFC 3161 ASN.1 DER TSTInfo Timestamp Token (-----BEGIN TIMESTAMP TOKEN-----) over a file or 64-character SHA-256 hex digest.
tsa verify --token <path_or_pem> --file <path_or_sha256_hex> --data-dir <dir> Verifies Timestamp Token signature and constant-time SHA-256 messageImprint match.
inspect <file_or_inline> --file <path> --data-dir <dir> Decodes X.509 PEM, PKCS#10 CSR, Timestamp Token, or OpenSSH *-cert-v01@openssh.com wire byte trees into offset/length JSON.
token mint --profile <id> --sans <csv> --max-uses <N> --ttl <secs> --user <uid> --data-dir <dir> Mints a single-use bootstrap token (vca_enroll_*, --max-uses 1) or reusable service PAT (vca_pat_*, --max-uses > 1).
crl --out <file> --data-dir <dir> Exports a freshly signed RFC 5280 X.509 CRL v2 PEM file (-----BEGIN X509 CRL-----).
krl --out <file> --data-dir <dir> Exports the current OpenSSH Key Revocation List (SSHKRL).
backup --out <file> --data-dir <dir> Exports a lossless NIST AES-256-GCM encrypted VCA_BACKUP_V2 authority snapshot.
compliance --out <file> --data-dir <dir> Exports a signed SOC2 / ISO 27001 compliance dossier JSON.

2. Configuration File (vca.conf) & Environment Variables

vca resolves configuration in strict precedence order (highest to lowest): CLI Flags -> VCA_* Environment Variables -> --config <vca.conf> (VCA_CONFIG) -> Built-in Defaults.

vca.conf Key Environment Variable CLI Flag Default Value Description
listen_addr VCA_LISTEN_ADDR --addr 127.0.0.1:8444 HTTP/1.1 TCP bind address and port.
issuer_url VCA_ISSUER_URL --issuer http://127.0.0.1:8444 Public canonical URL embedded in OIDC discovery, ACME v2 directory, AIA, and CRL DP.
data_dir VCA_DATA_DIR --data-dir data/vca Directory storing master.kek, segmented .log/.idx WAL files, and .snap checkpoints.
storage_mode VCA_STORAGE_MODE --mode vprevail Persistence backend: vprevail (embedded 64-shard MVCC WAL), vprevail_cluster, vprevail_http, or sqlite.
vprevail_addr VCA_VPREVAIL_ADDR --vprevail-addr 127.0.0.1:7654 Upstream vprevail cluster TCP (VPRV binary RPC) or HTTP endpoint.
sqlite_path VCA_SQLITE_PATH --sqlite-path data/vca/vca.sqlite SQLite database file path when storage_mode = sqlite.
vsight_syslog_addr VCA_VSIGHT_SYSLOG_ADDR --vsight-syslog (disabled) Optional host:port for streaming live TCP RFC 5424 signed SIEM syslog events to vsight.
vwarden_pdp_url VCA_VWARDEN_PDP_URL --vwarden-pdp (disabled) Optional upstream vwarden PDP base URL (POST /access/v1/evaluate).
tls_cert VCA_TLS_CERT --tls-cert (disabled) Path to PEM server certificate chain enabling native HTTPS on vca serve.
tls_key VCA_TLS_KEY --tls-key (disabled) Path to PEM PKCS#8 private key paired with tls_cert.
tls_client_ca VCA_TLS_CLIENT_CA --tls-client-ca (disabled) Path to PEM CA bundle enabling mandatory mutual TLS (mTLS) client certificate verification.
tls_auto VCA_TLS_AUTO --tls-auto false Auto-provisions an ephemeral in-memory ECDSA-P256 CA and server TLS certificate for vca serve.
prod_mode VCA_PROD --prod false Enables strict production startup guard: requires TLS, non-default shared secrets & bootstrap password, CSPRNG TOTP secret, and 100,000 PBKDF2 iterations.
start_sealed VCA_START_SEALED --start-sealed false Boots the authority sealed in RAM (is_sealed = true), awaiting M-of-N Shamir shares via /api/v1/ceremonies/unseal.
max_conns VCA_MAX_CONNS --max-conns 256 Bounded concurrent TCP/TLS connection ceiling; excess connections receive 503 Service Unavailable.
soar_secret VCA_SOAR_SECRET --soar-secret (dev default) Shared HMAC-SHA256 secret authenticating vsight SOAR containment requests (>= 16 chars in --prod).
mesh_secret VCA_MESH_SECRET --mesh-secret (dev default) Shared HMAC-SHA256 secret signing vgate vnet_tok_ mesh leases (>= 16 chars in --prod).
bootstrap_admin_password VCA_BOOTSTRAP_ADMIN_PASSWORD --bootstrap-password (dev default) Initial administrator bootstrap password (>= 12 chars in --prod); PBKDF2 work factor tunable via VCA_PBKDF2_ITERS.

Example vca.conf

INI
# Production Authority Configuration
listen_addr        = 0.0.0.0:8444
issuer_url         = https://pki.corp.internal
data_dir           = ./data
storage_mode       = vprevail
vsight_syslog_addr = 10.20.0.50:6514
vwarden_pdp_url    = https://id.corp.internal

3. Policy Profile & Credential Bundle JSON Schemas

3.1 ABAC Issuance Profile Schema (POST /api/v1/profiles)

JSON
{
  "profile_id": "prof-edge-mtls",
  "org_id": "org-platform",
  "ca_id": "ca-int-edge",
  "cert_kind": "x509_leaf",
  "display_name": "Edge Gateway mTLS Profile",
  "max_ttl_secs": 86400,
  "require_mfa": true,
  "allowed_san_patterns": "*.corp.internal,*.edge.corp.internal",
  "ssh_extensions_csv": "permit-pty,permit-port-forwarding",
  "abac_expression": "dept==Platform && group_in:sre"
}

3.2 Atomic Triple-Credential ZSP Response (POST /api/v1/self/mint-bundle)

JSON
{
  "bundle_id": "zsp_8d21a94f301e",
  "x509_cert_id": "xcert_94f1c20b88a1",
  "x509_serial_hex": "3ea9104bc2",
  "x509_sct_leaf_hash": "d56833378df9c6ef25cd9cb1139d7671bdeba1e153dc39d2ea5a1acb80bae4f5",
  "x509_certificate_pem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  "ssh_cert_id": "scert_41b09e77c120",
  "ssh_authorized_cert": "ssh-ed25519-cert-v01@openssh.com AAAAHHNzaC1lZDI1NTE5LWNlcnQtdjAxQG9wZW5zc2guY29t... alice@default",
  "vnet_token": "vnet_tok_1763097600_prod-mesh_usr-alice_9f82c140e71a9b024d18c7a3e60b1124",
  "spiffe_uri": "spiffe://corp.internal/ns/platform/sa/alice",
  "expires_at": 1763097600
}

4. OpenAPI 3.1.0 REST Endpoint Reference

Method Endpoint Path Auth / Role Guard Purpose
GET /api/v1/health Public Liveness, is_sealed state, active storage backend, and ct_tree_size.
GET /api/v1/metrics Admin / Delegated Prometheus / OpenMetrics counters and 24h / 7d / 30d certificate expiry buckets.
GET /api/v1/openapi.json Public Complete machine-readable OpenAPI 3.1.0 specification.
GET /.well-known/openid-configuration Public OpenID Connect 1.0 Discovery document.
GET /.well-known/jwks.json Public RFC 8037 Ed25519 (OKP) JSON Web Key Set.
POST /api/v1/auth/login Public (Rate-Limited) Verifies PBKDF2 password + TOTP MFA and mints EdDSA session JWT.
POST /api/v1/oidc/authorize Bearer / Credentials Issues single-use OIDC Authorization Code bound to S256 PKCE challenge.
POST /api/v1/oidc/token PKCE / RFC 8693 STS Exchanges PKCE code + verifier for JWTs, or exchanges OIDC JWT for Fulcio X.509 cert.
POST /api/v1/tokens/enroll Global / Delegated Admin Mints SAN-locked vca_enroll_* (one-time) or vca_pat_* (reusable) machine tokens.
GET /api/v1/self/profile Interactive Bearer Returns caller identity, RBAC role, org_id, spiffe_id, and ISO 18004 TOTP QR SVG.
POST /api/v1/self/mint-bundle Bearer / Enroll Token Atomically mints X.509 v3 mTLS + OpenSSH User cert + vnet_tok_ mesh bundle.
POST /api/v1/self/x509-sign Bearer / Enroll Token Zero-escrow PKCS#10 CSR sanitizer & signer returning 3-tier certificate_chain_pem.
POST /api/v1/self/ssh-sign Bearer / Enroll Token Zero-escrow OpenSSH .pub key signer (user or host certificate).
POST /api/v1/self/renew Bearer Re-signs an active certificate with a new serial number and validity window.
POST /api/v1/self/keyless-sign Interactive Bearer Mints 10-minute Fulcio-style code-signing X.509 v3 certificate + Merkle SCT.
POST /api/v1/inspect Public / Bearer Decodes ASN.1 DER TLV or OpenSSH PROTOCOL.certkeys wire byte offsets.
GET /api/v1/ca Interactive Bearer Lists Root X.509, Intermediate X.509, OpenSSH User, and OpenSSH Host authorities.
GET /api/v1/ca/roots Public Exports Root & Intermediate X.509 CA PEM trust bundle.
POST /api/v1/ca/intermediate Global Admin Provisions a NameConstraints-scoped Intermediate X.509 v3 CA.
POST /api/v1/ca/seal Global Admin Zeros master.kek and unsealed CA keys in RAM immediately (is_sealed = true).
POST /api/v1/ca/cross-sign Global Admin Issues a cross-signed Root CA rollover bridge certificate (G1 -> G2).
GET/POST /api/v1/ceremonies Global Admin Lists or advances durable M-of-N Shamir quorum ceremonies.
POST /api/v1/ceremonies/unseal M-of-N Shamir Shares Reconstructs master.kek over GF(2^8) and unseals the authority in RAM.
GET /api/v1/certificates Interactive Bearer Lists certificates scoped to caller ownership, org_id, or global view.
POST /api/v1/certificates/revoke Owner / Org / Global Admin Revokes a certificate with an RFC 5280 reason code.
GET /api/v1/x509/crl Public (?format=pem) Signs and serves RFC 5280 X.509 CRL v2 (JSON or application/pkix-crl PEM).
POST /api/v1/x509/ocsp Public Signs and returns RFC 6960 OCSP status (good, revoked, or unknown).
GET /api/v1/ssh/krl Public (?format=raw) Serves OpenSSH Key Revocation List (JSON or binary SSHKRL\n\0 stream).
GET /api/v1/ssh/ca-keys Public Exports OpenSSH TrustedUserCAKeys and @cert-authority lines.
GET /api/v1/ssh/allowed-signers Public Exports OpenSSH allowed_signers trust bundle for artifact signature verification.
POST /api/v1/tsa/timestamp Interactive Bearer Signs an RFC 3161 ASN.1 DER TSTInfo Timestamp Token.
POST /api/v1/tsa/verify Public Verifies an RFC 3161 Timestamp Token against an artifact SHA-256 hex digest.
GET/POST /api/v1/profiles Global / Delegated Admin Lists or creates ABAC certificate profiles within caller scope.
GET/POST /api/v1/users Global / Delegated Admin Lists or provisions principals within caller scope.
GET /api/v1/ct/v1/get-sth Public Signs and returns the RFC 6962 Merkle Signed Tree Head (STH).
GET /api/v1/ct/v1/get-proof-by-index Public Computes and verifies the O(log N) Merkle inclusion proof for ?index=N.
POST /api/v1/soar/quarantine Vsight-HMAC / Global Admin Atomically revokes all credentials of a compromised principal and emits RFC 5424 syslog.
GET /api/v1/audit Global / Delegated Admin Verifies SHA-256 hash-chain and Ed25519 signature integrity across audit logs.
GET/POST /api/v1/admin/backup, /restore, /compliance-bundle Global Admin Exports/restores encrypted VCA_BACKUP_V2 snapshots and signed SOC2 dossiers.
GET/POST /acme/v2/directory, /new-nonce, /new-acct, /new-order, /chall, /finalize, /cert Public / Enroll Token Stateful RFC 8555 Private ACME v2 automated TLS provisioning endpoints.
GET /.well-known/est/cacerts, /.well-known/est/csrattrs Public RFC 7030 EST base64 PKCS#7 certs-only CA bundle and ASN.1 DER CsrAttrs discovery.
POST /.well-known/est/simpleenroll, /.well-known/est/simplereenroll HTTP Basic / Bearer / Enroll Token RFC 7030 EST zero-escrow PKCS#10 CSR device enrollment and automated re-enrollment returning PKCS#7 certs-only.
GET/POST /scep?operation=GetCACaps|GetCACert|PKIOperation Public (GET) / Auth (POST) RFC 8894 SCEP device discovery and DER PKCS#7 CertRep automated certificate issuance.

vca — Performance, Cryptographic Throughput & Sizing Guide

vca — Cryptographic Certificate Authority & Trust Engine

1. Performance Architecture Principles

Short-lived zero-trust credentials (10-minute keyless signing certificates, 1-hour Triple-Credential ZSP bundles, and 4-hour service-mesh mTLS leaves) increase certificate issuance velocity by 100x compared to legacy 1-year PKI deployments. vca sustains high-throughput signing with sub-millisecond read paths through five architectural optimizations:

  1. Native Compiled Execution & Bounded Buffers: Compiles directly to native x86_64/ARM64 machine code with zero external TLS/ASN.1 shared-library marshaling overhead and strict HTTP/1.1 connection caps (10s socket timeouts, 32 KiB header cap, 4 MiB body cap).
  2. Zero-Allocation Definite-Length ASN.1 DER Codec: Encodes canonical ITU-T X.690 DER TBSCertificate, CertificateList, OCSPResponse, and RFC 3161 TSTInfo byte buffers in deterministic linear passes capped at 256 KiB and nesting depth 16.
  3. Accelerated Elliptic-Curve & RSA-CRT Signing:
    • Ed25519 (RFC 8032 / RFC 8410) executes deterministic signature generation in tens of microseconds and is recommended as the primary high-velocity algorithm for Root/Intermediate X.509 CAs, OpenSSH User/Host CAs, Merkle CT STH signatures, and OIDC JWTs.
    • ECDSA NIST P-256 (secp256r1) uses a constant-time 256-step Jacobian Montgomery ladder (Z-projective coordinates avoiding per-step modular inversions) paired with RFC 6979 deterministic HMAC-SHA256 nonces.
    • RSA-2048 / RSA-4096 (RFC 8017) uses 9-integer Chinese Remainder Theorem (RSA-CRT) private-key acceleration with cryptographic blinding and Bellcore fault-injection verification before emitting signatures.
  4. Immutable Power-of-Two Merkle Subtree Cache: Complete binary subtrees in the RFC 6962 Certificate Transparency log are cached immutably on append, reducing both Signed Tree Head (STH) root computation and inclusion proof generation from $O(N)$ to $O(\log_2 N)$ SHA-256 hashes.
  5. 64-Shard MVCC Store + Segmented LZ4 WAL: Hot queries (OCSP, JWKS, get-sth, get-proof-by-index, profile lookups) execute in memory across 64 FNV-1a shards with {org_id} shard affinity, while mutations append 32-byte IEEE CRC32 binary WAL frames with LZ4-compressed .snap checkpoints.

2. Cryptographic Signing, DER & Issuance Benchmarks

Representative single-node production (-prod) measurements on an 8-vCPU / 16 GiB x86_64 server (vprevail 64-shard MVCC + NVMe WAL):

Subsystem / Operation Cryptographic / Codec Work Median Latency (p50) Tail Latency (p99) Sustained Single-Node Throughput
ASN.1 DER TBSCertificate Encode + Parse Definite-length TLV build + RDN sort + bounds check 0.04 ms 0.11 ms > 85,000 ops/s
X.509 v3 Leaf Issuance (Ed25519 + Merkle SCT) CSR PoP verify + DER build + Ed25519 sign + CT append + WAL 0.42 ms 1.15 ms ~ 7,800 certs/s
X.509 v3 Leaf Issuance (ECDSA-P256 + Merkle SCT) CSR PoP verify + Jacobian P-256 sign + CT append + WAL 1.35 ms 3.10 ms ~ 2,400 certs/s
X.509 v3 Leaf Issuance (RSA-2048 CRT + Merkle SCT) CSR PoP verify + Blinded RSA-CRT + Bellcore verify + WAL 2.80 ms 6.40 ms ~ 1,150 certs/s
OpenSSH User/Host Cert Sign (Ed25519) PROTOCOL.certkeys pack + option sort + Ed25519 sign + WAL 0.28 ms 0.79 ms > 11,200 certs/s
Triple-Credential ZSP Bundle (POST /api/v1/self/mint-bundle) ABAC eval + X.509 Ed25519 + SSH Ed25519 + vnet_tok_ + CT + WAL 0.86 ms 2.25 ms ~ 3,900 bundles/s
RFC 3161 Timestamp Token (POST /api/v1/tsa/timestamp) DER TSTInfo encode + Ed25519 sign 0.21 ms 0.58 ms > 15,000 tokens/s
RFC 6960 Live OCSP Responder (POST /api/v1/x509/ocsp) Serial index lookup + DER OCSP sign 0.19 ms 0.54 ms > 16,500 req/s
Merkle CT STH & Inclusion Proof (N = 100,000 leaves) Cached $O(\log_2 N)$ SHA-256 path (17 hashes) + Ed25519 STH 0.15 ms 0.45 ms > 21,000 proofs/s
Interactive Password Login (PBKDF2-HMAC-SHA256) 10,000-round salted PBKDF2 + TOTP + EdDSA JWT mint 4.20 ms 8.90 ms ~ 850 logins/s (rate-limited per account)

3. Merkle CT Tree Scaling & WAL Recovery Metrics

Corpus Scale (Issued Certificates & CT Leaves) On-Disk LZ4 .snap Size Active RAM Footprint Cold-Start Snapshot + WAL Recovery Time Merkle Inclusion Proof Depth ($\lceil \log_2 N \rceil$)
10,000 credentials ~ 3.8 MiB ~ 28 MiB ~ 18 ms 14 SHA-256 sibling nodes (448 B)
100,000 credentials ~ 36 MiB ~ 195 MiB ~ 145 ms 17 SHA-256 sibling nodes (544 B)
1,000,000 credentials ~ 350 MiB ~ 1.65 GiB ~ 1.35 s 20 SHA-256 sibling nodes (640 B)

4. Production Sizing & Algorithm Selection Guidelines

  1. Default to Ed25519 for Internal mTLS, SSH, and ZSP Leases:

Ed25519 produces compact 64-byte signatures and 32-byte public keys, runs over 3x faster than ECDSA-P256 and 6x faster than RSA-2048, and is natively supported by TLS 1.3 stacks, Go/Rust/V services, and OpenSSH 6.5+.

  1. Use ECDSA-P256 Intermediate CAs for Browser & LegacyFIPS TLS Gateways:

Provision a dedicated ECDSA-P256 Scoped Intermediate CA (--alg ECDSA-P256) when issuing certificates consumed by legacy Java, Windows SChannel, or browser clients that expect ecdsa-with-SHA256.

  1. Place --data-dir on Local NVMe SSDs:

Segmented .log WAL appends (64 MiB segment rotation) and atomic .snap checkpoints achieve lowest p99 tail latency on local NVMe storage. For multi-node high availability, run --mode vprevail_cluster against a replicated vprevail quorum.

  1. Automate CRL / SSHKRL Edge Caching:

Edge load balancers and SSH bastions should poll GET /api/v1/x509/crl?format=pem and GET /api/v1/ssh/krl?format=raw every 60–300 seconds, reserving synchronous POST /api/v1/x509/ocsp queries for high-value administrative endpoints.

vca — Consolidated End-User, Administrator & Operations Handbook

vca — Zero-Trust Private PKI & SSH Certificate Authority


Part I: vca — Unified Zero-Trust X.509 v3 PKI & OpenSSH Certificate Authority

Overview

vca is a self-contained, zero-external-dependency Private Public Key Infrastructure (PKI), X.509 v3 Certificate Authority, OpenSSH User & Host Certificate Authority, RFC 6962 Merkle Certificate Transparency (CT) Log, RFC 3161 Timestamp Authority (TSA), Private ACME v2 Server, and OIDC 1.0 Workload Identity Minter. Distributed as a single native executable for Windows, Linux, and macOS, vca unifies short-lived TLS/mTLS workload certificates, zero-standing-privilege SSH access, keyless code signing, and cryptographic auditability under one policy plane.

AUTHORITY TOPOLOGY

vca End-to-End Zero-Trust X.509 v3 PKI, OpenSSH CA, OIDC Federation & Merkle CT Architecture

Click any component node to inspect how vca evaluates workload identity, signs certificates, and appends transparency proofs.

Interactive SVG • Click any node (6 components)
1. WORKLOADS & OPERATORS CLI / ACME v2 / OIDC / Web Studio 2. POLICY & SIGNING AUTHORITY CORE ABAC + X.509 v3 DER + OpenSSH CA 3. TRANSPARENCY & SEALED VAULT RFC 6962 Merkle CT + Sharded MVCC CSR / OIDC MFA / ZSP X.509 Policy SSH Policy CT + WAL CT + KRL Relying Clients Workloads & CI Runners CSR, SSH PubKey, ACME & OIDC Principals Operators & End Users 4-Workspace PKI Web Studio Policy Engine OIDC & ABAC Policy Gate S256 PKCE + Option P3 Compiler PKI Engine X.509 v3 DER Authority Root / Scoped Int / OCSP / CRL SSH Engine OpenSSH Cert Authority User/Host Certs + Binary SSHKRL Transparency & State Merkle CT & Sealed Vault RFC 6962 STH + AES-256-GCM WAL
Components:
Relying Clients
Workloads & CI Runners
Zero-Escrow Enrollment ACME v2
Component 1 of 6
Architectural Role & Purpose

Services, TLS ingress proxies, SSH bastions, and CI pipelines requesting short-lived cryptographic identities.

Contextual Description & System Interaction

Guarantees zero private-key escrow on standard enrollment flows while eliminating long-lived static secrets.

Core Functionality & Security Mechanics
  • Generates private keys locally and submits signed PKCS#10 CSRs or OpenSSH public keys
  • Automates zero-touch TLS certificate renewal over Private ACME v2 directory flows
  • Exchanges OIDC S256 PKCE or workload tokens for keyless 10-minute signing certificates
Principals
Operators & End Users
Role-Separated Web Studio CLI
Component 2 of 6
Architectural Role & Purpose

Developers minting ZSP bundles and administrators governing CA hierarchies, Shamir ceremonies, and ABAC profiles.

Contextual Description & System Interaction

Separates self-service credential workflows (/ui/portal) from scoped (/ui/delegated) and global (/ui/admin) governance.

Core Functionality & Security Mechanics
  • Enrolls RFC 6238 TOTP MFA via offline ISO 18004 SVG QR codes
  • Mints atomic Triple-Credential ZSP bundles (X.509 mTLS + OpenSSH User Cert + Mesh Token)
  • Executes Shamir M-of-N unseal ceremonies, cross-signing rollovers, and wire inspections
Policy Engine
OIDC & ABAC Policy Gate
OIDC Verifier Option P3 ABAC Engine
Component 3 of 6
Architectural Role & Purpose

Authenticates principals and compiles conjunctive ABAC profile constraints prior to any signing operation.

Contextual Description & System Interaction

Acts as a fail-closed zero-trust gate preventing unauthorized SANs, privilege escalation, or excessive TTLs.

Core Functionality & Security Mechanics
  • Verifies EdDSA JWT signatures, S256 PKCE challenges, step-up MFA claims, and vca_enroll_ tokens
  • Enforces allowed SAN wildcard patterns, permitted DNS subtrees, and SSH principal whitelists
  • Clamps requested certificate lifetimes strictly to the matched profile max_ttl_seconds ceiling
PKI Engine
X.509 v3 DER Authority
ITU-T X.690 DER Multi-Tier X.509 v3
Component 4 of 6
Architectural Role & Purpose

Constructs, validates, and signs canonical X.509 v3 certificates, RFC 5280 CRLs, OCSP responses, and TSA tokens.

Contextual Description & System Interaction

Implements definite-length ASN.1 DER encoding and decoding natively with zero external crypto library dependencies.

Core Functionality & Security Mechanics
  • Supports Ed25519, Jacobian ECDSA-P256, blinded RSA-2048/3072/4096, and X25519 key agreement
  • Enforces critical BasicConstraints (pathLenConstraint) and Intermediate NameConstraints subtrees
  • Strips untrusted PKCS#10 CSR extensions and serves live CRL v2 and OCSP revocation status
SSH Engine
OpenSSH Cert Authority
OpenSSH Wire Codec SSHKRL Engine
Component 5 of 6
Architectural Role & Purpose

Signs short-lived OpenSSH user and host certificates, binary SSHKRL lists, and Git/artifact allowed_signers.

Contextual Description & System Interaction

Replaces static ~/.ssh/authorized_keys files and TOFU host prompts with short-lived cryptographic certificates.

Core Functionality & Security Mechanics
  • Issues ssh-ed25519-cert-v01, ecdsa-sha2-nistp256-cert-v01, and rsa-sha2-256/512-cert-v01
  • Sorts critical_options (source-address, force-command) and extensions lexicographically
  • Generates raw SSHKRL binary revocation artifacts for sshd RevokedKeys enforcement
Transparency & State
Merkle CT & Sealed Vault
RFC 6962 CT Log Sharded MVCC Vault
Component 6 of 6
Architectural Role & Purpose

Seals CA keys in AES-256-GCM envelopes, records Merkle CT proofs, and persists sharded MVCC + CRC32 WAL state.

Contextual Description & System Interaction

Provides cryptographic non-repudiation for every issued credential and tamper-evident authority durability.

Core Functionality & Security Mechanics
  • Protects Master KEK with GF(2^8) Shamir M-of-N shares and instant RAM zeroization on seal
  • Appends every issued certificate to the RFC 6962 Merkle tree with O(log N) inclusion proofs
  • Persists Ed25519-signed hash-chained RFC 5424 audit logs across MVCC WAL, cluster, or SQLite

Core Capabilities

Audience Capability Operational Value
Developers & Engineers Zero-Standing-Privilege SSH & mTLS (/ui/portal) Sign client-generated PKCS#10 CSRs and ~/.ssh/id_*.pub keys without private key escrow, mint atomic Triple-Credential ZSP bundles (X.509 v3 + OpenSSH + vnet_tok_), and obtain 10-minute Fulcio-style keyless OIDC code-signing certificates.
Workload & Mesh Operators Automated ACME v2, SPIFFE & Enrollment Tokens Automate TLS and service-mesh certificate lifecycle via stateful RFC 8555 Private ACME v2 (/acme/v2/directory), RFC 8693 OAuth 2.0 Token Exchange, and SAN-scoped machine bootstrap tokens (vca_enroll_* and vca_pat_*).
Delegated Org Operators Scoped Organizational Unit Governance (/ui/delegated) Manage principals, scoped issuance profiles, enrollment tokens, and immediate certificate revocations strictly within assigned Organizational Unit boundaries (org_id).
PKI Administrators Multi-Tier CA Hierarchy, Shamir Quorum & Rollover (/ui/admin) Govern Root CAs, RFC 5280 NameConstraints-scoped Intermediate CAs, and OpenSSH User/Host CAs protected by NIST SP 800-38D AES-256-GCM sealing, GF(2^8) M-of-N Shamir threshold ceremonies, and zero-downtime Root CA cross-signing.
Security & Compliance Teams Merkle CT Log, Live CRL/OCSP/SSHKRL & SOAR Verify O(log N) RFC 6962 Merkle inclusion proofs and Ed25519 Signed Tree Heads (STH), query live CRL v2 / RFC 6960 OCSP / binary SSHKRL, trigger closed-loop vsight SOAR containment, and export signed SOC2 / ISO 27001 compliance dossiers.

Live PKI Studio Preview

Identity & TOTP Authentication Gate (/ui/auth)

vca Identity & TOTP Authentication Gate

Self-Service Credentials, ISO 18004 MFA Pairing & Inventory (/ui/portal)

vca Self-Service Principal Profile, ISO 18004 TOTP QR & Issued Credentials


End-User Documentation Suite

  1. Overview & Readme — Product overview, zero-trust PKI capabilities, Web Studio preview, and quickstart commands.
  2. How-To Guide — Step-by-step recipes for offline Root + online Intermediate CA hierarchies, mTLS issuance, OpenSSH host/user signing, CT inclusion proof verification, and CRL/OCSP/SSHKRL revocation.
  3. End-User Guide — Developer and workload workflows, Web Studio navigation, zero-escrow CSR submission, SSH certificate login, and ASN.1 DER / SSH wire inspection.
  4. Administrator Guide — PKI hierarchy governance, Shamir M-of-N key ceremonies, zero-downtime Root rollover, ABAC issuance profiles, OIDC federation rules, encrypted backups, and WAL recovery.
  5. Operations & Use Cases — Production runbooks for zero-standing-privilege SSH bastions, service-mesh mTLS automation, CT log auditing, and incident SOAR revocation.
  6. Configuration & CLI Reference — Complete CLI subcommand and flag catalog, vca.conf and environment variables, policy JSON schemas, and OpenAPI 3.1 REST endpoints.
  7. Performance & Capacity Guide — Cryptographic signing throughput across Ed25519/ECDSA-P256/RSA, ASN.1 DER latency, Merkle CT append/proof latency, and WAL recovery metrics.
  8. Master User Handbook — Single-volume consolidated compendium combining all End-User, How-To, Administrator, Operations, CLI, and Performance guides.

Quickstart

Run vca using the prebuilt native binary for your platform (vca.exe on Windows or ./vca on Linux and macOS):

BASH
# Display semantic version and cryptographic engine summary
./vca version

# Start the HTTP/1.1 OpenAPI Control Plane & 4-Workspace PKI Studio
./vca serve 127.0.0.1:8444 --data-dir data/vca --issuer http://127.0.0.1:8444

# Provision a NameConstraints-scoped Intermediate X.509 v3 CA
./vca ca init-intermediate \
  --cn "VCA Edge TLS Intermediate Authority" \
  --ca-id ca-int-edge \
  --domains ".corp.internal" \
  --out-chain edge_ca_chain.pem \
  --data-dir data/vca

# Issue a 3-tier X.509 v3 workload certificate chain (Leaf + Intermediate + Root)
./vca cert issue-x509 \
  --cn gateway.corp.internal \
  --san "gateway.corp.internal,api.corp.internal" \
  --ca-id ca-int-edge \
  --out-cert gateway_fullchain.pem \
  --out-key gateway.key \
  --data-dir data/vca

# Sign a short-lived OpenSSH user certificate without private key escrow
./vca ssh sign \
  --pubkey ~/.ssh/id_ed25519.pub \
  --principal "alice,sre-admin" \
  --type user \
  --ttl 28800 \
  --out ~/.ssh/id_ed25519-cert.pub \
  --data-dir data/vca

Open http://127.0.0.1:8444/ui/auth in your browser to access the Authentication Gate, Self-Service Portal, Delegated Operations Console, and Global Administrator Console.


Part II: vca — Step-by-Step How-To Guide

1. Bootstrapping an Offline Root & Online Scoped Intermediate CA Hierarchy

Production PKI deployments isolate the Root X.509 v3 trust anchor from daily leaf certificate signing by issuing Scoped Intermediate CAs restricted with RFC 5280 NameConstraints.

Step 1.1: Initialize the Authority Store and Root Hierarchy

Starting vca against a clean --data-dir automatically generates a 256-bit Master Key Encryption Key (master.kek), splits it into 2-of-3 GF(2^8) Shamir shares, and provisions sealed X.509 v3 Root (ca-root-x509), OpenSSH User (ca-user-ssh), and OpenSSH Host (ca-host-ssh) authorities under NIST SP 800-38D AES-256-GCM envelopes (ENC[vca-v2-gcm:...]).

BASH
./vca serve 127.0.0.1:8444 --data-dir ./data --issuer https://pki.corp.internal

Step 1.2: Provision Domain-Scoped Online Intermediate CAs

Create dedicated Intermediate CAs for public edge gateways and internal service-mesh workloads. Each Intermediate CA sets basicConstraints: critical, CA:TRUE, pathLenConstraint: 0 and enforces permittedSubtrees DNS boundaries:

BASH
# Edge TLS Intermediate CA (Ed25519) constrained to .corp.internal
./vca ca init-intermediate \
  --cn "VCA Edge TLS Intermediate Authority" \
  --ca-id ca-int-edge \
  --domains ".corp.internal" \
  --alg Ed25519 \
  --out-chain ./certs/ca-int-edge-chain.pem \
  --data-dir ./data

# Service-Mesh mTLS Intermediate CA (ECDSA-P256) constrained to .mesh.corp.internal
./vca ca init-intermediate \
  --cn "VCA Workload mTLS Intermediate Authority" \
  --ca-id ca-int-mtls \
  --domains ".mesh.corp.internal" \
  --alg ECDSA-P256 \
  --out-chain ./certs/ca-int-mtls-chain.pem \
  --data-dir ./data

You can also provision Intermediate CAs live via the REST API or Global Administrator Console (/ui/admin):

BASH
curl -sS -X POST http://127.0.0.1:8444/api/v1/ca/intermediate \
  -H "Authorization: Bearer ${ADMIN_JWT}" \
  -H "Content-Type: application/json" \
  -d '{
    "ca_id": "ca-int-edge",
    "display_name": "VCA Edge TLS Intermediate Authority",
    "permitted_dns_domains": ".corp.internal",
    "algorithm": "Ed25519"
  }'

Multi-Tier Root, Scoped Intermediate & OpenSSH CA Hierarchy


2. Issuing mTLS Workload Certificates (CLI & Zero-Escrow CSR API)

Recipe 2.1: Direct CLI Issuance with Full 3-Tier PEM Chain

Issue a short-lived workload certificate signed by ca-int-mtls. vca appends an RFC 6962 Signed Certificate Timestamp (SCT) extension, logs the certificate in the Merkle CT tree, and writes the complete Leaf + Intermediate + Root PEM chain:

BASH
./vca cert issue-x509 \
  --cn payments.mesh.corp.internal \
  --san "payments.mesh.corp.internal,ledger.mesh.corp.internal" \
  --alg ECDSA-P256 \
  --ttl 14400 \
  --ca-id ca-int-mtls \
  --out-cert ./certs/mesh/payments-fullchain.pem \
  --out-key ./certs/mesh/payments.key \
  --data-dir ./data

Recipe 2.2: Zero-Private-Key-Escrow PKCS#10 CSR Signing via REST API

Generate the private key locally on the workload host so private key material never crosses the network, then submit only the PKCS#10 CSR using either an interactive Bearer JWT or a SAN-scoped enrollment token (vca_enroll_...):

BASH
# 1. Mint a single-use machine enrollment token scoped to *.mesh.corp.internal
ENROLL_TOK=$(curl -sS -X POST http://127.0.0.1:8444/api/v1/tokens/enroll \
  -H "Authorization: Bearer ${ADMIN_JWT}" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "prof-zsp-triple",
    "allowed_sans": "*.mesh.corp.internal",
    "max_uses": 1,
    "ttl_secs": 3600
  }')

# 2. Submit client-generated PKCS#10 CSR for zero-escrow signing
curl -sS -X POST http://127.0.0.1:8444/api/v1/self/x509-sign \
  -H "Authorization: Bearer vca_enroll_..." \
  -H "Content-Type: application/json" \
  -d '{
    "ca_id": "ca-int-mtls",
    "csr_pem": "-----BEGIN CERTIFICATE REQUEST-----\n...\n-----END CERTIFICATE REQUEST-----",
    "dns_names": ["orders.mesh.corp.internal"],
    "requested_ttl": 3600
  }'

vca verifies the CSR Proof-of-Possession signature, strips all untrusted client CSR extensions, enforces RFC 6125 single-label wildcard SAN rules and Intermediate NameConstraints, and returns certificate_pem, certificate_chain_pem, serial_hex, and sct_leaf_hash.


3. Signing Short-Lived OpenSSH User & Host Certificates

vca implements OpenSSH PROTOCOL.certkeys across ssh-ed25519-cert-v01@openssh.com, rsa-sha2-256-cert-v01@openssh.com, and ecdsa-sha2-nistp256-cert-v01@openssh.com without ever escrowing SSH private keys.

Step 3.1: Configure OpenSSH Daemons & Clients to Trust vca

BASH
# Export TrustedUserCAKeys and @cert-authority known_hosts entries
curl -sS http://127.0.0.1:8444/api/v1/ssh/ca-keys

On target Linux servers (./config/ssh/sshd_config), trust the vca User SSH CA and install its host certificate:

TEXT
TrustedUserCAKeys ./certs/ssh/vca_user_ca.pub
HostKey ./certs/ssh/ssh_host_ed25519_key
HostCertificate ./certs/ssh/ssh_host_ed25519_key-cert.pub
RevokedKeys ./certs/ssh/vca_revoked.krl

Step 3.2: Sign an OpenSSH Host Certificate (cert_type = 2)

BASH
./vca ssh sign \
  --pubkey ./certs/ssh/ssh_host_ed25519_key.pub \
  --principal "bastion01.corp.internal,10.20.0.10" \
  --type host \
  --ttl 2592000 \
  --out ./certs/ssh/ssh_host_ed25519_key-cert.pub \
  --data-dir ./data

Step 3.3: Sign a Short-Lived Developer OpenSSH User Certificate (cert_type = 1)

BASH
# Via CLI
./vca ssh sign \
  --pubkey ~/.ssh/id_ed25519.pub \
  --principal "alice,sre-admin" \
  --type user \
  --ttl 28800 \
  --out ~/.ssh/id_ed25519-cert.pub \
  --data-dir ./data

# Or via Zero-Escrow REST API
curl -sS -X POST http://127.0.0.1:8444/api/v1/self/ssh-sign \
  -H "Authorization: Bearer ${USER_JWT}" \
  -H "Content-Type: application/json" \
  -d '{
    "ssh_public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl alice@laptop",
    "cert_type": "user",
    "principals": ["alice", "sre-admin"],
    "requested_ttl": 3600
  }'

4. Verifying Certificate Transparency (CT) Merkle Inclusion Proofs

Every X.509 v3 certificate issued by vca (standard CSR, Triple-Credential ZSP bundle, ACME v2 finalize, or Keyless OIDC signing) is appended to an RFC 6962 SHA-256 Merkle binary tree.

BASH
# 1. Fetch the Ed25519-signed Merkle Signed Tree Head (STH)
curl -sS http://127.0.0.1:8444/api/v1/ct/v1/get-sth

# 2. Request and verify an O(log N) Merkle inclusion proof for leaf index 1
curl -sS "http://127.0.0.1:8444/api/v1/ct/v1/get-proof-by-index?index=1"

Example inclusion proof response:

JSON
{
  "leaf_index": 1,
  "tree_size": 5,
  "leaf_hash_hex": "d56833378df9c6ef25cd9cb1139d7671bdeba1e153dc39d2ea5a1acb80bae4f5",
  "root_hash_hex": "994cb99522cd3a7291eac3d115c510c680481403533a3d41dc5fba34e7eac2d0",
  "audit_path": [
    "a09903b8b2c5ab86b534de8a88b5340dfab970c59c7e2915d73b6bf1de7f21f3",
    "180c7eaa882a79e0899e044a0cf853d3465d543cdff3b41912eef14d6f1cfce6",
    "608e1655eb4ee1b276f0164da83a2a97aed2098715e3f3adc7b9f0ac56443f31"
  ],
  "verified": true
}

Merkle Certificate Transparency Inclusion Proof in Dark Mode


5. Revoking Compromised Credentials via CRL v2, OCSP & OpenSSH KRL

When a workload key or developer laptop is compromised, revoke the credential immediately by cert_id with an RFC 5280 revocation reason (keyCompromise, cessationOfOperation, superseded, or privilegeWithdrawn):

BASH
# 1. Revoke the certificate immediately
curl -sS -X POST http://127.0.0.1:8444/api/v1/certificates/revoke \
  -H "Authorization: Bearer ${ADMIN_JWT}" \
  -H "Content-Type: application/json" \
  -d '{
    "cert_id": "xcert_012ea21fee4e6431",
    "reason": "keyCompromise"
  }'

# 2. Query real-time RFC 6960 OCSP status ("good", "revoked", or "unknown")
curl -sS -X POST http://127.0.0.1:8444/api/v1/x509/ocsp \
  -H "Content-Type: application/json" \
  -d '{"serial_hex": "3ea3a5f60"}'

# 3. Export signed PEM X.509 CRL v2 for TLS proxies and edge load balancers
./vca crl --out ./certs/vca_revoked.crl.pem --data-dir ./data
curl -sS "http://127.0.0.1:8444/api/v1/x509/crl?format=pem" -o ./certs/vca_revoked.crl.pem

# 4. Export binary OpenSSH Key Revocation List (SSHKRL) for sshd RevokedKeys
./vca krl --out ./certs/ssh/vca_revoked.krl --data-dir ./data
curl -sS "http://127.0.0.1:8444/api/v1/ssh/krl?format=raw" -o ./certs/ssh/vca_revoked.krl

6. Native HTTPS / mTLS Serving & EST / SCEP Device Enrollment

Step 6.1: Serve vca Natively over HTTPS or Mutual TLS (mTLS)

Start vca directly over TLS without an external reverse proxy using either explicit PEM files or an ephemeral auto-provisioned ECDSA-P256 bundle:

BASH
# Quick native HTTPS with an auto-provisioned ECDSA-P256 certificate
./vca serve 0.0.0.0:8444 --tls-auto --data-dir ./data

# Production mTLS enforcing client certificates signed by your CA bundle
./vca serve 0.0.0.0:8444 \
  --tls-cert ./certs/vca_server.pem \
  --tls-key ./certs/vca_server.key \
  --tls-client-ca ./certs/vca_root_ca.pem \
  --data-dir ./data

Step 6.2: Automated Network & MDM Device Enrollment via EST (RFC 7030) and SCEP (RFC 8894)

BASH
# 1. Fetch the RFC 7030 EST PKCS#7 certs-only CA bundle
curl -sS https://pki.corp.internal/.well-known/est/cacerts -o cacerts.p7b.b64

# 2. Enroll a network appliance via EST simpleenroll (HTTP Basic or Bearer / vca_enroll_* token)
curl -sS -X POST https://pki.corp.internal/.well-known/est/simpleenroll \
  -u "alice:vca-secret-2026" \
  -H "Content-Type: application/pkcs10" \
  --data-binary @device.csr.b64 \
  -o device.p7b.b64

# 3. Query SCEP capabilities and CA certificate for MDM / router clients
curl -sS "https://pki.corp.internal/scep?operation=GetCACaps"
curl -sS "https://pki.corp.internal/scep?operation=GetCACert" -o ca.der

Part III: vca — End-User & Developer Guide

1. Navigating the Role-Separated PKI Web Studio

vca provides four role-separated browser workspaces served directly by the authority daemon (http://127.0.0.1:8444/ui/*). Each workspace defaults to crisp Institutional Light Mode (data-theme="light") with a persistent 1-click Dark Mode toggle in the top header bar:

Workspace Path Target Persona Primary Capabilities
/ui/auth All Principals Username + PBKDF2 password + 6-digit RFC 6238 TOTP sign-in, plus OIDC 1.0 + PKCE and ACME v2 endpoint discovery.
/ui/portal Developers & Workloads (member) Triple-Credential ZSP bundles, zero-escrow PKCS#10 CSR and SSH .pub signing, keyless OIDC code-signing, RFC 3161 timestamping, ASN.1 DER / SSH wire inspection, TOTP QR pairing, and personal credential renewal/revocation.
/ui/delegated OrgUnit Leads (delegated_admin) Scoped certificate inventory, OrgUnit principal provisioning, and SAN-locked machine enrollment token minting within the caller's org_id.
/ui/admin PKI Governors (super_admin, global_admin) Multi-tier Root/Intermediate/SSH CA topology, Shamir M-of-N seal/unseal ceremonies, ABAC policy profiles, Merkle CT log proofs, live CRL/OCSP/SSHKRL, vsight SOAR containment, and encrypted backups.

2. Signing In & Pairing TOTP Multi-Factor Authentication

  1. Open /ui/auth in your browser.
  2. Enter your username, password, and (when MFA is enabled on your account) the current 6-digit TOTP verification code from your authenticator app, then click Sign In & Mint EdDSA Session.
  3. Navigate to Self-Service Portal -> My Credentials & MFA and click Refresh Profile & Credentials to view your verified SPIFFE ID (spiffe://<trust-domain>/ns/<org>/sa/<user>) and scan your offline ISO/IEC 18004 vector SVG QR code.

Authentication & TOTP MFA Sign-In Gate

Principal Profile, ISO 18004 QR Code & Personal Credential Inventory


3. Minting Atomic Triple-Credential ZSP Bundles

Instead of juggling separate mTLS certificates, static SSH keys, and VPN configurations, developers can mint a short-lived Triple-Credential Zero-Standing-Privilege (ZSP) Bundle from /ui/portal (Triple-Credential ZSP tab):

  1. Set the Target vgate Zero-Trust Mesh Network (for example, prod-mesh) and Requested Lease TTL (for example, 3600 seconds).
  2. Select one or more authorized OpenSSH Principals (alice, sre-admin, deploy) using the multi-select chip selector.
  3. Click Mint Triple-Credential Bundle.

Minting an Atomic Triple-Credential ZSP Bundle in the Self-Service Portal

The Lightbox modal displays a single JSON bundle containing:

  • x509_certificate_pem — Short-lived X.509 v3 mTLS client certificate bound to your SPIFFE URI and ABAC claims (OID 1.3.6.1.4.1.59999.1.1) with an embedded Merkle CT SCT.
  • ssh_authorized_cert — Short-lived OpenSSH User certificate (ssh-ed25519-cert-v01@openssh.com) carrying your approved principals and permit-pty / permit-port-forwarding extensions.
  • vnet_token — HMAC-authenticated vnet_tok_... mesh session token accepted by vgate zero-trust gateways.

4. Submitting Zero-Escrow CSRs & Logging In with OpenSSH Certificates

4.1 Zero-Escrow PKCS#10 CSR Submission

When your private key must remain on your workstation, HSM, or container volume:

  1. Generate an Ed25519, ECDSA-P256, or RSA-2048/4096 keypair and PKCS#10 CSR locally.
  2. Open Self-Service Portal -> Zero-Escrow CSR & SSH Sign.
  3. Enter your requested DNS Subject Alternative Names (for example, workload.corp.internal), paste the -----BEGIN CERTIFICATE REQUEST----- block, and click Sign PKCS#10 CSR.
  4. Save the returned 3-tier certificate_chain_pem alongside your local private key.

4.2 Zero-Escrow OpenSSH Certificate Login Workflow

  1. Copy the contents of your local public key (~/.ssh/id_ed25519.pub)—never your private key.
  2. In Zero-Escrow CSR & SSH Sign, paste the .pub line, keep User Certificate (SSH_CERT_TYPE_USER = 1) selected, and click Sign OpenSSH Public Key (or run vca ssh sign --pubkey ~/.ssh/id_ed25519.pub --principal alice --out ~/.ssh/id_ed25519-cert.pub).
  3. Write the authorized_cert_line to ~/.ssh/id_ed25519-cert.pub next to ~/.ssh/id_ed25519.
  4. Connect directly with standard OpenSSH:
BASH
# Inspect your issued certificate validity, serial, principals, and CA fingerprint
ssh-keygen -L -f ~/.ssh/id_ed25519-cert.pub

# Connect to any host trusting the vca OpenSSH User CA
ssh alice@bastion01.corp.internal

OpenSSH automatically presents ~/.ssh/id_ed25519-cert.pub alongside ~/.ssh/id_ed25519 without requiring any static ~/.ssh/authorized_keys entry on the remote host.


5. Keyless OIDC Signing, RFC 3161 Timestamping & Wire Inspection

5.1 Keyless OIDC Ephemeral Code Signing & allowed_signers

Open Keyless OIDC & TSA in /ui/portal:

  • Click Mint 10-Minute Keyless X.509 v3 Cert to exchange your active OIDC session for a Fulcio-style ephemeral signing certificate bound to your SPIFFE identity and logged permanently in the Merkle CT tree.
  • Click Issue RFC 3161 Timestamp Token over any 64-character SHA-256 release artifact digest (POST /api/v1/tsa/timestamp) so verifiers can prove the signature existed while the 10-minute ephemeral certificate was valid.
  • Click Export OpenSSH allowed_signers (GET /api/v1/ssh/allowed-signers) to verify Git tags and release bundles using ssh-keygen -Y verify.

5.2 Visual ASN.1 DER & OpenSSH Wire Byte-Tree Inspector

Open ASN.1 & SSH Wire Inspector in /ui/portal (or run ./vca inspect <file>):

  • Paste any X.509 PEM certificate, PKCS#10 CSR, RFC 3161 Timestamp Token, or OpenSSH *-cert-v01@openssh.com line and click Inspect Byte-Tree in Lightbox.
  • Review exact byte offsets, definite-length TLV lengths, nesting depths, OIDs, SANs, or OpenSSH PROTOCOL.certkeys wire fields before deploying credentials to production.

6. Renewing & Revoking Personal Credentials

In My Credentials & MFA, every active credential owned by your principal lists two one-click actions:

  • Renew (POST /api/v1/self/renew) — Re-evaluates policy and re-signs the public key with a fresh cryptographic serial number and updated validity window while preserving historical immutability of the prior certificate record.
  • Revoke (POST /api/v1/certificates/revoke) — Marks the credential revoked immediately across live OCSP, CRL v2, and OpenSSH KRL endpoints.

Part IV: vca — PKI Administrator Guide

1. PKI Hierarchy Governance & Role Separation

vca enforces strict three-tier Role-Based Access Control (RBAC) combined with Organizational Unit (org_id) tenancy boundaries:

Role Scope Permitted Governance Actions
super_admin / global_admin Global Authority Provision Scoped Intermediate CAs, execute Root CA cross-signing, trigger RAM seal / Shamir M-of-N unseal ceremonies, manage all OrgUnits/profiles/users, run SOAR quarantines, export encrypted VCA_BACKUP_V2 snapshots, and generate SOC2 dossiers.
delegated_admin / org_admin Assigned org_id Only View OrgUnit certificates, create users and ABAC profiles strictly within their own org_id (cannot promote any user to global_admin), mint scoped enrollment tokens, and revoke OrgUnit certificates.
member Reflexive Self-Service Mint personal/workload certificates permitted by ABAC profiles, inspect artifacts, and renew or revoke only certificates they personally own.

2. Managing Root, Intermediate & OpenSSH Authorities

Navigate to /ui/admin (Multi-Tier CAs & Rollover tab) to inspect active signing authorities:

  1. Root X.509 v3 Authority (x509_root) — Trust anchor with CA:TRUE, pathLenConstraint: 2, sealed at rest using NIST SP 800-38D AES-256-GCM (ENC[vca-v2-gcm:<iv>:<tag>:<ciphertext>]).
  2. Scoped Intermediate X.509 v3 Authorities (x509_intermediate) — Signed by the Root CA with CA:TRUE, pathLenConstraint: 0 and critical RFC 5280 NameConstraints (permittedSubtrees), ensuring an edge Intermediate CA scoped to .corp.internal can never issue certificates for .prod.payments or external domains.
  3. OpenSSH User & Host Authorities (ssh_user_ca, ssh_host_ca) — Separate signing authorities for human/automation SSH user principals (cert_type = 1) and server host identities (cert_type = 2). Note that issuing an OpenSSH Host certificate requires an administrative role or a pre-authorized host enrollment token.

Multi-Tier CA Topology & Rollover Governance Console


3. Shamir M-of-N Key Ceremonies & Zero-Downtime Root Rotation

3.1 Master KEK Protection & On-Demand RAM Sealing

On initial bootstrap, vca generates a 32-byte CSPRNG master.kek and splits it into 2-of-3 Shamir Secret Shares over $\text{GF}(2^8)$ (x^8 + x^4 + x^3 + x + 1). Distribute each vca_share_2of3_<idx>_<hex> token to a separate key custodian.

During a security incident or maintenance window, seal the authority in RAM immediately:

BASH
# Zero the 256-bit Master KEK and unsealed CA key cache in RAM
curl -sS -X POST http://127.0.0.1:8444/api/v1/ca/seal \
  -H "Authorization: Bearer ${ADMIN_JWT}"

While sealed ("is_sealed": true on /api/v1/health), all signing endpoints fail closed with 503 Service Unavailable. Reconstruct master.kek in memory by submitting threshold shares via /ui/admin (Shamir M-of-N Seal & Unseal tab) or the API:

BASH
curl -sS -X POST http://127.0.0.1:8444/api/v1/ceremonies/unseal \
  -H "Content-Type: application/json" \
  -d '{
    "shares": [
      "vca_share_2of3_1_...",
      "vca_share_2of3_2_..."
    ]
  }'

3.2 Zero-Downtime Root CA Rollover Cross-Signing

When rotating from Root Generation 1 (G1) to Root Generation 2 (G2), issue a Cross-Signed Bridge Certificate (POST /api/v1/ca/cross-sign) whose Subject and SubjectPublicKeyInfo belong to G2 while Issuer and signature belong to G1:

BASH
curl -sS -X POST http://127.0.0.1:8444/api/v1/ca/cross-sign \
  -H "Authorization: Bearer ${ADMIN_JWT}" \
  -H "Content-Type: application/json" \
  -d '{
    "new_common_name": "VCA Root X.509 Authority G2",
    "algorithm": "Ed25519"
  }'

Legacy clients trusting G1 validate chains signed by G2 seamlessly during the transition window without Simultaneous Flag-Day trust store updates.


4. Issuance Policy Profiles & ABAC Expression Governance

In /ui/admin (ABAC Policy Compiler tab), administrators define CertProfile templates governing TTL ceilings, allowed SAN wildcard patterns, MFA enforcement, cryptographic algorithms (Ed25519, ECDSA-P256, RSA-2048, RSA-4096, X25519), and fail-closed ABAC predicates:

ABAC Policy Compiler & Configured Certificate Profiles

BASH
curl -sS -X POST http://127.0.0.1:8444/api/v1/profiles \
  -H "Authorization: Bearer ${ADMIN_JWT}" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "prof-prod-bastion",
    "org_id": "org-platform",
    "max_ttl_secs": 14400,
    "require_mfa": true,
    "allowed_san_patterns": "*.prod.corp.internal",
    "abac_expression": "dept==Platform && group_in:sre"
  }'

Fail-Closed Policy Evaluation Rules

  1. Unrecognized ABAC Clauses Fail Closed: Any unknown attribute key or malformed operator immediately denies issuance (403 Forbidden).
  2. RFC 6125 Single-Label Wildcard Enforcement: A pattern of *.corp.internal matches api.corp.internal (true), but strictly rejects multi-label subdomains such as deep.api.corp.internal (false) and bare apex corp.internal (false).
  3. Cryptographic Claims Compilation: Approved principal attributes (org_id, department, groups, entitlements) are compiled directly into X.509 v3 extension OID 1.3.6.1.4.1.59999.1.1 and OpenSSH certificate extension vca-abac-claims@vca.internal so downstream proxies verify authorization offline.

5. OIDC 1.0 Federation & External PDP Integration

  1. Built-In OIDC 1.0 + PKCE (S256) & RFC 8693 STS:
    • Relying parties discover endpoints via GET /.well-known/openid-configuration and Ed25519 public keys (OKP) via GET /.well-known/jwks.json.
    • Workloads holding a valid OIDC JWT can call POST /api/v1/oidc/token with grant_type = "urn:ietf:params:oauth:grant-type:token-exchange" to obtain short-lived X.509 v3 certificates bound to their spiffe_id claim.
  2. Upstream vwarden Policy Decision Point (--vwarden-pdp):
    • Configure vwarden_pdp_url = https://vwarden.corp.internal in vca.conf (or --vwarden-pdp) so vca consults POST /access/v1/evaluate on central vwarden clusters before minting privileged production credentials.
  3. Closed-Loop vsight SIEM & SOAR (--vsight-syslog):
    • Configure vsight_syslog_addr = 10.10.0.25:6514 to stream Ed25519-signed RFC 5424 audit lines over TCP, and allow vsight to invoke POST /api/v1/soar/quarantine authenticated via constant-time X-Vsight-Signature HMAC-SHA256 headers.

6. Encrypted Authority Backups, WAL Durability & Disaster Recovery

6.1 Segmented WAL, Sparse Indexes & LZ4 Checkpoints

In default vprevail mode, vca persists mutations across 64 FNV-1a shards with {org_id} hash-tag co-location into segmented 32-byte IEEE CRC32 binary write-ahead logs (00000000000000000000.log), 24-byte .idx sparse indexes, and LZ4-compressed .snap checkpoints. On cold start or crash recovery:

  • vca loads the latest verified .snap checkpoint, replays subsequent .log frames, automatically truncates any torn trailing bytes, and rolls back any uncommitted TX_BEGIN frame lacking a matching TX_COMMIT.
  • Merkle CT leaves (ct_leaf_0..N) are deterministically rehydrated so tree hashes remain continuous across restarts.

6.2 Exporting & Restoring Lossless VCA_BACKUP_V2 Snapshots

Export a complete AES-256-GCM encrypted backup containing all CAs (with sealed private keys), users, OrgUnits, ABAC profiles, quorum ceremonies, and issued/revoked certificate records:

BASH
# Export encrypted VCA_BACKUP_V2 snapshot via CLI or REST API
./vca backup --out ./backups/vca-$(date +%F).backup.json --data-dir ./data

# Restore encrypted envelope onto a recovery node sharing the same master.kek
curl -sS -X POST http://127.0.0.1:8444/api/v1/admin/restore \
  -H "Authorization: Bearer ${ADMIN_JWT}" \
  -H "Content-Type: application/json" \
  -d '{"encrypted_envelope": "ENC[vca-v2-gcm:...]"}'

6.3 Generating Signed Compliance Dossiers & OpenMetrics

BASH
# Export signed SOC2 / ISO 27001 auditor dossier (CA counts, CT STH signature, verified audit chain)
./vca compliance --out ./backups/vca-compliance-dossier.json --data-dir ./data

# Scrape authenticated Prometheus / OpenMetrics certificate expiry horizon buckets (24h, 7d, 30d)
curl -sS http://127.0.0.1:8444/api/v1/metrics -H "Authorization: Bearer ${ADMIN_JWT}"

7. Production Deployment & Hardening Checklist

Before exposing vca in production environments, enable strict startup validation (--prod), sealed-on-boot custody (--start-sealed), and native TLS/mTLS termination:

BASH
export VCA_PROD=true
export VCA_START_SEALED=true
export VCA_SOAR_SECRET="<random-32-byte-hex>"
export VCA_MESH_SECRET="<random-32-byte-hex>"
export VCA_BOOTSTRAP_ADMIN_PASSWORD="<strong-admin-passphrase>"

./vca serve 0.0.0.0:8444 \
  --prod \
  --start-sealed \
  --max-conns 256 \
  --tls-cert /etc/vca/tls/tls.crt \
  --tls-key /etc/vca/tls/tls.key \
  --tls-client-ca /etc/vca/tls/client_ca.pem \
  --data-dir ./data

Reference deployment templates are bundled under deploy/:

  • deploy/vca.service: Hardened systemd unit (NoNewPrivileges, ProtectSystem=strict, PrivateTmp, CAP_NET_BIND_SERVICE).
  • deploy/Containerfile: Non-root (uid 10001) minimal runtime image with healthcheck.
  • deploy/k8s-deployment.yaml: Kubernetes Deployment with readinessProbe and livenessProbe targeting HTTPS /api/v1/health and Secret-backed VCA_* credentials.

Part V: vca — Operations, Production Runbooks & Use Cases

Runbook 1: Zero-Standing-Privilege (ZSP) SSH Bastion & Mesh Access

Operational Scenario

Platform engineers require on-demand interactive shell access (sre-admin) to production Linux hosts behind a vgate zero-trust bastion without leaving permanent public keys in ~/.ssh/authorized_keys or long-lived VPN credentials on laptops.

Step-by-Step Execution

  1. Configure Target Hosts Once: Distribute the vca User SSH CA public key (GET /api/v1/ssh/ca-keys) to ./certs/ssh/vca_user_ca.pub and configure ./config/ssh/sshd_config with TrustedUserCAKeys ./certs/ssh/vca_user_ca.pub and RevokedKeys ./certs/ssh/vca_revoked.krl.
  2. Authenticate with MFA: Engineer authenticates against vca (POST /api/v1/auth/login with 6-digit TOTP code) or via federated OIDC 1.0 PKCE (POST /api/v1/oidc/authorize -> POST /api/v1/oidc/token).
  3. Mint Atomic Triple-Credential Lease:
BASH
curl -sS -X POST https://pki.corp.internal/api/v1/self/mint-bundle \
  -H "Authorization: Bearer ${ENGINEER_JWT}" \
  -H "Content-Type: application/json" \
  -d '{
    "network_id": "prod-mesh",
    "requested_ttl": 3600,
    "principals": ["alice", "sre-admin"]
  }' > ./tmp/zsp_bundle.json

Atomic Triple-Credential ZSP Bundle Minting

  1. Connect & Auto-Expire: The engineer presents vnet_token to vgate, establishes mTLS using x509_certificate_pem, and connects via ssh -i ~/.ssh/id_ed25519 sre-admin@db01.corp.internal. After 3600 seconds, all three credentials expire cryptographically with zero cleanup scripts required.

Runbook 2: Service-Mesh mTLS & Private ACME v2 Automation

Operational Scenario

Edge ingress proxies (vgate, vsite) and internal microservices require automated X.509 v3 certificate provisioning and zero-downtime renewal without human intervention or private key escrow.

Option A: Stateful Private ACME v2 Workflow (RFC 8555)

BASH
# 1. Obtain fresh anti-replay nonce and register ACME client account
NONCE_JSON=$(curl -sS https://pki.corp.internal/acme/v2/new-nonce)
curl -sS -X POST https://pki.corp.internal/acme/v2/new-acct \
  -H "Content-Type: application/json" \
  -d '{"contact": "mailto:platform-ops@corp.internal"}'

# 2. Submit certificate order (unauthenticated orders start in "pending" state)
ORDER_JSON=$(curl -sS -X POST https://pki.corp.internal/acme/v2/new-order \
  -H "Content-Type: application/json" \
  -d '{"domains": ["ingress01.corp.internal"]}')

# 3. Validate domain ownership challenge (transitions order to "ready")
curl -sS -X POST https://pki.corp.internal/acme/v2/chall \
  -H "Content-Type: application/json" \
  -d '{"order_id": "ord_...", "challenge_token": "chall_..."}'

# 4. Finalize with local PKCS#10 CSR (CN must match ordered domain) & fetch PEM chain
FINAL_JSON=$(curl -sS -X POST https://pki.corp.internal/acme/v2/finalize \
  -H "Content-Type: application/json" \
  -d '{"order_id": "ord_...", "csr_pem": "-----BEGIN CERTIFICATE REQUEST-----\n..."}')

curl -sS "https://pki.corp.internal/acme/v2/cert?cert_id=xcert_..." -o ../vgate/certs/fullchain.pem

Option B: Workload Bootstrap via Scoped Enrollment Token (vca_pat_*)

For headless sidecars that cannot answer external HTTP challenges, mint a SAN-locked reusable machine PAT (max_uses: 50) restricted to *.mesh.corp.internal and invoke POST /api/v1/self/x509-sign on startup and POST /api/v1/self/renew at 70% of TTL.


Runbook 3: Certificate Transparency Auditing & Supply-Chain Notarization

Operational Scenario

Security auditors and CI/CD release pipelines (vstore, vllm, vvm, vkbm) require mathematical proof that every signing certificate is recorded in an append-only Merkle tree and that release artifacts were signed while the ephemeral certificate was valid.

Step-by-Step Execution

BASH
# 1. CI runner exchanges OIDC workload JWT for a 10-minute keyless signing certificate + SCT
curl -sS -X POST https://pki.corp.internal/api/v1/self/keyless-sign \
  -H "Authorization: Bearer ${CI_OIDC_JWT}" > keyless_cert.json

# 2. Stamp the compiled release binary SHA-256 with an RFC 3161 TSTInfo Timestamp Token
./vca tsa sign \
  --file release/app-linux-x64.tar.gz \
  --nonce 20261114cafe \
  --out release/app-linux-x64.tsr.pem \
  --data-dir ./data

# 3. Downstream consumers verify the RFC 3161 Timestamp Token offline/online
./vca tsa verify \
  --token release/app-linux-x64.tsr.pem \
  --file release/app-linux-x64.tar.gz \
  --data-dir ./data

# 4. Auditors verify the Ed25519 Signed Tree Head (STH) and O(log N) Merkle inclusion proof
curl -sS https://pki.corp.internal/api/v1/ct/v1/get-sth
curl -sS "https://pki.corp.internal/api/v1/ct/v1/get-proof-by-index?index=0"

Merkle CT Log Signed Tree Head & Inclusion Proof Verification


Runbook 4: Incident Containment, SOAR Quarantine & Emergency Sealing

Operational Scenario

vsight Endpoint Detection & Response (EDR) detects anomalous lateral movement originating from principal usr-alice, or operators detect an active intrusion targeting a regional PKI node.

Step-by-Step Containment

  1. Automated Closed-Loop Principal Quarantine (POST /api/v1/soar/quarantine):

vsight dispatches an HMAC-SHA256 authenticated webhook (X-Vsight-Signature) or an administrator triggers quarantine from /ui/admin (vsight SOAR & RFC 5424 Audit tab):

BASH
curl -sS -X POST https://pki.corp.internal/api/v1/soar/quarantine \
  -H "Authorization: Bearer ${ADMIN_JWT}" \
  -H "Content-Type: application/json" \
  -d '{
    "target_user_id": "usr-alice",
    "reason": "vsight_edr_compromise_containment"
  }'

vca atomically revokes every active X.509 v3 and OpenSSH credential issued to usr-alice, updates live OCSP/CRL/SSHKRL responders, appends an Ed25519-signed SHA-256 hash-chained audit event, and emits an RFC 5424 syslog alert.

  1. Propagate Revocation Lists Immediately:

Edge gateways refresh GET /api/v1/x509/crl?format=pem and SSH bastions refresh GET /api/v1/ssh/krl?format=raw.

  1. Verify Audit Ledger Integrity:
BASH
curl -sS https://pki.corp.internal/api/v1/audit \
  -H "Authorization: Bearer ${ADMIN_JWT}"

Confirm "chain_integrity_verified": true across all rolling SHA-256 event hashes and Ed25519 non-repudiation signatures.

  1. Emergency Host Seal (If Authority Host Is Threatened):

Invoke POST /api/v1/ca/seal to zero master.kek and all cached CA signing keys in RAM immediately until incident responders complete forensic verification and conduct a 2-of-3 Shamir unseal ceremony.


Part VI: vca — Configuration, CLI & REST API Reference

1. CLI Subcommand & Flag Reference

Invoke vca (vca.exe on Windows, ./vca on Linux and macOS) with any of the server, governance, or workload subcommands below.

1.1 Server, Governance & Diagnostic Subcommands

Subcommand Arguments & Flags Description
serve / start [listen_addr] --config <file> --addr <host:port> --issuer <url> --data-dir <dir> --mode <backend> --vprevail-addr <host:port> --sqlite-path <file> --vsight-syslog <host:port> --vwarden-pdp <url> Starts the concurrent HTTP/1.1 OpenAPI 3.1 Control Plane and 4-Workspace PKI Studio (default 127.0.0.1:8444).
openapi [issuer_url] --issuer <url> Outputs the complete OpenAPI 3.1.0 JSON specification to standard output.
discovery [issuer_url] --issuer <url> Outputs authority OIDC, ACME v2, and CT log discovery metadata JSON.
init-store [vprevail|vprevail_cluster|sqlite] Verifies authority store initialization in the selected storage backend.
verify-id <identifier> Validates a resource identifier against [a-zA-Z0-9._:-]{1,96} and traversal rules.
audit (none) Executes static cyclomatic complexity and security rule verification.
version -v, --version Prints semantic version (0.1.0) and supported capability summary.
help -h, --help Prints full CLI subcommand and flag usage summary.

1.2 PKI, OpenSSH, Timestamp & Operator Subcommands

Subcommand Supported Flags Output & Behavior
ca init-intermediate --cn <name> --ca-id <id> --domains <csv> --alg <Ed25519|ECDSA-P256|RSA-2048|RSA-4096> --out-chain <file> --data-dir <dir> Provisions an RFC 5280 NameConstraints-scoped Intermediate X.509 v3 CA signed by ca-root-x509, persists sealed keys, writes Intermediate + Root PEM to --out-chain, and prints JSON summary.
cert issue-x509 --cn <cn> --san <csv> --alg <alg> --ttl <secs> --ca-id <id> --user <uid> --out-cert <file> --out-key <file> --data-dir <dir> Generates a keypair, signs an X.509 v3 leaf certificate with embedded Merkle CT SCT, writes the 3-tier PEM chain (Leaf + Intermediate + Root) to --out-cert and PKCS#8 private key to --out-key.
ssh sign --pubkey <file_or_line> --principal <csv> --type <user|host> --ttl <secs> --user <uid> --out <file> --data-dir <dir> Zero-escrow signs an OpenSSH .pub key (ssh-ed25519, ssh-rsa, ecdsa-sha2-nistp256) into a User (type = 1) or Host (type = 2) certificate.
tsa sign --file <path_or_sha256_hex> --nonce <hex> --user <uid> --out <file> --data-dir <dir> Signs an RFC 3161 ASN.1 DER TSTInfo Timestamp Token (-----BEGIN TIMESTAMP TOKEN-----) over a file or 64-character SHA-256 hex digest.
tsa verify --token <path_or_pem> --file <path_or_sha256_hex> --data-dir <dir> Verifies Timestamp Token signature and constant-time SHA-256 messageImprint match.
inspect <file_or_inline> --file <path> --data-dir <dir> Decodes X.509 PEM, PKCS#10 CSR, Timestamp Token, or OpenSSH *-cert-v01@openssh.com wire byte trees into offset/length JSON.
token mint --profile <id> --sans <csv> --max-uses <N> --ttl <secs> --user <uid> --data-dir <dir> Mints a single-use bootstrap token (vca_enroll_*, --max-uses 1) or reusable service PAT (vca_pat_*, --max-uses > 1).
crl --out <file> --data-dir <dir> Exports a freshly signed RFC 5280 X.509 CRL v2 PEM file (-----BEGIN X509 CRL-----).
krl --out <file> --data-dir <dir> Exports the current OpenSSH Key Revocation List (SSHKRL).
backup --out <file> --data-dir <dir> Exports a lossless NIST AES-256-GCM encrypted VCA_BACKUP_V2 authority snapshot.
compliance --out <file> --data-dir <dir> Exports a signed SOC2 / ISO 27001 compliance dossier JSON.

2. Configuration File (vca.conf) & Environment Variables

vca resolves configuration in strict precedence order (highest to lowest): CLI Flags -> VCA_* Environment Variables -> --config <vca.conf> (VCA_CONFIG) -> Built-in Defaults.

vca.conf Key Environment Variable CLI Flag Default Value Description
listen_addr VCA_LISTEN_ADDR --addr 127.0.0.1:8444 HTTP/1.1 TCP bind address and port.
issuer_url VCA_ISSUER_URL --issuer http://127.0.0.1:8444 Public canonical URL embedded in OIDC discovery, ACME v2 directory, AIA, and CRL DP.
data_dir VCA_DATA_DIR --data-dir data/vca Directory storing master.kek, segmented .log/.idx WAL files, and .snap checkpoints.
storage_mode VCA_STORAGE_MODE --mode vprevail Persistence backend: vprevail (embedded 64-shard MVCC WAL), vprevail_cluster, vprevail_http, or sqlite.
vprevail_addr VCA_VPREVAIL_ADDR --vprevail-addr 127.0.0.1:7654 Upstream vprevail cluster TCP (VPRV binary RPC) or HTTP endpoint.
sqlite_path VCA_SQLITE_PATH --sqlite-path data/vca/vca.sqlite SQLite database file path when storage_mode = sqlite.
vsight_syslog_addr VCA_VSIGHT_SYSLOG_ADDR --vsight-syslog (disabled) Optional host:port for streaming live TCP RFC 5424 signed SIEM syslog events to vsight.
vwarden_pdp_url VCA_VWARDEN_PDP_URL --vwarden-pdp (disabled) Optional upstream vwarden PDP base URL (POST /access/v1/evaluate).
tls_cert VCA_TLS_CERT --tls-cert (disabled) Path to PEM server certificate chain enabling native HTTPS on vca serve.
tls_key VCA_TLS_KEY --tls-key (disabled) Path to PEM PKCS#8 private key paired with tls_cert.
tls_client_ca VCA_TLS_CLIENT_CA --tls-client-ca (disabled) Path to PEM CA bundle enabling mandatory mutual TLS (mTLS) client certificate verification.
tls_auto VCA_TLS_AUTO --tls-auto false Auto-provisions an ephemeral in-memory ECDSA-P256 CA and server TLS certificate for vca serve.
prod_mode VCA_PROD --prod false Enables strict production startup guard: requires TLS, non-default shared secrets & bootstrap password, CSPRNG TOTP secret, and 100,000 PBKDF2 iterations.
start_sealed VCA_START_SEALED --start-sealed false Boots the authority sealed in RAM (is_sealed = true), awaiting M-of-N Shamir shares via /api/v1/ceremonies/unseal.
max_conns VCA_MAX_CONNS --max-conns 256 Bounded concurrent TCP/TLS connection ceiling; excess connections receive 503 Service Unavailable.
soar_secret VCA_SOAR_SECRET --soar-secret (dev default) Shared HMAC-SHA256 secret authenticating vsight SOAR containment requests (>= 16 chars in --prod).
mesh_secret VCA_MESH_SECRET --mesh-secret (dev default) Shared HMAC-SHA256 secret signing vgate vnet_tok_ mesh leases (>= 16 chars in --prod).
bootstrap_admin_password VCA_BOOTSTRAP_ADMIN_PASSWORD --bootstrap-password (dev default) Initial administrator bootstrap password (>= 12 chars in --prod); PBKDF2 work factor tunable via VCA_PBKDF2_ITERS.

Example vca.conf

INI
# Production Authority Configuration
listen_addr        = 0.0.0.0:8444
issuer_url         = https://pki.corp.internal
data_dir           = ./data
storage_mode       = vprevail
vsight_syslog_addr = 10.20.0.50:6514
vwarden_pdp_url    = https://id.corp.internal

3. Policy Profile & Credential Bundle JSON Schemas

3.1 ABAC Issuance Profile Schema (POST /api/v1/profiles)

JSON
{
  "profile_id": "prof-edge-mtls",
  "org_id": "org-platform",
  "ca_id": "ca-int-edge",
  "cert_kind": "x509_leaf",
  "display_name": "Edge Gateway mTLS Profile",
  "max_ttl_secs": 86400,
  "require_mfa": true,
  "allowed_san_patterns": "*.corp.internal,*.edge.corp.internal",
  "ssh_extensions_csv": "permit-pty,permit-port-forwarding",
  "abac_expression": "dept==Platform && group_in:sre"
}

3.2 Atomic Triple-Credential ZSP Response (POST /api/v1/self/mint-bundle)

JSON
{
  "bundle_id": "zsp_8d21a94f301e",
  "x509_cert_id": "xcert_94f1c20b88a1",
  "x509_serial_hex": "3ea9104bc2",
  "x509_sct_leaf_hash": "d56833378df9c6ef25cd9cb1139d7671bdeba1e153dc39d2ea5a1acb80bae4f5",
  "x509_certificate_pem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  "ssh_cert_id": "scert_41b09e77c120",
  "ssh_authorized_cert": "ssh-ed25519-cert-v01@openssh.com AAAAHHNzaC1lZDI1NTE5LWNlcnQtdjAxQG9wZW5zc2guY29t... alice@default",
  "vnet_token": "vnet_tok_1763097600_prod-mesh_usr-alice_9f82c140e71a9b024d18c7a3e60b1124",
  "spiffe_uri": "spiffe://corp.internal/ns/platform/sa/alice",
  "expires_at": 1763097600
}

4. OpenAPI 3.1.0 REST Endpoint Reference

Method Endpoint Path Auth / Role Guard Purpose
GET /api/v1/health Public Liveness, is_sealed state, active storage backend, and ct_tree_size.
GET /api/v1/metrics Admin / Delegated Prometheus / OpenMetrics counters and 24h / 7d / 30d certificate expiry buckets.
GET /api/v1/openapi.json Public Complete machine-readable OpenAPI 3.1.0 specification.
GET /.well-known/openid-configuration Public OpenID Connect 1.0 Discovery document.
GET /.well-known/jwks.json Public RFC 8037 Ed25519 (OKP) JSON Web Key Set.
POST /api/v1/auth/login Public (Rate-Limited) Verifies PBKDF2 password + TOTP MFA and mints EdDSA session JWT.
POST /api/v1/oidc/authorize Bearer / Credentials Issues single-use OIDC Authorization Code bound to S256 PKCE challenge.
POST /api/v1/oidc/token PKCE / RFC 8693 STS Exchanges PKCE code + verifier for JWTs, or exchanges OIDC JWT for Fulcio X.509 cert.
POST /api/v1/tokens/enroll Global / Delegated Admin Mints SAN-locked vca_enroll_* (one-time) or vca_pat_* (reusable) machine tokens.
GET /api/v1/self/profile Interactive Bearer Returns caller identity, RBAC role, org_id, spiffe_id, and ISO 18004 TOTP QR SVG.
POST /api/v1/self/mint-bundle Bearer / Enroll Token Atomically mints X.509 v3 mTLS + OpenSSH User cert + vnet_tok_ mesh bundle.
POST /api/v1/self/x509-sign Bearer / Enroll Token Zero-escrow PKCS#10 CSR sanitizer & signer returning 3-tier certificate_chain_pem.
POST /api/v1/self/ssh-sign Bearer / Enroll Token Zero-escrow OpenSSH .pub key signer (user or host certificate).
POST /api/v1/self/renew Bearer Re-signs an active certificate with a new serial number and validity window.
POST /api/v1/self/keyless-sign Interactive Bearer Mints 10-minute Fulcio-style code-signing X.509 v3 certificate + Merkle SCT.
POST /api/v1/inspect Public / Bearer Decodes ASN.1 DER TLV or OpenSSH PROTOCOL.certkeys wire byte offsets.
GET /api/v1/ca Interactive Bearer Lists Root X.509, Intermediate X.509, OpenSSH User, and OpenSSH Host authorities.
GET /api/v1/ca/roots Public Exports Root & Intermediate X.509 CA PEM trust bundle.
POST /api/v1/ca/intermediate Global Admin Provisions a NameConstraints-scoped Intermediate X.509 v3 CA.
POST /api/v1/ca/seal Global Admin Zeros master.kek and unsealed CA keys in RAM immediately (is_sealed = true).
POST /api/v1/ca/cross-sign Global Admin Issues a cross-signed Root CA rollover bridge certificate (G1 -> G2).
GET/POST /api/v1/ceremonies Global Admin Lists or advances durable M-of-N Shamir quorum ceremonies.
POST /api/v1/ceremonies/unseal M-of-N Shamir Shares Reconstructs master.kek over GF(2^8) and unseals the authority in RAM.
GET /api/v1/certificates Interactive Bearer Lists certificates scoped to caller ownership, org_id, or global view.
POST /api/v1/certificates/revoke Owner / Org / Global Admin Revokes a certificate with an RFC 5280 reason code.
GET /api/v1/x509/crl Public (?format=pem) Signs and serves RFC 5280 X.509 CRL v2 (JSON or application/pkix-crl PEM).
POST /api/v1/x509/ocsp Public Signs and returns RFC 6960 OCSP status (good, revoked, or unknown).
GET /api/v1/ssh/krl Public (?format=raw) Serves OpenSSH Key Revocation List (JSON or binary SSHKRL\n\0 stream).
GET /api/v1/ssh/ca-keys Public Exports OpenSSH TrustedUserCAKeys and @cert-authority lines.
GET /api/v1/ssh/allowed-signers Public Exports OpenSSH allowed_signers trust bundle for artifact signature verification.
POST /api/v1/tsa/timestamp Interactive Bearer Signs an RFC 3161 ASN.1 DER TSTInfo Timestamp Token.
POST /api/v1/tsa/verify Public Verifies an RFC 3161 Timestamp Token against an artifact SHA-256 hex digest.
GET/POST /api/v1/profiles Global / Delegated Admin Lists or creates ABAC certificate profiles within caller scope.
GET/POST /api/v1/users Global / Delegated Admin Lists or provisions principals within caller scope.
GET /api/v1/ct/v1/get-sth Public Signs and returns the RFC 6962 Merkle Signed Tree Head (STH).
GET /api/v1/ct/v1/get-proof-by-index Public Computes and verifies the O(log N) Merkle inclusion proof for ?index=N.
POST /api/v1/soar/quarantine Vsight-HMAC / Global Admin Atomically revokes all credentials of a compromised principal and emits RFC 5424 syslog.
GET /api/v1/audit Global / Delegated Admin Verifies SHA-256 hash-chain and Ed25519 signature integrity across audit logs.
GET/POST /api/v1/admin/backup, /restore, /compliance-bundle Global Admin Exports/restores encrypted VCA_BACKUP_V2 snapshots and signed SOC2 dossiers.
GET/POST /acme/v2/directory, /new-nonce, /new-acct, /new-order, /chall, /finalize, /cert Public / Enroll Token Stateful RFC 8555 Private ACME v2 automated TLS provisioning endpoints.
GET /.well-known/est/cacerts, /.well-known/est/csrattrs Public RFC 7030 EST base64 PKCS#7 certs-only CA bundle and ASN.1 DER CsrAttrs discovery.
POST /.well-known/est/simpleenroll, /.well-known/est/simplereenroll HTTP Basic / Bearer / Enroll Token RFC 7030 EST zero-escrow PKCS#10 CSR device enrollment and automated re-enrollment returning PKCS#7 certs-only.
GET/POST /scep?operation=GetCACaps|GetCACert|PKIOperation Public (GET) / Auth (POST) RFC 8894 SCEP device discovery and DER PKCS#7 CertRep automated certificate issuance.

Part VII: vca — Performance, Cryptographic Throughput & Sizing Guide

1. Performance Architecture Principles

Short-lived zero-trust credentials (10-minute keyless signing certificates, 1-hour Triple-Credential ZSP bundles, and 4-hour service-mesh mTLS leaves) increase certificate issuance velocity by 100x compared to legacy 1-year PKI deployments. vca sustains high-throughput signing with sub-millisecond read paths through five architectural optimizations:

  1. Native Compiled Execution & Bounded Buffers: Compiles directly to native x86_64/ARM64 machine code with zero external TLS/ASN.1 shared-library marshaling overhead and strict HTTP/1.1 connection caps (10s socket timeouts, 32 KiB header cap, 4 MiB body cap).
  2. Zero-Allocation Definite-Length ASN.1 DER Codec: Encodes canonical ITU-T X.690 DER TBSCertificate, CertificateList, OCSPResponse, and RFC 3161 TSTInfo byte buffers in deterministic linear passes capped at 256 KiB and nesting depth 16.
  3. Accelerated Elliptic-Curve & RSA-CRT Signing:
    • Ed25519 (RFC 8032 / RFC 8410) executes deterministic signature generation in tens of microseconds and is recommended as the primary high-velocity algorithm for Root/Intermediate X.509 CAs, OpenSSH User/Host CAs, Merkle CT STH signatures, and OIDC JWTs.
    • ECDSA NIST P-256 (secp256r1) uses a constant-time 256-step Jacobian Montgomery ladder (Z-projective coordinates avoiding per-step modular inversions) paired with RFC 6979 deterministic HMAC-SHA256 nonces.
    • RSA-2048 / RSA-4096 (RFC 8017) uses 9-integer Chinese Remainder Theorem (RSA-CRT) private-key acceleration with cryptographic blinding and Bellcore fault-injection verification before emitting signatures.
  4. Immutable Power-of-Two Merkle Subtree Cache: Complete binary subtrees in the RFC 6962 Certificate Transparency log are cached immutably on append, reducing both Signed Tree Head (STH) root computation and inclusion proof generation from $O(N)$ to $O(\log_2 N)$ SHA-256 hashes.
  5. 64-Shard MVCC Store + Segmented LZ4 WAL: Hot queries (OCSP, JWKS, get-sth, get-proof-by-index, profile lookups) execute in memory across 64 FNV-1a shards with {org_id} shard affinity, while mutations append 32-byte IEEE CRC32 binary WAL frames with LZ4-compressed .snap checkpoints.

2. Cryptographic Signing, DER & Issuance Benchmarks

Representative single-node production (-prod) measurements on an 8-vCPU / 16 GiB x86_64 server (vprevail 64-shard MVCC + NVMe WAL):

Subsystem / Operation Cryptographic / Codec Work Median Latency (p50) Tail Latency (p99) Sustained Single-Node Throughput
ASN.1 DER TBSCertificate Encode + Parse Definite-length TLV build + RDN sort + bounds check 0.04 ms 0.11 ms > 85,000 ops/s
X.509 v3 Leaf Issuance (Ed25519 + Merkle SCT) CSR PoP verify + DER build + Ed25519 sign + CT append + WAL 0.42 ms 1.15 ms ~ 7,800 certs/s
X.509 v3 Leaf Issuance (ECDSA-P256 + Merkle SCT) CSR PoP verify + Jacobian P-256 sign + CT append + WAL 1.35 ms 3.10 ms ~ 2,400 certs/s
X.509 v3 Leaf Issuance (RSA-2048 CRT + Merkle SCT) CSR PoP verify + Blinded RSA-CRT + Bellcore verify + WAL 2.80 ms 6.40 ms ~ 1,150 certs/s
OpenSSH User/Host Cert Sign (Ed25519) PROTOCOL.certkeys pack + option sort + Ed25519 sign + WAL 0.28 ms 0.79 ms > 11,200 certs/s
Triple-Credential ZSP Bundle (POST /api/v1/self/mint-bundle) ABAC eval + X.509 Ed25519 + SSH Ed25519 + vnet_tok_ + CT + WAL 0.86 ms 2.25 ms ~ 3,900 bundles/s
RFC 3161 Timestamp Token (POST /api/v1/tsa/timestamp) DER TSTInfo encode + Ed25519 sign 0.21 ms 0.58 ms > 15,000 tokens/s
RFC 6960 Live OCSP Responder (POST /api/v1/x509/ocsp) Serial index lookup + DER OCSP sign 0.19 ms 0.54 ms > 16,500 req/s
Merkle CT STH & Inclusion Proof (N = 100,000 leaves) Cached $O(\log_2 N)$ SHA-256 path (17 hashes) + Ed25519 STH 0.15 ms 0.45 ms > 21,000 proofs/s
Interactive Password Login (PBKDF2-HMAC-SHA256) 10,000-round salted PBKDF2 + TOTP + EdDSA JWT mint 4.20 ms 8.90 ms ~ 850 logins/s (rate-limited per account)

3. Merkle CT Tree Scaling & WAL Recovery Metrics

Corpus Scale (Issued Certificates & CT Leaves) On-Disk LZ4 .snap Size Active RAM Footprint Cold-Start Snapshot + WAL Recovery Time Merkle Inclusion Proof Depth ($\lceil \log_2 N \rceil$)
10,000 credentials ~ 3.8 MiB ~ 28 MiB ~ 18 ms 14 SHA-256 sibling nodes (448 B)
100,000 credentials ~ 36 MiB ~ 195 MiB ~ 145 ms 17 SHA-256 sibling nodes (544 B)
1,000,000 credentials ~ 350 MiB ~ 1.65 GiB ~ 1.35 s 20 SHA-256 sibling nodes (640 B)

4. Production Sizing & Algorithm Selection Guidelines

  1. Default to Ed25519 for Internal mTLS, SSH, and ZSP Leases:

Ed25519 produces compact 64-byte signatures and 32-byte public keys, runs over 3x faster than ECDSA-P256 and 6x faster than RSA-2048, and is natively supported by TLS 1.3 stacks, Go/Rust/V services, and OpenSSH 6.5+.

  1. Use ECDSA-P256 Intermediate CAs for Browser & LegacyFIPS TLS Gateways:

Provision a dedicated ECDSA-P256 Scoped Intermediate CA (--alg ECDSA-P256) when issuing certificates consumed by legacy Java, Windows SChannel, or browser clients that expect ecdsa-with-SHA256.

  1. Place --data-dir on Local NVMe SSDs:

Segmented .log WAL appends (64 MiB segment rotation) and atomic .snap checkpoints achieve lowest p99 tail latency on local NVMe storage. For multi-node high availability, run --mode vprevail_cluster against a replicated vprevail quorum.

  1. Automate CRL / SSHKRL Edge Caching:

Edge load balancers and SSH bastions should poll GET /api/v1/x509/crl?format=pem and GET /api/v1/ssh/krl?format=raw every 60–300 seconds, reserving synchronous POST /api/v1/x509/ocsp queries for high-value administrative endpoints.