# MongoDB\Driver\ClientEncryption::createDataKey

(mongodb >=1.7.0)

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

### Descripción

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.

### Parámetros

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

### Valores devueltos

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

### Errores/Excepciones

- Lanza una MongoDB\Driver\Exception\InvalidArgumentException en errores de análisis de argumentos.
- Lanza una MongoDB\Driver\Exception\ConnectionException si la conexión al servidor falla (por razones diferentes a la autenticación).
- Lanza una MongoDB\Driver\Exception\AuthenticationException si la autenticación es necesaria y falla.
- Throws MongoDB\Driver\Exception\RuntimeException on other errors.

### Historial de cambios

Versión | Descripción
--- | ---
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.