{"id":51609647,"url":"https://github.com/oriolrius/ssh-ca-cosmian-kms","last_synced_at":"2026-07-12T06:02:51.552Z","repository":{"id":368188902,"uuid":"1283882045","full_name":"oriolrius/ssh-ca-cosmian-kms","owner":"oriolrius","description":"OpenSSH Certificate Authority backed by Cosmian KMS — technical reference, Docker PoC (UC1–UC9) and KMS-backed KRL distribution design. The CA private key never touches disk (PKCS#11).","archived":false,"fork":false,"pushed_at":"2026-06-29T12:53:18.000Z","size":959,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-29T13:17:17.887Z","etag":null,"topics":["ansible","certificate-authority","cosmian","devsecops","hsm","infrastructure-security","key-revocation","kms","krl","openssh","pkcs11","pki","ssh","ssh-ca","ssh-certificates","zero-trust"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oriolrius.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-29T10:20:54.000Z","updated_at":"2026-06-29T12:53:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/oriolrius/ssh-ca-cosmian-kms","commit_stats":null,"previous_names":["oriolrius/ssh-ca-cosmian-kms"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/oriolrius/ssh-ca-cosmian-kms","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oriolrius%2Fssh-ca-cosmian-kms","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oriolrius%2Fssh-ca-cosmian-kms/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oriolrius%2Fssh-ca-cosmian-kms/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oriolrius%2Fssh-ca-cosmian-kms/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oriolrius","download_url":"https://codeload.github.com/oriolrius/ssh-ca-cosmian-kms/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oriolrius%2Fssh-ca-cosmian-kms/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35383520,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-12T02:00:06.386Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansible","certificate-authority","cosmian","devsecops","hsm","infrastructure-security","key-revocation","kms","krl","openssh","pkcs11","pki","ssh","ssh-ca","ssh-certificates","zero-trust"],"created_at":"2026-07-12T06:02:50.881Z","updated_at":"2026-07-12T06:02:51.546Z","avatar_url":"https://github.com/oriolrius.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SSH Certificate Authority with Cosmian KMS\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Docs](https://img.shields.io/badge/docs-technical%20reference-blue.svg)](docs/technical-reference.md)\n[![Build PDF](https://github.com/oriolrius/ssh-ca-cosmian-kms/actions/workflows/build-pdf.yml/badge.svg)](https://github.com/oriolrius/ssh-ca-cosmian-kms/actions/workflows/build-pdf.yml)\n[![CI](https://github.com/oriolrius/ssh-ca-cosmian-kms/actions/workflows/ci.yml/badge.svg)](https://github.com/oriolrius/ssh-ca-cosmian-kms/actions/workflows/ci.yml)\n[![Docs](https://github.com/oriolrius/ssh-ca-cosmian-kms/actions/workflows/docs.yml/badge.svg)](https://github.com/oriolrius/ssh-ca-cosmian-kms/actions/workflows/docs.yml)\n[![Security](https://github.com/oriolrius/ssh-ca-cosmian-kms/actions/workflows/security.yml/badge.svg)](https://github.com/oriolrius/ssh-ca-cosmian-kms/actions/workflows/security.yml)\n[![Docker image](https://github.com/oriolrius/ssh-ca-cosmian-kms/actions/workflows/docker.yml/badge.svg)](https://github.com/oriolrius/ssh-ca-cosmian-kms/pkgs/container/ssh-ca-cosmian-kms%2Fkrl-distributor)\n[![Download PDF](https://img.shields.io/badge/download-PDF-red.svg)](https://github.com/oriolrius/ssh-ca-cosmian-kms/releases/download/latest/ssh-ca-technical-reference.pdf)\n\nA practitioner-grade reference for replacing per-host SSH keys with **OpenSSH\ncertificates**, where the Certificate Authority private key lives inside\n[Cosmian KMS](https://github.com/Cosmian/kms) and is used for signing over\n**PKCS#11** — so the CA key never exists as a file on disk.\n\nSSH certificates turn trust management from **O(N×M)** (every user × every host)\ninto **O(N+M)**, while adding expiry, principal-based RBAC, least-privilege\nrestrictions, and a human-attributable audit trail.\n\n\u003e [!IMPORTANT]\n\u003e This repository is **documentation and a proof-of-concept**, not a turnkey\n\u003e product. All keys, fingerprints, hostnames and IPs that appear in the docs are\n\u003e from a disposable lab. No private keys or secrets are committed — see\n\u003e [Security \u0026 privacy](#security--privacy).\n\n## What's inside\n\n| Topic | What it covers |\n|---|---|\n| **Certificate internals** | OpenSSH cert wire format, the 6-step `sshd` verification chain, host vs. user certificates |\n| **Eliminating TOFU \u0026 `authorized_keys`** | Host certificates remove `known_hosts` churn; user certificates remove per-host `authorized_keys` |\n| **RBAC via principals** | `AuthorizedPrincipalsFile` maps role-principals to local accounts |\n| **Least privilege in the cert** | `-O clear`, `force-command`, `source-address`, PTY denial — enforced cryptographically by `sshd` |\n| **Revocation** | Key Revocation Lists (KRL), plus short-TTL certs as the primary mechanism |\n| **KMS-backed CA** | Cosmian KMS + PKCS#11 (`libcosmian_pkcs11.so`); CA key never written to disk |\n| **Automation** | Jan-Piet Mens' Ansible pattern (key generated on the node, signed on the controller via `ssh-agent`) |\n\n## Repository structure\n\n```text\n.\n├── README.md / LICENSE / CLAUDE.md\n├── CONTRIBUTING.md / SECURITY.md / CHANGELOG.md\n├── .github/workflows/      build-pdf · ci · docs · security\n├── docs/\n│   ├── technical-reference.md   Canonical source for the technical reference\n│   ├── media/                   Figures used by the reference (and the PDF)\n│   ├── diagrams/                Editable Mermaid sources for the figures\n│   ├── poc-validation.md        Narrated UC1–UC9 walkthrough\n│   ├── krl-distribution.md      Encrypted, stateless KRL distribution design\n│   └── pdf/                     PDF build pipeline (pandoc + xelatex)\n├── poc/                    One-command Docker PoC (make up \u0026\u0026 make test)\n├── services/krl-distributor/   FastAPI KRL distribution service (KMS-backed)\n├── ansible/                Role automating host-cert issuance (dual-CA + KMS)\n└── examples/               Sanitized sshd_config, auth_principals, cosmian.toml…\n```\n\n## Documentation\n\nThe Markdown files are the **canonical sources**; CI builds a polished PDF of\neach (same look and feel, diagrams inline) and attaches them to the\n[`latest` release](https://github.com/oriolrius/ssh-ca-cosmian-kms/releases/tag/latest).\n\n| Document | Read | Download |\n|---|---|---|\n| **Technical reference** — architecture, crypto internals, configuration, automation | [Markdown](docs/technical-reference.md) | [PDF](https://github.com/oriolrius/ssh-ca-cosmian-kms/releases/download/latest/ssh-ca-technical-reference.pdf) |\n| **PoC validation** — reproducible Docker walkthrough of UC1–UC9 | [Markdown](docs/poc-validation.md) | [PDF](https://github.com/oriolrius/ssh-ca-cosmian-kms/releases/download/latest/ssh-ca-poc-validation.pdf) |\n| **KRL distribution design** — stateless, encrypted REST delivery via KMS | [Markdown](docs/krl-distribution.md) | [PDF](https://github.com/oriolrius/ssh-ca-cosmian-kms/releases/download/latest/ssh-ca-krl-distribution.pdf) |\n\n## Quick start\n\n**Run the whole PoC with one command** (needs Docker and the host's `ssh` /\n`ssh-keygen`):\n\n```bash\ncd poc\nmake up        # build + start the sshd server\nmake test      # run UC1-UC9, each step self-asserting\nmake clean     # tear down\n```\n\nUC1–UC9 exercise the dual CA, host/user certificate signing, TOFU elimination,\nprincipal-based RBAC, PTY denial, force-command, expiry, and KRL revocation. The\ndefault file-based dual-CA path needs **no KMS**. For the production path — CA\nkeys held in Cosmian KMS and used via PKCS#11 so they never touch disk — see\n[`poc/README.md`](poc/README.md) and `poc/scripts/kms-sign.sh`. A narrated,\nstep-by-step version lives in [docs/poc-validation.md](docs/poc-validation.md).\n\n### Installing the Cosmian CLI (for the KMS path)\n\nUse the Ubuntu 22.04 release — the `.deb` and the Ubuntu 24.04 zip require\n`GLIBC_2.38` and won't run on 22.04.\n\n```bash\nwget 'https://github.com/Cosmian/cli/releases/download/1.9.0/ubuntu_22_04-release.zip'\nunzip ubuntu_22_04-release.zip\n\nBASE=\"ubuntu_22_04-release/home/runner/work/cli/cli/target/x86_64-unknown-linux-gnu/release\"\nsudo install -m 755 \"$BASE/cosmian\" /usr/local/bin/\nsudo install -m 755 \"$BASE/libcosmian_pkcs11.so\" /usr/local/lib/\n\ncosmian --version   # cosmian_cli 1.9.0\n```\n\n\u003e [!NOTE]\n\u003e The PKCS#11 provider (`libcosmian_pkcs11.so`) ships in that **zip, not the\n\u003e `.deb`**. If `cosmian --version` works but KMS signing fails, the provider is\n\u003e missing — install it from the zip as shown above.\n\n## Key design decisions\n\n- **ECDSA nistp256 for the CA key** (not Ed25519): PKCS#11 v2.40 — the version\n  most HSMs and KMSs implement — does not define Ed25519 (`CKM_EDDSA` arrived only\n  in PKCS#11 v3.0). ECDSA nistp256 keeps the KMS/HSM door open at 128-bit security.\n  Ed25519 remains the recommended choice for end-entity host/user keys.\n- **Dual-CA architecture**: separate User CA and Host CA to limit blast radius —\n  a compromised user CA cannot forge host identities, and vice versa.\n- **CA key never on disk**: signing goes through `libcosmian_pkcs11.so`, either via\n  `ssh-add -s \u003cmodule\u003e` (so `ssh-keygen` and Ansible's `openssh_cert` work\n  unmodified) or `ssh-keygen -D \u003cmodule\u003e`.\n- **Short certificate TTLs** as the primary revocation mechanism, with KRLs as the\n  emergency path.\n\n## Security \u0026 privacy\n\n- **No secrets are committed.** Generated keys and certificates live only under\n  the git-ignored `poc/run/`. The `.gitignore` blocks key/secret patterns, and\n  **gitleaks** runs both as a pre-commit hook and in CI\n  ([`security.yml`](.github/workflows/security.yml)) over the full history.\n- All identifiers in the docs (CA fingerprints, `server.lab.local`, the\n  `10.222.9.0/24` lab subnet, `192.0.2.x` example addresses) are **disposable lab\n  values**, safe to publish.\n- See [`SECURITY.md`](SECURITY.md) for the project's security posture and how to\n  report a vulnerability. Always generate fresh keys; never reuse demo material.\n\n## Contributing\n\n`docs/technical-reference.md` is the single source of truth — edit the Markdown\ndirectly. The PDF is regenerated by CI on every push to `main` and attached to\nthe [`latest` release](https://github.com/oriolrius/ssh-ca-cosmian-kms/releases/tag/latest).\n\nTo build the PDF locally you need `pandoc`, `xelatex`\n(`texlive-xetex` + `texlive-latex-extra`/`-recommended`), and the Liberation\nand DejaVu fonts:\n\n```bash\ndocs/pdf/build.sh            # writes docs/technical-reference.pdf\n```\n\nThe PDF styling lives in `docs/pdf/` (`template.tex`, `preamble.tex`, and two\nLua filters for table widths and figure centering).\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow and [CHANGELOG.md](CHANGELOG.md) for the history.\n\n## License\n\n[MIT](LICENSE) © 2026 Oriol Rius. Built on the work of\n[Jan-Piet Mens](https://jpmens.net/) and the OpenSSH and Cosmian projects.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foriolrius%2Fssh-ca-cosmian-kms","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foriolrius%2Fssh-ca-cosmian-kms","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foriolrius%2Fssh-ca-cosmian-kms/lists"}