MongoDB\Driver\ClientEncryption::createDataKey

Creates a key document

&reftitle.description; final public `MongoDB\BSON\Binary` `MongoDB\Driver\ClientEncryption::createDataKey` `string` `kmsProvider` ``array``null```options`&null;

Creates a new key document and inserts it into the key vault collection.

&reftitle.parameters;

`kmsProvider`

- The KMS provider (e.g. `"local"`, `"aws"`) that will be used to encrypt the new data key.

`options`

- ## Data key options

  Option | Type | Description
  masterKey | `array` | The masterKey document identifies a KMS-specific key used to encrypt the new data key. This option is required unless `kmsProvider` is `"local"`. &mongodb.option.encryption.masterKey-options-by-provider;
  keyAltNames | `array` | 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 `_id`.
  keyMaterial | `MongoDB\BSON\Binary` | 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.

&reftitle.returnvalues;

Returns the identifier of the new key as a `MongoDB\BSON\Binary` object with subtype 4 (UUID).

&reftitle.errors;

&mongodb.throws.std;
- Throws `MongoDB\Driver\Exception\RuntimeException` on other errors.

&reftitle.changelog;

&Version; | &Description;
PECL mongodb 1.15.0 | Added the `"keyMaterial"` option.
PECL mongodb 1.10.0 | Azure and GCP are now supported as KMS providers for client-side encryption.