From c5f436b4d06b18af53c69a9ed8aba5430a75219b Mon Sep 17 00:00:00 2001 From: Jan Dittberner Date: Tue, 29 Nov 2022 20:12:04 +0100 Subject: [PATCH] Add development documentation --- README.md | 41 ++++++++++++++++++++++++++++++++++++----- 1 file changed, 36 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index f15cbb1..e8e7291 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,37 @@ -# Running with softhsm2 +# CAcert signer -## Setup HSM keys and certificates +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 @@ -15,14 +46,14 @@ export PKCS11_PIN_LOCALHSM=123456 go run ./cmd/signer -setup ``` -## Run the signer +### Run the signer ```shell export PKCS11_PIN_LOCALHSM=123456 go run ./cmd/signer ``` -## Run the client simulator with socat +### 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: @@ -32,7 +63,7 @@ sudo apt install socat ``` ```shell -go build ./cmd/clientsim +make clientsim socat -d -d -v pty,rawer,link=$(pwd)/testPty EXEC:./clientsim,pty,rawer ```