<div id="docs-body">
 <div class="section">
  <div class="titlepage">
   <div>
    <div>
     <h4 class="title">
      <a name="keyring-aws-plugin">
      </a>
      8.4.4.7 Using the keyring_aws Amazon Web Services Keyring Plugin
     </h4>
    </div>
   </div>
  </div>
  <a class="indexterm" name="idm46045240452000">
  </a>
  <a class="indexterm" name="idm46045240450944">
  </a>
  <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
   <div class="admon-title">
    Note
   </div>
   <p>
    The
    <code class="literal">
     keyring_aws
    </code>
    plugin is an extension
          included in MySQL Enterprise Edition, a commercial product. To learn more about
          commercial products, see
    <a class="ulink" href="https://www.mysql.com/products/" target="_blank">
     https://www.mysql.com/products/
    </a>
    .
   </p>
  </div>
  <p>
   The
   <code class="literal">
    keyring_aws
   </code>
   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
   <code class="literal">
    keyring_aws
   </code>
   .
  </p>
  <p>
   MySQL Enterprise Edition can work with
   <code class="literal">
    keyring_aws
   </code>
   on Red Hat
        Enterprise Linux, SUSE Linux Enterprise Server, Debian, Ubuntu,
        macOS, and Windows. MySQL Enterprise Edition does not support the use of
   <code class="literal">
    keyring_aws
   </code>
   on these platforms:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      EL6
     </p>
    </li>
    <li class="listitem">
     <p>
      Generic Linux (glibc2.12)
     </p>
    </li>
    <li class="listitem">
     <p>
      SLES 12 (with versions after MySQL Server 5.7)
     </p>
    </li>
    <li class="listitem">
     <p>
      Solaris
     </p>
    </li>
   </ul>
  </div>
  <p>
   The discussion here assumes that you are familiar with AWS in
        general and KMS in particular. Some pertinent information
        sources:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      <a class="ulink" href="https://aws.amazon.com/kms/" target="_blank">
       AWS site
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="ulink" href="https://docs.aws.amazon.com/kms/" target="_blank">
       KMS
            documentation
      </a>
     </p>
    </li>
   </ul>
  </div>
  <p>
   The following sections provide configuration and usage
        information for the
   <code class="literal">
    keyring_aws
   </code>
   keyring
        plugin:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      <a class="xref" href="keyring-aws-plugin.html#keyring-aws-plugin-configuration" title="keyring_aws Configuration">
       keyring_aws Configuration
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="keyring-aws-plugin.html#keyring-aws-plugin-operation" title="keyring_aws Operation">
       keyring_aws Operation
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="keyring-aws-plugin.html#keyring-aws-plugin-credential-changes" title="keyring_aws Credential Changes">
       keyring_aws Credential Changes
      </a>
     </p>
    </li>
   </ul>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="keyring-aws-plugin-configuration">
       </a>
       keyring_aws Configuration
      </h5>
     </div>
    </div>
   </div>
   <p>
    To install
    <code class="literal">
     keyring_aws
    </code>
    , use the general
          instructions found in
    <a class="xref" href="keyring-plugin-installation.html" title="8.4.4.3 Keyring Plugin Installation">
     Section 8.4.4.3, “Keyring Plugin Installation”
    </a>
    , together with
          the plugin-specific configuration information found here.
   </p>
   <p>
    The plugin library file contains the
    <code class="literal">
     keyring_aws
    </code>
    plugin and two loadable
          functions,
    <a class="link" href="keyring-functions-plugin-specific.html#function_keyring-aws-rotate-cmk">
     <code class="literal">
      keyring_aws_rotate_cmk()
     </code>
    </a>
    and
    <a class="link" href="keyring-functions-plugin-specific.html#function_keyring-aws-rotate-keys">
     <code class="literal">
      keyring_aws_rotate_keys()
     </code>
    </a>
    .
   </p>
   <p>
    To configure
    <code class="literal">
     keyring_aws
    </code>
    , you must obtain a
          secret access key that provides credentials for communicating
          with AWS KMS and write it to a configuration file:
   </p>
   <div class="orderedlist">
    <ol class="orderedlist" type="1">
     <li class="listitem">
      <p>
       Create an AWS KMS account.
      </p>
     </li>
     <li class="listitem">
      <p>
       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.
      </p>
     </li>
     <li class="listitem">
      <p>
       Use the AWS KMS account to create a KMS key ID. At MySQL
              startup, set the
       <a class="link" href="keyring-system-variables.html#sysvar_keyring_aws_cmk_id">
        <code class="literal">
         keyring_aws_cmk_id
        </code>
       </a>
       system
              variable to the CMK ID value. This variable is mandatory
              and there is no default. (Its value can be changed at
              runtime if desired using
       <a class="link" href="set-variable.html" title="15.7.6.1 SET Syntax for Variable Assignment">
        <code class="literal">
         SET
              GLOBAL
        </code>
       </a>
       .)
      </p>
     </li>
     <li class="listitem">
      <p>
       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. For example, on Unix
              and Unix-like systems, to use
       <code class="filename">
        /usr/local/mysql/mysql-keyring/keyring_aws_conf
       </code>
       as the file name, the following commands (executed as
       <code class="literal">
        root
       </code>
       ) create its parent directory and
              set the directory mode and ownership:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-terminal"><div class="docs-select-all right" id="sa19766366"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal"><span class="token prompt">$&gt; </span><span class="token command">cd</span> /usr/local/mysql
<span class="token prompt">$&gt; </span><span class="token command">mkdir</span> mysql-keyring
<span class="token prompt">$&gt; </span><span class="token command">chmod</span> 750 mysql-keyring
<span class="token prompt">$&gt; </span><span class="token command">chown</span> mysql mysql-keyring
<span class="token prompt">$&gt; </span><span class="token command">chgrp</span> mysql mysql-keyring</code></pre>
      </div>
      <p>
       At MySQL startup, set the
       <a class="link" href="keyring-system-variables.html#sysvar_keyring_aws_conf_file">
        <code class="literal">
         keyring_aws_conf_file
        </code>
       </a>
       system variable to
       <code class="filename">
        /usr/local/mysql/mysql-keyring/keyring_aws_conf
       </code>
       to indicate the configuration file location to the server.
      </p>
     </li>
     <li class="listitem">
      <p>
       Prepare the
       <code class="literal">
        keyring_aws
       </code>
       configuration
              file, which should contain two lines:
      </p>
      <div class="itemizedlist">
       <ul class="itemizedlist" style="list-style-type: disc; ">
        <li class="listitem">
         <p>
          Line 1: The secret access key ID
         </p>
        </li>
        <li class="listitem">
         <p>
          Line 2: The secret access key
         </p>
        </li>
       </ul>
      </div>
      <p>
       For example, if the key ID is
       <code class="literal">
        wwwwwwwwwwwwwEXAMPLE
       </code>
       and the key is
       <code class="literal">
        xxxxxxxxxxxxx/yyyyyyy/zzzzzzzzEXAMPLEKEY
       </code>
       ,
              the configuration file looks like this:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-none"><div class="docs-select-all right" id="sa62622299"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-none">wwwwwwwwwwwwwEXAMPLE
xxxxxxxxxxxxx/yyyyyyy/zzzzzzzzEXAMPLEKEY</code></pre>
      </div>
     </li>
    </ol>
   </div>
   <p>
    To be usable during the server startup process,
    <code class="literal">
     keyring_aws
    </code>
    must be loaded using the
    <a class="link" href="server-options.html#option_mysqld_early-plugin-load">
     <code class="option">
      --early-plugin-load
     </code>
    </a>
    option. The
    <a class="link" href="keyring-system-variables.html#sysvar_keyring_aws_cmk_id">
     <code class="literal">
      keyring_aws_cmk_id
     </code>
    </a>
    system
          variable is mandatory and configures the KMS key ID obtained
          from the AWS KMS server. The
    <a class="link" href="keyring-system-variables.html#sysvar_keyring_aws_conf_file">
     <code class="literal">
      keyring_aws_conf_file
     </code>
    </a>
    and
    <a class="link" href="keyring-system-variables.html#sysvar_keyring_aws_data_file">
     <code class="literal">
      keyring_aws_data_file
     </code>
    </a>
    system
          variables optionally configure the locations of the files used
          by the
    <code class="literal">
     keyring_aws
    </code>
    plugin for configuration
          information and data storage. 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
    <code class="filename">
     my.cnf
    </code>
    file, adjusting the
    <code class="filename">
     .so
    </code>
    suffix and file locations for your
          platform as necessary:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-ini"><div class="docs-select-all right" id="sa27168296"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-ini"><span class="token selector">[mysqld]</span>
<span class="token constant">early-plugin-load</span><span class="token attr-value"><span class="token punctuation">=</span>keyring_aws.so</span>
<span class="token constant">keyring_aws_cmk_id</span><span class="token attr-value"><span class="token punctuation">=</span>'arn:aws:kms:us-west-2:111122223333:key/abcd1234-ef56-ab12-cd34-ef56abcd1234'</span>
<span class="token constant">keyring_aws_conf_file</span><span class="token attr-value"><span class="token punctuation">=</span>/usr/local/mysql/mysql-keyring/keyring_aws_conf</span>
<span class="token constant">keyring_aws_data_file</span><span class="token attr-value"><span class="token punctuation">=</span>/usr/local/mysql/mysql-keyring/keyring_aws_data</span></code></pre>
   </div>
   <p>
    For the
    <code class="literal">
     keyring_aws
    </code>
    plugin to start
          successfully, the configuration file must exist and contain
          valid secret access key information, initialized as described
          previously. The storage file need not exist. If it does not,
    <code class="literal">
     keyring_aws
    </code>
    attempts to create it (as well
          as its parent directory, if necessary).
   </p>
   <p>
    For additional information about the system variables used to
          configure the
    <code class="literal">
     keyring_aws
    </code>
    plugin, see
    <a class="xref" href="keyring-system-variables.html" title="8.4.4.16 Keyring System Variables">
     Section 8.4.4.16, “Keyring System Variables”
    </a>
    .
   </p>
   <p>
    Start the MySQL server and install the functions associated
          with the
    <code class="literal">
     keyring_aws
    </code>
    plugin. This is a
          one-time operation, performed by executing the following
          statements, adjusting the
    <code class="filename">
     .so
    </code>
    suffix for
          your platform as necessary:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa9424985"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token keyword">CREATE</span> <span class="token keyword">FUNCTION</span> keyring_aws_rotate_cmk <span class="token keyword">RETURNS</span> <span class="token datatype">INTEGER</span>
  <span class="token keyword">SONAME</span> <span class="token string">'keyring_aws.so'</span><span class="token punctuation">;</span>
<span class="token keyword">CREATE</span> <span class="token keyword">FUNCTION</span> keyring_aws_rotate_keys <span class="token keyword">RETURNS</span> <span class="token datatype">INTEGER</span>
  <span class="token keyword">SONAME</span> <span class="token string">'keyring_aws.so'</span><span class="token punctuation">;</span></code></pre>
   </div>
   <p>
    For additional information about the
    <code class="literal">
     keyring_aws
    </code>
    functions, see
    <a class="xref" href="keyring-functions-plugin-specific.html" title="8.4.4.13 Plugin-Specific Keyring Key-Management Functions">
     Section 8.4.4.13, “Plugin-Specific Keyring Key-Management Functions”
    </a>
    .
   </p>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="keyring-aws-plugin-operation">
       </a>
       keyring_aws Operation
      </h5>
     </div>
    </div>
   </div>
   <p>
    At plugin startup, the
    <code class="literal">
     keyring_aws
    </code>
    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.
   </p>
   <p>
    During operation,
    <code class="literal">
     keyring_aws
    </code>
    maintains
          encrypted keys in the in-memory cache and uses the storage
          file as local persistent storage. Each keyring operation is
          transactional:
    <code class="literal">
     keyring_aws
    </code>
    either
          successfully changes both the in-memory key cache and the
          keyring storage file, or the operation fails and the keyring
          state remains unchanged.
   </p>
   <p>
    To ensure that keys are flushed only when the correct keyring
          storage file exists,
    <code class="literal">
     keyring_aws
    </code>
    stores a
          SHA-256 checksum of the keyring in the file. Before updating
          the file, the plugin verifies that it contains the expected
          checksum.
   </p>
   <p>
    The
    <code class="literal">
     keyring_aws
    </code>
    plugin supports the
          functions that comprise the standard MySQL Keyring service
          interface. Keyring operations performed by these functions are
          accessible at two levels:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       SQL interface: In SQL statements, call the functions
              described in
       <a class="xref" href="keyring-functions-general-purpose.html" title="8.4.4.12 General-Purpose Keyring Key-Management Functions">
        Section 8.4.4.12, “General-Purpose Keyring Key-Management Functions”
       </a>
       .
      </p>
     </li>
     <li class="listitem">
      <p>
       C interface: In C-language code, call the keyring service
              functions described in
       <a class="xref" href="keyring-service.html" title="7.6.9.2 The Keyring Service">
        Section 7.6.9.2, “The Keyring Service”
       </a>
       .
      </p>
     </li>
    </ul>
   </div>
   <p>
    Example (using the SQL interface):
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa48028531"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token keyword">SELECT</span> keyring_key_generate<span class="token punctuation">(</span><span class="token string">'MyKey'</span><span class="token punctuation">,</span> <span class="token string">'AES'</span><span class="token punctuation">,</span> <span class="token number">32</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token keyword">SELECT</span> keyring_key_remove<span class="token punctuation">(</span><span class="token string">'MyKey'</span><span class="token punctuation">)</span><span class="token punctuation">;</span></code></pre>
   </div>
   <p>
    In addition, the
    <a class="link" href="keyring-functions-plugin-specific.html#function_keyring-aws-rotate-cmk">
     <code class="literal">
      keyring_aws_rotate_cmk()
     </code>
    </a>
    and
    <a class="link" href="keyring-functions-plugin-specific.html#function_keyring-aws-rotate-keys">
     <code class="literal">
      keyring_aws_rotate_keys()
     </code>
    </a>
    functions
    <span class="quote">
     “
     <span class="quote">
      extend
     </span>
     ”
    </span>
    the keyring plugin interface
          to provide AWS-related capabilities not covered by the
          standard keyring service interface. These capabilities are
          accessible only by calling these functions using SQL. There
          are no corresponding C-language key service functions.
   </p>
   <p>
    For information about the characteristics of key values
          permitted by
    <code class="literal">
     keyring_aws
    </code>
    , see
    <a class="xref" href="keyring-key-types.html" title="8.4.4.10 Supported Keyring Key Types and Lengths">
     Section 8.4.4.10, “Supported Keyring Key Types and Lengths”
    </a>
    .
   </p>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="keyring-aws-plugin-credential-changes">
       </a>
       keyring_aws Credential Changes
      </h5>
     </div>
    </div>
   </div>
   <p>
    Assuming that the
    <code class="literal">
     keyring_aws
    </code>
    plugin has
          initialized properly at server startup, it is possible to
          change the credentials used for communicating with AWS KMS:
   </p>
   <div class="orderedlist">
    <ol class="orderedlist" type="1">
     <li class="listitem">
      <p>
       Use AWS KMS to create a new secret access key ID and
              secret access key.
      </p>
     </li>
     <li class="listitem">
      <p>
       Store the new credentials in the configuration file (the
              file named by the
       <a class="link" href="keyring-system-variables.html#sysvar_keyring_aws_conf_file">
        <code class="literal">
         keyring_aws_conf_file
        </code>
       </a>
       system variable). The file format is as described
              previously.
      </p>
     </li>
     <li class="listitem">
      <p>
       Reinitialize the
       <code class="literal">
        keyring_aws
       </code>
       plugin so
              that it re-reads the configuration file. Assuming that the
              new credentials are valid, the plugin should initialize
              successfully.
      </p>
      <p>
       There are two ways to reinitialize the plugin:
      </p>
      <div class="itemizedlist">
       <ul class="itemizedlist" style="list-style-type: disc; ">
        <li class="listitem">
         <p>
          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.
         </p>
        </li>
        <li class="listitem">
         <p>
          Reinitialize the plugin without restarting the server
                  by executing the following statements, adjusting the
          <code class="filename">
           .so
          </code>
          suffix for your platform as
                  necessary:
         </p>
         <div class="copytoclipboard-wrapper">
          <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa94751389"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token keyword">UNINSTALL</span> <span class="token keyword">PLUGIN</span> keyring_aws<span class="token punctuation">;</span>
<span class="token keyword">INSTALL</span> <span class="token keyword">PLUGIN</span> keyring_aws <span class="token keyword">SONAME</span> <span class="token string">'keyring_aws.so'</span><span class="token punctuation">;</span></code></pre>
         </div>
         <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
          <div class="admon-title">
           Note
          </div>
          <p>
           In addition to loading a plugin at runtime,
           <a class="link" href="install-plugin.html" title="15.7.4.4 INSTALL PLUGIN Statement">
            <code class="literal">
             INSTALL PLUGIN
            </code>
           </a>
           has
                    the side effect of registering the plugin it in the
           <code class="literal">
            mysql.plugin
           </code>
           system table.
                    Because of this, if you decide to stop using
           <code class="literal">
            keyring_aws
           </code>
           , it is not sufficient
                    to remove the
           <a class="link" href="server-options.html#option_mysqld_early-plugin-load">
            <code class="option">
             --early-plugin-load
            </code>
           </a>
           option from the set of options used to start the
                    server. 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
           <code class="literal">
            mysql.plugin
           </code>
           .
          </p>
          <p>
           Consequently, if you execute the
           <a class="link" href="uninstall-plugin.html" title="15.7.4.6 UNINSTALL PLUGIN Statement">
            <code class="literal">
             UNINSTALL PLUGIN
            </code>
           </a>
           plus
           <a class="link" href="install-plugin.html" title="15.7.4.4 INSTALL PLUGIN Statement">
            <code class="literal">
             INSTALL PLUGIN
            </code>
           </a>
           sequence just described to change the AWS KMS
                    credentials, then to stop using
           <code class="literal">
            keyring_aws
           </code>
           , it is necessary to
                    execute
           <a class="link" href="uninstall-plugin.html" title="15.7.4.6 UNINSTALL PLUGIN Statement">
            <code class="literal">
             UNINSTALL
                    PLUGIN
            </code>
           </a>
           again to unregister the plugin in
                    addition to removing the
           <a class="link" href="server-options.html#option_mysqld_early-plugin-load">
            <code class="option">
             --early-plugin-load
            </code>
           </a>
           option.
          </p>
         </div>
        </li>
       </ul>
      </div>
     </li>
    </ol>
   </div>
  </div>
 </div>
 <br/>
</div>
