Documentation Home
MySQL 9.4 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 41.2Mb
PDF (A4) - 41.3Mb
Man Pages (TGZ) - 262.8Kb
Man Pages (Zip) - 368.8Kb
Info (Gzip) - 4.1Mb
Info (Zip) - 4.1Mb


MySQL 9.4 Reference Manual  / ...  / Security  / Security Components and Plugins  / The MySQL Keyring  /  Using the component_keyring_aws AWS Keyring Component

8.4.5.8 Using the component_keyring_aws AWS Keyring Component

Note

component_keyring_aws is an extension included in MySQL Enterprise Edition, a commercial product. To learn more about commercial products, seehttps://www.mysql.com/products/.

The AWS Keyring component is intended to replace the AWS Keyring plugin, which is now deprecated. SeeMigration from AWS keyring plugin.

Thecomponent_keyring_aws keyring component stores keys encrypted by AWS KMS, using the Customer Managed Key (CMK) service, in a file local to the server host.

component_keyring_aws supports the functions that comprise the standard MySQL Keyring service interface. Keyring operations performed by those functions are accessible in SQL statements as described inSection 8.4.5.14, “General-Purpose Keyring Key-Management Functions”.

Example:

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

For information about the characteristics of key values permitted bycomponent_keyring_aws, seeSection 8.4.5.12, “Supported Keyring Key Types and Lengths”.

To usecomponent_keyring_aws for keystore management, you must:

  1. Write a manifest that tells the server to loadcomponent_keyring_aws, as described inSection 8.4.5.2, “Keyring Component Installation”.

    Forcomponent_keyring_aws, the contents of the manifest file are shown here:

    {  "components": "file://component_aws_keyring"}

  2. Write a configuration file forcomponent_keyring_aws, as described inAWS Keyring Component Configuration.

The AWS keyring component supports two authentication modes, simple and native, as determined by the value of theaws_authentication.mode parameter specified incomponent_keyring_aws.cnf. This parameter is required. Configuration of the component for supporting each of these modes can be found inSimple authentication mode, andNative authentication mode, respectively.

AWS Keyring Component Configuration

When it initializes,component_keyring_aws reads a component configuration filecomponent_keyring_aws.cnf, as described inSection 8.4.5.2, “Keyring Component Installation”.

In some cases, additional information can be read from an AWS configuration file, a credentials file, or both. These files are described later in this section.

Ifcomponent_keyring_aws cannot find the configuration file, an error results, and the component cannot initialize.

Thecomponent_keyring_aws.cnf component configuration file must be in valid JSON format. Configuration items supported in this file are shown in the following table:

Table 8.31 component_keyring_aws.cnf Configuration Items

ParameterParentDescriptionValidRequiredDefaultPermitted values
cmk_id—Customer Managed Key (CMK) identifier obtained from AWS KMS server—Yes——
data_file—Location of component JSON storage file—Yes——
cache_keys—true: Keys cached in memory in plaintext;false: Keys decrypted when accessed—Nofalsetrue,false
modeaws_authenticationAWS authentication mode—Yes—native,simple
profileaws_authenticationName of AWS profile used by AWS native authenticationWhenaws_authentication.mode isnativeNodefault—
regionaws_authenticationAWS regionWhenaws_authentication.mode issimpleYes, whenaws_authentication.mode issimpleus-east-1—
access_key_idaws_authenticationAWS acccess key identifierWhenaws_authentication.mode issimpleYes, whenaws_authentication.mode issimple——
access_key_secretaws_authenticationAWS acccess key secretWhenaws_authentication.mode issimpleYes, whenaws_authentication.mode issimple——
connect_timeout_msaws_connectionSocket connection timeout No1000—
hostaws_connection.proxyProxy host—No——
portaws_connection.proxyProxy port—No——
useraws_connection.proxyProxy user name—No——
passwordaws_connection.proxyProxy user password—No——
read_only—Whentrue, no operations which modify the keyring areallowed—Nofalsetrue,false

aws_authentication.region defaults tous-east-1, and must be set explicitly for any other region.

Component configuration file parameters that are not valid are ignored. For example,aws_authentication.access_key_id andaws_authentication.access_key_secret have no effect when theaws_authentication.mode isnative.

The database administrator has the responsibility for creating any configuration files to be used, and for ensuring that their contents are correct. If an error occurs, server startup fails; the administrator must correct any issues indicated by diagnostic messages in the server error log.

Important

Any configuration file that stores a key secret should have a restrictive mode and be accessible only to the account used to run the MySQL server.

Given the preceding configuration file items, to configurecomponent_keyring_aws, create a component configuration file namedcomponent_keyring_aws.cnf in the directory indicated previously.

A read/write keyring data file using JSON format, whose location is determined by thedata_file configuration item, is also required; the following instructions assume that such a file exists at/usr/local/mysql/keyring.json. An example of its content is shown here:

{  "version":"1.0","elements":    [      {        "user":"mary@%",        "data_id":"key0",        "data_type":"AES",        "data":"0102010078865A35D86559D92C3124146819057E927382E061F6EA7613DF2B9BE72FB0E62C01A1CF92B96934CB08D42D231CF6828A420000006E306C06092A864886F70D010706A05F305D020100305806092A864886F70D010701301E060960864801650304012E3011040C19F809F27900EACEF99DE2B4020110802BEDA406610AF033504B601C5EC937EFB9F38BB631F68856FF7FA81E637FCC400BA35900929E99E628E1B3E7",        "extension":[]      },      {        "user":"mary@%",        "data_id":"key1",        "data_type":"AES",        "data":"0102010078865A35D86559D92C3124146819057E927382E061F6EA7613DF2B9BE72FB0E62C017CAA36B2F756892C3AFCAA074A13E655000001043082010006092A864886F70D010706A081F23081EF0201003081E906092A864 886F70D010701301E060960864801650304012E3011040CCDECB095F68DE68BC331A0730201108081BB52EF64775CCE3DD47ADD8C274A297EB1A6E988085C0036D0AAE64DE50BB7D5AC020A12BF70",        "extension":[]      },      {        "user":"john@%",        "data_id":"key2",        "data_type":"AES",        "data":"0102010078865A35D86559D92C3124146819057E927382E061F6EA7613DF2B9BE72FB0E62C01BB9CC22B82E3DB50C76FD855DE0CB305000001043082010006092A864886F70D010706A081F23081EF0201003081E906092A864886F70D010701301E060960864801650304012E3011040C778A6EDBA93A1FF27D82F5340201108081BB809B9599C191BF0DF1F7721DB2915F7A02A5928981BF9264D9B76BE41046C3B5AF60006F4A",        "extension":[]        }    ]}
Note

Each of thedata values just shown consists of a single line; the values have been wrapped here to fit within the confines of the viewing space.

Keyring operations are transactional:component_keyring_aws uses a backup file during write operations to ensure that it can roll back to the original file if an operation fails. The backup file has the same name as the data file with the added suffix.backup.

component_keyring_aws configuration files may not be placed anywhere within the MySQL server data directory.

Simple authentication mode

This mode provides ease of use when more advanced AWS mechanisms are not needed. (This also simplifies upgrading from the legacy AWS keyring plugin to the component; seeMigration from AWS keyring plugin.) Theconfig andcredentials files are not used in this case; the configuration is read from the globalcomponent_keyring_aws.cnf only. To enable simple authentication mode, setaws_authentication.mode tosimple in this file.

In simple mode, the component uses the access key ID and secret obtained from AWS, which are also set incomponent_keyring_aws.cnf, as the values of theaws_authentication.access_key_id andaws_authentication.access_key_secret configuration items. In addition, you must specify a region usingaws_authentication.region.

The contents of a samplecomponent_keyring_aws.cnf that meets the requirements for enabling simple authentication mode are shown here:

{  "cmk_id": "arn:aws:kms:us-east-1:79566666666:key/d0111111-1111-1111-1111-999999999abd",  "data_file": "/usr/local/mysql/keyring.json",  "cache_keys": "true",  "aws_authentication":   {    "mode": "simple",    "region": "us-east-1",    "access_key_id": "wwwwwwwwwwwwwEXAMPLE",    "access_key_secret": "xxxxxxxxxxxxx/yyyyyyy/zzzzzzzzEXAMPLEKEY"  }}
Native authentication mode

Whenaws_authentication.mode isnative, the AWS keyring component uses the standard AWS authentication configuration mechanism (seeAWS SDKs and Tools: Configuration) and the AWS profile specified in the component configuration file. The source for AWS credentials in this case is the AWS default credentials provider chain (seeAWS SDKs and Tools: Standardized credential providers).

Enabling AWS native authentication mode with the AWS Keyring component are more complex, but includes the following advantages:

  • Conformance with standard AWS client behavior

  • Support for authentication configuration methods other than storing long-term secrets in the same file as other configuration items.

  • Possible to leverage the role connected to an AWS container or compute node, thus improving security.

  • More flexible configuration, since a wider range of parameters—such as timeouts, proxying, and use of a CA—is available then with the alternative mode.

To enable AWS native authentication,aws_authentication.mode must be set tonative in thecomponent_keyring_aws.cnf file, as shown here:

{  "cmk_id": "arn:aws:kms:us-east-1:79566666666:key/d0111111-1111-1111-1111-999999999abd",  "data_file": "/usr/local/mysql/keyring.json",  "cache_keys": true,  "aws_authentication":   {    "mode": "native"  }}

Configuration of the component for AWS native authentication is based on a chain of credentials providers. Each provider uses a different source for credentials; possible sources include files, environment variables, and external services. Credential providers are called in the order specified by the default providers chain described in the next few paragraphs.

Default credentials provider chain.  A credentials provider chain consists of one or more credential providers. Each such provider provides credentials taken from a different source. Providers are called until credentials are provided and collected for further use. The default chain consists of the credential providers listed here together with the credentials each of them provides:

To use AWS native authentication,aws_authentication.mode must be set tonative in thecomponent_keyring_aws.cnf file, as shown here:

{  "cmk_id": "arn:aws:kms:us-east-1:79566666666:key/d0111111-1111-1111-1111-999999999abd",  "data_file": "/usr/local/mysql/keyring.json",  "cache_keys": true,  "aws_authentication":   {    "mode": "native"  }}

The AWS configuration file (config) uses INI format similar to that employed in the MySQL Servermy.cnf file. You can specify a section of this file to be read by settingaws_authentication.profile. For example, settingaws_authentication.profile tomysql causes the component to read the[mysql] section ofconfig, as shown here:

{  "cmk_id": "arn:aws:kms:us-east-1:79566666666:key/d0111111-1111-1111-1111-999999999abd",  "data_file": "/usr/local/mysql/keyring.json",  "cache_keys": true,  "aws_authentication":   {    "mode": "native","profile": "mysql"    }}

Ifaws_authentication.profile is not specified, the component tries to read theconfig file section labelled[default].

The AWS keyring component also supports an AWScredentials file to act as a source of credentials for the providerProfileConfigFileAWSCredentialsProvider as described later in this section's discussion of native authentication mode. This file's location is determined in the same way as that of thecomponent_keyring_aws.cnf andconfig files. To override the default for thecredentials file (%USERPROFILE%\.aws\credentials for Windows,~/.aws/credentials for Linux or MacOS), set theAWS_SHARED_CREDENTIALS_FILE environment variable to the desired location.

Migration from AWS keyring plugin

To migrate from the AWS keyring plugin to the AWS keyring component, it is necessary to perform the following steps:

  1. Create an equivalent configuration for the component:

    1. Write a local or global manifest filemysqld.my (seeSection 8.4.5.2, “Keyring Component Installation”). The content of the file must match what is shown here:

      {  "components": "file://component_keyring_aws"}

    2. Write a component configuration filecomponent_keyring_aws.cnf as described inSection 8.4.5.4, “Using the component_keyring_file File-Based Keyring Component” (in the example forcomponent_keyring_file). See also the instructions given for configuration simple configuration section. In particular, the value of thecmk_id configuration item used by the component must be set to the that of thekeyring_aws_cmk_id used by the plugin; similarly, theaws_region item's value must be set to the value ofkeyring_aws_region. For example:

      {  "cmk_id": "arn:aws:kms:us-east-1:79566666666:key/d0111111-1111-1111-1111-999999999abd",  "data_file": "/usr/local/mysql/keyring.json",  "cache_keys": true,  "aws_authentication":   {     "mode":"simple",     "region": "us-east-1",     "access_key_id": "wwwwwwwwwwwwwEXAMPLE",     "access_key_secret": "xxxxxxxxxxxxx/yyyyyyy/zzzzzzzzEXAMPLEKEY"   }}

      Values of the access key ID and secret just shown must be copied from thekeyring_aws configuration file used by the AWS keyring plugin (seeSection 8.4.5.7, “Using the keyring_aws Amazon Web Services Keyring Plugin”).

  2. Perform key migration as described inSection 8.4.5.13, “Migrating Keys Between Keyring Keystores”.

  3. Uninstall the plugin.