<div id="docs-body">
 <div class="section">
  <div class="titlepage">
   <div>
    <div>
     <h4 class="title">
      <a name="keyring-service">
      </a>
      7.6.9.2 The Keyring Service
     </h4>
    </div>
   </div>
  </div>
  <a class="indexterm" name="idm46045254330512">
  </a>
  <a class="indexterm" name="idm46045254329024">
  </a>
  <p>
   MySQL Server supports a keyring service that enables internal
        components and plugins to securely store sensitive information
        for later retrieval. MySQL distributions provide a keyring
        interface that is accessible at two levels:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      At the SQL level, as a set of loadable functions that each
            map onto calls to the service routines.
     </p>
    </li>
    <li class="listitem">
     <p>
      As a C language interface, callable as a plugin service from
            server plugins or loadable functions.
     </p>
    </li>
   </ul>
  </div>
  <p>
   This section describes how to use the keyring service functions
        to store, retrieve, and remove keys in the MySQL keyring
        keystore. For information about the SQL interface that uses
        functions,
   <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>
   .
        For general keyring information, see
   <a class="xref" href="keyring.html" title="8.4.4 The MySQL Keyring">
    Section 8.4.4, “The MySQL Keyring”
   </a>
   .
  </p>
  <p>
   The keyring service uses whatever underlying keyring plugin is
        enabled, if any. If no keyring plugin is enabled, keyring
        service calls fail.
  </p>
  <p>
   A
   <span class="quote">
    “
    <span class="quote">
     record
    </span>
    ”
   </span>
   in the keystore consists of data (the
        key itself) and a unique identifier through which the key is
        accessed. The identifier has two parts:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      <code class="literal">
       key_id
      </code>
      : The key ID or name.
      <code class="literal">
       key_id
      </code>
      values that begin with
      <code class="literal">
       mysql_
      </code>
      are reserved by MySQL Server.
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       user_id
      </code>
      : The session effective user ID.
            If there is no user context, this value can be
      <code class="literal">
       NULL
      </code>
      . The value need not actually be a
      <span class="quote">
       “
       <span class="quote">
        user
       </span>
       ”
      </span>
      ; the meaning depends on the application.
     </p>
     <p>
      Functions that implement the keyring function interface pass
            the value of
      <a class="link" href="information-functions.html#function_current-user">
       <code class="literal">
        CURRENT_USER()
       </code>
      </a>
      as the
      <code class="literal">
       user_id
      </code>
      value to keyring service
            functions.
     </p>
    </li>
   </ul>
  </div>
  <p>
   The keyring service functions have these characteristics in
        common:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      Each function returns 0 for success, 1 for failure.
     </p>
    </li>
    <li class="listitem">
     <p>
      The
      <code class="literal">
       key_id
      </code>
      and
      <code class="literal">
       user_id
      </code>
      arguments form a unique combination indicating which key in
            the keyring to use.
     </p>
    </li>
    <li class="listitem">
     <p>
      The
      <code class="literal">
       key_type
      </code>
      argument provides additional
            information about the key, such as its encryption method or
            intended use.
     </p>
    </li>
    <li class="listitem">
     <p>
      Keyring service functions treat key IDs, user names, types,
            and values as binary strings, so comparisons are
            case-sensitive. For example, IDs of
      <code class="literal">
       MyKey
      </code>
      and
      <code class="literal">
       mykey
      </code>
      refer to different keys.
     </p>
    </li>
   </ul>
  </div>
  <p>
   These keyring service functions are available:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      <code class="literal">
       my_key_fetch()
      </code>
     </p>
     <a class="indexterm" name="idm46045254302400">
     </a>
     <a class="indexterm" name="idm46045254301312">
     </a>
     <p>
      Deobfuscates and retrieves a key from the keyring, along
            with its type. The function allocates the memory for the
            buffers used to store the returned key and key type. The
            caller should zero or obfuscate the memory when it is no
            longer needed, then free it.
     </p>
     <p>
      Syntax:
     </p>
     <div class="copytoclipboard-wrapper">
      <pre class="programlisting language-c"><div class="docs-select-all right" id="sa41835447"><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-c">bool <span class="token function">my_key_fetch</span><span class="token punctuation">(</span><span class="token keyword">const</span> <span class="token keyword">char</span> <span class="token operator">*</span>key_id<span class="token punctuation">,</span> <span class="token keyword">const</span> <span class="token keyword">char</span> <span class="token operator">*</span><span class="token operator">*</span>key_type<span class="token punctuation">,</span>
                  <span class="token keyword">const</span> <span class="token keyword">char</span><span class="token operator">*</span> user_id<span class="token punctuation">,</span> <span class="token keyword">void</span> <span class="token operator">*</span><span class="token operator">*</span>key<span class="token punctuation">,</span> size_t <span class="token operator">*</span>key_len<span class="token punctuation">)</span></code></pre>
     </div>
     <p>
      Arguments:
     </p>
     <div class="itemizedlist">
      <ul class="itemizedlist" style="list-style-type: circle; ">
       <li class="listitem">
        <p>
         <code class="literal">
          key_id
         </code>
         ,
         <code class="literal">
          user_id
         </code>
         :
                Null-terminated strings that as a pair form a unique
                identifier indicating which key to fetch.
        </p>
       </li>
       <li class="listitem">
        <p>
         <code class="literal">
          key_type
         </code>
         : The address of a buffer
                pointer. The function stores into it a pointer to a
                null-terminated string that provides additional
                information about the key (stored when the key was
                added).
        </p>
       </li>
       <li class="listitem">
        <p>
         <code class="literal">
          key
         </code>
         : The address of a buffer pointer.
                The function stores into it a pointer to the buffer
                containing the fetched key data.
        </p>
       </li>
       <li class="listitem">
        <p>
         <code class="literal">
          key_len
         </code>
         : The address of a variable
                into which the function stores the size in bytes of the
         <code class="literal">
          *key
         </code>
         buffer.
        </p>
       </li>
      </ul>
     </div>
     <p>
      Return value:
     </p>
     <p>
      Returns 0 for success, 1 for failure.
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       my_key_generate()
      </code>
     </p>
     <a class="indexterm" name="idm46045254286496">
     </a>
     <a class="indexterm" name="idm46045254285392">
     </a>
     <p>
      Generates a new random key of a given type and length and
            stores it in the keyring. The key has a length of
      <code class="literal">
       key_len
      </code>
      and is associated with the
            identifier formed from
      <code class="literal">
       key_id
      </code>
      and
      <code class="literal">
       user_id
      </code>
      . The type and length values must
            be consistent with the values supported by the underlying
            keyring plugin. 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>
     <p>
      Syntax:
     </p>
     <div class="copytoclipboard-wrapper">
      <pre class="programlisting language-c"><div class="docs-select-all right" id="sa94271826"><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-c">bool <span class="token function">my_key_generate</span><span class="token punctuation">(</span><span class="token keyword">const</span> <span class="token keyword">char</span> <span class="token operator">*</span>key_id<span class="token punctuation">,</span> <span class="token keyword">const</span> <span class="token keyword">char</span> <span class="token operator">*</span>key_type<span class="token punctuation">,</span>
                     <span class="token keyword">const</span> <span class="token keyword">char</span> <span class="token operator">*</span>user_id<span class="token punctuation">,</span> size_t key_len<span class="token punctuation">)</span></code></pre>
     </div>
     <p>
      Arguments:
     </p>
     <div class="itemizedlist">
      <ul class="itemizedlist" style="list-style-type: circle; ">
       <li class="listitem">
        <p>
         <code class="literal">
          key_id
         </code>
         ,
         <code class="literal">
          user_id
         </code>
         :
                Null-terminated strings that as a pair form a unique
                identifier for the key to be generated.
        </p>
       </li>
       <li class="listitem">
        <p>
         <code class="literal">
          key_type
         </code>
         : A null-terminated string
                that provides additional information about the key.
        </p>
       </li>
       <li class="listitem">
        <p>
         <code class="literal">
          key_len
         </code>
         : The size in bytes of the key
                to be generated.
        </p>
       </li>
      </ul>
     </div>
     <p>
      Return value:
     </p>
     <p>
      Returns 0 for success, 1 for failure.
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       my_key_remove()
      </code>
     </p>
     <a class="indexterm" name="idm46045254270128">
     </a>
     <a class="indexterm" name="idm46045254269024">
     </a>
     <p>
      Removes a key from the keyring.
     </p>
     <p>
      Syntax:
     </p>
     <div class="copytoclipboard-wrapper">
      <pre class="programlisting one-line language-c"><div class="docs-select-all right" id="sa85380486"><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-c">bool <span class="token function">my_key_remove</span><span class="token punctuation">(</span><span class="token keyword">const</span> <span class="token keyword">char</span> <span class="token operator">*</span>key_id<span class="token punctuation">,</span> <span class="token keyword">const</span> <span class="token keyword">char</span><span class="token operator">*</span> user_id<span class="token punctuation">)</span></code></pre>
     </div>
     <p>
      Arguments:
     </p>
     <div class="itemizedlist">
      <ul class="itemizedlist" style="list-style-type: circle; ">
       <li class="listitem">
        <p>
         <code class="literal">
          key_id
         </code>
         ,
         <code class="literal">
          user_id
         </code>
         :
                Null-terminated strings that as a pair form a unique
                identifier for the key to be removed.
        </p>
       </li>
      </ul>
     </div>
     <p>
      Return value:
     </p>
     <p>
      Returns 0 for success, 1 for failure.
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="literal">
       my_key_store()
      </code>
     </p>
     <a class="indexterm" name="idm46045254260192">
     </a>
     <a class="indexterm" name="idm46045254259104">
     </a>
     <p>
      Obfuscates and stores a key in the keyring.
     </p>
     <p>
      Syntax:
     </p>
     <div class="copytoclipboard-wrapper">
      <pre class="programlisting language-c"><div class="docs-select-all right" id="sa16892601"><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-c">bool <span class="token function">my_key_store</span><span class="token punctuation">(</span><span class="token keyword">const</span> <span class="token keyword">char</span> <span class="token operator">*</span>key_id<span class="token punctuation">,</span> <span class="token keyword">const</span> <span class="token keyword">char</span> <span class="token operator">*</span>key_type<span class="token punctuation">,</span>
                  <span class="token keyword">const</span> <span class="token keyword">char</span><span class="token operator">*</span> user_id<span class="token punctuation">,</span> <span class="token keyword">void</span> <span class="token operator">*</span>key<span class="token punctuation">,</span> size_t key_len<span class="token punctuation">)</span></code></pre>
     </div>
     <p>
      Arguments:
     </p>
     <div class="itemizedlist">
      <ul class="itemizedlist" style="list-style-type: circle; ">
       <li class="listitem">
        <p>
         <code class="literal">
          key_id
         </code>
         ,
         <code class="literal">
          user_id
         </code>
         :
                Null-terminated strings that as a pair form a unique
                identifier for the key to be stored.
        </p>
       </li>
       <li class="listitem">
        <p>
         <code class="literal">
          key_type
         </code>
         : A null-terminated string
                that provides additional information about the key.
        </p>
       </li>
       <li class="listitem">
        <p>
         <code class="literal">
          key
         </code>
         : The buffer containing the key
                data to be stored.
        </p>
       </li>
       <li class="listitem">
        <p>
         <code class="literal">
          key_len
         </code>
         : The size in bytes of the
         <code class="literal">
          key
         </code>
         buffer.
        </p>
       </li>
      </ul>
     </div>
     <p>
      Return value:
     </p>
     <p>
      Returns 0 for success, 1 for failure.
     </p>
    </li>
   </ul>
  </div>
 </div>
 <br/>
</div>
