See more

Using Self-Defending KMS for MariaDB Encryption at Rest

  • Last updated:
  • access_time Reading time:

Fortanix Self-Defending Key Management Encryption Plugin

Overview

MariaDB supports Data-at-Rest encryption. For details about Data-at-Rest encryption in MariaDB, please see following

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 Self-Defending KMS provides a secure and flexible solution for this. For secure and easy encryption key management, Fortanix provides an encryption management solution through the Self-Defending KMS key management plugin. The Self-Defending KMS plugin is a key management and encryption plugin that uses Fortanix Self-Defending KMS. This plugin supports the use of multiple encryption keys.

Self-Defending KMS key management plugin uses Self-Defending KMS to generate AES keys. Keys are stored securely in Self-Defending KMS and only key meta-data is stored in a file on disk. The key meta-data is used to fetch the key from Self-Defending KMS when needed.

This article explains how to set up and configure Fortanix’s Self-Defending KMS key management plugin for MariaDB.

Adding App in Self-Defending KMS

Before you use the plugin, you need to create an app in Self-Defending KMS that will be used to communicate with Self-Defending KMS for key management needs. Start by adding an App in Self-Defending KMS in an appropriate group or a new group. For instructions on how to add a group or app please user Getting Started Guide.

Once you have added the application, note down its API key by copying the API key from the App table view by clicking on the icon for “COPY API KEY” as shown below. You will need this API key for setup.

Installing the Plugin

Self-Defending KMS 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.

Apps-Step1.png

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 Self-Defending KMS Plugin

plugin_load_add = sdkms_key_management

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.

Configuring the Self-Defending Key Management Plugin

To enable the Self-Defending KMS 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_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 Self-Defending KMS Plugin

plugin_load_add = sdkms_key_management

sdkms_key_management_api_endpoint = https://sdkms.fortanix.com

sdkms_key_management_api_key = YjhlYWRkNTItMzN...WXFOVkVtUzBRcjVR

sdkms_key_management_meta_data_dir = /opt/fortanix/mariadb

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

Using the Self-Defending KMS Key Management Plugin

Once the Self-Defending KMS Key Management 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 Self-Defending KMS.

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

Using Multiple Encryption Keys

The Self-Defending KMS Key Management 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 Self-Defending KMS.

To create an encrypted table with a specific key id, create table as follows

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.

System Variables

sdkms_key_management_api_endpoint

  • Description: Self-Defending KMS API Endpoint. This is the URL of your Self-Defending KMS setup which will be used to communicate to Self-Defending KMS. 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: Self-Defending KMS App API key. This is the API key of your app in Self-Defending KMS that will be used authenticate to Self-Defending KMS. 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 Self-Defending KMS 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 Self-Defending KMS 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 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 

Self-Defending KMS Plugin in action

Application activity

Whenever a Self-Defending KMS plugin needs to create a key or use a key in Self-Defending KMS, it will authenticate to Self-Defending KMS. All activities by the plugin are logged in Self-Defending KMS.

 Following screen shot shows the activity logs for the MariaDB application and an audit trail of various encryption key usage.

applicationactivity.png

MariaDB Encryption Keys

The plugin creates keys in Self-Defending KMS. Name of the key is determined as follows

mariadb-tde-key-<key id>-<key version>

Following screen shot shows various keys created by Self-Defending KMS plugin in MariaDB.

mariadbecnryptionkeys.png

Encryption Key Usage

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

encryptionkeyusage.png