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.

K E S C l i e n t K E S S e r v e r C i p h e r T r u s t M a n a g e r

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>
Please make sure to use correct values for KSCTL_URL, KSCTL_USERNAME and KSCTL_PASSWORD If your CipherTrust Manager instance has been configured with a TLS certificate trusted by your machine, then you can also set KSCTL_NOSSLVERIFY: false.
  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",
      "resources": [

    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


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.

For a production setup we highly recommend to use a certificate signed by trusted Certificate Authority. This can be either your internal CA or a public CA such as Let’s Encrypt.
  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 and DNS name localhost (as SAN). Customize the command to match your setup.

    kes tool identity new --server --key server.key --cert server.cert --ip "" --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:"
  2. Create a private key and certificate for the application

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

    You can compute the app identity at any time.

    kes tool identity of app.cert
  3. Create the config file server-config.yml

    root:    disabled  # We disable the root identity since we don't need it in this guide 
      key:  server.key
      cert: server.cert
        - /v1/key/create/my-app*
        - /v1/key/generate/my-app*
        - /v1/key/decrypt/my-app*
        - ${APP_IDENTITY}
          endpoint: ""  # The REST API endpoint of your KeySecure instance - e.g.
            token:  ""  # Your refresh token
            domain: ""  # Your domain. If empty, defaults to root domain.
            retry:  15s
            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 tool 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 KES_CLIENT_CERT=app.cert
    export KES_CLIENT_KEY=app.key
    kes key create -k my-app-key
    export APP_IDENTITY=$(kes tool 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.
  6. 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>

Using KES with a MinIO Server

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

See the KES for MinIO instruction guide for additional steps needed to use your new KES Server with a MinIO 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 MinIO Server.

MinIO Server Requires Expanded Permissions:
Starting with MinIO Server RELEASE.2023-02-17T17-52-43Z, MinIO requires expanded KES permissions for functionality. The example configuration in this section contains all required permissions.