1.0 Introduction
MariaDB supports Data-at-Rest encryption. For more information about Data-at-Rest encryption in MariaDB, refer to https://mariadb.com/kb/en/library/data-at-rest-encryption-overview/
Cryptographically secure generation and secure management of encryption keys are required for true security of data at rest encrypted by MariaDB. Fortanix Data Security Manager provides a secure and flexible solution for this. For secure and easy encryption key management, Fortanix provides an encryption management solution through the Fortanix DSM key management plugin. The Fortanix Data Security Manager plugin is a key management and encryption plugin that uses Fortanix Data Security Manager. This plugin supports the use of multiple encryption keys.
Fortanix DSM key management plugin uses Fortanix Data Security Manager to generate AES keys. Keys are stored securely in Fortanix Data Security Manager and only key meta-data is stored in a file on disk. The key meta-data is used to fetch the key from Fortanix Data Security Manager when needed.
This article explains how to set up and configure Fortanix’s DSM key management plugin for MariaDB.
2.0 Prerequisites
Ensure the following:
Fortanix-Data-Security-Manager (DSM) Encryption Plugin: This plugin is required by MariaDB. This plugin can be provided by Foranix 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 Data Security Manager (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 the <Your_DSM_Service_URL> on the web browser and enter your credentials to log in to the Fortanix DSM.
Figure 1: Logging In
3.3 Creating a Group
Perform the following steps to create a group in the Fortanix DSM:
Click the Groups menu item in the DSM left navigation bar and click the + button on the Groups page to add a new group.
Figure 2: Add Groups
On the Adding new group page, enter the following details:
Title: Enter a title for your group.
Description (optional): Enter a short description for the group.
Click the SAVE button to create the new group.
The new group has been added to the Fortanix DSM successfully.
3.4 Creating an Application
Perform the following steps to create an application (app) in the Fortanix DSM:
Click the Apps menu item in the DSM left navigation bar and click the + button on the Apps page to add a new app.
Figure 3: Add Application
On the Adding new app page, enter the following details:
App name: Enter the name of your application.
Interface (optional): Select the KMIP option as interface type from the drop down menu.
ADD DESCRIPTION (optional): Enter a short description for the application.
Authentication method: Select the default API Key as the method of authentication from the drop down menu. For more information on these authentication methods, refer to User's Guide: Authentication documentation.
Assigning the new app to groups: Select the group created in Section 3.3: Creating a Group from the list.
Click the SAVE button to add the new application.
The new application has been 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:
Click the Apps menu item in the DSM left navigation bar and 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 the VIEW API KEY DETAILS button.
From the API Key Details dialog box, copy the API Key of the app to be used later.
4.0 Installing the Plugin
Fortanix DSM key management encryption plugin is available as a shared library (sdkms_key_management.so). This plugin library has a dependency on libcurl and libjsoncpp libraries. These libraries should be installed on the database server where this plugin will be used.
Copy the plugin library to MariaDB plugin library folder (for example : /usr/lib64/mysql/plugin).
Even after the package library is copied to the appropriate folder, the plugin is not actually installed by MariaDB. There are two methods that can be used to install the plugin with MariaDB.
The first method can be used to install the plugin without restarting the server. You can install the plugin dynamically by executing INSTALL SONAME or INSTALL PLUGIN.
For example: INSTALL SONAME 'sdkms_key_management';
The second method can be used to tell the server to load the plugin when it starts up. The plugin can be installed this way by providing the --plugin-load or the --plugin-load-add options. This can be specified as a command-line argument to mysqld or it 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_management5.0 Uninstalling the Plugin
Before you uninstall the plugin, you should ensure that data-at-rest encryption is completely disabled and that MariaDB no longer needs the plugin to decrypt tables or other files.
You can uninstall the plugin dynamically by executing UNINSTALL SONAME or UNINSTALL PLUGIN.
For example: UNINSTALL SONAME 'sdkms_key_management';
If you installed the plugin by providing the --plugin-load or the --plugin-load-add options in a relevant server option group in an option file, then those options should be removed to prevent the plugin from being loaded the next time the server is restarted.
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. For details about these system variables, please see the section below about system variables.
sdkms_key_management_api_endpointsdkms_key_management_api_keysdkms_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/mariadbAfter 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=YESNow, table t will be encrypted using the encryption key generated by Fortanix DSM.
For more information on how to use encryption, refer to 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=2When 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=valueScope: 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=valueScope: 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=valueScope: 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=valueScope: 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=valueScope: 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=valueScope: 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--
Following screen shot 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.
