Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

GO - Key Management Service

A REST based Key Management Service written in GO.

GoDoc Build Status

What is GO-KMS?

GO-KMS is a encryption Key Management Service in GO. Modelled extensively on AWS KMS behaviour, the API is used for symmetrical key management. It offers Cryptography as a Service (CaaS) functionality such as encryption/decryption/reencryption without exposing keys.

The crypto provider is based on AES and a key size of 256bits using the GCM cipher to provide confidentiality as well as authentication.

Keys are encrypted and stored on disk, using a master key which is derived using PBKDF2 from a passphrase when run in pure software mode. It is also possible to combine GO-KMS with a Hardware Security Module (HSM) which can be leveraged to create and encrypt a master key using the HSM for generation and protection. HSM support is done using the PKCS#11 standard.

GO-KMS authentication is done using HMAC-SHA256 over HTTPS.

GO-KMS - Command Line Interface

GO-KMS-CLI is a command line interface which can be used to manage and interact with go-kms. The project can be found here:


  • AES Key store
  • Cryptography as a Service
    • Encrypt
    • Decrypt
    • Re-encrypt
  • Keys encrypted while at rest
  • Shared-key Authentication
  • Playground for HSM support via SoftHSM2 and PKCS#11


  • Some documentation about the keys
  • RSA Encryption provider
  • Automatic key rotation?
  • Full HSM provider support


To run get the project...

go get

The dependencies are in the vendor folder already, but should you want to you can run ...

dep ensure

You need to set the following variables:

export GOKMS_AUTH_KEY=/path/to/auth.key
export GOKMS_CRYPTO_PROVIDER= hsm | gokms
export GOKMS_HOST=localhost
export GOKMS_PORT=8020
export GOKMS_SSL_CERT=/path/to/ssl_cert.pem
export GOKMS_SSL_KEY=/path/to/ssl_key.pem

If the GOKMS_CRYPTO_PROVIDER is set to "gokms" then you also need to set:

export GOKMS_KSMC_PATH=/path/to/keys/
export GOKMS_KSMC_PASSPHRASE="a very long Passphrase that will be used for key derivation"

If the GOKMS_CRYPTO_PROVIDER is set to "hsm" then you also need to set:

export GOKMS_HSM_LIB=/path/to/your/hsm/
export GOKMS_HSM_SLOT="0"
export GOKMS_HSM_AES_KEYID="TheNameOfTheCryptoKey"

# optional: If not set no pkcs11 login will be performed.  Useful for Tokens with no PIN set.
export GOKMS_HSM_SLOT_PIN="1234"


Authorization is done via a Authorization header sent in a request. Anonymous requests are not allowed. To authenticate a request, you must sign the request with the shared key when making the request and pass that signature as part of the request.

Here you can see an example of a Authorization header


You construct the signature is built in the following format:

authRequestSig = method + "\n" +
                 Date + "\n" +

This would result in the following signature to be signed:

POST\nWed, 28 Jan 2015 10:42:13 UTC\n/api/v1/go-ksm

Note that you MUST past the same date value in the request. Date should be supplied in UTC using RFC1123 format.

x-kms-date=Wed, 28 Jan 2015 10:42:13 UTC

The signature must be exactly in the same order and include the new line character.

Now encode the signature using the HMAC-SHA256 algorithm using the shared key.

This will result in a key like this:


Example go code to create the signature

date := time.Now().UTC().Format(time.RFC1123) // UTC time
request.Header.Add("x-kms-date", date)

authRequestKey := fmt.Sprintf("%s\n%s\n%s", method, date, resource)

// See package on how golang creates hmacs
hmac := crypto.GetHmac256(authRequestKey, SharedKey)  

request.Header.Add("Authorization", hmac)

Good resources:




Install notes if building SofthHsm2 support:

Add some missing things needed to build, pkcs11

sudo yum install libtool-ltdl-devel

Install softhsm2

sudo yum-config-manager --add-repo
sudo yum install softhsm2

Create a place to store the tokens

mkdir /home/keithball/Documents/tokens

Create/change config file to reflect new token location

# SoftHSM v2 configuration file

directories.tokendir = /home/keithball/Documents/tokens
objectstore.backend = file

log.level = DEBUG

Create initial token...

export SOFTHSM2_CONF=$PWD/softhsm2.conf
softhsm2-util --init-token --slot 0 --label "My token 1"

Check it worked ok

softhsm2-util --show-slots


A JSON RPC based Key Management Service written in GO.







No releases published


No packages published