cacert-gosigner/README.md

81 lines
No EOL
2.5 KiB
Markdown

# CAcert signer
This is the CAcert signer reimplementation in Go that implements a more robust wire protocol and has configurable
support for hardware security modules (HSMs) for online and offline key pairs.
See [the design document](docs/design.md) for design considerations and architecture diagrams.
## Development preconditions
You will need GNU make to build the application. On Debian systems you can install GNU make and crossbuild tools
for ARM binary builds using:
```shell
sudo apt install make crossbuild-essential-arm64 crossbuild-essential-armhf
```
Install [go](https://go.dev/) >= 1.17, [golangci-lint](https://golangci-lint.run/usage/install/) >= 1.50.0 and
[goreleaser](https://goreleaser.com/install/), as these are used for building and linting the application.
Read the documentation of these tools, to find out how to use them.
## Building the binaries
There is a `Makefile` to automate builds of the signer and clientsim binaries. Run
```shell
make
```
to run linting, tests and binary builds.
## Running with softhsm2
### Setup HSM keys and certificates
```shell
sudo apt install softhsm2
umask 077
mkdir -p ~/.config/softhsm2/tokens
echo "directories.tokendir = $HOME/.config/softhsm2/tokens/" > ~/.config/softhsm2/softhsm2.conf
cp docs/config.sample.yaml config.yaml
# modify config.yaml to fit your needs
softhsm2-util --init-token --free --label localhsm --so-pin 47110815 --pin 123456
# initialize the keys
export PKCS11_PIN_LOCALHSM=123456
go run ./cmd/signer -setup
```
### Run the signer
```shell
export PKCS11_PIN_LOCALHSM=123456
go run ./cmd/signer
```
### Run the client simulator with socat
You may run the client simulator that sends commands via `stdout` and reads responses on `stdin` via `socat` to
simulate traffic on an emulated serial device:
```shell
sudo apt install socat
```
```shell
make clientsim
socat -d -d -v pty,rawer,link=$(pwd)/testPty EXEC:./clientsim,pty,rawer
```
You will need to configure `$(pwd)/testPty` as `serial`/`device` in your `config.yaml` to let the signer command find
the emulated serial device.
## Using socat to simulate TTYs for signer and signer client
The following `socat` command line will open TTY pseudo devices in `./testPty` as well as
`../cacert-gosignerclient/testPty`. This will allow both the signer and the signer client code to have
`testPty` as `device` value in their configuration YAML file.
```shell
socat -d -d pty,rawer,link=$(pwd)/testPty pty,rawer,link=$(pwd)/../cacert-gosignerclient/testPty
```