Fortanix SDKMS

This tutorial shows how to setup a KES server that uses Fortanix SDKMS as a persistent and secure key store:

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.

     

   • Give the application a descriptive name, such as KES

   • Select REST API as the integration

   • Choose API Key as the authentication method

     

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.

   

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

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

   

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

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

   You can compute the app identity anytime.

   kes 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 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 MINIO_KES_CERT_FILE=app.cert
   export MINIO_KES_KEY_FILE=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 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 Fortanix SDKMS 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:
  fortanix:
    # https://www.fortanix.com/products/data-security-manager/key-management-service
    sdkms: 
      endpoint: "" 
      group_id: "" 
      credentials: 
        key: ""    
      tls:         
        ca: ""