AWS SecretsManager

This guide shows how to setup a KES server that uses AWS SecretsManager as a persistent key store protected by the AWS-KMS:

1. AWS SecretsManager Configuration
2. KES Server setup

                         ╔═══════════════════════════════════════════════════╗
┌────────────┐           ║  ┌────────────┐          ┌─────────────────────┐  ║
│ KES Client ├───────────╫──┤ KES Server ├──────────┤ AWS Secrets-Manager │  ║
└────────────┘           ║  └────────────┘          └──────────┬──────────┘  ║
                         ╚═════════════════════════════════════╪═════════════╝
                                                               |
                                                         ┌─────┴─────┐
                                                         |  AWS-KMS  |
                                                         └───────────┘

---

AWS SecretsManager

The AWS SecretsManager is basically a key-value store for secrets - like passwords, access tokens and cryptographic keys. AWS will encrypt these secrets via their AWS-KMS service.

To create, retrieve and delete secrets at/from the AWS SecretsManager you need an AWS IAM user - i.e. an AWS access key and AWS secret key pair with sufficient IAM policy permissions. If you already have an IAM user / the access key and secret key, you can skip the following to steps:

1. Go to the AWS console and create a new user. Use the Programmatic access type to create a new access key / secret key pair.
2. Attach policies to that user to grant access to the AWS SecretsManager and the AWS-KMS. AWS has predefined policies (SecretsManagerReadWrite and AWSKeyManagementServicePowerUser) that will work but also grant a lot of permissions that are not needed. Your AWS IAM user needs to have to following permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "Stmt1578498399136",
      "Action": [
        "secretsmanager:CreateSecret",
        "secretsmanager:DeleteSecret",
        "secretsmanager:GetSecretValue",
        "secretsmanager:ListSecrets"
      ],
      "Effect": "Allow",
      "Resource": "*"
    },
    {
      "Sid": "Stmt1578498562539",
      "Action": [
        "kms:Decrypt",
        "kms:DescribeKey",
        "kms:Encrypt"
      ],
      "Effect": "Allow",
      "Resource": "*"
    }
  ]
}

Note that this example policy grants access to all KMS and SecretsManager resources. You can restrict that by specifying a AWS ARN as resource instead *.

KES Server setup

First, we need to generate a TLS private key and certificate for our KES server. A KES server can only be run with TLS - since secure-by-default. Here we use self-signed certificates for simplicity. For a production setup we highly recommend to use a certificate signed by CA (e.g. your internal CA or a public CA like Let's Encrypt)

1. Generate a TLS private key and certificate for the KES server.
   The following command will generate a new TLS private key server.key and a X.509 certificate server.cert that is self-signed and issued for the IP 127.0.0.1 and DNS name localhost (as SAN). You may want to customize the command to match your setup.

   kes tool identity new --server --key server.key --cert server.cert --ip "127.0.0.1" --dns localhost

   Any other tooling for X.509 certificate generation works as well. For example, you could use openssl:

   $ openssl ecparam -genkey -name prime256v1 | openssl ec -out server.key
   
   $ openssl req -new -x509 -days 30 -key server.key -out server.cert \
      -subj "/C=/ST=/L=/O=/CN=localhost" -addext "subjectAltName = IP:127.0.0.1"
   

2. Then, create private key and certificate for your application:

   kes tool identity new --key=app.key --cert=app.cert app

   You can compute the app identity via:

   kes tool identity of app.cert

3. Now, we have defined all entities in our demo setup. Let's wire everything together by creating the config file server-config.yml:

   address: 0.0.0.0:7373
   root:    disabled  # We disable the root identity since we don't need it in this guide 
   
   tls:
     key : server.key
     cert: server.cert
   
   policy:
     my-app:
       paths:
       - /v1/key/create/my-app*
       - /v1/key/generate/my-app*
       - /v1/key/decrypt/my-app*
       identities:
       - ${APP_IDENTITY}
   
   keys:
     aws:
       secretsmanager:
         endpoint: secretsmanager.us-east-2.amazonaws.com  # Use the SecretsManager in your region.
         region:   us-east-2                               # Use your region
         kmskey:   ""                                      # Your AWS-KMS master key (CMK) - optional.
         credentials:
           accesskey: "" # Your AWS Access Key
           secretkey: "" # Your AWS Secret Key

   Please use your access key / secret key pair.

4. Finally we can start a KES server in a new window/tab:

   export APP_IDENTITY=$(kes tool identity of app.cert)
   
   kes server --config=server-config.yml --auth=off

   --auth=off is required since our root.cert and app.cert certificates are self-signed

5. In the previous window/tab we now can connect to the server by:

   export KES_CLIENT_CERT=app.cert
   export KES_CLIENT_KEY=app.key
   kes key create -k my-app-key

   -k is required because we use self-signed certificates

6. Finally, we can derive and decrypt data keys from the previously created my-app-key:

   kes key derive -k my-app-key
   {
     plaintext : ...
     ciphertext: ...
   }

   kes key decrypt -k my-app-key <base64-ciphertext>