Thales CipherTrust Manager (formerly Gemalto KeySecure)

This tutorial shows how to setup a KES server that uses a Thales CipherTrust Manager instance (formerly known as Gemalto KeySecure) as a persistent and secure key store.

This guide assumes that you have a running CipherTrust Manager instance. It has been tested with CipherTrust Manager k170v version 2.0.0 and Gemalto KeySecure k170v version 1.9.1 and 1.10.0.

CipherTrust Manager Setup

To connect to your CipherTrust Manager instance via the ksctl CLI you need a config.yaml file similar to:

KSCTL_URL: <your-keysecure-endpoint>
KSCTL_USERNAME: <your-user/admin-name>
KSCTL_PASSWORD: <your-user/admin-password>
KSCTL_VERBOSITY: false
KSCTL_RESP: json
KSCTL_NOSSLVERIFY: true
KSCTL_TIMEOUT: 30

1. Create a new group for KES

   ksctl groups create --name KES-Service

2. Create a new user for the group

   This prints a JSON object containing a user_id needed for a later step. If you already have an existing user that you want to assign to the KES-Service group, skip this step and proceed with 3.

   ksctl users create --name <username> --pword '<password>'

3. Assign the user to the KES-Service group created in step 1

   ksctl groups adduser --name KES-Service --userid "<user-ID>"

   The user ID prints when creating the user. Otherwise, obtain the ID with the ksctl users list command.

   A user-ID is similar to: local|8791ce13-2766-4948-a828-71bac67131c9.

4. Create a policy for the KES-Service group

   Create a text file named kes-policy.json that grants members of the KES-Service group create, read and delete permissions. The contents of the file should be similar to the following:

   {                                                                                          
     "allow": true,
     "name": "kes-policy",
     "actions":[
         "CreateKey",
         "ExportKey",
         "ReadKey",
         "DeleteKey"
     ],
     "resources": [
         "kylo:kylo:vault:secrets:*"
     ]
   }

   This policy allows KES to create, fetch and delete master keys. If you want to prevent KES from e.g. deleting master keys omit the DeleteKey action.

   Similarly, you can restrict the master keys that can be accessed by KES via the resources definition.

   Use the following command to create the policy using the file created above.

   ksctl policy create --jsonfile kes-policy.json

5. Attach the policy to the KES-Service group

   Create a file named kes-attachment.json with the policy attachment specification:

   {                                                                                          
      "cust": {
         "groups": ["KES-Service"]
      }
   }

   Use the following command to attach the kes-policy to the KES-Service group:

   ksctl polattach create -p kes-policy -g kes-attachment.json

6. Create a refresh token for the KES server to use to obtain short-lived authentication tokens.

   The following command returns a new refresh token:

   ksctl tokens create --user <username> --password '<password>' --issue-rt | jq -r .refresh_token

   Replace <username> and <password> with the credentials for a user that is a member of the KES-Service group.

   The command outputs a refresh token similar to

   CEvk5cdHLG7si05LReIeDbXE3PKD082YdUFAnxX75md3jzV0BnyHyAmPPJiA0

KES Server Setup

The KES Server requires a TLS private key and certificate.

The KES server is secure-by-default and can only run with TLS. This tutorial uses self-signed certificates for simplicity.

1. Generate a TLS private key and certificate for the KES server

   The following command generates a new TLS private key server.key and a self-signed X.509 certificate server.cert that is issued for the IP 127.0.0.1 and DNS name localhost (as SAN). Customize the command to match your setup.

   kes 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. Create a private key and certificate for the application

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

   You can compute the app identity at any time.

   kes identity of app.cert

3. Create 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: 
       allow:
       - /v1/key/create/my-app*
       - /v1/key/generate/my-app*
       - /v1/key/decrypt/my-app*
       identities:
       - ${APP_IDENTITY}
   
   keystore:
     gemalto:
       keysecure:
         endpoint: ""  # The REST API endpoint of your KeySecure instance - e.g. https://127.0.0.1
         credentials:
           token:  ""  # Your refresh token
           domain: ""  # Your domain. If empty, defaults to root domain.
           retry:  15s
         tls:
           ca: "" # Optionally, specify the certificate of the CA that issued the KeySecure TLS certificate.

   Use your refreshed token.

4. Start a KES server in a new window/tab:

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

   The command uses --auth=off because our root.cert and app.cert certificates are self-signed.

   If starting the server fails with an error message similar to:

   x509: certificate is not valid for any names, but wanted to match <your-endpoint>

   then your CipherTrust Manager instance serves a TLS certificate with neither a common name (subject) nor a subject alternative name (SAN). Such a certificate is invalid. Update the TLS certificate of your CipherTrust Manager instance.

   You can analyze a certificate with: openssl x509 -text -noout <certificate>

5. In the other window or tab, connect to the server

   export MINIO_KES_CERT_FILE=app.cert
   export MINIO_KES_KEY_FILE=app.key
   kes key create -k my-app-key

6. Derive and decrypt data keys from the previously created my-app-key

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

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

Using KES with a AIStor Server

AIStor Server requires KES to enable server-side data encryption.

See the KES for AIStor instruction guide for additional steps needed to use your new KES Server with a AIStor Server.

Configuration References

The following section describes the Key Encryption Service (KES) configuration settings to use Thales CipherTrust Manager (formerly Gemalto KeySecure) as the root KMS to store external keys, such as the keys used for Server-Side Encryption on a AIStor Server.

address: 0.0.0.0:7373
root: ${ROOT_IDENTITY}

tls:
  key: kes-server.key
  cert: kes-server.cert

api:
  /v1/ready:
    skip_auth: false
    timeout:   15s

policy:
  minio-server:
    allow:
    - /v1/key/create/*
    - /v1/key/generate/*
    - /v1/key/decrypt/*
    - /v1/key/bulk/decrypt
    - /v1/key/list/*
    - /v1/status
    - /v1/metrics
    - /v1/log/audit
    - /v1/log/error
    deny:
    - /v1/key/generate/my-app-internal*
    - /v1/key/decrypt/my-app-internal*
    identities:
    - ${MINIO_IDENTITY}

  my-app:
    allow:
    - /v1/key/create/my-app*
    - /v1/key/generate/my-app*
    - /v1/key/decrypt/my-app*
    deny:
    - /v1/key/generate/my-app-internal*
    - /v1/key/decrypt/my-app-internal*
    identities:
    - df7281ca3fed4ef7d06297eb7cb9d590a4edc863b4425f4762bb2afaebfd3258
    - c0ecd5962eaf937422268b80a93dde4786dc9783fb2480ddea0f3e5fe471a731

keys:
  - name: "minio-encryption-key-alpha"
  - name: "minio-encryption-key-baker"
  - name: "minio-encryption-key-charlie"

cache:
  expiry:
    any: 5m0s
    unused: 20s
    offline: 0s

log:

  # Log error events to STDERR. Valid values are "on" or "off". 
  # Default is "on".
  error: on

  # Log audit events to STDOUT. Valid values are "on" and "off". 
  # Default is "off".
  audit: off

keystore:
  gemalto:
    keysecure:
      endpoint: ""   
      credentials:   
        token: ""    
        domain: ""   
        retry: 15s   
      tls:           
        ca: ""