certrally

module
v0.4.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 2, 2026 License: Apache-2.0

README

certrally

GitHub Release GitHub Stars Last Commit Maintenance License Tests Supply chain OpenSSF Scorecard

certrally is a command line client for certificate enrollment with the Certificate Management Protocol (CMP), Enrollment over Secure Transport (EST) and the Simple Certificate Enrolment Protocol (SCEP). The documentation is at misiektoja.github.io/certrally.

certrally enrolls an ML-DSA-65 certificate from the test CA with a shared secret

CMP (RFC 9810, which replaces RFC 4210, with the RFC 9483 profile)

  • ir, cr, kur, p10cr and rr with a shared secret or a certificate
  • Keys that the CA generates (central key generation)
  • Requests forwarded by a registration authority in nested messages
  • CA certificates, root CA updates, request templates and CRLs from the CA
  • ping to check a server and mock to run a test CA on your machine
  • Deliberately wrong messages with enroll --fault to test how a CA copes
  • A step-by-step enroll that prints the matching command for scripts

EST (RFC 7030)

  • Enrollment, renewal, server key generation, CA certificates and CSR attributes
  • Authentication with a password, a bearer token, a TLS client certificate or TLS-SRP
  • est mock to run a test EST CA on your machine

SCEP (RFC 8894)

  • Enrollment, renewal and polling of pending requests, also in a later run
  • CA certificates, the CA chain, the next CA certificate, certificates and CRLs from the CA
  • Digest, cipher and HTTP method chosen from the server capabilities, with old algorithms on request
  • scep mock to run a test SCEP CA on your machine

All protocols

  • A live diagram of every message and plain explanations of failures
  • RSA, ECDSA, Ed25519, ML-DSA, composite ML-DSA and ML-KEM keys, also offline with keygen. SCEP takes RSA and ECDSA keys
  • No trust setup: certrally trusts the CA it talks to or the one in --ca-cert
  • Warnings about responses that break the RFCs and a strict profile that rejects them
  • JSON output, capture files and exit statuses for scripts
  • inspect and lint to decode recorded messages and check them

Tested with EJBCA, Nokia NCM, Insta Certifier and the openssl cmp mock server over CMP, with Cisco libest over EST and with EJBCA, Nokia NCM, OpenXPKI and micromdm/scep over SCEP. See Tested servers.

Install

Each release has archives for Linux, macOS and Windows on amd64 and arm64. A binary downloaded with a browser on macOS needs xattr -d com.apple.quarantine certrally before its first run, because it is not notarized.

With Homebrew on macOS or Linux, which also installs shell completions:

brew install misiektoja/tap/certrally

As a container image for linux/amd64 and linux/arm64:

docker run --rm ghcr.io/misiektoja/certrally --help

The image runs as an unprivileged user. To save files to the current directory, run it as your user and mount the directory:

docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/work" -w /work -e CERTRALLY_SECRET \
  ghcr.io/misiektoja/certrally enroll --server https://ca.example.com/.well-known/cmp \
  --ref device-42 --cert-out device.pem --key-out device.key

From source with Go 1.27.3 or newer:

go install github.com/misiektoja/certrally/cmd/certrally@latest

Releases are signed with cosign and carry GitHub build provenance and SBOMs. Verify a download shows how to check one.

Quick start

certrally mock runs a CMP test CA on your machine. Start it in one terminal:

certrally mock --secret demo-secret --ca-out ca.pem

Request a certificate from another terminal in the same directory:

certrally enroll --server http://127.0.0.1:8080/.well-known/cmp --ref demo --ca-cert ca.pem --secret demo-secret --cert-out device.pem --key-out device.key

The test CA prints the same command when it starts. certrally draws each message as it is sent and received, then describes the certificate:

  certrally                                           127.0.0.1:8080
  │                                                                │
  │ ir  PBMAC1  432 B                                              │
  │ ─────────────────────────────────────────────────────────────▶ │
  │                            ip  accepted  PBMAC1  1.4 KiB  8 ms │
  │ ◀───────────────────────────────────────────────────────────── │
  │ certConf  PBMAC1  281 B                                        │
  │ ─────────────────────────────────────────────────────────────▶ │
  │                                   pkiconf  PBMAC1  629 B  2 ms │
  │ ◀───────────────────────────────────────────────────────────── │

✓ Certificate issued
  Subject  CN=demo
  Issuer   CN=Test CA
  Serial   93:AC:6F:24:1A:B9:81:D1:62:EA:8A:C0:2A:6A:DD:FC
  Valid    2026-11-02 17:35 UTC to 2027-11-02 17:36 UTC
  Key      ECDSA P-256
  Status   accepted
  Saved    device.key, device.pem

Getting started continues with a real CA, key updates, step-by-step enrollment, revocation and trust. Enroll over EST and Enroll over SCEP cover the other protocols.

Usage

certrally --help
certrally enroll --help
certrally --version

enroll, poll, revoke, cacerts, ping and mock use CMP and also run under certrally cmp. The EST and SCEP commands run under certrally est and certrally scep. certrally completion bash|zsh|fish|powershell prints a shell completion script and certrally man prints a man page.

Documentation

The full documentation is at misiektoja.github.io/certrally:

The pages are also readable on GitHub in docs/.

Contributing

See CONTRIBUTING.md. Report security issues as described in SECURITY.md.

License

certrally is licensed under the Apache License 2.0.

Directories

Path Synopsis
cmd
certrally command
Command certrally is a certificate enrollment client for the Certificate Management Protocol.
Command certrally is a certificate enrollment client for the Certificate Management Protocol.
internal
capture
Package capture writes the messages of a CMP, EST or SCEP exchange to a file, so that they can be inspected or replayed later.
Package capture writes the messages of a CMP, EST or SCEP exchange to a file, so that they can be inspected or replayed later.
cli
Package cli implements the certrally command line.
Package cli implements the certrally command line.
cmpfile
Package cmpfile reads CMP, EST and SCEP messages from capture files and from files that hold one message as DER, PEM, base64 or hex.
Package cmpfile reads CMP, EST and SCEP messages from capture files and from files that hold one message as DER, PEM, base64 or hex.
dn
Package dn parses distinguished names and subject alternative names given on the command line and formats distinguished names for display.
Package dn parses distinguished names and subject alternative names given on the command line and formats distinguished names for display.
estca
Package estca is an EST test CA that keeps its key and everything it issues in memory.
Package estca is an EST test CA that keeps its key and everything it issues in memory.
keys
Package keys generates, encodes and describes the private keys certrally enrolls.
Package keys generates, encodes and describes the private keys certrally enrolls.
pemfile
Package pemfile reads certificates, requests and keys from files and writes results safely.
Package pemfile reads certificates, requests and keys from files and writes results safely.
profile
Package profile checks CMP responses against the rules of the Lightweight CMP Profile (RFC 9483) and RFC 9810 that the go-pki-cmp client relaxes for interoperability.
Package profile checks CMP responses against the rules of the Lightweight CMP Profile (RFC 9483) and RFC 9810 that the go-pki-cmp client relaxes for interoperability.
scepca
Package scepca is a SCEP test CA that keeps its keys and everything it issues in memory.
Package scepca is a SCEP test CA that keeps its keys and everything it issues in memory.
secret
Package secret obtains shared secrets, passwords and tokens from a command-line value, a file, an environment variable or a prompt.
Package secret obtains shared secrets, passwords and tokens from a command-line value, a file, an environment variable or a prompt.
termcolor
Package termcolor decides when certrally colours its output.
Package termcolor decides when certrally colours its output.
trace
Package trace records the CMP, EST or SCEP messages a client exchanges over HTTP, for the ladder view and for telling transport failures apart from protocol failures.
Package trace records the CMP, EST or SCEP messages a client exchanges over HTTP, for the ladder view and for telling transport failures apart from protocol failures.
ui
Package ui renders the ladder view of a CMP, EST or SCEP exchange and the result reports of certrally.
Package ui renders the ladder view of a CMP, EST or SCEP exchange and the result reports of certrally.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL