6.4.4.9 Using the keyring_aws Amazon Web Services Keyring Plugin使用keyring_aws亚马逊网络服务密钥环插件

Note注意

The keyring_aws plugin is an extension included in MySQL Enterprise Edition, a commercial product. keyring_aws插件是商业产品MySQL企业版中包含的一个扩展。To learn more about commercial products, see https://www.mysql.com/products/.要了解有关商业产品的更多信息,请参阅https://www.mysql.com/products/

The keyring_aws keyring plugin communicates with the Amazon Web Services Key Management Service (AWS KMS) as a back end for key generation and uses a local file for key storage. All keyring material is generated exclusively by the AWS server, not by keyring_aws.keyring_aws密钥环插件作为密钥生成的后端与Amazon Web Services密钥管理服务(aws KMS)通信,并使用本地文件进行密钥存储。所有密钥环材料都是由AWS服务器专门生成的,而不是由keyring_aws生成的。

keyring_aws is available on these platforms:keyring_aws在以下平台上可用:

The discussion here assumes that you are familiar with AWS in general and KMS in particular. Some pertinent information sources:这里的讨论假设您熟悉AWS,特别是KMS。一些相关信息来源:

The following sections provide configuration and usage information for the keyring_aws keyring plugin:以下部分提供了keyring_aws密钥环插件的配置和使用信息:

keyring_aws Configuration配置

To install keyring_aws, use the general instructions found in Section 6.4.4.3, “Keyring Plugin Installation”, together with the plugin-specific configuration information found here.要安装keyring_aws,请使用第6.4.4.3节,“keyring插件安装”中的一般说明,以及此处提供的插件特定配置信息。

The plugin library file contains the keyring_aws plugin and two loadable functions, keyring_aws_rotate_cmk() and keyring_aws_rotate_keys().插件库文件包含keyring_aws插件和两个可加载的函数,keyring_aws_rotate_cmk()keyring_aws-rotate_keys()

To configure keyring_aws, you must obtain a secret access key that provides credentials for communicating with AWS KMS and write it to a configuration file:要配置keyring_aws,您必须获得一个提供与aws KMS通信凭据的秘密访问密钥,并将其写入配置文件:

  1. Create an AWS KMS account.创建AWS KMS帐户。

  2. Use AWS KMS to create a secret access key ID and secret access key. The access key serves to verify your identity and that of your applications.使用AWS KMS创建秘密访问密钥ID和秘密访问密钥。访问密钥用于验证您和应用程序的身份。

  3. Use the AWS KMS account to create a customer master key (CMK) ID. 使用AWS KMS帐户创建客户主密钥(CMK)ID。At MySQL startup, set the keyring_aws_cmk_id system variable to the CMK ID value. MySQL启动时,将keyring_aws_cmk_id系统变量设置为cmk id值。This variable is mandatory and there is no default. (Its value can be changed at runtime if desired using SET GLOBAL.)此变量是必需的,没有默认值。(如果需要,可以在运行时使用SET GLOBAL更改其值。)

  4. If necessary, create the directory in which the configuration file should be located. The directory should have a restrictive mode and be accessible only to the account used to run the MySQL server. 如有必要,请创建配置文件应位于的目录。该目录应具有限制模式,并且只能由用于运行MySQL服务器的帐户访问。For example, on Unix and Unix-like systems, to use /usr/local/mysql/mysql-keyring/keyring_aws_conf as the file name, the following commands (executed as root) create its parent directory and set the directory mode and ownership:例如,在Unix和类Unix系统上,要使用/usr/local/mysql/mysql-keyring/keyring_aws_conf作为文件名,以下命令(以root身份执行)创建其父目录并设置目录模式和所有权:

    shell> cd /usr/local/mysql
    shell> mkdir mysql-keyring
    shell> chmod 750 mysql-keyring
    shell> chown mysql mysql-keyring
    shell> chgrp mysql mysql-keyring

    At MySQL startup, set the keyring_aws_conf_file system variable to /usr/local/mysql/mysql-keyring/keyring_aws_conf to indicate the configuration file location to the server.MySQL启动时,将keyring_aws_conf_file系统变量设置为/usr/local/MySQL/MySQL-keyring/keyring_aws_conf,以指示服务器的配置文件位置。

  5. Prepare the keyring_aws configuration file, which should contain two lines:准备keyring_aws配置文件,其中应包含两行:

    • Line 1: The secret access key ID第1行:秘密访问密钥ID

    • Line 2: The secret access key第2行:秘密访问密钥

    For example, if the key ID is wwwwwwwwwwwwwEXAMPLE and the key is xxxxxxxxxxxxx/yyyyyyy/zzzzzzzzEXAMPLEKEY, the configuration file looks like this:例如,如果密钥ID为wwwwwwwwwwwwwEXAMPLE,密钥为xxxxxxxxxxxxx/yyyyyyy/zzzzzzzzEXAMPLEKEY,则配置文件如下:

    wwwwwwwwwwwwwEXAMPLE
    xxxxxxxxxxxxx/yyyyyyy/zzzzzzzzEXAMPLEKEY

To be usable during the server startup process, keyring_aws must be loaded using the --early-plugin-load option. 为了在服务器启动过程中使用,必须使用--early-plugin-load选项加载keyring_awsThe keyring_aws_cmk_id system variable is mandatory and configures the customer master key (CMK) ID obtained from the AWS KMS server. keyring_aws_cmk_id系统变量是必需的,用于配置从aws KMS服务器获得的客户主密钥(cmk)id。The keyring_aws_conf_file and keyring_aws_data_file system variables optionally configure the locations of the files used by the keyring_aws plugin for configuration information and data storage. keyring_aws_conf_filekeyring_aws_data_file系统变量可选地配置keyring_aws插件用于配置信息和数据存储的文件的位置。The file location variable default values are platform specific. 文件位置变量的默认值是特定于平台的。To configure the locations explicitly, set the variable values at startup. 要显式配置位置,请在启动时设置变量值。For example, use these lines in the server my.cnf file, adjusting the .so suffix and file locations for your platform as necessary:例如,在服务器my.cnf文件中使用这些行,根据需要调整so后缀和平台的文件位置:

[mysqld]
early-plugin-load=keyring_aws.so
keyring_aws_cmk_id='arn:aws:kms:us-west-2:111122223333:key/abcd1234-ef56-ab12-cd34-ef56abcd1234'
keyring_aws_conf_file=/usr/local/mysql/mysql-keyring/keyring_aws_conf
keyring_aws_data_file=/usr/local/mysql/mysql-keyring/keyring_aws_data

For the keyring_aws plugin to start successfully, the configuration file must exist and contain valid secret access key information, initialized as described previously. 为了使keyring_aws插件成功启动,配置文件必须存在并包含有效的秘密访问密钥信息,如前所述进行初始化。The storage file need not exist. If it does not, keyring_aws attempts to create it (as well as its parent directory, if necessary).存储文件不需要存在。如果没有,keyring_aws会尝试创建它(以及它的父目录,如果需要)。

For additional information about the system variables used to configure the keyring_aws plugin, see Section 6.4.4.18, “Keyring System Variables”.有关用于配置keyring_aws插件的系统变量的更多信息,请参阅第6.4.4.18节,“keyring系统变量”

Start the MySQL server and install the functions associated with the keyring_aws plugin. 启动MySQL服务器并安装与keyring_aws插件关联的函数。This is a one-time operation, performed by executing the following statements, adjusting the .so suffix for your platform as necessary:这是一个一次性操作,通过执行以下语句,根据需要调整您的平台的.so后缀来执行:

CREATE FUNCTION keyring_aws_rotate_cmk RETURNS INTEGER
  SONAME 'keyring_aws.so';
CREATE FUNCTION keyring_aws_rotate_keys RETURNS INTEGER
  SONAME 'keyring_aws.so';

For additional information about the keyring_aws functions, see Section 6.4.4.15, “Plugin-Specific Keyring Key-Management Functions”.有关keyring_aws函数的更多信息,请参阅第6.4.4.15节,“插件特定的密钥管理函数”

keyring_aws Operation行动

At plugin startup, the keyring_aws plugin reads the AWS secret access key ID and key from its configuration file. It also reads any encrypted keys contained in its storage file into its in-memory cache.在插件启动时,keyring_aws插件从其配置文件中读取aws秘密访问密钥ID和密钥。它还将存储文件中包含的任何加密密钥读取到内存缓存中。

During operation, keyring_aws maintains encrypted keys in the in-memory cache and uses the storage file as local persistent storage. 在操作过程中,keyring_aws在内存缓存中维护加密密钥,并将存储文件用作本地持久存储。Each keyring operation is transactional: keyring_aws either successfully changes both the in-memory key cache and the keyring storage file, or the operation fails and the keyring state remains unchanged.每个密钥环操作都是事务性的:keyring_aws要么成功更改了内存中的密钥缓存和密钥环存储文件,要么操作失败,密钥环状态保持不变。

To ensure that keys are flushed only when the correct keyring storage file exists, keyring_aws stores a SHA-256 checksum of the keyring in the file. Before updating the file, the plugin verifies that it contains the expected checksum.为了确保只有在存在正确的密钥环存储文件时才刷新密钥,keyring_aws会在文件中存储密钥环的SHA-256校验和。在更新文件之前,插件会验证它是否包含预期的校验和。

The keyring_aws plugin supports the functions that comprise the standard MySQL Keyring service interface. Keyring operations performed by these functions are accessible at two levels:keyring_aws插件支持构成标准MySQL keyring服务接口的功能。通过这些功能执行的钥匙扣操作可在两个级别访问:

Example (using the SQL interface):示例(使用SQL接口):

SELECT keyring_key_generate('MyKey', 'AES', 32);
SELECT keyring_key_remove('MyKey');

In addition, the keyring_aws_rotate_cmk() and keyring_aws_rotate_keys() functions extend the keyring plugin interface to provide AWS-related capabilities not covered by the standard keyring service interface. 此外,keyring_aws_rotate_cmk()keyring_aws_rotate_keys()函数“扩展”了密钥环插件接口,以提供标准密钥环服务接口未涵盖的aws相关功能。These capabilities are accessible only by calling these functions using SQL. There are no corresponding C-languge key service functions.这些功能只能通过使用SQL调用这些函数来访问。没有相应的C语言按键服务功能。

For information about the characteristics of key values permitted by keyring_aws, see Section 6.4.4.12, “Supported Keyring Key Types and Lengths”.有关keyring_aws允许的键值特征的信息,请参阅第6.4.4.12节,“支持的keyring密钥类型和长度”

keyring_aws Credential Changes凭证更改

Assuming that the keyring_aws plugin has initialized properly at server startup, it is possible to change the credentials used for communicating with AWS KMS:假设keyring_aws插件在服务器启动时已正确初始化,则可以更改用于与AWS KMS通信的凭据:

  1. Use AWS KMS to create a new secret access key ID and secret access key.使用AWS KMS创建新的秘密访问密钥ID和秘密访问密钥。

  2. Store the new credentials in the configuration file (the file named by the keyring_aws_conf_file system variable). The file format is as described previously.将新凭据存储在配置文件(由keyring_aws_conf_file系统变量命名的文件)中。文件格式如前所述。

  3. Reinitialize the keyring_aws plugin so that it re-reads the configuration file. Assuming that the new credentials are valid, the plugin should initialize successfully.重新初始化keyring_aws插件,使其重新读取配置文件。假设新凭据有效,插件应成功初始化。

    There are two ways to reinitialize the plugin:有两种方法可以重新初始化插件:

    • Restart the server. This is simpler and has no side effects, but is not suitable for installations that require minimal server downtime with as few restarts as possible.重新启动服务器。这更简单,没有副作用,但不适合需要最少服务器停机时间和尽可能少重启的安装。

    • Reinitialize the plugin without restarting the server by executing the following statements, adjusting the .so suffix for your platform as necessary:通过执行以下语句重新初始化插件,而无需重新启动服务器,必要时调整平台的.so后缀:

      UNINSTALL PLUGIN keyring_aws;
      INSTALL PLUGIN keyring_aws SONAME 'keyring_aws.so';
      Note注意

      In addition to loading a plugin at runtime, INSTALL PLUGIN has the side effect of registering the plugin it in the mysql.plugin system table. 除了在运行时加载插件外,INSTALL PLUGIN还有在mysql.plugin系统表中注册插件的副作用。Because of this, if you decide to stop using keyring_aws, it is not sufficient to remove the --early-plugin-load option from the set of options used to start the server. 因此,如果您决定停止使用keyring_aws,从用于启动服务器的选项集中删除--early-plugin-load选项是不够的。That stops the plugin from loading early, but the server still attempts to load it when it gets to the point in the startup sequence where it loads the plugins registered in mysql.plugin.这会阻止插件提前加载,但服务器在启动序列中加载mysql.plugin中注册的插件时仍会尝试加载它。

      Consequently, if you execute the UNINSTALL PLUGIN plus INSTALL PLUGIN sequence just described to change the AWS KMS credentials, then to stop using keyring_aws, it is necessary to execute UNINSTALL PLUGIN again to unregister the plugin in addition to removing the --early-plugin-load option.因此,如果您执行刚才描述的UNINSTALL PLUGININSTALL PLUGIN序列来更改AWS KMS凭据,然后要停止使用keyring_AWS,除了删除--early-plugin-load选项外,还需要再次执行UNINSTALL PLUGIN以注销插件。