1.0 Introduction

This article describes how to integrate {{glossary.Fortanix-Data-Security-Manager}} (DSM) with MinIO’s Key Encryption Service (KES) server that uses Fortanix DSM as a persistent and secure key store. KES server runs inside Kubernetes and distributes cryptographic keys to Fortanix DSM applications.

2.0 Architecture Workflow

KES Server acts as a bridge between the Fortanix DSM and cloud-native applications. Here Fortanix DSM serves as the central KMS that protects the master keys and acts as the root of trust in your infrastructure. Instead of deploying and managing a separate KMS for each set of applications, when an application wants to encrypt data, it can request a new DEK from a KES server or ask the KES server to decrypt an encrypted DEK. This reduces the load on the central KMS (Fortanix DSM), as KES can handle the majority of application requests without directly interacting with Fortanix DSM. For more information, refer to https://blog.min.io/introducing-kes/.

3.0 Configure Fortanix DSM

A Fortanix DSM service must be configured, and the URL must be accessible. To create a Fortanix DSM account and group, refer to the following sections:

3.1 Signing Up

{{snippet.Signing Up}}

3.2 Creating an Account

Access <Your_DSM_Service_URL> in a web browser and enter your credentials to log in to Fortanix DSM.

{{snippet.Creating an Account}}

3.3 Creating a Group

Perform the following steps to create a group in the Fortanix DSM:

In the DSM left navigation panel, click the Groups menu item, and then click the + button to create a new group.
Figure 3: Add groups
On the Adding new group page, do the following:
1. Title: Enter a name for your group.
2. Description (optional): Enter a short description of the group.
Click SAVE to create the new group.

The new group is added to the Fortanix DSM successfully.

3.4 Creating an Application

Perform the following steps to create an application (app) in the Fortanix DSM:

In the DSM left navigation panel, click the Apps menu item, and then click the + button to create a new app.
Figure 4: Add application
On the Adding new app page, do the following:
1. App name: Enter the name for your application.
2. ADD DESCRIPTION (optional): Enter a short description of the application.
3. Authentication method: Select the default API Key as the authentication method from the drop down menu. For more information on these authentication methods, refer to the User's Guide: Authentication.
4. Assigning the new app to groups: Select the group created in Section 3.3: Creating a Group from the list.
Click SAVE to add the new application.

The new application is added to the Fortanix DSM successfully.

3.5 Copying the API Key

Perform the following steps to copy the API key from the Fortanix DSM:

In the DSM left navigation panel, click the Apps menu item, and then click the app created in Section 3.4: Creating an Application to go to the detailed view of the app.
On the INFO tab, click VIEW API KEY DETAILS.
From the API Key Details dialog box, copy the API Key of the app to use it later.

4.0 KES Server Setup

First, you need to generate a TLS private key and certificate for the 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 using a certificate signed by CA. For example, your internal CA or a public CA such as Let's Encrypt.

4.1 Generate a TLS Private Key and Certificate for the KES Server

The following command will generate a new TLS private key server.key and a X.509 certificate server.cert that is self-signed and issued for the IP 127.0.0.1 and DNS name localhost (as SAN). You may want to 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"

4.2 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 using:

kes tool identity of app.cert

4.3 Create Configuration File

Now, you have defined all entities in your demo setup. 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:
     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.4 Start the KES Server

Finally, start the KES Server in a new window/tab.

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

Where, --auth=off is required since your root.cert and app.cert certificates are self-signed.

4.5 Connect to the Server

In the previous window/tab, you can now connect to the server using the following commands:

export KES_CLIENT_CERT=app.cert
export KES_CLIENT_KEY=app.key
kes key create -k my-app-key

Where, -k is required because your are using self-signed certificates.

4.6 Decrypt Data Encryption Keys

Finally, you can derive and decrypt the 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>

Which key will be created on Fortanix DSM in the MinIO integration?