cert

README

cert — a certificate and X.509 swiss‑army knife

cert is a small command‑line tool for inspecting and working with X.509/TLS certificates and connections. It consolidates several utilities from goutils into a single, ergonomic CLI.

AI notes:

• None of the code has been written with AI.
• The docs are currently largely AI-generated while I work on the tool itself.

Overview

The cert binary provides subcommands to:

• Connect to TLS endpoints and print connection details (version, cipher, peers).
• Fetch and display certificate chains or dump certificate files.
• Save a remote host's full certificate chain to PEM.
• Compute and compare Subject Key Identifiers (SKIs) for keys/certs.
• Verify certificate chains using optional custom root/intermediate bundles and optional revocation checks.

Stack and Tooling

• Language: Go (module name: cert, Go toolchain declared in go.mod).
• CLI framework: spf13/cobra
• Configuration: spf13/viper (flags + environment + optional YAML config)
• Dependencies: vendored via Go modules (go.mod, go.sum).
• Packaging/Release: goreleaser (see .goreleaser.yaml).
• CI: CircleCI (see badge above and .circleci/config.yml).

Requirements

• Go toolchain installed. The module currently declares:
  • go 1.25 in go.mod (use a compatible or newer Go version).
• Network access if connecting to remote TLS endpoints.

Installation

Option A: From source (local clone)

• Build a local binary:

  git clone https://github.com/kisom/cert && cd cert
  go build -o cert .

• Or install into your $GOBIN/$GOPATH/bin:

  go install github.com/kisom/cert@latest

Option B: With an embedded version string

See the "Embedding version information" section below for -ldflags usage.

Option C: From releases

• This project is configured for GoReleaser. Prebuilt archives may be published on GitHub under kisom/cert when releases are cut. If a release is missing for your platform, build from source.
  TODO: Link directly to the Releases page once available.

Usage

Each subcommand has --help. Global flags apply to all commands.

Global flags (from cmd/config.go):

• --config string Path to config file (default: $HOME/.config/goutils/cert.yaml)
• --ca string CA certificate bundle file (PEM)
• -d, --display-mode string Hex display mode for SKI and serial (lower|upper) (default: lower)
• -i, --intermediates-file string Intermediate certificate bundle (PEM)
• -k, --skip-verify Skip certificate verification
• -t, --strict-tls Use strict TLS settings
• -v, --verbose Verbose output

Notes:

• --skip-verify and --strict-tls are mutually exclusive.

Subcommands:

• cert tlsinfo host:port [more ...] Connect and print TLS connection details (TLS version, cipher suite, and peer cert subjects/issuers). Uses a proxy‑aware dialer and does not validate the peer (InsecureSkipVerify=true) — intended for inspection.

• cert dump [host:port|cert.pem]... Fetch and display certificates for a host or dump one or more certificate files. With --leaf-only, print only the leaf when connecting to a host. Local flag: -l, --leaf-only.

• cert bundler Create archives of certificate chains from a YAML configuration file. See the long help for the expected YAML structure and examples. Local flags: -f, --config-file (default: bundle.yaml), -o, --output (output directory; default: pkg).

• cert csrpub <file.csr> [more ...] Extract the public key from one or more CSRs and write each to a PEM file named <file>.pub. Use --stdout to write the PEM to stdout instead of a file. Local flags: --stdout.

• cert stealchain host:port [more ...] Retrieve and save the presented certificate chain from one or more TLS endpoints to <host>.pem files. Honors --ca; uses system pool if not provided. Local flag: -s, --sni-name to override SNI.

• cert matchkey -c cert.pem -k key.pem Check whether the given certificate and private key correspond. Returns non‑zero on mismatch unless --verbose is set and a match is found. Local flags: -c, --cert-file, -k, --key-file (both required).

• cert ski [more ...] Display the Subject Key Identifier (SKI) for one or more keys/certs. With --should-match, compares all SKIs and warns on mismatch. Honors --display-mode for hex formatting. Local flag: -m, --should-match.

• cert pem Encode or decode PEM files. Provide exactly one filename.

  • To encode raw binary to PEM, pass -t, --pem-type (e.g. CERTIFICATE) and the tool writes the PEM to stdout.
  • To decode a PEM file to raw DER, pass -b, --binary-out <out-file> and the tool writes the decoded bytes to the given file. Local flags: -b, --binary-out, -t, --pem-type (exactly one of these is required; they are mutually exclusive).

• cert serial [host:port|cert.pem]... Display the certificate serial number for each input.

  • By default, prints the serial as hex; use global --display-mode to select hex case.
  • With -n, --numeric, prints the serial as an integer. Local flags: -n, --numeric.

• cert verify host:port|cert.pem [more ...] Verify certificate chains for hosts or cert files. Supports custom root and intermediate bundles, optional forced intermediate loading, optional revocation checks, and verbose progress. Local flags: -f, --force-intermediate-bundle, -r, --check-revocation. Exits with status 1 if any verification fails.

• cert expiry <cert.pem> [more ...] Display certificate expiry dates for one or more certificate files or hosts. Local flags:

  • -p, --leeway <duration>: treat certificates expiring within this leeway as expiring soon (e.g. 1h30m).
  • -q, --expiring-only: only display certificates expiring soon.

• cert ca-signed <cert.pem> [more ...] Check whether a certificate is signed by the specified CA. Requires a single CA certificate via the global --ca option. Results are printed per input as one of:

  • SELF-SIGNED
  • INVALID
  • OK (expires ) Exit status is non‑zero if no certificates are provided.

• cert version Print the embedded version string.

Configuration and environment

Configuration is managed via Cobra flags and Viper:

• Prefer command‑line flags shown above; each subcommand also has --help.
• Config file: by default, $HOME/.config/goutils/cert.yaml if present. You can set a custom file via --config <path>.
• Environment variables: Viper's AutomaticEnv() is enabled, but no key replacer is configured. That means only keys without dashes can be set via environment variables in most shells. For example, CA and VERBOSE may work, but keys like intermediates-file or skip-verify typically cannot be exported because - is not valid in environment variable names. Prefer flags or the config file for those.

Example config file (~/.config/goutils/cert.yaml):

ca: /etc/ssl/certs/ca-bundle.crt intermediates-file: /path/to/intermediates.pem display-mode: lower skip-verify: false strict-tls: true verbose: false should-match: false leaf-only: false leeway: 0s expiring-only: false sni-name: "" config-file: bundle.yaml output: pkg binary-out: "" pem-type: CERTIFICATE force-intermediate-bundle: false check-revocation: false

Examples

• Show TLS info for a couple hosts:

  cert tlsinfo example.com:443 golang.org:443

• Dump just the leaf certificate from a host:

  cert dump --leaf-only example.com:443

• Save a host's full chain to PEM and override SNI:

  cert stealchain -s www.example.com example.net:443

• Verify a certificate file against custom roots and intermediates with revocation checks:

  cert verify -r --ca roots.pem -i intermediates.pem certs/service.pem

• Extract the public key from a CSR to stdout:

  cert csrpub --stdout request.csr

• Extract public keys from multiple CSRs, writing request.csr.pub files:

  cert csrpub service.csr api.csr

• Print SKIs for a key and a cert and require that they match:

  cert ski -m service.key service.crt

• Print a serial as an integer:

  cert serial -n service.crt

• Check that a cert was signed by a specific CA:

  cert ca-signed --ca org-root.pem service.crt

Embedding version information

The cert version subcommand prints an embedded version string. The version information is set at build time using Go linker flags.

Examples:

• Local build with a specific version tag:

  go build -ldflags "-X cert/cmd.Version=v1.2.3" -o cert .

• Include a commit identifier:

  go build -ldflags "-X cert/cmd.Version=git-1b00701" -o cert .

• Installing with go install while setting the version:

  go install -ldflags "-X cert/cmd.Version=v1.2.3" ./...

If no value is provided, the default version string is "dev".

Project Structure

Top‑level files and directories:

• main.go — entry point, calls cmd.Execute().
• cmd/ — Cobra command implementations:
  • root.go — root command and CLI description.
  • config.go — global flags, Viper config/env setup, TLS helpers.
  • dump.go — cert dump.
  • bundler.go — cert bundler.
  • matchkey.go — cert matchkey.
  • csrpub.go — cert csrpub.
  • pem.go — cert pem.
  • ski.go — cert ski.
  • stealchain.go — cert stealchain.
  • tlsinfo.go — cert tlsinfo.
  • verify.go — cert verify.
  • version.go — cert version.
• tlsinfo/ — small helper package for printing TLS connection details.
• .goreleaser.yaml — GoReleaser configuration.
• .circleci/ — CircleCI pipeline configuration.
• LICENSE — Apache 2.0 license.

License

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details.

Notes

• Module path is cert. When importing within this repository, packages are referenced as cert/... (e.g., cert/cmd, cert/tlsinfo). If you fork and change the module path, update imports accordingly.
• Proxy‑aware networking and TLS helpers come from git.wntrmute.dev/kyle/goutils.

Documentation

Overview

Copyright © 2025 K. Isom <kyle@imap.cc>