jarianc/certauth
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
certauth/PLAN.md

13 KiB
Raw Blame History

Certificate Authority Infrastructure Plan

Overview

Build a secure, self-contained Certificate Authority (CA) infrastructure on an isolated Ubuntu machine (192.168.8.248) using two YubiKeys for hardware-secured key storage, with a web-based Key Vault UI for certificate management.

Architecture

┌─────────────────────────────────────────────────────┐
│              certauth Machine (192.168.8.248)        │
│                                                      │
│  ┌──────────────┐      ┌──────────────┐             │
│  │  YubiKey #1  │      │  YubiKey #2  │             │
│  │  Root CA Key │      │ Intermediate │             │
│  │  (PIN+Touch) │      │  CA Key      │             │
│  └──────┬───────┘      │  (PIN+Touch) │             │
│         │               └──────┬───────┘             │
│         │                      │                     │
│    Root Certificate       Intermediate Cert          │
│    (signed on YK1)        (signed by Root)           │
│                                    │                 │
│                          ┌─────────▼─────────┐      │
│                          │  Certificate API  │      │
│                          │  + Key Vault UI   │      │
│                          └─────────┬─────────┘      │
│                                    │                 │
│                          ┌─────────▼─────────┐      │
│                          │  Certificate DB   │      │
│                          │  (SQLite/Postgres) │      │
│                          └───────────────────┘      │
│                                                      │
│  Firewall: Only local network (192.168.8.0/24)      │
│  No outbound internet except Ubuntu package updates  │
└─────────────────────────────────────────────────────┘

Phase 1: Machine Hardening

1.1 Base System Configuration

  • Fresh Ubuntu Server installation verification
  • Create dedicated certauth user with sudo privileges
  • Disable root login, enforce key-based SSH
  • Configure SSH to only accept connections from local network (192.168.8.0/24)
  • Set up UFW firewall:
    • Allow SSH (port 22) from 192.168.8.0/24 only
    • Allow HTTPS (port 443) for Key Vault UI from 192.168.8.0/24 only
    • Allow HTTP (port 80) for redirect from 192.168.8.0/24 only
    • Deny all other inbound traffic
    • Deny all outbound traffic except:
      • Ubuntu package repositories (archive.ubuntu.com, security.ubuntu.com)
      • DNS (port 53)
      • NTP (port 123)
      • Local network traffic (192.168.8.0/24)

1.2 System Hardening

  • Automatic security updates enabled
  • Fail2ban for SSH protection
  • Auditd for security auditing
  • Remove unnecessary packages and services
  • ConfigureAppArmor profiles
  • Set up encrypted swap
  • Configure secure kernel parameters (sysctl)

1.3 YubiKey Preparation

  • Install yubikey-manager, pcscd, opensc, gnutls-bin
  • Verify YubiKey connectivity and PIV applet
  • Test both YubiKeys are recognized

Phase 2: YubiKey #1 - Root CA

2.1 YubiKey Configuration

  • Set PIV PIN (strong, 9-16 chars)
  • Set PIV PUK (for PIN reset)
  • Set management key
  • Configure touch policy to callback or fixed-on for the signing key slot
  • Generate RSA 4096-bit (or EC P-384) key pair on the YubiKey (never leaves device)
  • Key stored in PIV slot 9c (signing)

2.2 Root Certificate Generation

  • Generate self-signed Root CA certificate on YubiKey
  • Validity: 20-30 years
  • Key usage: Certificate Signing, CRL Signing
  • Basic constraints: CA:TRUE, pathlen:1
  • Subject: CN=certauth Root CA, O=Home, C=US (customizable)
  • Store Root CA certificate in /etc/ssl/ca/root/

2.3 Security

  • Root CA certificate is public and stored on disk
  • Root private key never leaves YubiKey #1
  • YubiKey #1 can be physically removed and stored offline when not in use
  • All signing operations require PIN + physical touch

Phase 3: YubiKey #2 - Intermediate CA

3.1 YubiKey Configuration

  • Set PIV PIN (strong, 9-16 chars, different from YK1)
  • Set PIV PUK
  • Set management key
  • Configure touch policy to callback or fixed-on for signing key slot
  • Generate RSA 4096-bit (or EC P-384) key pair on the YubiKey
  • Key stored in PIV slot 9c (signing)

3.2 Intermediate Certificate Generation

  • Generate CSR on YubiKey #2
  • Sign CSR using YubiKey #1 (Root CA) — requires PIN + touch on YK1
  • Validity: 10-15 years
  • Key usage: Certificate Signing, CRL Signing
  • Basic constraints: CA:TRUE, pathlen:0
  • Subject: CN=certauth Intermediate CA, O=Home, C=US
  • Store Intermediate CA certificate in /etc/ssl/ca/intermediate/

3.3 Security

  • Intermediate private key never leaves YubiKey #2
  • All signing operations require PIN + physical touch
  • Certificate chain: Root CA → Intermediate CA → Leaf Certificates

Phase 4: Certificate Management API & Key Vault UI

4.1 Technology Stack

  • Backend: Python FastAPI (lightweight, async, good OpenAPI support)
  • Database: SQLite (simple, file-based, sufficient for this scale)
  • Frontend: HTMX + Tailwind CSS (minimal JS, server-rendered, fast)
  • Reverse Proxy: Caddy (automatic HTTPS, simple config)
  • Process Manager: systemd

4.2 API Endpoints

Authentication:
  POST /api/auth/login          - Admin login (username + password + TOTP)
  POST /api/auth/logout         - Logout
  GET  /api/auth/verify         - Verify API key

Domain Management:
  POST /api/domains             - Register a new domain (e.g., *.example.com)
  GET  /api/domains             - List all registered domains
  GET  /api/domains/{id}        - Get domain details
  DELETE /api/domains/{id}      - Revoke domain registration

Certificate Management:
  POST /api/certs/request       - Request a new certificate for a domain
  GET  /api/certs               - List all certificates
  GET  /api/certs/{id}          - Get certificate details
  GET  /api/certs/{id}/download - Download certificate + chain
  POST /api/certs/{id}/revoke   - Revoke a certificate
  POST /api/certs/{id}/renew    - Renew a certificate

Health & Status:
  GET  /api/health              - Health check
  GET  /api/yubikeys            - YubiKey status (connected, slots)

4.3 Key Vault UI Features

  • Dashboard showing certificate inventory, expiring certs, YubiKey status
  • Domain registration form with validation
  • Certificate request workflow:
    1. Select registered domain
    2. Specify SANs (Subject Alternative Names)
    3. Choose validity period
    4. Confirm request (triggers signing workflow)
  • Certificate signing workflow:
    1. System generates CSR locally
    2. Admin inserts YubiKey #2, enters PIN, touches YubiKey
    3. Certificate is signed and stored
    4. Certificate + chain available for download
  • Certificate download page with PEM files
  • Audit log viewer
  • Settings page for CA configuration

4.4 Signing Workflow (Human-in-the-Loop)

Since YubiKey requires physical touch + PIN, the signing process is semi-interactive:

1. Admin requests certificate via UI/API
2. System generates CSR and stores pending request
3. Admin runs: certauth sign --request <id>
   - This prompts for YubiKey #2 PIN
   - Admin touches YubiKey #2 when prompted
   - Certificate is signed by Intermediate CA
4. Signed certificate stored in database
5. Status updated to "issued"
6. Certificate available for download

Alternative: Web-based signing using WebAuthn/CTAP2 (future enhancement)

4.5 API Key Authentication

  • Admin generates API keys via UI
  • API keys are scoped (read-only, sign, admin)
  • Services authenticate with API key header: X-API-Key: <key>
  • API keys stored hashed in database

Phase 5: Security Hardening

5.1 Application Security

  • All API endpoints require authentication
  • Rate limiting on API endpoints
  • Input validation and sanitization
  • SQL injection prevention (parameterized queries)
  • CSRF protection for UI
  • Content Security Policy headers
  • Secure cookie flags (HttpOnly, Secure, SameSite)

5.2 Data Protection

  • Database encrypted at rest (LUKS encrypted partition)
  • Certificate files stored with restricted permissions (root:certauth, 0640)
  • No secrets in plaintext logs
  • API keys hashed (bcrypt)
  • Passwords hashed (bcrypt)

5.3 Network Security

  • Caddy configured with strong TLS settings
  • Only binds to local network interfaces
  • No services exposed to internet
  • Outbound connections restricted by firewall

5.4 Operational Security

  • Audit logging of all certificate operations
  • Regular backup of certificates and configuration (encrypted)
  • Monitoring for failed authentication attempts
  • Log rotation and retention policy

Phase 6: Setup Script

6.1 Automated Setup Script (setup-certauth.sh)

A single script that can provision a fresh Ubuntu machine:

  • Validates prerequisites (Ubuntu version, YubiKeys present)
  • Runs all hardening steps
  • Configures YubiKeys (interactive prompts for PINs)
  • Generates CA certificates
  • Installs and configures the Certificate API
  • Sets up firewall rules
  • Creates systemd services
  • Outputs configuration summary and credentials

6.2 Configuration File (certauth.conf)

All configurable values in one file:

  • CA subject information
  • Certificate validity periods
  • Network configuration
  • Admin credentials
  • YubiKey PIN policies

6.3 Documentation

  • README with architecture overview
  • OPERATIONS.md with daily usage instructions
  • TROUBLESHOOTING.md with common issues
  • BACKUP.md with backup and restore procedures

Directory Structure

certauth/
├── setup-certauth.sh           # Main setup script
├── certauth.conf               # Configuration file
├── README.md                   # Project documentation
├── OPERATIONS.md               # Operations guide
├── scripts/
│   ├── harden-system.sh        # System hardening
│   ├── configure-yubikey.sh    # YubiKey setup
│   ├── generate-ca.sh          # CA certificate generation
│   ├── install-api.sh          # API installation
│   └── configure-firewall.sh   # Firewall setup
├── api/
│   ├── main.py                 # FastAPI application
│   ├── models.py               # Database models
│   ├── auth.py                 # Authentication
│   ├── signing.py              # Certificate signing logic
│   ├── templates/              # HTML templates
│   ├── static/                 # Static assets
│   └── requirements.txt        # Python dependencies
├── systemd/
│   ├── certauth-api.service    # API service unit
│   └── certauth-sign.timer     # Signing timer unit
├── caddy/
│   └── Caddyfile               # Caddy configuration
├── ssl/
│   └── openssl.cnf             # OpenSSL configuration
└── tests/
    └── test_api.py             # API tests

Implementation Order

  1. Plan Review — You review and approve this plan
  2. Machine Hardening — SSH into machine, verify state, apply hardening
  3. YubiKey Setup — Configure both YubiKeys with Root and Intermediate CAs
  4. API Development — Build the Certificate Management API and UI
  5. Integration — Connect API to YubiKeys for signing
  6. Testing — End-to-end testing of certificate issuance
  7. Setup Script — Create reproducible setup script
  8. Documentation — Final documentation and handover

Security Considerations & Trade-offs

YubiKey Touch Policy

  • callback: Prompts user to touch (most flexible, requires polling)
  • fixed-on: Always requires touch (most secure, slightly slower UX)
  • Recommendation: fixed-on for both keys

Key Algorithm

  • RSA 4096: Wider compatibility, larger keys/certs
  • EC P-384: Smaller, faster, modern
  • Recommendation: RSA 4096 for maximum compatibility with all services/browsers

Signing Workflow

  • Fully automated signing is not possible with YubiKey touch requirement
  • Admin must be present to touch YubiKey and enter PIN
  • This is a feature, not a limitation — it provides human-in-the-loop security
  • For bulk operations, a CLI tool handles batch signing requests

Offline Root CA

  • YubiKey #1 (Root) can be removed after Intermediate CA is created
  • Root is only needed if Intermediate CA key is compromised
  • This provides true offline root CA capability

Questions for Confirmation

  1. Key algorithm: RSA 4096 vs EC P-384? (RSA 4096 recommended for compatibility)
  2. Certificate validity: Root: 25 years, Intermediate: 15 years, Leaf: configurable per-request?
  3. TOTP for admin login: Enable two-factor authentication?
  4. Backup strategy: Encrypted backups to local disk only, or also to network share?
  5. Additional domains: Any specific domains to pre-register beyond *.example.com?
  6. CRL/OCSP: Do we need Certificate Revocation List or OCSP responder? (Adds complexity)
  7. Admin username: Should the admin account be certauth or a different username?