Creates a key document

- « MongoDB\Driver\ClientEncryption::__construct

- MongoDB\Driver\ClientEncryption::decrypt »

- PHP Manual
- MongoDB\Driver\ClientEncryption
- Creates a key document

# MongoDB\Driver\ClientEncryption::createDataKey

(mongodb >=1.7.0)

MongoDB\Driver\ClientEncryption::createDataKey — Creates a key document

### Description

final public MongoDB\Driver\ClientEncryption::createDataKey(string `$kmsProvider`, ?array `$options` = `null`): MongoDB\BSON\Binary

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

### 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"`.

  `"aws"` provider options
  Option | Type | Description
  --- | --- | ---
  region | string | Required.
  key | string | Required. The Amazon Resource Name (ARN) to the AWS customer master key (CMK).
  endpoint | string | Optional. An alternate host identifier to send KMS requests to. May include port number.

  `"azure"` provider options
  Option | Type | Description
  --- | --- | ---
  keyVaultEndpoint | string | Required. Host with optional port (e.g. "example.vault.azure.net").
  keyName | string | Required.
  keyVersion | string | Optional. A specific version of the named key. Defaults to using the key's primary version.

  `"gcp"` provider options
  Option | Type | Description
  --- | --- | ---
  projectId | string | Required.
  location | string | Required.
  keyRing | string | Required.
  keyName | string | Required.
  keyVersion | string | Optional. A specific version of the named key. Defaults to using the key's primary version.
  endpoint | string | Optional. Host with optional port. Defaults to "cloudkms.googleapis.com".

  `"kmip"` provider options
  Option | Type | Description
  --- | --- | ---
  keyId | string | Optional. Unique identifier to a 96-byte KMIP secret data managed object. If unspecified, the driver creates a random 96-byte KMIP secret data managed object.
  endpoint | string | Optional. Host with optional port.

  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.

### Return Values

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

### Errors/Exceptions

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
- Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
- Throws MongoDB\Driver\Exception\RuntimeException on other errors.

### 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.