upki-ca 0.1.5

uPKI Certificate Authority server

uPKI CA Server

Certificate Authority (CA) Server for the uPKI Public Key Infrastructure system. Manages the full certificate lifecycle and exposes PKI operations to Registration Authorities over a ZeroMQ protocol.

Overview

The uPKI CA Server is the trust anchor of the uPKI ecosystem. It runs as a persistent background process listening on two dedicated ZMQ ports:

• Port 5000 — CA operations: certificate signing, renewal, revocation, CRL generation, OCSP checks
• Port 5001 — RA registration: initial handshake to onboard a new Registration Authority

It is designed to operate standalone or in a containerised stack together with uPKI RA Server and uPKI CLI.

Architecture

graph TB
    subgraph "Clients"
        CLI[uPKI CLI]
        ACME[ACME Clients<br/>cert-manager, Traefik]
    end

    subgraph "uPKI RA Server"
        RA[Registration Authority<br/>Port 8000]
    end

    subgraph "uPKI CA Server"
        direction TB
        CA_OPS[CA Listener<br/>Port 5000]
        RA_REG[Register Listener<br/>Port 5001]

        subgraph "Core"
            Auth[Authority]
            Profiles[Profiles]
        end

        subgraph "Storage"
            FileDB[(TinyDB +<br/>Filesystem)]
        end
    end

    CLI -->|HTTPS + mTLS| RA
    ACME -->|HTTPS| RA

    RA -->|ZMQ REQ/REP| CA_OPS
    RA -->|ZMQ REQ/REP| RA_REG

    CA_OPS --> Auth
    RA_REG --> Auth
    Auth --> Profiles
    Auth --> FileDB

Key Features

• Certificate Lifecycle — Sign, renew, revoke, and delete certificates via ZMQ commands
• CRL Management — Generate and serve Certificate Revocation Lists on demand
• OCSP Checks — Real-time certificate status verification
• Certificate Profiles — Built-in and custom profiles with configurable key type, validity, extensions, and SANs
• RA Registration — Seed-based handshake to securely onboard Registration Authorities
• Import Existing CA — Bootstrap from an existing key/certificate pair (--ca-key / --ca-cert)
• Docker Auto-bootstrap — Single start command initialises the PKI on first boot then runs both listeners
• Multiple Storage Backends — File-based storage (default, powered by TinyDB) with a MongoDB interface stub

Requirements

• Python 3.11+
• Poetry (package manager)
• cryptography library

Installation

From PyPI

pip install upki-ca

From Source

git clone https://github.com/circle-rd/upki-ca.git
cd upki-ca
poetry install

Development Installation

poetry install --with dev,lint

CLI Usage

The main entry point is ca_server.py. All commands accept --path <dir> to override the default storage location (~/.upki/ca).

Initialize the PKI

Creates the CA key and certificate on first run. Idempotent on subsequent runs.

# Generate a fresh CA
poetry run python ca_server.py init

# Import an existing CA key and certificate
poetry run python ca_server.py init --ca-key ca.key --ca-cert ca.crt

# Import a password-protected key
poetry run python ca_server.py init --ca-key ca.key --ca-cert ca.crt --ca-password-file /run/secrets/ca_pass

A registration seed is printed on first init. Keep it secure — the RA operator will need it.

Register a Registration Authority

Starts the registration listener (port 5001, clear mode) and waits for the RA to complete the handshake.

poetry run python ca_server.py register

Start the CA Server

Starts the CA listener (port 5000, TLS mode). The RA must already be registered.

# Default: tcp://127.0.0.1:5000
poetry run python ca_server.py listen

# Custom bind address
poetry run python ca_server.py listen --host 0.0.0.0 --port 5000

Auto-bootstrap (Docker / Production)

Initialises the PKI on the first boot (or skips it if already done), then runs both listeners concurrently. This is the default Docker entrypoint.

poetry run python ca_server.py start

Configuration

On first run, ca_server.py init creates ca.config.yml in the storage directory with the following defaults:

company: "Company Name"
domain: "example.com"
host: "127.0.0.1"
port: 5000 # CA listener; registration listener uses port + 1
clients: "register" # all | register | manual
password: null # CA private key password (null = no encryption)
seed: null # RA registration seed (auto-generated if absent)
key_type: "rsa" # rsa | dsa
key_length: 4096
digest: "sha256" # md5 | sha1 | sha256 | sha512
crl_validity: 7 # CRL validity in days

Environment Variables

When running via Docker or systemd, configuration can be injected without editing the config file:

Variable	Description
UPKI_DATA_DIR	Override the storage path (--path equivalent)
UPKI_CA_SEED	Registration seed (used by start on first boot)
UPKI_CA_HOST	Bind address for both ZMQ sockets (default 0.0.0.0)
UPKI_CA_KEY_FILE	Path to an existing CA private key to import
UPKI_CA_CERT_FILE	Path to an existing CA certificate to import

Certificate Profiles

Profiles are stored as YAML files under ~/.upki/ca/profiles/. The following built-in profiles are created automatically at initialisation:

Profile	Type	Default Validity	Key Usage
ca	sslCA	10 years	keyCertSign, cRLSign
ra	sslCA	1 year	digitalSignature, keyEncipherment
server	server	60 days	serverAuth
webapp	server	60 days	serverAuth, clientAuth
laptop	user	30 days	clientAuth, emailProtection
user	user	30 days	clientAuth
admin	user	1 year	clientAuth

Custom profiles can be added by dropping a YAML file in the profiles/ directory.

Docker Deployment

Using Docker Run

docker run -d \
  --name upki-ca \
  -p 5000:5000 \
  -p 5001:5001 \
  -v upki_data:/data \
  -e UPKI_DATA_DIR=/data \
  -e UPKI_CA_SEED=<your-seed> \
  ghcr.io/circle-rd/upki-ca:latest

Using Docker Compose

services:
  upki-ca:
    image: ghcr.io/circle-rd/upki-ca:latest
    ports:
      - "5000:5000"
      - "5001:5001"
    volumes:
      - upki_data:/data
    environment:
      UPKI_DATA_DIR: /data
      UPKI_CA_SEED: ${CA_SEED}
    restart: unless-stopped

volumes:
  upki_data:

Build from Source

docker build -t upki-ca:latest .

Project Organization

upki-ca/
├── ca_server.py              # Main entry point (CLI)
├── pyproject.toml            # Poetry configuration
├── Dockerfile                # Docker image definition
├── docs/
│   ├── CA_ZMQ_PROTOCOL.md   # ZMQ protocol specification
│   └── SPECIFICATIONS_CA.md # CA specifications
├── upki_ca/
│   ├── ca/
│   │   ├── authority.py      # Core CA singleton (sign, revoke, renew…)
│   │   ├── cert_request.py   # CSR parsing and validation
│   │   ├── private_key.py    # Private key generation / import
│   │   └── public_cert.py    # Certificate building and serialisation
│   ├── connectors/
│   │   ├── listener.py       # Base ZMQ REP socket
│   │   ├── zmq_listener.py   # CA operations dispatcher (port 5000)
│   │   └── zmq_register.py   # RA registration handler (port 5001)
│   ├── core/
│   │   ├── common.py         # Base class with shared utilities
│   │   ├── options.py        # Allowed values, profiles, durations
│   │   ├── upki_error.py     # Custom exception hierarchy
│   │   ├── upki_logger.py    # Logging setup
│   │   └── validators.py     # Input validation (DN fields, SANs…)
│   ├── storage/
│   │   ├── abstract_storage.py # Storage interface
│   │   ├── file_storage.py     # TinyDB + filesystem (default)
│   │   └── mongo_storage.py    # MongoDB stub (not yet implemented)
│   └── utils/
│       ├── config.py           # YAML config loader / writer
│       └── profiles.py         # Profile management
└── tests/
    ├── test_00_common.py
    ├── test_10_config.py
    ├── test_10_validators.py
    ├── test_20_ca_server.py
    ├── test_20_profiles.py
    └── test_100_pki_functional.py

CA ZMQ Operations

The CA exposes the following commands on port 5000. See docs/CA_ZMQ_PROTOCOL.md for the full message format.

Command	Description
get_ca	Retrieve the CA certificate
get_crl	Retrieve the current CRL
generate_crl	Force CRL regeneration
generate	Generate a key pair and sign a cert
sign	Sign an external CSR
renew	Renew an existing certificate
revoke	Revoke a certificate
unrevoke	Remove a certificate from the CRL
delete	Delete a certificate record
view	Retrieve certificate details
ocsp_check	Check the revocation status of a cert

Development

Running Tests

poetry run pytest tests/

Code Style

poetry run ruff check .
poetry run ruff format .

Related Projects

• uPKI RA Server — Registration Authority, bridges clients to this CA
• uPKI CLI — Client application for certificate enrolment and renewal

License

MIT License