PiTrust PKI & Zero-Trust mTLS

PiTrust CAZero-Trust mTLSKubernetes OperatorAir-Gapped Ready

PiTrust is PiLab’s modern, cloud-native Certificate Authority (CA) and PKI management system built in Go. It powers zero-trust mutual TLS (mTLS) authentication, X.509 certificate lifecycle management, and real-time validation across all PiVirt daemons (pivirtd, agent, director, iscsiman) and Kubernetes clusters.

Architecture Overview

PiTrust uses a hierarchical 2-tier PKI model with automated signing, embedded SQLite tracking, OCSP real-time revocation, and a Kubernetes Operator for declarative lifecycle management:

flowchart TB
    subgraph Root["Trust Anchor"]
        RCA["PiTrust Root CA<br/>(4096-bit RSA)"]
        ICA["PiTrust X1 Intermediate CA<br/>(2048-bit RSA)"]
        RCA --> ICA
    end

    subgraph PiTrustServer["PiTrust CA Server (Go)"]
        API["ConnectRPC / gRPC API<br/>(:8080)"]
        OCSP["OCSP Responder & CRL"]
        DB[("certs.db<br/>(SQLite Store)")]
        ICA --> API
        API --> DB
        OCSP --> DB
    end

    subgraph Workloads["PiVirt Cluster & Workloads"]
        Director["pivirt-director<br/>(Control Plane)"]
        Agent["pivirt-agent<br/>(Node Daemon)"]
        Hypervisor["pivirtd<br/>(Hypervisor)"]
        ISCSIMan["iscsiman<br/>(Storage Manager)"]
    end

    subgraph K8sIntegration["Kubernetes & Operator"]
        CRD["ManagedCertificate CRD<br/>(certz.pilab.hu/v1alpha1)"]
        Operator["PiTrust Operator"]
        Secrets["Kubernetes TLS Secrets"]
        CRD --> Operator
        Operator -->|gRPC Issue| API
        Operator -->|Sync| Secrets
    end

    API -->|Issue mTLS Certs| Director
    API -->|Issue mTLS Certs| Agent
    API -->|Issue mTLS Certs| Hypervisor
    API -->|Issue mTLS Certs| ISCSIMan
    Director <-->|mTLS / ConnectRPC| Agent
    Agent <-->|mTLS / ConnectRPC| Hypervisor
    Agent <-->|mTLS / ConnectRPC| ISCSIMan

Key Capabilities

Hierarchical 2-Tier PKI

Offline-capable Root CA (PiRootR1.pem) and signing X1 Intermediate CA (PiCA.pem) ensuring strict separation of trust.

Zero External Challenges

Unlike ACME / Let’s Encrypt, PiTrust requires no external HTTP or DNS challenges — ideal for private networks and air-gapped datacenters.

Kubernetes Operator & CRD

Declarative ManagedCertificate custom resources automatically provision and renew TLS Secrets 30 days before expiration.

Embedded SQLite & OCSP

Lightweight, single-binary architecture with fast embedded SQLite storage and real-time OCSP status responder.

Certificate Types

Certificate Type	Target Scope	Key Usage	Extended Key Usage
`mtls-server`	`director`, `pivirtd`, `agent` endpoints	Digital Signature, Key Encipherment	`Server Authentication`
`mtls-client`	`pvcli`, node agents, internal RPC callers	Digital Signature	`Client Authentication`
`https`	Director Web UI & Public APIs	Digital Signature, Key Encipherment	`Server Authentication`
`ca-intermediate`	Regional or Cluster Sub-CAs	Cert Sign, CRL Sign	`OCSPSigning`

Deployment & Usage

You can issue client and server certificates directly using the pitrust CLI:

# 1. Issue mTLS Server Certificate for pivirtd host
pitrust issue-mtls-server \
  --name "node-01.pivirt.internal" \
  --dns "node-01.pivirt.internal" \
  --dns "node-01" \
  --ip "192.168.1.10" \
  --organization "PiLab" \
  --days 365

# 2. Issue mTLS Client Certificate for agent
pitrust issue-mtls-client \
  --name "pivirt-agent-node-01" \
  --organization "PiLab" \
  --org-unit "Hypervisors" \
  --days 365

# 3. Verify Certificate Chain
openssl verify -CAfile certs/Root/PiRootR1.pem -untrusted certs/Root/PiCA.pem node-01.pivirt.internal.crt

Deploy declarative ManagedCertificate custom resources in Kubernetes clusters:

apiVersion: certz.pilab.hu/v1alpha1
kind: ManagedCertificate
metadata:
  name: pivirt-director-tls
  namespace: pivirt-system
spec:
  commonName: director.pivirt.svc.cluster.local
  dnsNames:
    - director.pivirt.svc.cluster.local
    - director.pivirt.internal
  type: mtls-server
  secretName: pivirt-director-tls-secret
  duration: "8760h"
  renewBefore: "720h" # Auto-renew 30 days before expiry

Apply the manifest:

kubectl apply -f pivirt-director-tls.yaml
kubectl get managedcertificate -n pivirt-system

Configure pivirt-agent and pivirtd to load PiTrust-issued certificates:

node_id: "node-01"
cluster_id: "prod-cluster"
tls:
  enabled: true
  ca_cert: "/etc/pivirt/certs/ca-chain.pem"
  cert_file: "/etc/pivirt/certs/agent-client.crt"
  key_file: "/etc/pivirt/certs/agent-client.key"
  verify_peer: true
  require_client_cert: true

Operational Verification & Troubleshooting

Real-Time OCSP Status Check

PiTrust includes a built-in OCSP responder for real-time certificate status queries:

# Query OCSP responder on port 8080
openssl ocsp \
  -issuer certs/Root/PiCA.pem \
  -cert /etc/pivirt/certs/agent-client.crt \
  -url http://pitrust.pivirt.internal:8080/ocsp \
  -CAfile certs/Root/PiRootR1.pem

Expected output:

/etc/pivirt/certs/agent-client.crt: good
  This Update: Sep  4 10:00:00 2026 GMT
  Next Update: Sep 11 10:00:00 2026 GMT

Revoking a Compromised Certificate

# Revoke certificate by serial number or file
pitrust revoke --cert /etc/pivirt/certs/compromised-node.crt --reason keyCompromise

# Generate updated CRL
pitrust crl generate --out /var/www/crl/pitrust.crl

System Architecture — Core daemon topologies and ConnectRPC communication.
TLS & Mutual mTLS Configuration — End-to-end TLS encryption guides.
Authentication API — Token and credential management.