<div id="docs-body">
 <div class="section">
  <div class="titlepage">
   <div>
    <div>
     <h4 class="title">
      <a name="keyring-plugin-installation">
      </a>
      8.4.4.3 Keyring Plugin Installation
     </h4>
    </div>
   </div>
  </div>
  <a class="indexterm" name="idm46045240888256">
  </a>
  <a class="indexterm" name="idm46045240886768">
  </a>
  <a class="indexterm" name="idm46045240885280">
  </a>
  <a class="indexterm" name="idm46045240883792">
  </a>
  <a class="indexterm" name="idm46045240882304">
  </a>
  <a class="indexterm" name="idm46045240880800">
  </a>
  <p>
   Keyring service consumers require that a keyring component or
        plugin be installed:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      To use a keyring plugin, begin with the instructions here.
            (Also, for general information about installing plugins, see
      <a class="xref" href="plugin-loading.html" title="7.6.1 Installing and Uninstalling Plugins">
       Section 7.6.1, “Installing and Uninstalling Plugins”
      </a>
      .)
     </p>
    </li>
    <li class="listitem">
     <p>
      To use a keyring component instead, begin with
      <a class="xref" href="keyring-component-installation.html" title="8.4.4.2 Keyring Component Installation">
       Section 8.4.4.2, “Keyring Component Installation”
      </a>
      .
     </p>
    </li>
    <li class="listitem">
     <p>
      If you intend to use keyring functions in conjunction with
            the chosen keyring component or plugin, install the
            functions after installing that component or plugin, using
            the instructions 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>
   </ul>
  </div>
  <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
   <div class="admon-title">
    Note
   </div>
   <p>
    Only one keyring component or plugin should be enabled at a
          time. Enabling multiple keyring components or plugins is
          unsupported and results may not be as anticipated.
   </p>
   <p>
    A keyring component must be enabled on the MySQL Server
          instance if you need to support secure storage for persisted
          system variable values, rather than a keyring plugin, which do
          not support the function. See
    <a class="xref" href="persisted-system-variables.html#persisted-system-variables-sensitive" title="Persisting Sensitive System Variables">
     Persisting Sensitive System Variables
    </a>
    .
   </p>
  </div>
  <p>
   MySQL provides these keyring plugin choices:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      <code class="literal">
       keyring_okv
      </code>
      : A KMIP 1.1 plugin for use
            with KMIP-compatible back end keyring storage products such
            as Oracle Key Vault and Gemalto SafeNet KeySecure Appliance.
            Available in MySQL Enterprise Edition distributions.
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       keyring_aws
      </code>
      : Communicates with the Amazon
            Web Services Key Management Service as a back end for key
            generation and uses a local file for key storage. Available
            in MySQL Enterprise Edition distributions.
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       keyring_hashicorp
      </code>
      : Communicates with
            HashiCorp Vault for back end storage. Available in MySQL Enterprise Edition
            distributions.
     </p>
    </li>
   </ul>
  </div>
  <p>
   To be usable by the server, the plugin library file must be
        located in the MySQL plugin directory (the directory named by
        the
   <a class="link" href="server-system-variables.html#sysvar_plugin_dir">
    <code class="literal">
     plugin_dir
    </code>
   </a>
   system
        variable). If necessary, configure the plugin directory location
        by setting the value of
   <a class="link" href="server-system-variables.html#sysvar_plugin_dir">
    <code class="literal">
     plugin_dir
    </code>
   </a>
   at server startup.
  </p>
  <p>
   A keyring component or plugin must be loaded early during the
        server startup sequence so that other components can access it
        as necessary during their own initialization. For example, the
   <code class="literal">
    InnoDB
   </code>
   storage engine uses the keyring for
        tablespace encryption, so a keyring component or plugin must be
        loaded and available prior to
   <code class="literal">
    InnoDB
   </code>
   initialization.
  </p>
  <p>
   Installation for each keyring plugin is similar. The following
        instructions describe how to install
   <code class="literal">
    keyring_okv
   </code>
   . To use a different keyring
        plugin, substitute its name for
   <code class="literal">
    keyring_okv
   </code>
   .
  </p>
  <p>
   The
   <code class="literal">
    keyring_okv
   </code>
   plugin library file base name
        is
   <code class="literal">
    keyring_okv
   </code>
   . The file name suffix differs
        per platform (for example,
   <code class="filename">
    .so
   </code>
   for Unix and
        Unix-like systems,
   <code class="filename">
    .dll
   </code>
   for Windows).
  </p>
  <p>
   To load the plugin, use the
   <a class="link" href="server-options.html#option_mysqld_early-plugin-load">
    <code class="option">
     --early-plugin-load
    </code>
   </a>
   option to
        name the plugin library file that contains it. For example, on
        platforms where the plugin library file suffix is
   <code class="filename">
    .so
   </code>
   , use these lines in the server
   <code class="filename">
    my.cnf
   </code>
   file, adjusting the
   <code class="filename">
    .so
   </code>
   suffix for your platform as necessary:
  </p>
  <div class="copytoclipboard-wrapper">
   <pre class="programlisting language-ini"><div class="docs-select-all right" id="sa56215350"><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_okv.so</span></code></pre>
  </div>
  <p>
   Before starting the server, check the notes for your chosen
        keyring plugin for configuration instructions specific to that
        plugin:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      <code class="literal">
       keyring_okv
      </code>
      :
      <a class="xref" href="keyring-okv-plugin.html" title="8.4.4.6 Using the keyring_okv KMIP Plugin">
       Section 8.4.4.6, “Using the keyring_okv KMIP Plugin”
      </a>
      .
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       keyring_aws
      </code>
      :
      <a class="xref" href="keyring-aws-plugin.html" title="8.4.4.7 Using the keyring_aws Amazon Web Services Keyring Plugin">
       Section 8.4.4.7, “Using the keyring_aws Amazon Web Services Keyring Plugin”
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       keyring_hashicorp
      </code>
      :
      <a class="xref" href="keyring-hashicorp-plugin.html" title="8.4.4.8 Using the HashiCorp Vault Keyring Plugin">
       Section 8.4.4.8, “Using the HashiCorp Vault Keyring Plugin”
      </a>
     </p>
    </li>
   </ul>
  </div>
  <p>
   After performing any plugin-specific configuration, start the
        server. Verify plugin installation by examining the Information
        Schema
   <a class="link" href="information-schema-plugins-table.html" title="28.3.22 The INFORMATION_SCHEMA PLUGINS Table">
    <code class="literal">
     PLUGINS
    </code>
   </a>
   table or use the
   <a class="link" href="show-plugins.html" title="15.7.7.27 SHOW PLUGINS Statement">
    <code class="literal">
     SHOW PLUGINS
    </code>
   </a>
   statement (see
   <a class="xref" href="obtaining-plugin-information.html" title="7.6.2 Obtaining Server Plugin Information">
    Section 7.6.2, “Obtaining Server Plugin Information”
   </a>
   ). For example:
  </p>
  <div class="copytoclipboard-wrapper">
   <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa36101961"><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 prompt">mysql&gt;</span> <span class="token keyword">SELECT</span> PLUGIN_NAME<span class="token punctuation">,</span> PLUGIN_STATUS
       <span class="token keyword">FROM</span> INFORMATION_SCHEMA<span class="token punctuation">.</span><span class="token keyword">PLUGINS</span>
       <span class="token keyword">WHERE</span> PLUGIN_NAME <span class="token operator">LIKE</span> <span class="token string">'keyring%'</span><span class="token punctuation">;</span>
<span class="token output"><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span></span>
<span class="token output"><span class="token punctuation">|</span> PLUGIN_NAME  <span class="token punctuation">|</span> PLUGIN_STATUS <span class="token punctuation">|</span></span>
<span class="token output"><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span></span>
<span class="token output"><span class="token punctuation">|</span> keyring_okv  <span class="token punctuation">|</span> ACTIVE        <span class="token punctuation">|</span></span>
<span class="token output"><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span></span></code></pre>
  </div>
  <p>
   If the plugin fails to initialize, check the server error log
        for diagnostic messages.
  </p>
  <p>
   Plugins can be loaded by methods other than
   <a class="link" href="server-options.html#option_mysqld_early-plugin-load">
    <code class="option">
     --early-plugin-load
    </code>
   </a>
   , such as the
   <a class="link" href="server-options.html#option_mysqld_plugin-load">
    <code class="option">
     --plugin-load
    </code>
   </a>
   or
   <a class="link" href="server-options.html#option_mysqld_plugin-load-add">
    <code class="option">
     --plugin-load-add
    </code>
   </a>
   option or the
   <a class="link" href="install-plugin.html" title="15.7.4.4 INSTALL PLUGIN Statement">
    <code class="literal">
     INSTALL PLUGIN
    </code>
   </a>
   statement.
        However, keyring plugins loaded using those methods may be
        available too late in the server startup sequence for certain
        components that use the keyring, such as
   <code class="literal">
    InnoDB
   </code>
   :
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      Plugin loading using
      <a class="link" href="server-options.html#option_mysqld_plugin-load">
       <code class="option">
        --plugin-load
       </code>
      </a>
      or
      <a class="link" href="server-options.html#option_mysqld_plugin-load-add">
       <code class="option">
        --plugin-load-add
       </code>
      </a>
      occurs
            after
      <code class="literal">
       InnoDB
      </code>
      initialization.
     </p>
    </li>
    <li class="listitem">
     <p>
      Plugins installed using
      <a class="link" href="install-plugin.html" title="15.7.4.4 INSTALL PLUGIN Statement">
       <code class="literal">
        INSTALL
            PLUGIN
       </code>
      </a>
      are registered in the
      <code class="literal">
       mysql.plugin
      </code>
      system table and loaded
            automatically for subsequent server restarts. However,
            because
      <code class="literal">
       mysql.plugin
      </code>
      is an
      <code class="literal">
       InnoDB
      </code>
      table, any plugins named in it can
            be loaded during startup only after
      <code class="literal">
       InnoDB
      </code>
      initialization.
     </p>
    </li>
   </ul>
  </div>
  <p>
   If no keyring component or plugin is available when a component
        tries to access the keyring service, the service cannot be used
        by that component. As a result, the component may fail to
        initialize or may initialize with limited functionality. For
        example, if
   <code class="literal">
    InnoDB
   </code>
   finds that there are
        encrypted tablespaces when it initializes, it attempts to access
        the keyring. If the keyring is unavailable,
   <code class="literal">
    InnoDB
   </code>
   can access only unencrypted
        tablespaces. To ensure that
   <code class="literal">
    InnoDB
   </code>
   can access
        encrypted tablespaces as well, use
   <a class="link" href="server-options.html#option_mysqld_early-plugin-load">
    <code class="option">
     --early-plugin-load
    </code>
   </a>
   to load the
        keyring plugin.
  </p>
 </div>
 <br/>
</div>
