<div id="docs-body">
 <div class="section">
  <div class="titlepage">
   <div>
    <div>
     <h4 class="title">
      <a name="keyring-okv-plugin">
      </a>
      8.4.4.6 Using the keyring_okv KMIP Plugin
     </h4>
    </div>
   </div>
  </div>
  <a class="indexterm" name="idm46045240680944">
  </a>
  <a class="indexterm" name="idm46045240679888">
  </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_okv
    </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 Key Management Interoperability Protocol (KMIP) enables
        communication of cryptographic keys between a key management
        server and its clients. The
   <code class="literal">
    keyring_okv
   </code>
   keyring plugin uses the KMIP 1.1 protocol to communicate
        securely as a client of a KMIP back end. Keyring material is
        generated exclusively by the back end, not by
   <code class="literal">
    keyring_okv
   </code>
   . The plugin works with these
        KMIP-compatible products:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      Oracle Key Vault
     </p>
    </li>
    <li class="listitem">
     <p>
      Gemalto SafeNet KeySecure Appliance
     </p>
    </li>
    <li class="listitem">
     <p>
      Townsend Alliance Key Manager
     </p>
    </li>
    <li class="listitem">
     <p>
      Entrust KeyControl
     </p>
    </li>
   </ul>
  </div>
  <p>
   Each MySQL Server instance must be registered separately as a
        client for KMIP. If two or more MySQL Server instances use the
        same set of credentials, they can interfere with each other’s
        functioning.
  </p>
  <p>
   The
   <code class="literal">
    keyring_okv
   </code>
   plugin supports the functions
        that comprise the standard MySQL Keyring service interface.
        Keyring operations performed by those 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="sa56991243"><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>
   For information about the characteristics of key values
        permitted by
   <code class="literal">
    keyring_okv
   </code>
   ,
   <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>
  <p>
   To install
   <code class="literal">
    keyring_okv
   </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
        configuration information specific to
   <code class="literal">
    keyring_okv
   </code>
   found here.
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      <a class="xref" href="keyring-okv-plugin.html#keyring-okv-configuration" title="General keyring_okv Configuration">
       General keyring_okv Configuration
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="keyring-okv-plugin.html#keyring-okv-oracle-key-vault" title="Configuring keyring_okv for Oracle Key Vault">
       Configuring keyring_okv for Oracle Key Vault
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="keyring-okv-plugin.html#keyring-okv-keysecure" title="Configuring keyring_okv for Gemalto SafeNet KeySecure Appliance">
       Configuring keyring_okv for Gemalto SafeNet KeySecure Appliance
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="keyring-okv-plugin.html#keyring-okv-alliance" title="Configuring keyring_okv for Townsend Alliance Key Manager">
       Configuring keyring_okv for Townsend Alliance Key Manager
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="keyring-okv-plugin.html#keyring-okv-entrust-keycontrol" title="Configuring keyring_okv for Entrust KeyControl">
       Configuring keyring_okv for Entrust KeyControl
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="keyring-okv-plugin.html#keyring-okv-encrypt-key-file" title="Password-Protecting the keyring_okv Key File">
       Password-Protecting the keyring_okv Key File
      </a>
     </p>
    </li>
   </ul>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="keyring-okv-configuration">
       </a>
       General keyring_okv Configuration
      </h5>
     </div>
    </div>
   </div>
   <a class="indexterm" name="idm46045240650816">
   </a>
   <p>
    Regardless of which KMIP back end the
    <code class="literal">
     keyring_okv
    </code>
    plugin uses for keyring
          storage, the
    <a class="link" href="keyring-system-variables.html#sysvar_keyring_okv_conf_dir">
     <code class="literal">
      keyring_okv_conf_dir
     </code>
    </a>
    system
          variable configures the location of the directory used by
    <code class="literal">
     keyring_okv
    </code>
    for its support files. The
          default value is empty, so you must set the variable to name a
          properly configured directory before the plugin can
          communicate with the KMIP back end. Unless you do so,
    <code class="literal">
     keyring_okv
    </code>
    writes a message to the error
          log during server startup that it cannot communicate:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-none"><div class="docs-select-all right" id="sa34762772"><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">[Warning] Plugin keyring_okv reported: 'For keyring_okv to be
initialized, please point the keyring_okv_conf_dir variable to a directory
containing Oracle Key Vault configuration file and ssl materials'</code></pre>
   </div>
   <p>
    The
    <a class="link" href="keyring-system-variables.html#sysvar_keyring_okv_conf_dir">
     <code class="literal">
      keyring_okv_conf_dir
     </code>
    </a>
    variable must name a directory that contains the following
          items:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       <code class="filename">
        okvclient.ora
       </code>
       : A file that contains
              details of the KMIP back end with which
       <code class="literal">
        keyring_okv
       </code>
       communicates.
      </p>
     </li>
     <li class="listitem">
      <p>
       <code class="filename">
        ssl
       </code>
       : A directory that contains the
              certificate and key files required to establish a secure
              connection with the KMIP back end:
       <code class="filename">
        CA.pem
       </code>
       ,
       <code class="filename">
        cert.pem
       </code>
       , and
       <code class="filename">
        key.pem
       </code>
       . If the key file is
              password-protected, the
       <code class="filename">
        ssl
       </code>
       directory
              can contain a single-line text file named
       <code class="filename">
        password.txt
       </code>
       containing the password
              needed to decrypt the key file.
      </p>
     </li>
    </ul>
   </div>
   <p>
    Both the
    <code class="filename">
     okvclient.ora
    </code>
    file and
    <code class="filename">
     ssl
    </code>
    directory with the certificate and
          key files are required for
    <code class="literal">
     keyring_okv
    </code>
    to
          work properly. The procedure used to populate the
          configuration directory with these files depends on the KMIP
          back end used with
    <code class="literal">
     keyring_okv
    </code>
    , as
          described elsewhere.
   </p>
   <p>
    The configuration directory used by
    <code class="literal">
     keyring_okv
    </code>
    as the location for its support
          files 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 the
    <code class="filename">
     /usr/local/mysql/mysql-keyring-okv
    </code>
    directory, the following commands (executed as
    <code class="literal">
     root
    </code>
    ) create the directory and set its mode
          and ownership:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-terminal"><div class="docs-select-all right" id="sa86268224"><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">cd /usr/local/mysql
mkdir mysql-keyring-okv
chmod 750 mysql-keyring-okv
chown mysql mysql-keyring-okv
chgrp mysql mysql-keyring-okv</code></pre>
   </div>
   <p>
    To be usable during the server startup process,
    <code class="literal">
     keyring_okv
    </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.
          Also, set the
    <a class="link" href="keyring-system-variables.html#sysvar_keyring_okv_conf_dir">
     <code class="literal">
      keyring_okv_conf_dir
     </code>
    </a>
    system
          variable to tell
    <code class="literal">
     keyring_okv
    </code>
    where to find
          its configuration directory. For example, use these lines in
          the server
    <code class="filename">
     my.cnf
    </code>
    file, adjusting the
    <code class="filename">
     .so
    </code>
    suffix and directory location for
          your platform as necessary:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-ini"><div class="docs-select-all right" id="sa78467540"><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>
<span class="token constant">keyring_okv_conf_dir</span><span class="token attr-value"><span class="token punctuation">=</span>/usr/local/mysql/mysql-keyring-okv</span></code></pre>
   </div>
   <p>
    For additional information about
    <a class="link" href="keyring-system-variables.html#sysvar_keyring_okv_conf_dir">
     <code class="literal">
      keyring_okv_conf_dir
     </code>
    </a>
    , 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>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="keyring-okv-oracle-key-vault">
       </a>
       Configuring keyring_okv for Oracle Key Vault
      </h5>
     </div>
    </div>
   </div>
   <a class="indexterm" name="idm46045240615760">
   </a>
   <a class="indexterm" name="idm46045240614304">
   </a>
   <p>
    The discussion here assumes that you are familiar with Oracle
          Key Vault. Some pertinent information sources:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       <a class="ulink" href="http://www.oracle.com/technetwork/database/options/key-management/overview/index.html" target="_blank">
        Oracle
              Key Vault site
       </a>
      </p>
     </li>
     <li class="listitem">
      <p>
       <a class="ulink" href="http://www.oracle.com/technetwork/database/options/key-management/documentation/index.html" target="_blank">
        Oracle
              Key Vault documentation
       </a>
      </p>
     </li>
    </ul>
   </div>
   <p>
    In Oracle Key Vault terminology, clients that use Oracle Key
          Vault to store and retrieve security objects are called
          endpoints. To communicate with Oracle Key Vault, it is
          necessary to register as an endpoint and enroll by downloading
          and installing endpoint support files. Note that you must
          register a separate endpoint for each MySQL Server instance.
          If two or more MySQL Server instances use the same endpoint,
          they can interfere with each other’s functioning.
   </p>
   <p>
    The following procedure briefly summarizes the process of
          setting up
    <code class="literal">
     keyring_okv
    </code>
    for use with Oracle
          Key Vault:
   </p>
   <div class="orderedlist">
    <ol class="orderedlist" type="1">
     <li class="listitem">
      <p>
       Create the configuration directory for the
       <code class="literal">
        keyring_okv
       </code>
       plugin to use.
      </p>
     </li>
     <li class="listitem">
      <p>
       Register an endpoint with Oracle Key Vault to obtain an
              enrollment token.
      </p>
     </li>
     <li class="listitem">
      <p>
       Use the enrollment token to obtain the
       <code class="filename">
        okvclient.jar
       </code>
       client software
              download.
      </p>
     </li>
     <li class="listitem">
      <p>
       Install the client software to populate the
       <code class="literal">
        keyring_okv
       </code>
       configuration directory
              that contains the Oracle Key Vault support files.
      </p>
     </li>
    </ol>
   </div>
   <p>
    Use the following procedure to configure
    <code class="literal">
     keyring_okv
    </code>
    and Oracle Key Vault to work
          together. This description only summarizes how to interact
          with Oracle Key Vault. For details, visit the
    <a class="ulink" href="http://www.oracle.com/technetwork/database/options/key-management/overview/index.html" target="_blank">
     Oracle
          Key Vault
    </a>
    site and consult the
    <em class="citetitle">
     Oracle Key
          Vault Administrator's Guide
    </em>
    .
   </p>
   <div class="orderedlist">
    <ol class="orderedlist" type="1">
     <li class="listitem">
      <p>
       Create the configuration directory that contains the
              Oracle Key Vault support files, and make sure that the
       <a class="link" href="keyring-system-variables.html#sysvar_keyring_okv_conf_dir">
        <code class="literal">
         keyring_okv_conf_dir
        </code>
       </a>
       system variable is set to name that directory (for
              details, see
       <a class="xref" href="keyring-okv-plugin.html#keyring-okv-configuration" title="General keyring_okv Configuration">
        General keyring_okv Configuration
       </a>
       ).
      </p>
     </li>
     <li class="listitem">
      <p>
       Log in to the Oracle Key Vault management console as a
              user who has the System Administrator role.
      </p>
     </li>
     <li class="listitem">
      <p>
       Select the Endpoints tab to arrive at the Endpoints page.
              On the Endpoints page, click Add.
      </p>
     </li>
     <li class="listitem">
      <p>
       Provide the required endpoint information and click
              Register. The endpoint type should be Other. Successful
              registration results in an enrollment token.
      </p>
     </li>
     <li class="listitem">
      <p>
       Log out from the Oracle Key Vault server.
      </p>
     </li>
     <li class="listitem">
      <p>
       Connect again to the Oracle Key Vault server, this time
              without logging in. Use the endpoint enrollment token to
              enroll and request the
       <code class="filename">
        okvclient.jar
       </code>
       software download. Save this file to your system.
      </p>
     </li>
     <li class="listitem">
      <p>
       Install the
       <code class="filename">
        okvclient.jar
       </code>
       file using
              the following command (you must have JDK 1.4 or higher):
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting one-line language-terminal"><div class="docs-select-all right" id="sa99523913"><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">java <span class="token property">-jar</span> okvclient<span class="token punctuation">.</span>jar <span class="token property">-d</span> <em class="replaceable">dir_name</em> <span class="token punctuation">[</span><span class="token property">-v</span><span class="token punctuation">]</span></code></pre>
      </div>
      <p>
       The directory name following the
       <code class="option">
        -d
       </code>
       option is the location in which to install extracted
              files. The
       <code class="option">
        -v
       </code>
       option, if given, causes
              log information to be produced that may be useful if the
              command fails.
      </p>
      <p>
       When the command asks for an Oracle Key Vault endpoint
              password, do not provide one. Instead, press
       <span class="keycap">
        <strong>
         Enter
        </strong>
       </span>
       . (The result is that no password is
              required when the endpoint connects to Oracle Key Vault.)
      </p>
      <p>
       The preceding command produces an
       <code class="filename">
        okvclient.ora
       </code>
       file, which should be
              in this location under the directory named by the
       <code class="option">
        -d
       </code>
       option in the preceding
       <span class="command">
        <strong>
         java
              -jar
        </strong>
       </span>
       command:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting one-line language-terminal"><div class="docs-select-all right" id="sa59182986"><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">install_dir/conf/okvclient<span class="token punctuation">.</span>ora</code></pre>
      </div>
      <p>
       The expected file contents include lines that look like
              this:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-ini"><div class="docs-select-all right" id="sa95466085"><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 constant">SERVER</span><span class="token attr-value"><span class="token punctuation">=</span><em class="replaceable">host_ip</em>:<em class="replaceable">port_num</em></span>
<span class="token constant">STANDBY_SERVER</span><span class="token attr-value"><span class="token punctuation">=</span><em class="replaceable">host_ip</em>:<em class="replaceable">port_num</em></span></code></pre>
      </div>
      <p>
       The
       <code class="literal">
        SERVER
       </code>
       variable is mandatory, and
              the
       <code class="literal">
        STANDBY_SERVER
       </code>
       variable is
              optional. The
       <code class="literal">
        keyring_okv
       </code>
       plugin
              attempts to communicate with the server running on the
              host named by the
       <code class="literal">
        SERVER
       </code>
       variable and
              falls back to
       <code class="literal">
        STANDBY_SERVER
       </code>
       if that
              fails.
      </p>
      <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
       <div class="admon-title">
        Note
       </div>
       <p>
        If the existing file is not in this format, then create
                a new file with the lines shown in the previous example.
                Also, consider backing up the
        <code class="filename">
         okvclient.ora
        </code>
        file before you run
                the
        <span class="command">
         <strong>
          okvutil
         </strong>
        </span>
        command. Restore the file
                as needed.
       </p>
      </div>
      <p>
       You can specify more than one standby server (up to a
              maximum of 64). If you do, the
       <code class="literal">
        keyring_okv
       </code>
       plugin iterates over them
              until it can establish a connection, and fails if it
              cannot. To add extra standby servers, edit the
       <code class="filename">
        okvclient.ora
       </code>
       file to specify the IP
              addresses and port numbers of the servers as a
              comma-separated list in the value of the
       <code class="literal">
        STANDBY_SERVER
       </code>
       variable. For example:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting one-line language-ini"><div class="docs-select-all right" id="sa14977566"><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 constant">STANDBY_SERVER</span><span class="token attr-value"><span class="token punctuation">=</span><em class="replaceable">host_ip</em>:<em class="replaceable">port_num</em>,<em class="replaceable">host_ip</em>:<em class="replaceable">port_num</em>,<em class="replaceable">host_ip</em>:<em class="replaceable">port_num</em>,<em class="replaceable">host_ip</em>:<em class="replaceable">port_num</em></span></code></pre>
      </div>
      <p>
       Ensure that the list of standby servers is kept short,
              accurate, and up to date, and servers that are no longer
              valid are removed. There is a 20-second wait for each
              connection attempt, so the presence of a long list of
              invalid servers can significantly affect the
       <code class="literal">
        keyring_okv
       </code>
       plugin’s connection time
              and therefore the server startup time.
      </p>
     </li>
     <li class="listitem">
      <p>
       Go to the Oracle Key Vault installer directory and test
              the setup by running this command:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting one-line language-terminal"><div class="docs-select-all right" id="sa50196700"><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">okvutil/bin/okvutil list</code></pre>
      </div>
      <p>
       The output should look something like this:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-none"><div class="docs-select-all right" id="sa71201063"><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">Unique ID                               Type            Identifier
255AB8DE-C97F-482C-E053-0100007F28B9	Symmetric Key	-
264BF6E0-A20E-7C42-E053-0100007FB29C	Symmetric Key	-</code></pre>
      </div>
      <p>
       For a fresh Oracle Key Vault server (a server without any
              key in it), the output looks like this instead, to
              indicate that there are no keys in the vault:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting one-line language-none"><div class="docs-select-all right" id="sa37934248"><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">no objects found</code></pre>
      </div>
     </li>
     <li class="listitem">
      <p>
       Use this command to extract the
       <code class="filename">
        ssl
       </code>
       directory containing SSL materials from the
       <code class="filename">
        okvclient.jar
       </code>
       file:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting one-line language-terminal"><div class="docs-select-all right" id="sa25035246"><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">jar xf okvclient<span class="token punctuation">.</span>jar ssl</code></pre>
      </div>
     </li>
     <li class="listitem">
      <p>
       Copy the Oracle Key Vault support files (the
       <code class="filename">
        okvclient.ora
       </code>
       file and the
       <code class="filename">
        ssl
       </code>
       directory) into the configuration
              directory.
      </p>
     </li>
     <li class="listitem">
      <p>
       (Optional) If you wish to password-protect the key file,
              use the instructions in
       <a class="xref" href="keyring-okv-plugin.html#keyring-okv-encrypt-key-file" title="Password-Protecting the keyring_okv Key File">
        Password-Protecting the keyring_okv Key File
       </a>
       .
      </p>
     </li>
    </ol>
   </div>
   <p>
    After completing the preceding procedure, restart the MySQL
          server. It loads the
    <code class="literal">
     keyring_okv
    </code>
    plugin and
    <code class="literal">
     keyring_okv
    </code>
    uses the files in its
          configuration directory to communicate with Oracle Key Vault.
   </p>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="keyring-okv-keysecure">
       </a>
       Configuring keyring_okv for Gemalto SafeNet KeySecure Appliance
      </h5>
     </div>
    </div>
   </div>
   <a class="indexterm" name="idm46045240543696">
   </a>
   <a class="indexterm" name="idm46045240542256">
   </a>
   <a class="indexterm" name="idm46045240540736">
   </a>
   <p>
    Gemalto SafeNet KeySecure Appliance uses the KMIP protocol
          (version 1.1 or 1.2). The
    <code class="literal">
     keyring_okv
    </code>
    keyring plugin (which supports KMIP 1.1) can use KeySecure as
          its KMIP back end for keyring storage.
   </p>
   <p>
    Use the following procedure to configure
    <code class="literal">
     keyring_okv
    </code>
    and KeySecure to work together.
          The description only summarizes how to interact with
          KeySecure. For details, consult the section named Add a KMIP
          Server in the
    <a class="ulink" href="https://www2.gemalto.com/aws-marketplace/usage/vks/uploadedFiles/Support_and_Downloads/AWS/007-012362-001-keysecure-appliance-user-guide-v7.1.0.pdf" target="_blank">
     KeySecure
          User Guide
    </a>
    .
   </p>
   <div class="orderedlist">
    <ol class="orderedlist" type="1">
     <li class="listitem">
      <p>
       Create the configuration directory that contains the
              KeySecure support files, and make sure that the
       <a class="link" href="keyring-system-variables.html#sysvar_keyring_okv_conf_dir">
        <code class="literal">
         keyring_okv_conf_dir
        </code>
       </a>
       system variable is set to name that directory (for
              details, see
       <a class="xref" href="keyring-okv-plugin.html#keyring-okv-configuration" title="General keyring_okv Configuration">
        General keyring_okv Configuration
       </a>
       ).
      </p>
     </li>
     <li class="listitem">
      <p>
       In the configuration directory, create a subdirectory
              named
       <code class="filename">
        ssl
       </code>
       to use for storing the
              required SSL certificate and key files.
      </p>
     </li>
     <li class="listitem">
      <p>
       In the configuration directory, create a file named
       <code class="filename">
        okvclient.ora
       </code>
       . It should have
              following format:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-ini"><div class="docs-select-all right" id="sa11400941"><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 constant">SERVER</span><span class="token attr-value"><span class="token punctuation">=</span><em class="replaceable">host_ip</em>:<em class="replaceable">port_num</em></span>
<span class="token constant">STANDBY_SERVER</span><span class="token attr-value"><span class="token punctuation">=</span><em class="replaceable">host_ip</em>:<em class="replaceable">port_num</em></span></code></pre>
      </div>
      <p>
       For example, if KeySecure is running on host 198.51.100.20
              and listening on port 9002, and also running on
              alternative host 203.0.113.125 and listening on port 8041,
              the
       <code class="filename">
        okvclient.ora
       </code>
       file looks like
              this:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-ini"><div class="docs-select-all right" id="sa23216038"><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 constant">SERVER</span><span class="token attr-value"><span class="token punctuation">=</span>198.51.100.20:9002</span>
<span class="token constant">STANDBY_SERVER</span><span class="token attr-value"><span class="token punctuation">=</span>203.0.113.125:8041</span></code></pre>
      </div>
      <p>
       You can specify more than one standby server (up to a
              maximum of 64). If you do, the
       <code class="literal">
        keyring_okv
       </code>
       plugin iterates over them
              until it can establish a connection, and fails if it
              cannot. To add extra standby servers, edit the
       <code class="filename">
        okvclient.ora
       </code>
       file to specify the IP
              addresses and port numbers of the servers as a
              comma-separated list in the value of the
       <code class="literal">
        STANDBY_SERVER
       </code>
       variable. For example:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting one-line language-ini"><div class="docs-select-all right" id="sa25666803"><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 constant">STANDBY_SERVER</span><span class="token attr-value"><span class="token punctuation">=</span><em class="replaceable">host_ip</em>:<em class="replaceable">port_num</em>,<em class="replaceable">host_ip</em>:<em class="replaceable">port_num</em>,<em class="replaceable">host_ip</em>:<em class="replaceable">port_num</em>,<em class="replaceable">host_ip</em>:<em class="replaceable">port_num</em></span></code></pre>
      </div>
      <p>
       Ensure that the list of standby servers is kept short,
              accurate, and up to date, and servers that are no longer
              valid are removed. There is a 20-second wait for each
              connection attempt, so the presence of a long list of
              invalid servers can significantly affect the
       <code class="literal">
        keyring_okv
       </code>
       plugin’s connection time
              and therefore the server startup time.
      </p>
     </li>
     <li class="listitem">
      <p>
       Connect to the KeySecure Management Console as an
              administrator with credentials for Certificate Authorities
              access.
      </p>
     </li>
     <li class="listitem">
      <p>
       Navigate to Security &gt;&gt; Local CAs and create a local
              certificate authority (CA).
      </p>
     </li>
     <li class="listitem">
      <p>
       Go to Trusted CA Lists. Select Default and click on
              Properties. Then select Edit for Trusted Certificate
              Authority List and add the CA just created.
      </p>
     </li>
     <li class="listitem">
      <p>
       Download the CA and save it in the
       <code class="filename">
        ssl
       </code>
       directory as a file named
       <code class="filename">
        CA.pem
       </code>
       .
      </p>
     </li>
     <li class="listitem">
      <p>
       Navigate to Security &gt;&gt; Certificate Requests and
              create a certificate. Then you can download a compressed
       <span class="command">
        <strong>
         tar
        </strong>
       </span>
       file containing certificate PEM
              files.
      </p>
     </li>
     <li class="listitem">
      <p>
       Extract the PEM files from in the downloaded file. For
              example, if the file name is
       <code class="filename">
        csr_w_pk_pkcs8.gz
       </code>
       , decompress and
              unpack it using this command:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting one-line language-terminal"><div class="docs-select-all right" id="sa77976260"><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">tar zxvf csr_w_pk_pkcs8<span class="token punctuation">.</span>gz</code></pre>
      </div>
      <p>
       Two files result from the extraction operation:
       <code class="filename">
        certificate_request.pem
       </code>
       and
       <code class="filename">
        private_key_pkcs8.pem
       </code>
       .
      </p>
     </li>
     <li class="listitem">
      <p>
       Use this
       <span class="command">
        <strong>
         openssl
        </strong>
       </span>
       command to decrypt the
              private key and create a file named
       <code class="filename">
        key.pem
       </code>
       :
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting one-line language-terminal"><div class="docs-select-all right" id="sa1010699"><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">openssl pkcs8 <span class="token property">-in</span> private_key_pkcs8<span class="token punctuation">.</span>pem <span class="token property">-out</span> key<span class="token punctuation">.</span>pem</code></pre>
      </div>
     </li>
     <li class="listitem">
      <p>
       Copy the
       <code class="filename">
        key.pem
       </code>
       file into the
       <code class="filename">
        ssl
       </code>
       directory.
      </p>
     </li>
     <li class="listitem">
      <p>
       Copy the certificate request in
       <code class="filename">
        certificate_request.pem
       </code>
       into the
              clipboard.
      </p>
     </li>
     <li class="listitem">
      <p>
       Navigate to Security &gt;&gt; Local CAs. Select the same
              CA that you created earlier (the one you downloaded to
              create the
       <code class="filename">
        CA.pem
       </code>
       file), and click
              Sign Request. Paste the Certificate Request from the
              clipboard, choose a certificate purpose of Client (the
              keyring is a client of KeySecure), and click Sign Request.
              The result is a certificate signed with the selected CA in
              a new page.
      </p>
     </li>
     <li class="listitem">
      <p>
       Copy the signed certificate to the clipboard, then save
              the clipboard contents as a file named
       <code class="filename">
        cert.pem
       </code>
       in the
       <code class="filename">
        ssl
       </code>
       directory.
      </p>
     </li>
     <li class="listitem">
      <p>
       (Optional) If you wish to password-protect the key file,
              use the instructions in
       <a class="xref" href="keyring-okv-plugin.html#keyring-okv-encrypt-key-file" title="Password-Protecting the keyring_okv Key File">
        Password-Protecting the keyring_okv Key File
       </a>
       .
      </p>
     </li>
    </ol>
   </div>
   <p>
    After completing the preceding procedure, restart the MySQL
          server. It loads the
    <code class="literal">
     keyring_okv
    </code>
    plugin and
    <code class="literal">
     keyring_okv
    </code>
    uses the files in its
          configuration directory to communicate with KeySecure.
   </p>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="keyring-okv-alliance">
       </a>
       Configuring keyring_okv for Townsend Alliance Key Manager
      </h5>
     </div>
    </div>
   </div>
   <a class="indexterm" name="idm46045240485984">
   </a>
   <a class="indexterm" name="idm46045240484544">
   </a>
   <a class="indexterm" name="idm46045240483024">
   </a>
   <p>
    Townsend Alliance Key Manager uses the KMIP protocol. The
    <code class="literal">
     keyring_okv
    </code>
    keyring plugin can use Alliance
          Key Manager as its KMIP back end for keyring storage. For
          additional information, see
    <a class="ulink" href="https://www.townsendsecurity.com/product/encryption-key-management-mysql" target="_blank">
     Alliance
          Key Manager for MySQL
    </a>
    .
   </p>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="keyring-okv-entrust-keycontrol">
       </a>
       Configuring keyring_okv for Entrust KeyControl
      </h5>
     </div>
    </div>
   </div>
   <a class="indexterm" name="idm46045240478096">
   </a>
   <a class="indexterm" name="idm46045240476640">
   </a>
   <a class="indexterm" name="idm46045240475136">
   </a>
   <p>
    Entrust KeyControl uses the KMIP protocol. The
    <code class="literal">
     keyring_okv
    </code>
    keyring plugin can use Entrust
          KeyControl as its KMIP back end for keyring storage. For
          additional information, see the
    <a class="ulink" href="https://www.entrust.com/-/media/documentation/integration-guides/oracle-mysql-enterprise-keycontrol-nshield-ig.pdf" target="_blank">
     Oracle
          MySQL and Entrust KeyControl with nShield HSM Integration
          Guide
    </a>
    .
   </p>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="keyring-okv-encrypt-key-file">
       </a>
       Password-Protecting the keyring_okv Key File
      </h5>
     </div>
    </div>
   </div>
   <p>
    You can optionally protect the key file with a password and
          supply a file containing the password to enable the key file
          to be decrypted. To so do, change location to the
    <code class="filename">
     ssl
    </code>
    directory and perform these steps:
   </p>
   <div class="orderedlist">
    <ol class="orderedlist" type="1">
     <li class="listitem">
      <p>
       Encrypt the
       <code class="filename">
        key.pem
       </code>
       key file. For
              example, use a command like this, and enter the encryption
              password at the prompts:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-terminal"><div class="docs-select-all right" id="sa37987443"><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">openssl</span> rsa <span class="token property">-des3</span> <span class="token property">-in</span> key<span class="token punctuation">.</span>pem <span class="token property">-out</span> key<span class="token punctuation">.</span>pem<span class="token punctuation">.</span>new
Enter PEM pass phrase<span class="token punctuation">:</span>
Verifying - Enter PEM pass phrase<span class="token punctuation">:</span></code></pre>
      </div>
     </li>
     <li class="listitem">
      <p>
       Save the encryption password in a single-line text file
              named
       <code class="filename">
        password.txt
       </code>
       in the
       <code class="filename">
        ssl
       </code>
       directory.
      </p>
     </li>
     <li class="listitem">
      <p>
       Verify that the encrypted key file can be decrypted using
              the following command. The decrypted file should display
              on the console:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting one-line language-terminal"><div class="docs-select-all right" id="sa22192364"><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">openssl</span> rsa <span class="token property">-in</span> key<span class="token punctuation">.</span>pem<span class="token punctuation">.</span>new <span class="token property">-passin</span> file<span class="token punctuation">:</span>password<span class="token punctuation">.</span>txt</code></pre>
      </div>
     </li>
     <li class="listitem">
      <p>
       Remove the original
       <code class="filename">
        key.pem
       </code>
       file and
              rename
       <code class="filename">
        key.pem.new
       </code>
       to
       <code class="filename">
        key.pem
       </code>
       .
      </p>
     </li>
     <li class="listitem">
      <p>
       Change the ownership and access mode of new
       <code class="filename">
        key.pem
       </code>
       file and
       <code class="filename">
        password.txt
       </code>
       file as necessary to
              ensure that they have the same restrictions as other files
              in the
       <code class="filename">
        ssl
       </code>
       directory.
      </p>
     </li>
    </ol>
   </div>
  </div>
 </div>
 <br/>
</div>
