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
在以下平台上可用:
EL7
macOS 10.13 and 10.14
SLES 12
Ubuntu 14.04 and 16.04
Windows
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
密钥环插件的配置和使用信息:
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通信凭据的秘密访问密钥,并将其写入配置文件:
Create an AWS KMS account.创建AWS KMS帐户。
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和秘密访问密钥。访问密钥用于验证您和应用程序的身份。
Use the AWS KMS account to create a customer master key (CMK) ID. 使用AWS KMS帐户创建客户主密钥(CMK)ID。At MySQL startup, set the MySQL启动时,将keyring_aws_cmk_id
system variable to the CMK ID value. 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
更改其值。)
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 例如,在Unix和类Unix系统上,要使用/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:/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 MySQL启动时,将keyring_aws_conf_file
system variable to /usr/local/mysql/mysql-keyring/keyring_aws_conf
to indicate the configuration file location to the server.keyring_aws_conf_file
系统变量设置为/usr/local/MySQL/MySQL-keyring/keyring_aws_conf
,以指示服务器的配置文件位置。
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 例如,如果密钥ID为wwwwwwwwwwwwwEXAMPLE
and the key is xxxxxxxxxxxxx/yyyyyyy/zzzzzzzzEXAMPLEKEY
, the configuration file looks like this: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_aws
。The 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_file
和keyring_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 启动MySQL服务器并安装与keyring_aws
plugin. 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节,“插件特定的密钥管理函数”。
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服务接口的功能。通过这些功能执行的钥匙扣操作可在两个级别访问:
SQL interface: In SQL statements, call the functions described in Section 6.4.4.14, “General-Purpose Keyring Key-Management Functions”.SQL接口:在SQL语句中,调用第6.4.4.14节,“通用密钥管理函数”中描述的函数。
C interface: In C-language code, call the keyring service functions described in Section 5.6.9.2, “The Keyring Service”.C接口:在C语言代码中,调用第5.6.9.2节,“钥匙圈服务”中描述的钥匙圈服务函数。
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密钥类型和长度”。
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通信的凭据:
Use AWS KMS to create a new secret access key ID and secret access key.使用AWS KMS创建新的秘密访问密钥ID和秘密访问密钥。
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
系统变量命名的文件)中。文件格式如前所述。
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';
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 PLUGIN
加INSTALL PLUGIN
序列来更改AWS KMS凭据,然后要停止使用keyring_AWS,除了删除--early-plugin-load
选项外,还需要再次执行UNINSTALL PLUGIN
以注销插件。