Fortanix SDKMS

This tutorial shows how to setup a KES server that uses Fortanix SDKMS 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 F o r t a n i x S D K M S

Fortanix SDKMS

  1. Create Application

    Register a new application that can authenticate and communicate to the Fortanix SDKMS instance.

    • Go to the Apps section in the Fortanix SDKMS UI.

      Step 1

    • Give the application a descriptive name, such as KES

    • Select REST API as the integration

    • Choose API Key as the authentication method

      Step 2

  2. Assign Group

    The assigned group serves as the default for the application. Newly created keys belong to this group unless you specify an explicit group ID in the KES configuration file.

    Step 3

  3. Create the application and copy the application’s API key.

    This key is the access credential KES uses to talk to Fortanix SDKMS.

    Step 4

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 127.0.0.1 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 "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

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

    You can compute the app identity anytime.

    kes tool identity of app.cert
    
  3. Create Configuration file

    Create the config file named server-config.yml:

    address: 0.0.0.0:7373
    
    admin:
      identity: disabled  # We disable the admin 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:
       fortanix:
         sdkms:
           endpoint: "<your-fortanix-sdkms-endpoint>"    # Use your Fortanix instance endpoint.
           credentials:
             key: "<your-api-key>" # Insert the application's API key      
    
  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.
  5. In the other tab, connect to the server

    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. 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 Fortanix SDKMS 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.