Skip to content
This repository has been archived by the owner on Aug 25, 2023. It is now read-only.

trustbloc/webkms

Repository files navigation

Release License Godocs

Build Status codecov Go Report Card

KMS

TrustBloc KMS is a server implementation of KMS and Crypto APIs from Aries Framework Go. The KMS server adds a layer of security and storage options for the cryptographic keys. KMS/Crypto operations are exposed over REST API.

Running kms-server

Run make kms-server to build a kms-server executable. You can also build a docker image using make kms-server-docker.

Start the KMS server with the following command:

$ ./build/bin/kms-server start [flags]

or

$ docker run -p 8074:8074 ghcr.io/trustbloc/kms:latest start [flags]

If the server is run as a docker container, you need to expose the port on which the KMS server is listening for incoming connections.

Example with MongoDB and local secret lock:

$ ./build/bin/kms-server start --host localhost:8076 --database-type mongodb --database-url mongodb://mongodb.example.com:27017 --secret-lock-type=local --secret-lock-key-path=<path_to_key>

Flags

Flag Environment variable Description
--host KMS_HOST The host to run the kms-server on. Format: HostName:Port.
--metrics-host KMS_METRICS_HOST The host to run metrics on. Format: HostName:Port.
--base-url KMS_BASE_URL An optional base URL value to prepend to a key store URL.
--database-type KMS_DATABASE_TYPE The type of database to use for storing key stores metadata. Supported options: mem, couchdb, mongodb.
--database-url KMS_DATABASE_URL The URL of the database. Not needed if using in-memory storage.
--database-prefix KMS_DATABASE_PREFIX An optional prefix to be used when creating and retrieving the underlying database.
--database-timeout KMS_DATABASE_TIMEOUT Total time to wait for the database to become available. Supports valid duration strings. Defaults to 30s.
--secret-lock-type KMS_SECRET_LOCK_TYPE Type of a secret lock used to protect server KMS. Supported options: local, aws.
--secret-lock-key-path KMS_SECRET_LOCK_KEY_PATH The path to the file with key to be used by local secret lock. If missing noop service lock is used.
--secret-lock-aws-key-uri KMS_SECRET_LOCK_AWS_KEY_URI The URI of AWS key to be used by server secret lock if the secret lock type is "aws".
--secret-lock-aws-access-key KMS_SECRET_LOCK_AWS_ACCESS_KEY The AWS access key ID to be used by server secret lock if the secret lock type is "aws".
--secret-lock-aws-secret-key KMS_SECRET_LOCK_AWS_SECRET_KEY The AWS secret access key to be used by server secret lock if the secret lock type is "aws".
--auth-server-url KMS_AUTH_SERVER_URL The URL of Auth server.
--auth-server-token KMS_AUTH_SERVER_TOKEN A static token used to protect the GET /secrets API in Auth server.
--secret-lock-aws-endpoint KMS_SECRET_LOCK_AWS_ENDPOINT The endpoint of AWS KMS service. Should be set only in a test environment.
--tls-cacerts KMS_TLS_CACERTS Comma-separated list of CA certs path.
--tls-serve-cert KMS_TLS_SERVE_CERT The path to the server certificate to use when serving HTTPS.
--tls-serve-key KMS_TLS_SERVE_KEY The path to the private key to use when serving HTTPS.
--tls-systemcertpool KMS_TLS_SYSTEMCERTPOOL Use system certificate pool. Possible values: [true] [false]. Defaults to false.
--gnap-signing-key KMS_GNAP_SIGNING_KEY The path to the private key to use when signing GNAP introspection requests.
--did-domain KMS_DID_DOMAIN The URL to the did consortium's domain.
--key-store-cache-ttl KMS_KEY_STORE_CACHE_TTL An optional value for key store cache TTL (time to live). Defaults to 10m if caching is enabled.
--enable-cache KMS_CACHE_ENABLE Enables caching support. Possible values: [true] [false]. Defaults to true.
--shamir-secret-cache-ttl KMS_SHAMIR_SECRET_CACHE_TTL An optional value for Shamir secrets cache TTL. Defaults to 10m if caching is enabled. If set to 0, keys are never cached.
--kms-cache-ttl KMS_KMS_CACHE_TTL An optional value for cache TTL for keys stored in server kms. Defaults to 10m if caching is enabled. If set to 0, keys are never cached.
--enable-cors KMS_CORS_ENABLE Enables CORS. Possible values: [true] [false]. Defaults to false.
--auth-type KMS_AUTH_TYPE Comma-separated list of the types of authorization to enable. Possible values [GNAP] [ZCAP]. Defaults to 'ZCAP'.
--log-level KMS_LOG_LEVEL Logging level. Supported options: critical, error, warning, info, debug. Defaults to info.

Running tests

Prerequisites

  • Go 1.17
  • Docker
  • Docker-Compose
  • Make
  • 127.0.0.1 oidc.provider.example.com entry in hosts file

Targets

# run all build targets
$ make all

# run license and linter checks
$ make checks

# run unit tests
$ make unit-test

# run bdd tests
$ make bdd-test

REST API

Generate OpenAPI specification

The OpenAPI spec for the kms-server can be generated by running the following target from the project root directory:

$ make open-api-spec

The generated spec can be found under ./test/bdd/fixtures/specs/openAPI.yml.

Run OpenAPI demo

Start the OpenAPI demo by running

$ make open-api-demo

Once the services are up, click here to launch the OpenAPI interface.

Architecture overview

kms-server-architecture

Secret lock

Secret lock is used to encrypt keys before storing them into the underlying storage. No key materials are ever stored unencrypted. Secret lock can be any component that supports secretlock.Service API from the Aries Framework Go.

All secret locks, currently used by the KMS server, use symmetric keys. The way how these keys are built or get from differentiates one secret lock from another.

Local secret lock

Local secret lock uses a key that is created and stored locally. In the case of User's Key Store, a symmetric key for the local secret lock is created during create key store operation. It is encrypted by Server's Secret Lock and stored to the Server DB.

Local secret lock for the KMS server reads the key from the file specified by KMS_SECRET_LOCK_KEY_PATH variable (--secret-lock-key-path flag).

AWS secret lock

Server's Secret Lock can use a key hosted by AWS KMS. Set KMS_SECRET_LOCK_TYPE=aws variable (--secret-lock-type=aws flag) to enable option with AWS secret lock. You will need to provide other parameters that are needed for using AWS key: KMS_SECRET_LOCK_AWS_KEY_URI, KMS_SECRET_LOCK_AWS_ACCESS_KEY and KMS_SECRET_LOCK_AWS_SECRET_KEY variables or appropriate flags.

Shamir secret lock

That type of secret lock can be forced to use for the User's Key Store by the KMS Server. If the server is started with KMS_AUTH_SERVER_URL variable set, then keys in the User's Key Store should be protected with Shamir secret lock. This lock uses Shamir's Secret Sharing scheme to reconstruct the original secret from the provided shares and the HKDF algorithm to expand the combined secret into a symmetric key to use for encrypt/decrypt operations.

If Shamir secret lock is used, every request that involves User's Key Store is expected to have a base64 encoded Secret-Share header with user's secret share and Auth-User header to fetch the second share from the Auth server.

Storage

The following databases are supported for the Server DB: MongoDB, CouchDB, and in-memory. You specify a type of the database in the KMS_DATABASE_TYPE environment variable (--database-type flag).

Use Cases

Refer here for in-depth description on how lock keys are used in example server's configurations.

Contributing

Thank you for your interest in contributing. Please see our community contribution guidelines for more information.

License

Apache License, Version 2.0 (Apache-2.0). See the LICENSE file.