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.
.png?sv=2022-11-02&spr=https&st=2025-05-29T08%3A40%3A01Z&se=2025-05-29T08%3A57%3A01Z&sr=c&sp=r&sig=GRiD7rI8u74RuHe9TMl1rWS2pJesWKxIYfagcASFjgo%3D)
Figure 1: Logging in
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:
In the DSM left navigation panel, click the Groups menu item, and then click the + button to create a new group.
Figure 2: Add groups
On the Adding new group page, do the following:
Title: Enter a name for your group.
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 3: Add application
On the Adding new app page, do the following:
App name: Enter the name for your application.
ADD DESCRIPTION (optional): Enter a short description of the application.
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.
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 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:
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.
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:

Figure 4: App info tab
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.

Figure 5: Security Objects created
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.

Figure 6: Security Object info