flaskpaste/documentation/pki.md

PKI Guide

FlaskPaste includes a built-in Public Key Infrastructure (PKI) for client certificate authentication.

Overview

The PKI system provides:

• Self-contained Certificate Authority (CA)
• Client certificate issuance
• Certificate revocation
• mTLS authentication via reverse proxy

Quick Start with CLI

1. Register and Get a Certificate

# Download CLI
curl -o fpaste https://paste.example.com/client && chmod +x fpaste

# Configure server
./fpaste config server https://paste.example.com

# Register (requires PKI password if set on server)
./fpaste register --configure

# Creates ~/.config/fpaste/{client.key, client.crt} and updates config

2. Use Authenticated Requests

# Create paste (now authenticated)
echo "secret data" | ./fpaste create

# List your pastes
./fpaste list

# Delete a paste
./fpaste delete <id>

Server Setup

Enable PKI

# Set PKI password (required for certificate operations)
export FLASKPASTE_PKI_PASSWORD="your-secure-password"

# Optional: enable public registration
export FLASKPASTE_REGISTRATION_ENABLED=true

# Start server
python run.py

Initialize CA

The CA is auto-generated on first certificate request, or manually:

curl -X POST https://paste.example.com/pki/ca \
  -H "Content-Type: application/json" \
  -d '{"common_name": "My Paste CA"}'

CLI Certificate Management

Check PKI Status

./fpaste pki status

Output:

PKI Status
  CA initialized: yes
  CA fingerprint: a1b2c3d4e5f6...
  CA expires: 2034-12-25
  Issued certs: 5
  Revoked: 1

Download CA Certificate

# Save and configure
./fpaste pki download -o ~/.config/fpaste/ca.crt --configure

# Or just view
./fpaste pki download

Issue Certificate (Admin)

# Requires admin privileges (first registered user)
./fpaste pki issue -n "alice" -o ./alice-certs/ --configure

Revoke Certificate (Admin)

./fpaste pki status  # Get serial number
./fpaste pki revoke <serial>

Self-Signed Certificate (Offline)

Generate a certificate without server interaction:

./fpaste cert -o ~/.config/fpaste/ --configure

# With custom options
./fpaste cert -n "my-client" -a ec -c secp384r1 -d 365

Reverse Proxy Configuration

nginx with mTLS

server {
    listen 443 ssl;
    server_name paste.example.com;

    # Server certificate
    ssl_certificate /etc/ssl/certs/paste.example.com.crt;
    ssl_certificate_key /etc/ssl/private/paste.example.com.key;

    # Client certificate verification
    ssl_client_certificate /etc/ssl/certs/flaskpaste-ca.crt;
    ssl_verify_client optional;

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header X-SSL-Client-SHA1 $ssl_client_fingerprint;
        proxy_set_header X-Proxy-Secret "your-shared-secret";
    }
}

HAProxy with mTLS

frontend https
    bind *:443 ssl crt /etc/ssl/paste.pem ca-file /etc/ssl/flaskpaste-ca.crt verify optional
    http-request set-header X-SSL-Client-SHA1 %{+Q}[ssl_c_sha1]
    http-request set-header X-Proxy-Secret your-shared-secret
    default_backend flaskpaste

backend flaskpaste
    server app 127.0.0.1:5000

Trust Levels

Level	Source	Expiry	Limits
Anonymous	No auth	1 day	3 MiB
Untrusted	Self-signed cert	7 days	50 MiB
Trusted	PKI-issued cert	30 days	50 MiB
Admin	First PKI user	30 days	50 MiB + admin ops

Security Considerations

• Store PKI password securely (environment variable, secrets manager)
• Protect CA private key (encrypted with AES-256-GCM)
• Use strong proxy secret for header trust validation
• Revoke compromised certificates promptly
• Monitor audit logs for AUTH_FAILURE events

API Reference

See api.md for detailed PKI endpoint documentation:

• GET /pki - PKI status
• POST /pki/ca - Generate CA
• GET /pki/ca.crt - Download CA certificate
• POST /pki/issue - Issue client certificate
• GET /pki/certs - List issued certificates
• POST /pki/revoke/{serial} - Revoke certificate
• GET /register/challenge - Get registration PoW challenge
• POST /register - Register for certificate