TLS & Mutual mTLS Configuration

PiVirt enforces TLS 1.3 encryption for data in transit and mutual TLS (mTLS) for authenticated daemon-to-daemon communication across the cluster.

TLS Configuration

Server TLS

# pivirtd config
server:
  grpc_addr: "0.0.0.0:9001"
  tls:
    cert_file: "/etc/pivirtd/tls/server.crt"
    key_file: "/etc/pivirtd/tls/server.key"
    ca_file: "/etc/pivirtd/tls/ca.crt"

Client TLS (pvcli)

# pvcli config
contexts:
  - name: "production"
    endpoint: "pivirtd-prod.pilab.hu:9001"
    tls:
      ca_file: "~/.config/pvcli/ca.crt"
      cert_file: "~/.config/pvcli/client.crt"
      key_file: "~/.config/pvcli/client.key"

mTLS Configuration

Mutual Authentication

# agent config
server:
  connectrpc:
    addr: "0.0.0.0:8443"
    tls:
      cert_file: "/etc/pivirt-agent/tls/server.crt"
      key_file: "/etc/pivirt-agent/tls/server.key"
      ca_file: "/etc/pivirt-agent/tls/ca.crt"
      client_ca_file: "/etc/pivirt-agent/tls/ca.crt"  # Require client certs

PiTrust mTLS Configuration

# agent config
tls:
  enabled: true
  ca_file: "/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

Certificate Management

Generate CA

# Generate CA private key
openssl genrsa -out ca.key 4096

# Generate CA certificate
openssl req -new -x509 -days 3650 -key ca.key -out ca.crt \
  -subj "/CN=PiVirt CA/O=PiLab/C=HU"

Generate Server Certificate

# Generate server private key
openssl genrsa -out server.key 2048

# Generate CSR
openssl req -new -key server.key -out server.csr \
  -subj "/CN=pivirtd.pilab.hu/O=PiLab/C=HU"

# Sign with CA
openssl x509 -req -days 365 -in server.csr -CA ca.crt -CAkey ca.key \
  -CAcreateserial -out server.crt \
  -extfile <(echo "subjectAltName=DNS:pivirtd.pilab.hu,DNS:localhost,IP:127.0.0.1")

Generate Client Certificate

# Generate client private key
openssl genrsa -out client.key 2048

# Generate CSR
openssl req -new -key client.key -out client.csr \
  -subj "/CN=admin@pilab.hu/O=PiLab/C=HU"

# Sign with CA
openssl x509 -req -days 365 -in client.csr -CA ca.crt -CAkey ca.key \
  -CAcreateserial -out client.crt

Verify Certificate

# Verify certificate chain
openssl verify -CAfile ca.crt server.crt

# View certificate details
openssl x509 -in server.crt -text -noout

# Check certificate expiry
openssl x509 -in server.crt -enddate -noout

PiTrust Automated Certificate Management

Automated Rotation via Kubernetes Operator

# ManagedCertificate CRD for automated mTLS issuance and renewal
apiVersion: certz.pilab.hu/v1alpha1
kind: ManagedCertificate
metadata:
  name: pivirt-agent-tls
  namespace: pivirt-system
spec:
  commonName: agent.pivirt.svc.cluster.local
  type: mtls-server
  secretName: pivirt-agent-tls-secret
  duration: "8760h"
  renewBefore: "720h" # Auto-renews 30 days before expiration

Direct CLI Certificate Issuance

# Issue mTLS server cert
pitrust issue-mtls-server --name "pivirtd.pilab.hu" --dns "pivirtd.pilab.hu" --days 365

# Issue mTLS client cert
pitrust issue-mtls-client --name "agent.pilab.hu" --days 365

TLS Versions & Ciphers

Recommended Configuration

# agent config
server:
  connectrpc:
    tls:
      min_version: "1.2"
      cipher_suites:
        - "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"
        - "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"
        - "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384"
        - "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256"

Certificate Pinning

Pin CA Certificate

# Extract CA fingerprint
openssl x509 -in ca.crt -noout -fingerprint -sha256

# Configure pinning in pvcli
pvcli config set-context production \
  --ca-fingerprint "SHA256:abc123..."

Troubleshooting

Certificate Errors

# Check certificate validity
openssl x509 -in server.crt -text -noout | grep -E "(Not Before|Not After)"

# Verify certificate chain
openssl verify -CAfile ca.crt server.crt

# Check SAN (Subject Alternative Name)
openssl x509 -in server.crt -text -noout | grep -A1 "Subject Alternative Name"

Common Issues

Issue	Resolution
Certificate expired	Regenerate certificate or check PiTrust operator
Unknown CA	Install CA certificate in trust store
SAN mismatch	Regenerate certificate with correct SAN
Handshake failure	Check TLS version, cipher suites

Debug TLS

# Test TLS connection
openssl s_client -connect pivirtd.pilab.hu:9001 -CAfile ca.crt

# Debug with verbose output
openssl s_client -connect pivirtd.pilab.hu:9001 -CAfile ca.crt -debug

# Check certificate chain
openssl s_client -connect pivirtd.pilab.hu:9001 -showcerts

Related

• Security Overview
• Authentication
• PiTrust PKI & mTLS