Gemalto KeySecure

Note: This guide refers to the Gemalto KeySecure support added by #63. This feature has not been released, yet

This guide shows how to setup a KES server that uses a Gemalto KeySecure instance as a persistent and secure key store:

1. KeySecure Setup
2. KES Server Setup
3. Recommendations

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

KeySecure Setup

This guide assumes that you have a running KeySecure instance. It has been tested with KeySecure k170v version 1.9.1.

The KES server needs to authenticate to the KeySecure instance. Therefore, we need to create a refresh token which the KES server can use to obtain short-lived authentication tokens. You can obtain a refresh token with the KeySecure CLI:

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

If you don't specify a domain then ksctl will assume that the user is assigned to the root domain.

This command will output a refresh token - similar to:

CEvk5cdHLG7si05LReIeDbXE3PKD082YdUFAnxX75md3jzV0BnyHyAmPPJiA0

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. First, create the TLS private key:

   openssl ecparam -genkey -name prime256v1 | openssl ec -out server.key

2. Then, create the corresponding TLS X.509 certificate:

   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"

   You can ignore output messages like: req: No value provided for Subject Attribute C, skipped. OpenSSL just tells you that you haven't specified a country, state, a.s.o for the certificate subject. Since we generate a self-signed certificate we don't have to worry about this.

3. 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

4. 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:
     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.

   Please use your refresh token credentials.

5. 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.
   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 KeySecure instance serves a TLS certificate with neither a common name (subject) nor a subject alternative name (SAN). Such a certificate is invalid. Please update the TLS certificate of your KeySecure instance. You can analyze a certificate with: openssl x509 -text -noout <certificate>

6. 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 app-key -k

   -k is required because we use self-signed certificates

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

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

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