ssl-provisioning 1.0.0__tar.gz

ssl_provisioning-1.0.0/.github/workflows/pypi.yaml

@@ -0,0 +1,45 @@
+name: Publish to PyPI
+
+# Publishes sslpv to PyPI when a version tag (vX.Y.Z) is pushed.
+# Uses PyPI Trusted Publishing (OIDC) — no API token is stored.
+# One-time setup on PyPI: add this repository and the workflow file name
+# "pypi.yaml" as a trusted publisher for the "sslpv" project.
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      # Required for Trusted Publishing (OIDC token exchange with PyPI).
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.10"
+
+      - name: Verify tag matches pyproject version
+        run: |
+          tag_version="${GITHUB_REF_NAME#v}"
+          pkg_version="$(grep -E '^version *= *' pyproject.toml | head -1 | sed -E 's/.*"([^"]+)".*/\1/')"
+          echo "tag=${tag_version} pyproject=${pkg_version}"
+          if [ "${tag_version}" != "${pkg_version}" ]; then
+            echo "::error::Tag ${tag_version} does not match pyproject.toml version ${pkg_version}"
+            exit 1
+          fi
+
+      - name: Run tests
+        run: uv run pytest -q
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

ssl_provisioning-1.0.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.venv/
+dist/
+build/
+*.pem
+*.crt
+*.key
+config.json
+!config.example.json

ssl_provisioning-1.0.0/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: ssl-provisioning
+Version: 1.0.0
+Summary: SSL certificate provisioning tool: a FastAPI server distributes fullchain/privkey to one-shot CLI clients over an authenticated, end-to-end encrypted channel.
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=42.0
+Requires-Dist: fastapi>=0.110
+Requires-Dist: prompt-toolkit>=3.0
+Requires-Dist: uvicorn>=0.27
+Description-Content-Type: text/markdown
+
+# sslpv
+
+`sslpv` is an SSL certificate provisioning tool. A long-running FastAPI server holds
+the paths to a `fullchain`/`privkey` pair and a set of API keys. A one-shot CLI client
+authenticates with an API key and pulls the current certificate and private key over an
+authenticated, end-to-end encrypted channel, writing them atomically to local paths.
+
+---
+
+## Installation
+
+The distribution is published on PyPI as `ssl-provisioning`; the installed command
+and import package are both named `sslpv`.
+
+**From PyPI:**
+
+```sh
+pip install ssl-provisioning
+# or, one-shot without a permanent install:
+uvx --from ssl-provisioning sslpv --help
+```
+
+**From a local checkout:**
+
+```sh
+uv pip install .   # or: pip install .
+```
+
+---
+
+## Server
+
+### Starting the server
+
+```sh
+sslpv server --config /path/to/config.json
+```
+
+The server blocks until interrupted (Ctrl-C).
+
+### config.json reference
+
+```json
+{
+  "fullchain": "/etc/letsencrypt/live/example.com/fullchain.pem",
+  "privkey": "/etc/letsencrypt/live/example.com/privkey.pem",
+  "apikeys": ["replace-with-a-long-random-secret", "another-client-key"],
+  "host": "0.0.0.0",
+  "port": 1243,
+  "server_certfile": null,
+  "server_keyfile": null,
+  "trusted_proxies": []
+}
+```
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `fullchain` | string | yes | Path to the PEM fullchain certificate to distribute to clients. |
+| `privkey` | string | yes | Path to the PEM private key to distribute to clients. |
+| `apikeys` | list of strings | yes | One or more API keys that clients may authenticate with. |
+| `host` | string | no | Bind address. Defaults to `"0.0.0.0"`. |
+| `port` | int | no | TCP port to listen on. Defaults to `1243`. |
+| `server_certfile` | string or null | no | TLS certificate for the server itself. Falls back to `fullchain` when null. |
+| `server_keyfile` | string or null | no | TLS private key for the server itself. Falls back to `privkey` when null. |
+| `trusted_proxies` | list of strings | no | IP addresses of trusted reverse proxies whose `X-Forwarded-For` header is used to determine the real client IP for rate limiting. |
+
+### File permissions
+
+The server hard-errors on startup if the config file is readable by group or other.
+Restrict permissions before starting:
+
+```sh
+chmod 600 /path/to/config.json
+chmod 600 /path/to/privkey.pem
+```
+
+---
+
+## Client
+
+```sh
+sslpv client \
+  --server https://example.com:1243 \
+  --key /path/to/apikey.txt \
+  --cert /path/to/fullchain.pem \
+  --privkey /path/to/privkey.pem
+```
+
+### Client flags
+
+| Flag | Required | Description |
+|---|---|---|
+| `--server URL` | yes | Server base URL. Must use `https`. |
+| `--key PATH` | yes | File containing the API key. |
+| `--cert PATH` | yes | Destination path for the retrieved PEM certificate. |
+| `--privkey PATH` | yes | Destination path for the retrieved PEM private key. |
+| `--insecure` | no | Disable TLS certificate verification. Dangerous; see note below. |
+| `--ca-cert PATH` | no | Path to a custom PEM CA bundle for TLS verification. |
+| `--pin-sha256 HEX` | no | Expected SHA-256 hex fingerprint of the server leaf certificate. |
+| `--timeout SECONDS` | no | Per-request timeout in seconds. Default: `30.0`. |
+
+### TLS for self-signed or IP-addressed servers
+
+For servers with self-signed certificates or no matching DNS name, use `--ca-cert` or
+`--pin-sha256` instead of `--insecure`:
+
+```sh
+# Trust a custom CA bundle
+sslpv client --server https://192.0.2.1:1243 --ca-cert /path/to/ca.pem ...
+
+# Pin by SHA-256 fingerprint (colons optional, case-insensitive)
+sslpv client --server https://192.0.2.1:1243 --pin-sha256 ab:cd:ef:... ...
+```
+
+`--insecure` disables all chain and hostname verification and leaves the connection
+vulnerable to MITM attacks. The end-to-end encryption described below still protects
+the payload content, but the identity of the server is not verified.
+
+---
+
+## How it works
+
+### Stateless signed challenge-response authentication
+
+1. The client fetches a signed one-time nonce from `/challenge`.
+2. The client computes an HMAC proof that binds the API key, HTTP method, endpoint path,
+   nonce, issue timestamp, and an ephemeral X25519 public key. The raw API key is never
+   sent over the wire.
+3. The server verifies the proof, checks the nonce has not been spent, and marks the
+   nonce as spent immediately (one-time use).
+
+### End-to-end AES-256-GCM payload encryption
+
+Each response payload (certificate or private key) is encrypted with AES-256-GCM. The
+symmetric key is derived from an X25519 ECDH exchange between a server-side ephemeral
+key and the client's ephemeral key, with the API key mixed in as additional key
+material. Even if the TLS layer is broken or bypassed (e.g. by an on-path attacker
+under `--insecure`), the payload cannot be decrypted or forged without knowledge of the
+API key.
+
+### TLS transport
+
+The server uses uvicorn with `ssl.PROTOCOL_TLS_SERVER` (TLS 1.2 or higher) and a
+modern cipher suite (`ECDHE+AESGCM:ECDHE+CHACHA20`). Use `--ca-cert` or `--pin-sha256`
+on the client when the server certificate is not trusted by the system CA store.
+
+---
+
+## Security model and limitations
+
+- **Availability / DoS**: Protection against on-path denial-of-service is out of scope.
+  Rate limiting is implemented per-IP but an on-path attacker can still disrupt
+  availability.
+- **Single-process requirement**: The server must run with `workers=1` (the default).
+  Nonce deduplication and the rate limiter use in-memory state; multiple workers would
+  allow nonce replay across process boundaries.
+- **API key confidentiality**: Keep API key files restricted to `0600`. A key with group
+  or other read permission will trigger a warning from the client.
+- **Config file confidentiality**: The server rejects a config file with group or other
+  read bits set. Always `chmod 600` the config.

ssl_provisioning-1.0.0/README.md

@@ -0,0 +1,160 @@
+# sslpv
+
+`sslpv` is an SSL certificate provisioning tool. A long-running FastAPI server holds
+the paths to a `fullchain`/`privkey` pair and a set of API keys. A one-shot CLI client
+authenticates with an API key and pulls the current certificate and private key over an
+authenticated, end-to-end encrypted channel, writing them atomically to local paths.
+
+---
+
+## Installation
+
+The distribution is published on PyPI as `ssl-provisioning`; the installed command
+and import package are both named `sslpv`.
+
+**From PyPI:**
+
+```sh
+pip install ssl-provisioning
+# or, one-shot without a permanent install:
+uvx --from ssl-provisioning sslpv --help
+```
+
+**From a local checkout:**
+
+```sh
+uv pip install .   # or: pip install .
+```
+
+---
+
+## Server
+
+### Starting the server
+
+```sh
+sslpv server --config /path/to/config.json
+```
+
+The server blocks until interrupted (Ctrl-C).
+
+### config.json reference
+
+```json
+{
+  "fullchain": "/etc/letsencrypt/live/example.com/fullchain.pem",
+  "privkey": "/etc/letsencrypt/live/example.com/privkey.pem",
+  "apikeys": ["replace-with-a-long-random-secret", "another-client-key"],
+  "host": "0.0.0.0",
+  "port": 1243,
+  "server_certfile": null,
+  "server_keyfile": null,
+  "trusted_proxies": []
+}
+```
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `fullchain` | string | yes | Path to the PEM fullchain certificate to distribute to clients. |
+| `privkey` | string | yes | Path to the PEM private key to distribute to clients. |
+| `apikeys` | list of strings | yes | One or more API keys that clients may authenticate with. |
+| `host` | string | no | Bind address. Defaults to `"0.0.0.0"`. |
+| `port` | int | no | TCP port to listen on. Defaults to `1243`. |
+| `server_certfile` | string or null | no | TLS certificate for the server itself. Falls back to `fullchain` when null. |
+| `server_keyfile` | string or null | no | TLS private key for the server itself. Falls back to `privkey` when null. |
+| `trusted_proxies` | list of strings | no | IP addresses of trusted reverse proxies whose `X-Forwarded-For` header is used to determine the real client IP for rate limiting. |
+
+### File permissions
+
+The server hard-errors on startup if the config file is readable by group or other.
+Restrict permissions before starting:
+
+```sh
+chmod 600 /path/to/config.json
+chmod 600 /path/to/privkey.pem
+```
+
+---
+
+## Client
+
+```sh
+sslpv client \
+  --server https://example.com:1243 \
+  --key /path/to/apikey.txt \
+  --cert /path/to/fullchain.pem \
+  --privkey /path/to/privkey.pem
+```
+
+### Client flags
+
+| Flag | Required | Description |
+|---|---|---|
+| `--server URL` | yes | Server base URL. Must use `https`. |
+| `--key PATH` | yes | File containing the API key. |
+| `--cert PATH` | yes | Destination path for the retrieved PEM certificate. |
+| `--privkey PATH` | yes | Destination path for the retrieved PEM private key. |
+| `--insecure` | no | Disable TLS certificate verification. Dangerous; see note below. |
+| `--ca-cert PATH` | no | Path to a custom PEM CA bundle for TLS verification. |
+| `--pin-sha256 HEX` | no | Expected SHA-256 hex fingerprint of the server leaf certificate. |
+| `--timeout SECONDS` | no | Per-request timeout in seconds. Default: `30.0`. |
+
+### TLS for self-signed or IP-addressed servers
+
+For servers with self-signed certificates or no matching DNS name, use `--ca-cert` or
+`--pin-sha256` instead of `--insecure`:
+
+```sh
+# Trust a custom CA bundle
+sslpv client --server https://192.0.2.1:1243 --ca-cert /path/to/ca.pem ...
+
+# Pin by SHA-256 fingerprint (colons optional, case-insensitive)
+sslpv client --server https://192.0.2.1:1243 --pin-sha256 ab:cd:ef:... ...
+```
+
+`--insecure` disables all chain and hostname verification and leaves the connection
+vulnerable to MITM attacks. The end-to-end encryption described below still protects
+the payload content, but the identity of the server is not verified.
+
+---
+
+## How it works
+
+### Stateless signed challenge-response authentication
+
+1. The client fetches a signed one-time nonce from `/challenge`.
+2. The client computes an HMAC proof that binds the API key, HTTP method, endpoint path,
+   nonce, issue timestamp, and an ephemeral X25519 public key. The raw API key is never
+   sent over the wire.
+3. The server verifies the proof, checks the nonce has not been spent, and marks the
+   nonce as spent immediately (one-time use).
+
+### End-to-end AES-256-GCM payload encryption
+
+Each response payload (certificate or private key) is encrypted with AES-256-GCM. The
+symmetric key is derived from an X25519 ECDH exchange between a server-side ephemeral
+key and the client's ephemeral key, with the API key mixed in as additional key
+material. Even if the TLS layer is broken or bypassed (e.g. by an on-path attacker
+under `--insecure`), the payload cannot be decrypted or forged without knowledge of the
+API key.
+
+### TLS transport
+
+The server uses uvicorn with `ssl.PROTOCOL_TLS_SERVER` (TLS 1.2 or higher) and a
+modern cipher suite (`ECDHE+AESGCM:ECDHE+CHACHA20`). Use `--ca-cert` or `--pin-sha256`
+on the client when the server certificate is not trusted by the system CA store.
+
+---
+
+## Security model and limitations
+
+- **Availability / DoS**: Protection against on-path denial-of-service is out of scope.
+  Rate limiting is implemented per-IP but an on-path attacker can still disrupt
+  availability.
+- **Single-process requirement**: The server must run with `workers=1` (the default).
+  Nonce deduplication and the rate limiter use in-memory state; multiple workers would
+  allow nonce replay across process boundaries.
+- **API key confidentiality**: Keep API key files restricted to `0600`. A key with group
+  or other read permission will trigger a warning from the client.
+- **Config file confidentiality**: The server rejects a config file with group or other
+  read bits set. Always `chmod 600` the config.

ssl_provisioning-1.0.0/config.example.json

@@ -0,0 +1,10 @@
+{
+  "fullchain": "/etc/letsencrypt/live/example.com/fullchain.pem",
+  "privkey": "/etc/letsencrypt/live/example.com/privkey.pem",
+  "apikeys": ["replace-with-a-long-random-secret", "another-client-key"],
+  "host": "0.0.0.0",
+  "port": 1243,
+  "server_certfile": null,
+  "server_keyfile": null,
+  "trusted_proxies": []
+}

ssl_provisioning-1.0.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "ssl-provisioning"
+version = "1.0.0"
+description = "SSL certificate provisioning tool: a FastAPI server distributes fullchain/privkey to one-shot CLI clients over an authenticated, end-to-end encrypted channel."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+dependencies = [
+    "fastapi>=0.110",
+    "uvicorn>=0.27",
+    "prompt_toolkit>=3.0",
+    "cryptography>=42.0",
+]
+
+[project.scripts]
+sslpv = "sslpv.main:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "httpx>=0.27",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sslpv"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

ssl_provisioning-1.0.0/src/sslpv/__init__.py

@@ -0,0 +1,3 @@
+"""sslpv: SSL certificate provisioning server and client."""
+
+__version__ = "1.0.0"

ssl_provisioning-1.0.0/src/sslpv/dependencies.py

@@ -0,0 +1,176 @@
+"""FastAPI dependencies: authentication and rate limiting."""
+
+import base64
+import time
+from typing import Any
+
+from cryptography.hazmat.primitives.asymmetric import x25519
+from fastapi import Depends, HTTPException, Request
+
+from sslpv.utils.crypto import verify_challenge, verify_proof
+
+# Challenge TTL in seconds
+TTL = 60
+
+# Maximum allowed clock skew between client and server
+_CLOCK_SKEW = 5
+
+
+def _parse_auth_header(authorization: str) -> tuple[str, int, str, str]:
+    """Parse a Bearer token of the form ``Bearer v1.<nonce>.<ts>.<sig>.<proof>``.
+
+    Args:
+        authorization(str): Raw Authorization header value.
+
+    Return:
+        parts(tuple): ``(nonce_b64, issue_ts, sig_b64, proof_b64)``.
+
+    Raises:
+        HTTPException: 401 if the header is missing, malformed, or wrong version.
+    """
+    if not authorization or not authorization.startswith("Bearer "):
+        raise HTTPException(401, "unauthorized")
+
+    token = authorization[len("Bearer "):]
+
+    if not token.startswith("v1."):
+        raise HTTPException(401, "unauthorized")
+
+    body = token[len("v1."):]
+    # nonce_b64, issue_ts, sig_b64, proof_b64 — base64 segments never contain '.'
+    parts = body.split(".")
+    if len(parts) != 4:
+        raise HTTPException(401, "unauthorized")
+
+    nonce_b64, ts_str, sig_b64, proof_b64 = parts
+
+    try:
+        issue_ts = int(ts_str)
+    except ValueError:
+        raise HTTPException(401, "unauthorized")
+
+    return nonce_b64, issue_ts, sig_b64, proof_b64
+
+
+def _parse_client_pubkey(header_value: str) -> tuple[bytes, str]:
+    """Decode and validate the X-Client-Pubkey header.
+
+    Args:
+        header_value(str): Base64-encoded 32-byte X25519 public key.
+
+    Return:
+        result(tuple): ``(raw_bytes, b64_string)``.
+
+    Raises:
+        HTTPException: 400 if the header is missing, not valid base64, or not 32 bytes.
+    """
+    try:
+        raw = base64.b64decode(header_value, validate=True)
+    except Exception:
+        raise HTTPException(400, "invalid X-Client-Pubkey header")
+
+    if len(raw) != 32:
+        raise HTTPException(400, "invalid X-Client-Pubkey header")
+
+    try:
+        x25519.X25519PublicKey.from_public_bytes(raw)
+    except Exception:
+        raise HTTPException(400, "invalid X-Client-Pubkey header")
+
+    return raw, header_value
+
+
+def _get_client_ip(request: Request, trusted_proxies: list[str]) -> str:
+    """Determine the real client IP, honouring trusted proxy forwarding.
+
+    Args:
+        request(Request): The incoming FastAPI request.
+        trusted_proxies(list[str]): IP addresses of trusted reverse proxies.
+
+    Return:
+        ip(str): The effective client IP address.
+    """
+    direct_ip = request.client.host if request.client else "unknown"
+    if direct_ip in trusted_proxies:
+        forwarded = request.headers.get("X-Forwarded-For", "")
+        first = forwarded.split(",")[0].strip()
+        if first:
+            return first
+    return direct_ip
+
+
+async def verify_auth(request: Request) -> dict[str, Any]:
+    """FastAPI dependency that authenticates and rate-limits every protected request.
+
+    Authentication steps (order is security-critical):
+    1. Determine real client IP; apply rate limiting.
+    2. Parse Authorization header (Bearer v1 token) and X-Client-Pubkey header.
+    3. Verify challenge signature.
+    4. Verify token freshness (TTL and clock skew).
+    5. Check nonce has not been spent.
+    6. Verify API-key proof (bound to method, path, nonce, pubkey).
+    7. Mark nonce as spent; return auth context.
+
+    All 401 failures return the same message ("unauthorized") to avoid oracles.
+
+    Args:
+        request(Request): The incoming FastAPI request.
+
+    Return:
+        auth(dict): ``{"apikey": str, "client_pubkey": bytes}``.
+
+    Raises:
+        HTTPException: 401 for auth failures, 429 for rate limiting, 400 for bad headers.
+    """
+    config = request.app.state.config
+    server_secret: bytes = request.app.state.server_secret
+    spent_nonces = request.app.state.spent_nonces
+    rate_limiter = request.app.state.rate_limiter
+
+    # Step a: rate limiting
+    ip = _get_client_ip(request, config.trusted_proxies)
+    if not rate_limiter.allow(ip):
+        raise HTTPException(429, "rate limited")
+
+    # Step b: parse Authorization header
+    authorization = request.headers.get("Authorization", "")
+    nonce_b64, issue_ts, sig_b64, proof_b64 = _parse_auth_header(authorization)
+
+    client_pubkey_header = request.headers.get("X-Client-Pubkey", "")
+    if not client_pubkey_header:
+        raise HTTPException(400, "invalid X-Client-Pubkey header")
+    client_pubkey_raw, client_pubkey_b64 = _parse_client_pubkey(client_pubkey_header)
+
+    # Step c: verify challenge signature
+    if not verify_challenge(server_secret, nonce_b64, issue_ts, sig_b64):
+        raise HTTPException(401, "unauthorized")
+
+    # Step d: check expiry and clock skew
+    now = int(time.time())
+    if now - issue_ts > TTL:
+        raise HTTPException(401, "unauthorized")
+    if issue_ts > now + _CLOCK_SKEW:
+        raise HTTPException(401, "unauthorized")
+
+    # Step e: check spent nonce
+    if spent_nonces.contains(nonce_b64):
+        raise HTTPException(401, "unauthorized")
+
+    # Step f: verify proof (bound to method, path, nonce, pubkey, apikey)
+    matched_apikey = verify_proof(
+        proof_b64,
+        config.apikeys,
+        request.method,
+        request.url.path,
+        nonce_b64,
+        issue_ts,
+        client_pubkey_b64,
+    )
+    if matched_apikey is None:
+        # Do NOT mark the nonce as spent — the attacker has not authenticated
+        raise HTTPException(401, "unauthorized")
+
+    # Step g: mark nonce spent and return auth context
+    spent_nonces.add(nonce_b64, expiry=issue_ts + TTL)
+
+    return {"apikey": matched_apikey, "client_pubkey": client_pubkey_raw}