Eperi Key Management Encryption Plugin

MariaDB's data-at-rest encryption requires the use of a key management and encryption plugin. These plugins are responsible both for the management of encryption keys and for the actual encryption and decryption of data.

MariaDB supports the use of multiple encryption keys. Each encryption key uses a 32-bit integer as a key identifier. If the specific plugin supports key rotation, then encryption keys can also be rotated, which creates a new version of the encryption key.

The Eperi Key Management plugin is a key management and encryption plugin that integrates with eperi Gateway for Databases.

Overview

The Eperi Key Management plugin is one of the key management and encryption plugins that can be set up for users who want to use data-at-rest encryption. Some of the plugin's primary features are:

  • It reads encryption keys from eperi Gateway for Databases.
  • It supports multiple encryption keys.
  • It supports key rotation.
  • It supports two different algorithms for encrypting data.

The eperi Gateway for Databases stores encryption keys on the key server outside of the database server itself, which provides an extra level of security. The eperi Gateway for Databases also supports performing all data encryption operations on the key server as well, but this is optional.

It also provides the following benefits:

  • Key management outside the database
  • No keys on database server hard disk
  • Graphical user interface for configuration
  • Encryption and decryption outside the database, supporting HSM's for maximum security.

Support for MariaDB is provided in eperi Gateway for Databases 3.4.

Installing the Eperi Key Management Plugin's Package

For information on how to install the package, see Eperi's documentation at the Eperi Customer Portal.

Installing the Plugin

Even after the package that contains the plugin's shared library is installed on the operating system, the plugin is not actually installed by MariaDB by default. The plugin can be installed 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]
...
plugin_load_add = eperi_key_management_plugin

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 'eperi_key_management_plugin';

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 Eperi Key Management Plugin

For information on how to configure the plugin, see Eperi's documentation at the Eperi Customer Portal.

Using the Eperi Key Management Plugin

Once the Eperi Key Management Plugin is enabled, you can use it by creating an encrypted table:

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

Now, table t will be encrypted using the encryption key from the key server.

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

Using Multiple Encryption Keys

The Eperi Key Management Plugin supports using multiple encryption keys. Each encryption key can be defined with a different 32-bit integer as a key identifier.

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.

Key Rotation

The Eperi Key Management plugin supports key rotation.

Versions

Version Status Introduced
1.0 Unknown eperi Gateway for Databases 3.4.0

System Variables

eperi_key_management_plugin_databaseId

  • Description: Determines the database ID which is processed in the eperi Gateway.
  • Commandline: --eperi-key-management-plugin-databaseid=value
  • Scope: Global
  • Dynamic: No
  • Data Type: integer
  • Default Value: 1

eperi_key_management_plugin_encryption_algorithm

  • Description: This system variable is used to determine which algorithm the plugin will use to encrypt data.
    • The recommended algorithm is AES_CTR, but this algorithm is only available when MariaDB is built with recent versions of OpenSSL. If the server is built with wolfSSL or yaSSL, then this algorithm is not available. See TLS and Cryptography Libraries Used by MariaDB for more information about which libraries are used on which platforms.
  • Commandline: --eperi-key-management-plugin-encryption-algorithm=value
  • Scope: Global
  • Dynamic: No
  • Data Type: enumerated
  • Default Value: AES_CBC
  • Valid Values: AES_CBC, AES_CTR

eperi_key_management_plugin_encryption_mode

  • Description: Encryption mode.
  • Commandline: --eperi-key-management-plugin-encryption-mode=value
  • Scope: Global
  • Dynamic: No
  • Data Type: enumerated
  • Default Value: database
  • Valid Values: database, gateway

eperi_key_management_plugin_osslmt

  • Description: Determines, whether the plugin should register callback functions for OpenSSL thread support.
  • Commandline: --eperi-key-management-plugin-osslmt=value
  • Scope: Global
  • Dynamic: No
  • Data Type: boolean
  • Default Value: 0 (Linux), 1 (Windows)

eperi_key_management_plugin_port

  • Description: Listener port for plugin.
  • Commandline: --eperi-key-management-plugin-port=value
  • Scope: Global
  • Dynamic: No
  • Data Type: integer
  • Default Value: 14332

eperi_key_management_plugin_url

  • Description: URL to key server. The expected format of the URL is <host>:<port>. The port number is optional, and the port number defaults to 14333 if it is not specified.
  • Commandline: --eperi-key-management-plugin-url=value
  • Scope: Global
  • Dynamic: No
  • Data Type: string
  • Default Value: NULL

eperi_key_management_plugin_url_check_disabled

  • Description: Determines, whether the connection between plugin and eperi Gateway is tested at server startup.
  • Commandline: --eperi-key-management-plugin-url-check-disabled=value
  • Scope: Global
  • Dynamic: No
  • Data Type: boolean
  • Default Value: 1

Options

eperi_key_management_plugin

  • Description: Controls how the server should treat the plugin when the server starts up.
    • Valid values are:
      • OFF - Disables the plugin without removing it from the mysql.plugins table.
      • ON - Enables the plugin. If the plugin cannot be initialized, then the server will still continue starting up, but the plugin will be disabled.
      • FORCE - Enables the plugin. If the plugin cannot be initialized, then the server will fail to start with an error.
      • FORCE_PLUS_PERMANENT - Enables the plugin. If the plugin cannot be initialized, then the server will fail to start with an error. In addition, the plugin cannot be uninstalled with UNINSTALL SONAME or UNINSTALL PLUGIN while the server is running.
    • See Plugin Overview: Configuring Plugin Activation at Server Startup for more information.
  • Commandline: --eperi-key-management-plugin=value
  • Data Type: enumerated
  • Default Value: ON
  • Valid Values: OFF, ON, FORCE, FORCE_PLUS_PERMANENT

See Also

Content reproduced on this site is the property of its respective owners, and this content is not reviewed in advance by MariaDB. The views, information and opinions expressed by this content do not necessarily represent those of MariaDB or any other party.

© 2021 MariaDB
Licensed under the Creative Commons Attribution 3.0 Unported License and the GNU Free Documentation License.
https://mariadb.com/kb/en/eperi-key-management-encryption-plugin/