CA

This is the n + 1st incarnation of a local IUS PKI tool. Basically it is a wrapper around OpenSSL and Git.

Download

You can either build from the sources, or download a pre-built binary.

To build from the sources see below. For download the the package repo:

curl -O https://gitea.schlittermann.de/api/packages/IUS/generic/goca
install -m 0755 ./goca /usr/local/bin/goca

Usage

Basic usage information can be printed using the -h option: goca -h. An outline of the usage follows.

The Goca tool uses subcommands for the different operations. Usage information about the subcommands can be printed using: goca SUBCOMMAND -h, e.g.:

goca create -h

The general format of the command line is:

goca [-config <config-file>] [global-options] SUBCOMMAND [local-options] [parameters]...

Passwords

Several operations need passwords:

• a password protecting the CA (subcommand option -capass PASS for the subcommands init, create)
• a password protecting the stored private keys (subcommand option -storepass PASS for the subcommands create, and show).

Both options expect a PASS parameter in one of the following forms:

• ask:<PROMPT>: request a password via the terminal (this is the default).
• env:<VAR>: read the password from the environment variable VAR.
• file:<FILE>: read the password from the given FILE.
• pass:<PASS>: use PASS as password.
• fd:<FD>: read the password from the given file descriptor.

Configuration

Goca can use a configuration file. The default location is $XDG_CONFIG_HOME/goca/config.toml or $HOME/.goca/config.toml when running with an effective UID != 0, and it is /etc/goca/config.toml when running with an effective UID == 0. The latter mode is not recommended. An alternative location can be used by using -config command line parameter (which must be the very first parameter).

A good starting point for a configuration are the built-in defaults. These values can be printed using:

goca -default-config

When running Goca the values read from the configuration file can be overridden by options on the command line. (Please note, the options are dependant on the subcommand (contrary to the config file, which is a flat config currently).

Initialization

Before starting the daily operation, you need to create backing certificate authority, e.g.:

goca init /O=example/OU=cert-authority/CN=example-ca

This step creates a directory (default name pki/), and initializes it as a Git repo.

All further Git operations use the current branch of that repo (default: master). If a remote tracking repo is configured for the current branch, all changes will be pushed to the remote repo automatically.

After initializing you may want to review the pki/templates folder. The templates can be used to output the certificates later.

Create a remote tracking Git repo

Having a remote repo can serve as kind of backup, or as a way to deploy created certificates.

You can just cd into the PKI dir (typically pki/ and configure a remote repo as usually. Or use Goca to do it:

goca git remote add origin <url of the remote repo>
goca git push -u origin master

Once this is done, Goca will syncronize the remote repo with the local PKI directory before and after each operation. For this push to happen it is important, that the local branch is configured to track a remote branch (this is set-up by the git push -u operation above).

Create User certificates

The creation of user certificates requires the subject of the certificate in either form: /O=example.com/OU=homeoffice/CN=hans@example.cokm, or CN=hans@example.com,OU=homeoffice,O=example.com. The CN attribute is required.

goca create CN=hans@example.com
goca show CN=hans@example.com

The subcommand options -capass, -storepass, and -outpass are useful for automation. The -template subcommand option (for show, or create -show`) can be used to fill a predefined template, like:

goca show -template pki/templates/openvpn.conf CN=hans@example.com

Or, as a onestop only operation:

goca create -template pki/templates/openvpn.conf -show CN=hans@eampl.com

It is an error to create a certificate with the same subject twice. See below on how to revoke it.

Revocation of certificates

Goca can revoke a given certificate (goca list might help you to get a list of active certificates):

goca revoke CN=hans@example.com`

or alternativly you can add the -revoke option to the create subcommand:

goca create -revoke -template pki/templates/openvpn.conf -show CN=hans@eampl.com

The revocation list can be retrieved using:

goca crl

Build and Install

1. Prepare a decent Go installation. Go 1.19 should work.

2. Download the source.

   • e.g. use git clone --depth=1 https://gitea.schlittermann.de/ius/goca
   • or download a tarball

   The master branch should be stable. Eventually we'll use tags to mark releases, or even use releases.

3. Build and install it:

   go build ./cmd/goca
   

   This will create a goca binary in the toplevel directory. You can call this binary (./goca) or install it wherever you want (e.g. instlall ./goca /usr/local/bin.

   If you want to have Go deciding on how to install it, use

   go install ./cmd/goca
   

   This will install the binary into $(go env GOPATH)/bin, you may want to adjust your PATH environment:

   PATH+=:$(go env GOPATH)/bin    # bash
   PATH=$PATH:$(go env GOPATH)/bin # sh
   

Updates

If you have Go installed, you can update the binary to the latest stable (@latest) version:

goca update

If you need other versions, e.g. the latest greatest (but not necesserily stable), do:

goca update -version=@master

Alternatives ways

• If you do not want to install it: go build ./cmd/goca.
• If you do not even want to build it: go run ./cmd/goca ….
• If you do not even want to keep it locally:
  • go install go.schlittermann.de/ius/goca/cmd/goca@latest
  • go run go.schlittermann.de/ius/goca/cmd/goca@latest