linux_patch_api/configs/CA_SETUP.md

Internal CA Setup Guide

Overview

This document describes how to set up an internal Certificate Authority (CA) for mTLS authentication in the Linux Patch API.

Certificate Requirements

Per SPEC.md:

• CA Type: Internal self-hosted Certificate Authority
• Certificate Type: Unique client certificate per client (1-year validity)
• TLS Version: TLS 1.3 only
• Distribution: Manual certificate distribution
• Rotation: 1-year certificate expiry, manual renewal process

CA Setup Steps

1. Create CA Private Key

# Create CA private key (keep this secure!)
openssl genrsa -aes256 -out ca.key.pem 4096
chmod 600 ca.key.pem

2. Create CA Certificate

# Create self-signed CA certificate
openssl req -x509 -new -nodes -key ca.key.pem -sha256 -days 3650 \
  -out ca.pem \
  -subj "/CN=LinuxPatchAPI CA/O=Internal/C=US"

3. Create Server Certificate

# Create server private key
openssl genrsa -out server.key.pem 2048
chmod 600 server.key.pem

# Create server CSR
openssl req -new -key server.key.pem -out server.csr.pem \
  -subj "/CN=linux-patch-api/O=Internal/C=US"

# Create server certificate (signed by CA)
openssl x509 -req -in server.csr.pem -CA ca.pem -CAkey ca.key.pem \
  -CAcreateserial -out server.pem -days 365 -sha256

# Verify server certificate
openssl x509 -in server.pem -text -noout | grep -E "(Subject:|DNS:)"

4. Create Client Certificate (per client)

# Create client private key
openssl genrsa -out client001.key.pem 2048
chmod 600 client001.key.pem

# Create client CSR
openssl req -new -key client001.key.pem -out client001.csr.pem \
  -subj "/CN=client001/O=Internal/C=US"

# Create client certificate (signed by CA)
openssl x509 -req -in client001.csr.pem -CA ca.pem -CAkey ca.key.pem \
  -CAcreateserial -out client001.pem -days 365 -sha256

# Package client cert + key + CA into PKCS12 (optional, for easier distribution)
openssl pkcs12 -export -in client001.pem -inkey client001.key.pem \
  -certfile ca.pem -out client001.p12

Certificate Deployment

Server Side

Copy certificates to /etc/linux_patch_api/certs/:

mkdir -p /etc/linux_patch_api/certs/
cp ca.pem /etc/linux_patch_api/certs/
cp server.pem /etc/linux_patch_api/certs/
cp server.key.pem /etc/linux_patch_api/certs/
chmod 600 /etc/linux_patch_api/certs/server.key.pem
chmod 644 /etc/linux_patch_api/certs/ca.pem
chmod 644 /etc/linux_patch_api/certs/server.pem

Client Side

Distribute client certificates securely:

1. Client certificate: client001.pem
2. Client private key: client001.key.pem
3. CA certificate: ca.pem

Warning: Never transmit private keys over insecure channels.

Certificate Renewal

Certificates expire after 1 year. Renewal process:

1. Generate new certificate with same key or new key
2. Sign new certificate with CA
3. Distribute new certificate to client/server
4. Restart service to load new certificate

Revocation

Not implemented per SPEC.md. Rely on:

• Certificate expiry (1-year max)
• Physical certificate retrieval on employee departure
• IP whitelist for additional access control

Security Notes

• CA Private Key: Store securely, restrict access
• Client Keys: 600 permissions, user-read-only
• Certificates: 644 permissions (public information)
• Transport: All certificate distribution over secure channels