When it initializes, component_keyring_aws reads a component configuration file component_keyring_aws.cnf, as described in Section 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.

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

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

aws_authentication.region defaults to us-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 and aws_authentication.access_key_secret have no effect when the aws_authentication.mode is native.

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.

Given the preceding configuration file items, to configure component_keyring_aws, create a component configuration file named component_keyring_aws.cnf in the directory indicated previously.

A read/write keyring data file using JSON format, whose location is determined by the data_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":"0102010078865A35D86559D92C3124146819057E927382E061F6EA7613DF2B9B
E72FB0E62C01A1CF92B96934CB08D42D231CF6828A420000006E306C06092A864886F70D010706A0
5F305D020100305806092A864886F70D010701301E060960864801650304012E3011040C19F809F2
7900EACEF99DE2B4020110802BEDA406610AF033504B601C5EC937EFB9F38BB631F68856FF7FA81E
637FCC400BA35900929E99E628E1B3E7",
        "extension":[]
      },
      {
        "user":"mary@%",
        "data_id":"key1",
        "data_type":"AES",
        "data":"0102010078865A35D86559D92C3124146819057E927382E061F6EA7613DF2B9B
E72FB0E62C017CAA36B2F756892C3AFCAA074A13E655000001043082010006092A864886F70D0107
06A081F23081EF0201003081E906092A864 886F70D010701301E060960864801650304012E30110
40CCDECB095F68DE68BC331A0730201108081BB52EF64775CCE3DD47ADD8C274A297EB1A6E988085
C0036D0AAE64DE50BB7D5AC020A12BF70",
        "extension":[]
      },
      {
        "user":"john@%",
        "data_id":"key2",
        "data_type":"AES",
        "data":"0102010078865A35D86559D92C3124146819057E927382E061F6EA7613DF2B9B
E72FB0E62C01BB9CC22B82E3DB50C76FD855DE0CB305000001043082010006092A864886F70D0107
06A081F23081EF0201003081E906092A864886F70D010701301E060960864801650304012E301104
0C778A6EDBA93A1FF27D82F5340201108081BB809B9599C191BF0DF1F7721DB2915F7A02A5928981
BF9264D9B76BE41046C3B5AF60006F4A",
        "extension":[]
        }
    ]
}

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.

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; see Migration from AWS keyring plugin.) The config and credentials files are not used in this case; the configuration is read from the global component_keyring_aws.cnf only. To enable simple authentication mode, set aws_authentication.mode to simple in this file.

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

The contents of a sample component_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"
  }
}

When aws_authentication.mode is native, the AWS keyring component uses the standard AWS authentication configuration mechanism (see AWS 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 (see AWS SDKs and Tools: Standardized credential providers).

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

To enable AWS native authentication, aws_authentication.mode must be set to native in the component_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 to native in the component_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 Server my.cnf file. You can specify a section of this file to be read by setting aws_authentication.profile. For example, setting aws_authentication.profile to mysql causes the component to read the [mysql] section of config, 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"  
  }
}

If aws_authentication.profile is not specified, the component tries to read the config file section labelled [default].

The AWS keyring component also supports an AWS credentials file to act as a source of credentials for the provider ProfileConfigFileAWSCredentialsProvider 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 the component_keyring_aws.cnf and config files. To override the default for the credentials file (%USERPROFILE%\.aws\credentials for Windows, ~/.aws/credentials for Linux or MacOS), set the AWS_SHARED_CREDENTIALS_FILE environment variable to the desired location.

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