<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 344035 $ -->

<refentry xml:id="mongodb-driver-clientencryption.createdatakey" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>MongoDB\Driver\ClientEncryption::createDataKey</refname>
  <refpurpose>Creates a key document</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <modifier>final</modifier> <modifier>public</modifier> <type>MongoDB\BSON\Binary</type><methodname>MongoDB\Driver\ClientEncryption::createDataKey</methodname>
   <methodparam><type>string</type><parameter>kmsProvider</parameter></methodparam>
   <methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>options</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <para>
   Creates a new key document and inserts it into the key vault collection.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <variablelist>
   <varlistentry>
    <term><parameter>kmsProvider</parameter></term>
    <listitem>
     <para>
      The KMS provider (e.g. <literal>"local"</literal>,
      <literal>"aws"</literal>) that will be used to encrypt the new data key.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>options</parameter></term>
    <listitem>
     <para>
      <table>
       <title>Data key options</title>
       <tgroup cols="3">
        <thead>
         <row>
          <entry>Option</entry>
          <entry>Type</entry>
          <entry>Description</entry>
         </row>
        </thead>
        <tbody>
         <row>
          <entry>masterKey</entry>
          <entry><type>array</type></entry>
          <entry>
           <para>
            The masterKey document identifies a KMS-specific key used to encrypt
            the new data key. This option is required unless
            <parameter>kmsProvider</parameter> is <literal>"local"</literal>.
           </para>
           &mongodb.option.encryption.masterKey-options-by-provider;
          </entry>
         </row>
         <row>
          <entry>keyAltNames</entry>
          <entry><type>array</type></entry>
          <entry>
           <para>
            An optional list of string alternate names used to reference a key.
            If a key is created with alternate names, then encryption may refer
            to the key by the unique alternate name instead of by
            <literal>_id</literal>.
           </para>
          </entry>
         </row>
         <row>
          <entry>keyMaterial</entry>
          <entry><classname>MongoDB\BSON\Binary</classname></entry>
          <entry>
           <para>
            An optional 96-byte value to use as custom key material for the data
            key being created. If keyMaterial is given, the custom key material
            is used for encrypting and decrypting data. Otherwise, the key
            material for the new data key is generated from a cryptographically
            secure random device.
           </para>
          </entry>
         </row>
        </tbody>
       </tgroup>
      </table>
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns the identifier of the new key as a
   <classname>MongoDB\BSON\Binary</classname> object with subtype 4 (UUID).
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <simplelist>
   &mongodb.throws.std;
   <member>Throws <classname>MongoDB\Driver\Exception\RuntimeException</classname> on other errors.</member>
  </simplelist>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>PECL mongodb 1.15.0</entry>
       <entry>
        Added the <literal>"keyMaterial"</literal> option.
       </entry>
      </row>
      <row>
       <entry>PECL mongodb 1.10.0</entry>
       <entry>
        Azure and GCP are now supported as KMS providers for client-side
        encryption.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
