Documentation menu
Introduction
Issuing certificates
Security
Reference

Home › Docs › Getting started

Getting started

Install homepki, create a root CA, an intermediate CA and a server certificate, then check that the chain verifies.

Install

With Homebrew, on macOS or Linux:

$ brew tap bcollard/homepki
$ brew install --cask homepki

Or download the archive for your platform (macOS or Linux, amd64 or arm64) from the latest release and put the homepki binary on your PATH. There is no other dependency: keys, signing and chain verification use Go's crypto/x509, so OpenSSL does not need to be installed. homepki version prints the installed release.

Create a first PKI

Every command works under a root CA identified by its domain (-d). Intermediates are named with -n, and leaves under an intermediate with -s (server) or -c (client).

$ homepki root-ca         -d runlocal.dev
$ homepki intermediate-ca -d runlocal.dev -n bu1
$ homepki server-cert     -d runlocal.dev -i bu1 -s kong-gateway --san kong.local
$ homepki client-cert     -d runlocal.dev -i bu1 -c my-client

Each command is synchronous: the files are on disk when it returns. Each tier needs the tier above it and stops with an error if it is missing.

Check the chain

Every tier has a list subcommand that verifies the chain of trust:

$ homepki server-cert list -d runlocal.dev -i bu1
Server Certificates for runlocal.dev/bu1:
  NAME              EXPIRES     DAYS LEFT  CHAIN
  ────────────────  ──────────  ─────────  ──────────
  kong-gateway.crt  2027-09-26  364        ✓ OK

See Listing and verification for the JSON output to use in scripts.

Where the files go

Everything lives under one working directory, resolved in this order:

  1. the --workdir flag, accepted by every command;
  2. the HOMEPKI_WORKDIR environment variable;
  3. ~/.homepki.
~/.homepki/
└── runlocal-dev/                          # the domain, dots replaced by dashes
    ├── ca/
    │   ├── runlocal-dev-root-ca.crt
    │   └── private/runlocal-dev-root-ca.key
    └── bu1/                               # an intermediate CA
        ├── bu1-intermediate-ca.crt
        ├── bu1-intermediate-ca-chain.crt  # intermediate + root: the CA bundle
        ├── private/bu1-intermediate-ca.key
        ├── server-tls/kong-gateway.crt, kong-gateway.key
        └── client-tls/my-client.crt, my-client.key

Private keys are unencrypted PKCS#8 PEM files with mode 0600, in private/ directories with mode 0700. Treat the working directory as sensitive and keep it out of version control. Revocation lists and PKCS#12 bundles appear in the same tree when you create them; Certificate hierarchy lists every file.

A throwaway PKI for a script

There is no delete command: removing a PKI means deleting its directory. For tests and demos, point HOMEPKI_WORKDIR at a temporary directory:

export HOMEPKI_WORKDIR=$(mktemp -d)
trap 'rm -rf "$HOMEPKI_WORKDIR"' EXIT

homepki root-ca         -d runlocal.dev
homepki intermediate-ca -d runlocal.dev -n bu1
homepki server-cert     -d runlocal.dev -i bu1 -s gw

A fresh directory per run also avoids the overwrite protection: generate commands refuse to replace existing files unless you pass --force.

Next steps

← PreviousOverview