<div id="docs-body">
 <div class="section">
  <div class="titlepage">
   <div>
    <div>
     <h4 class="title">
      <a name="keyring-file-component">
      </a>
      8.4.4.4 Using the component_keyring_file File-Based Keyring Component
     </h4>
    </div>
   </div>
  </div>
  <a class="indexterm" name="idm46045240814768">
  </a>
  <a class="indexterm" name="idm46045240813696">
  </a>
  <p>
   The
   <code class="literal">
    component_keyring_file
   </code>
   keyring component
        stores keyring data in a file local to the server host.
  </p>
  <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
   <div class="admon-title">
    Warning
   </div>
   <p>
    For encryption key management, the
    <code class="literal">
     component_keyring_file
    </code>
    and
    <code class="literal">
     component_keyring_encrypted_file
    </code>
    components
          are not intended as a regulatory compliance solution. Security
          standards such as PCI, FIPS, and others require use of key
          management systems to secure, manage, and protect encryption
          keys in key vaults or hardware security modules (HSMs).
   </p>
  </div>
  <p>
   To use
   <code class="literal">
    component_keyring_file
   </code>
   for keystore
        management, you must:
  </p>
  <div class="orderedlist">
   <ol class="orderedlist" type="1">
    <li class="listitem">
     <p>
      Write a manifest that tells the server to load
      <code class="literal">
       component_keyring_file
      </code>
      , as described in
      <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>
      Write a configuration file for
      <code class="literal">
       component_keyring_file
      </code>
      , as described
            here.
     </p>
    </li>
   </ol>
  </div>
  <p>
   When it initializes,
   <code class="literal">
    component_keyring_file
   </code>
   reads either a global configuration file, or a global
        configuration file paired with a local configuration file:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      The component attempts to read its global configuration file
            from the directory where the component library file is
            installed (that is, the server plugin directory).
     </p>
    </li>
    <li class="listitem">
     <p>
      If the global configuration file indicates use of a local
            configuration file, the component attempts to read its local
            configuration file from the data directory.
     </p>
    </li>
    <li class="listitem">
     <p>
      Although global and local configuration files are located in
            different directories, the file name is
      <code class="filename">
       component_keyring_file.cnf
      </code>
      in both
            locations.
     </p>
    </li>
    <li class="listitem">
     <p>
      It is an error for no configuration file to exist.
      <code class="literal">
       component_keyring_file
      </code>
      cannot initialize
            without a valid configuration.
     </p>
    </li>
   </ul>
  </div>
  <p>
   Local configuration files permit setting up multiple server
        instances to use
   <code class="literal">
    component_keyring_file
   </code>
   , such
        that component configuration for each server instance is
        specific to a given data directory instance. This enables the
        same keyring component to be used with a distinct data file for
        each instance.
  </p>
  <p>
   <code class="literal">
    component_keyring_file
   </code>
   configuration files
        have these properties:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      A configuration file must be in valid JSON format.
     </p>
    </li>
    <li class="listitem">
     <p>
      A configuration file permits these configuration items:
     </p>
     <div class="itemizedlist">
      <ul class="itemizedlist" style="list-style-type: circle; ">
       <li class="listitem">
        <p>
         <code class="literal">
          "read_local_config"
         </code>
         : This item is
                permitted only in the global configuration file. If the
                item is not present, the component uses only the global
                configuration file. If the item is present, its value is
         <code class="literal">
          true
         </code>
         or
         <code class="literal">
          false
         </code>
         ,
                indicating whether the component should read
                configuration information from the local configuration
                file.
        </p>
        <p>
         If the
         <code class="literal">
          "read_local_config"
         </code>
         item is
                present in the global configuration file along with
                other items, the component checks the
         <code class="literal">
          "read_local_config"
         </code>
         item value first:
        </p>
        <div class="itemizedlist">
         <ul class="itemizedlist" style="list-style-type: square; ">
          <li class="listitem">
           <p>
            If the value is
            <code class="literal">
             false
            </code>
            , the
                    component processes the other items in the global
                    configuration file and ignores the local
                    configuration file.
           </p>
          </li>
          <li class="listitem">
           <p>
            If the value is
            <code class="literal">
             true
            </code>
            , the
                    component ignores the other items in the global
                    configuration file and attempts to read the local
                    configuration file.
           </p>
          </li>
         </ul>
        </div>
       </li>
       <li class="listitem">
        <p>
         <code class="literal">
          "path"
         </code>
         : The item value is a string
                that names the file to use for storing keyring data. The
                file should be named using an absolute path, not a
                relative path. This item is mandatory in the
                configuration. If not specified,
         <code class="literal">
          component_keyring_file
         </code>
         initialization
                fails.
        </p>
       </li>
       <li class="listitem">
        <p>
         <code class="literal">
          "read_only"
         </code>
         : The item value indicates
                whether the keyring data file is read only. The item
                value is
         <code class="literal">
          true
         </code>
         (read only) or
         <code class="literal">
          false
         </code>
         (read/write). This item is
                mandatory in the configuration. If not specified,
         <code class="literal">
          component_keyring_file
         </code>
         initialization
                fails.
        </p>
       </li>
      </ul>
     </div>
    </li>
    <li class="listitem">
     <p>
      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 and the administrator must
            correct any issues indicated by diagnostics in the server
            error log.
     </p>
    </li>
   </ul>
  </div>
  <p>
   Given the preceding configuration file properties, to configure
   <code class="literal">
    component_keyring_file
   </code>
   , create a global
        configuration file named
   <code class="filename">
    component_keyring_file.cnf
   </code>
   in the directory
        where the
   <code class="literal">
    component_keyring_file
   </code>
   library file
        is installed, and optionally create a local configuration file,
        also named
   <code class="filename">
    component_keyring_file.cnf
   </code>
   , in
        the data directory. The following instructions assume that a
        keyring data file named
   <code class="filename">
    /usr/local/mysql/keyring/component_keyring_file
   </code>
   is to be used in read/write fashion.
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      To use a global configuration file only, the file contents
            look like this:
     </p>
     <div class="copytoclipboard-wrapper">
      <pre class="programlisting language-json"><div class="docs-select-all right" id="sa14510718"><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-json"><span class="token punctuation">{</span>
  <span class="token property">"path"</span><span class="token operator">:</span> <span class="token string">"/usr/local/mysql/keyring/component_keyring_file"</span><span class="token punctuation">,</span>
  <span class="token property">"read_only"</span><span class="token operator">:</span> <span class="token boolean">false</span>
<span class="token punctuation">}</span></code></pre>
     </div>
     <p>
      Create this file in the directory where the
      <code class="literal">
       component_keyring_file
      </code>
      library file is
            installed.
     </p>
     <p>
      This path must not point to or include the MySQL data
            directory.
     </p>
    </li>
    <li class="listitem">
     <p>
      Alternatively, to use a global and local configuration file
            pair, the global file looks like this:
     </p>
     <div class="copytoclipboard-wrapper">
      <pre class="programlisting language-json"><div class="docs-select-all right" id="sa42250483"><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-json"><span class="token punctuation">{</span>
  <span class="token property">"read_local_config"</span><span class="token operator">:</span> <span class="token boolean">true</span>
<span class="token punctuation">}</span></code></pre>
     </div>
     <p>
      Create this file in the directory where the
      <code class="literal">
       component_keyring_file
      </code>
      library file is
            installed.
     </p>
     <p>
      The local file looks like this:
     </p>
     <div class="copytoclipboard-wrapper">
      <pre class="programlisting language-json"><div class="docs-select-all right" id="sa57115530"><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-json"><span class="token punctuation">{</span>
  <span class="token property">"path"</span><span class="token operator">:</span> <span class="token string">"/usr/local/mysql/keyring/component_keyring_file"</span><span class="token punctuation">,</span>
  <span class="token property">"read_only"</span><span class="token operator">:</span> <span class="token boolean">false</span>
<span class="token punctuation">}</span></code></pre>
     </div>
     <p>
      This path must not point to or include the MySQL data
            directory.
     </p>
    </li>
   </ul>
  </div>
  <p>
   Keyring operations are transactional:
   <code class="literal">
    component_keyring_file
   </code>
   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 a suffix of
   <code class="filename">
    .backup
   </code>
   .
  </p>
  <p>
   <code class="literal">
    component_keyring_file
   </code>
   supports the functions
        that comprise the standard MySQL Keyring service interface.
        Keyring operations performed by those functions are accessible
        in SQL statements as 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>
  <p>
   Example:
  </p>
  <div class="copytoclipboard-wrapper">
   <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa88386371"><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">
    component_keyring_file
   </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>
 <br/>
</div>
