Overview

Key service is storing cryptographic keys for senders when emails are SEALed. The storage backend is Hashicorp Vault KV2 engine.

• Manage private keys per sender
• Register sent message ID with recipients
• Encrypt AES session keys with sender private key
• Decrypt AES session keys with sender private key

Configuration

Configuration is passed to the service as ENV variables. Please refer to the /internal/config/config.go file for a complete list of all supported configuration variables and their description.

DB migrations

SQL migration files are created in /db/migrations by using the Golang migrate tool. Example command to make a new migration file:

migrate create -ext sql -dir ./db/migrations messages_table

Build

Local binary

To make the service binary locally, you can run the following command from the root directory (you must have Go installed):

go build -o keysvc ./cmd/keysvc/...

Docker image

You can see the Dockerfile of the service under the /deployment directory. There is one Dockerfile for use during local development with /deployment/compose/Dockerfile and one for building an /deployment/ci/Dockerfile.

Metrics

The service exposes the following Prometheus metrics.

Metric Name	Type
http_requests_total	Counter with labels [operation, code]
http_request_duration_seconds	Histogram with labels [operation, code]
created_keys_total	Counter

Versioning

There is one global exported variable named Version in main.go. The variable is set to the latest tag or commit hash during the build process. You can look in the production Dockerfile to see how the Version is set during build. The version is printed in the service log on startup and can be used to verify which specific commit of the code is deployed. The Version is also present in the health check responses on the /liveness and /readiness endpoints.

Swagger API Documentation

The service uses Swag to generate Swagger documentation. The documentation is generated from annotations in the source code. You can find documentation and examples on how to use Swag in the Swaggo GitHub repository.

In order to generate the Swagger documentation, you need to run the generate_swagger.sh script.

./generate_swagger.sh

The script will generate the Swagger documentation by creating openapi.json file in the swagger directory.

Logging

The service outputs all logs to stdout as defined by the best practices in the Cloud Native community. See here for more details 12 Factor App. From there logs could be processed as needed in the specific running environment. The standard log levels are [debug,info,warn,error,fatal] and info is the default level. If you want to set another log level, use the ENV configuration variable LOG_LEVEL to set it.

Tests and Linters

Test

To execute the units tests for the service go to the root project directory and run:

go test -race ./...

Linters

To run the linters go to the root project directory and run:

golangci-lint run

Dependencies and Vendor

The project uses Go modules for managing dependencies and we commit the vendor directory. When you add/change dependencies, be sure to clean and update the vendor directory before submitting your Merge Request for review.

go mod tidy
go mod vendor

To understand why we commit the vendor directory, please refer to Vendor or not to vendor.