Entrust KeyControl

This guide shows how to setup a KES server that uses Entrust KeyControl (v10.1 or newer) as a persistent key store:

                         ╔═════════════════════════════════════════════════╗
┌────────────┐           ║  ┌────────────┐          ┌────────────────────┐ ║
│ KES Client ├───────────╫──┤ KES Server ├──────────┤ Entrust KeyControl │ ║
└────────────┘           ║  └────────────┘          └────────────────────┘ ║
                         ╚═════════════════════════════════════════════════╝

---

Entrust KeyControl

Entrust KeyControl is a proprietary KMS that provides a secret store that can be used by KES.

This guide assumes that you have setup an Entrust KeyControl v10.1 cluster. For setting up a Entrust KeyControl cluster checkout the Entrust documentation:

• Entrust KeyControl on AWS
• Entrust KeyControl on prem

1. Create a new Vault

First, login into your KeyControl cluster as secroot and create a new PASM Vault.

2. Login into Vault

Now, login into your KeyControl cluster as Vault admin (as specified when creating the Vault). The Vault admin should have received an email with a one-time password. The Vault URL can also be viewed in the Vault details tab:

3. Create a new Box

Once logged into the KeyControl Vault, create a new Box under Manage Boxes. Do not set a checkout or rotation duration.

3. Attach the 'Vault User' role policy

Now create a new policy with the Vault User role and attach the policy to the user account used by KES.

After creating a new vault, box inside the vault and granting a user access to the box you can proceed setting up the KES server.

KES Server Setup

1. Generate KES server private key & certificate

kes identity new --key private.key --cert public.crt --ip "127.0.0.1" --dns localhost

First, we need to generate a TLS private key and certificate for our KES server. If you already have TLS certificate you want to use for your KES server you can skip this step.

The command above generates a new TLS private key (private.key) and a self-signed X.509 certificate (public.crt) issued for the IP 127.0.0.1 and DNS name localhost similar to:

Your API key:

   kes:v1:APvbt/zbiewXNB+EwciOT+I21peq0odFYCwkJX8mMCxM

This is the only time it is shown. Keep it secret and secure!

Your Identity:

   1d1f89ad528a3bbb8fd64252d443c993f5a4d679b074d5bad49785e02ec38199

The identity is not a secret. It can be shared. Any peer
needs this identity in order to verify your API key.

The generated TLS private key is stored at: private.key
The generated TLS certificate is stored at: public.crt

The identity can be computed again via:

    kes identity of kes:v1:APvbt/zbiewXNB+EwciOT+I21peq0odFYCwkJX8mMCxM
    kes identity of public.crt

2. Generate a new API key

kes identity new

The client application needs some credentials to access the KES server. The command above generates a new API key similar to:

Your API key:

   kes:v1:AOlQZJRMYZeOioGk0ubYBMSFt1w6Hh1QZl3zG4PQxK/g

This is the only time it is shown. Keep it secret and secure!

Your Identity:

   eb559798a2fbcc3efbf036bed11108116e63f293324abdfe7574249ef5e56b36

The identity is not a secret. It can be shared. Any peer
needs this identity in order to verify your API key.

The identity can be computed again via:

    kes identity of kes:v1:AOlQZJRMYZeOioGk0ubYBMSFt1w6Hh1QZl3zG4PQxK/g

3. Configure KES server

Next, we can create the KES server configuration file: config.yml. Please, make sure that the identity in the policy section matches your API key identity.

address: 0.0.0.0:7373 # Listen on all network interfaces on port 7373

admin:
  identity: disabled  # We disable the admin identity since we don't need it in this guide 
   
tls:
  key: private.key    # The KES server TLS private key
  cert: public.crt    # The KES server TLS certificate
   
policy:
  my-app: 
    allow:
    - /v1/key/create/my-key*
    - /v1/key/generate/my-key*
    - /v1/key/decrypt/my-key*
    identities:
    - eb559798a2fbcc3efbf036bed11108116e63f293324abdfe7574249ef5e56b36 # Use the identity of your API key
   
keystore:
     entrust:
       keycontrol:
         endpoint: "https://keycontrol.my-org.com"    # Use your KeyControl instance endpoint.
         vault_id: ""                                 # The Vault ID - e.g: "e30497c1-bff7-4e81-beb7-fb35c4b7410c".
         box_id:   ""                                 # The Box name or ID - e.g: "tenant-1".
         credentials:
           username: ""                               # KeyControl username - e.g: "kes-tenant-1@my-org.com".
           password: ""                               # Password of KeyControl user

4. Start KES server

Now, we can start a KES server instance:

kes server --config config.yml --auth off

On linux, KES can use the mlock syscall to prevent the OS from writing in-memory data to disk (swapping). This prevents leaking senstive data accidentality. The following command allows KES to use the mlock syscall without running with root privileges:

sudo setcap cap_ipc_lock=+ep $(readlink -f $(which kes))

Then, we can start a KES server instance with memory protection:

kes server --config config.yml --auth off

KES CLI Access

1. Set KES_SERVER Endpoint

export KES_SERVER=https://127.0.0.1:7373

2. Set API key

export KES_API_KEY=kes:v1:AOlQZJRMYZeOioGk0ubYBMSFt1w6Hh1QZl3zG4PQxK/g

Use the API key generated before. The API key identity must match the identity in the KES config file.

3. Perform operations

Now, we can perform any API operation that is allowed based on the policy we assigned above. For example, we can create a key:

kes key create my-key-1

Then, we can use that key to generate a new data encryption key:

kes key dek my-key-1

This produces an output similar to:

{
 plaintext : UGgcVBgyQYwxKzve7UJNV5x8aTiPJFoR+s828reNjh0=
 ciphertext: eyJhZWFkIjoiQUVTLTI1Ni1HQ00tSE1BQy1TSEEtMjU2IiwiaWQiOiIxMTc1ZjJjNDMyMjNjNjNmNjY1MDk5ZDExNmU3Yzc4NCIsIml2IjoiVHBtbHpWTDh5a2t4VVREV1RSTU5Tdz09Iiwibm9uY2UiOiJkeGl0R3A3bFB6S21rTE5HIiwiYnl0ZXMiOiJaaWdobEZrTUFuVVBWSG0wZDhSYUNBY3pnRWRsQzJqWFhCK1YxaWl2MXdnYjhBRytuTWx0Y3BGK0RtV1VoNkZaIn0=
}

References

• Server API Doc
• Go SDK Doc