Using Fortanix Data Security Manager for MariaDB Encryption at Rest

1.0 Introduction

MariaDB supports Data-at-Rest encryption. For more information about Data-at-Rest encryption in MariaDB, refer to the https://mariadb.com/kb/en/library/data-at-rest-encryption-overview/

MariaDB requires cryptographically secure key generation and centralized key management to protect data at rest. Fortanix Data Security Manager (DSM) provides a secure and flexible way to manage these encryption keys outside the database environment.

You can use the Fortanix DSM Key Management Plugin to integrate MariaDB with Fortanix DSM. The plugin allows MariaDB to encrypt data using keys that Fortanix DSM generates, stores, and manages.

Fortanix DSM generates AES keys and stores them securely in its FIPS 140-2 Level 3 HSM-backed infrastructure. The plugin stores only key metadata on disk, which it uses to retrieve the full key from Fortanix DSM when needed. This approach ensures strong protection of encryption keys and supports granular key management.

This section explains how to:

• Install the Fortanix DSM plugin for MariaDB

• Configure the plugin to connect to Fortanix DSM

• Create encrypted tables using externally managed keys

• View and audit key usage in Fortanix DSM

2.0 Prerequisites

Ensure the following:

• Fortanix DSM Encryption Plugin: This plugin is required by MariaDB. This plugin can be provided by Fortanix on request depending on the MariaDB version.

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

To get started with the Fortanix DSM cloud service, you must register an account at <Your_DSM_Service_URL>. For example, https://eu.smartkey.io.

For detailed steps on how to set up the Fortanix DSM, refer to the User's Guide: Sign Up for Fortanix Data Security Manager SaaS documentation.

3.2 Creating an Account

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

For more information on how to set up an account in Fortanix DSM, refer to the User's Guide: Getting Started with Fortanix Data Security Manager - UI.

3.3 Creating a Group

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

1. In the DSM left navigation panel, click the Groups menu item, and then click the + button to create a new group.

   

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

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

1. In the DSM left navigation panel, click the Apps menu item, and then click the + button to create a new app.

   

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

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

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

2. On the INFO tab, click VIEW API KEY DETAILS.

3. From the API Key Details dialog box, copy the API Key of the app to be used later.

4.0 Installing the Plugin

The Fortanix DSM key management plugin is distributed as a shared library named sdkms_key_management.so. This plugin enables MariaDB to use encryption keys managed securely in Fortanix DSM.

Ensure the following libraries are installed on the system running MariaDB:

• libcurl

• libjsoncpp

These libraries are required for the plugin to communicate with the Fortanix DSM and handle configuration data.

Copy the sdkms_key_management.so plugin file to the MariaDB plugin directory. The default plugin directory is:

/usr/lib64/mysql/plugin

MariaDB does not install the plugin automatically when the shared library is copied. Use one of the following methods to install it:

1. Option A: Install Without Restart (Dynamic Loading)

   To install the plugin without restarting the server, run the following command in the MariaDB client:

   INSTALL SONAME 'sdkms_key_management';

   This command dynamically loads and registers the plugin with the running MariaDB server. For more information, refer to the INSTALL SONAME or INSTALL PLUGIN.

2. Option B: Install at Startup (Persistent)

   To ensure the plugin loads automatically when MariaDB starts, add the following line to the relevant option group in the MariaDB configuration file (my.cnf or mysqld.cnf):

   [mariadb]
   
   # Fortanix DSM Plugin
   plugin_load_add = sdkms_key_management

   Restart MariaDB to apply the configuration:

   sudo systemctl restart mariadb

   NOTE

   Use plugin_load_add instead of plugin-load if you are loading multiple plugins.

5.0 Uninstalling the Plugin

Before you uninstall the Fortanix DSM plugin, verify that MariaDB no longer uses it for decrypting any encrypted tables or data files. Ensure data-at-rest encryption is disabled or migrated as needed to avoid data inaccessibility.

To uninstall the plugin without restarting the MariaDB server, execute the following command from the MariaDB client:

sqlCopyEditUNINSTALL SONAME 'sdkms_key_management';

Alternatively, if the plugin was registered with a specific name, use:

sqlCopyEditUNINSTALL PLUGIN sdkms_key_management;

For more information, refer to the UNINSTALL SONAME or UNINSTALL PLUGIN.

If you configured MariaDB to load the plugin at startup using the --plugin-load or --plugin-load-add options in the configuration file (for example, my.cnf or mysqld.cnf), remove or comment out the corresponding line:

iniCopyEdit# plugin_load_add = sdkms_key_management

After making this change, restart MariaDB to apply the updated configuration:

bashCopyEditsudo systemctl restart mariadb

Failing to remove the plugin reference from the configuration file may cause MariaDB to attempt loading a missing plugin on startup, resulting in server errors.

6.0 Configure the Fortanix DSM Plugin

To enable the Fortanix DSM plugin, you also need to set the plugin's system variables. There are three system variables that are required to be set. They are as follows.

• sdkms_key_management_api_endpoint

• sdkms_key_management_api_key

• sdkms_key_management_meta_data_dir

These system variables can be specified as command-line arguments to mysqld or they can be specified in a relevant server option group in an option file. For example:

[mariadb]

...

# Fortanix Data Security Manager Plugin

plugin_load_add = sdkms_key_management

sdkms_key_management_api_endpoint = https://<fortanix_dsm_url>

sdkms_key_management_api_key = YjhlYWRkNTItMzN...WXFOVkVtUzBRcjVR

sdkms_key_management_meta_data_dir = /opt/fortanix/mariadb

After you have updated the configuration file, restart the MariaDB server to apply the changes and make the key management and encryption plugin available for use.

7.0 Using the Fortanix DSM Plugin

After the Fortanix DSM Plugin is enabled, you can use it by creating an encrypted table:

NOTE

By default Key ID 1 will be used if not explicitly specified.

CREATE TABLE t (i int) ENGINE=InnoDB ENCRYPTED=YES

Now, table t will be encrypted using the encryption key generated by Fortanix DSM.

For more information on how to use encryption, refer to the Data at Rest Encryption.

8.0 Using Multiple Encryption Keys

The Fortanix DSM Plugin supports using multiple encryption keys. Each encryption key can be defined with a different 32-bit integer as a key identifier. If a previously unused identifier is used, then the plugin will automatically generate a new key in Fortanix DSM.

Run the following command to create an encrypted table with a specific key-id:

CREATE TABLE t (i int) ENGINE=InnoDB ENCRYPTED=YES ENCRYPTION_KEY_ID=2

When encrypting InnoDB tables, the key that is used to encrypt tables can be changed.

When encrypting Aria tables, the key that is used to encrypt tables cannot currently be changed.

9.0 System Variables

sdkms_key_management_api_endpoint

• Description: Fortanix DSM API Endpoint. This is the URL of your Fortanix DSM setup which will be used to communicate to Fortanix DSM. The plugin will not work if this is not set.

• Command-line:

  --sdkms-key-management-api-endpoint=value

• Scope: Global

• Dynamic: no

• Data Type: string

• Default Value:

sdkms_key_management_api_key

• Description: Fortanix DSM App API key. This is the API key of your app in Fortanix DSM that will be used to authenticate to Fortanix DSM. The plugin will not work if this is not set

• Command-line:

  --sdkms-key-management-api-key=value

• Scope: Global

• Dynamic: no

• Data Type: string

• Default Value:

sdkms_key_management_meta_data_dir

• Description: Location for storing Fortanix DSM meta-data files. This directory must exist and mysql user should have read and write permission in this directory. The plugin will not work if this is not set

• Command-line:

  --sdkms-key-management-meta-data-dir=value

• Scope: Global

• Dynamic: no

• Data Type: string

• Default Value:

sdkms_key_management_request_timeout

• Description: Maximum time in seconds to connect to Fortanix DSM and perform the operation. If not specified, the default value of 10 seconds is used

• Command-line:

  --sdkms-key-management-request-timeout=value

• Scope: Global

• Dynamic: no

• Data Type: integer

• Default Value: 10

sdkms_key_management_proxy_address

• Description: Address of proxy if required. This should be in the form of proxy_server:proxy_port.

• Command-line:

  --sdkms-key-management-proxy-address=value

• Scope: Global

• Dynamic: no

• Data Type: string

• Default Value: Null

sdkms_key_management_proxy_credentials

• Description: If the proxy requires authentication, then specify the credentials as username:password.

• Command-line:

  --sdkms-key-management-proxy-credentials=value

• Scope: Global

• Dynamic: no

• Data Type: string

• Default Value: Null 

10.0 Fortanix DSM Plugin in Action

10.1 Application Activity

Whenever a Fortanix DSM plugin needs to create a key or use a key in Fortanix DSM, it will authenticate to Fortanix DSM. All activities by the plugin are logged in Fortanix DSM.

 The following image shows the activity logs for the MariaDB application and an audit trail of various encryption key usage:

10.2 MariaDB Encryption Keys

The plugin creates keys in Fortanix DSM. Name of the key is determined as follows

mariadb-tde-key--

The following figure shows various keys created by the Fortanix DSM plugin in MariaDB.

10.3 Encryption Key Usage

Whenever the plugin needs to use a key for processing an encrypted table, it will need to fetch the key from Fortanix DSM. The following screenshot shows activity logs for a specific encryption key as the key is created and later used by the Fortanix DSM key management plugin in MariaDB for processing an encrypted table.