1. class
  2. MongoDB
  3. \
  4. Driver
  5. \
  6. ClientEncryption

ClientEncryption

Since: 1.7.0

final class ClientEncryption (View source)

The MongoDB\Driver\ClientEncryption class handles creation of data keys for client-side encryption, as well as manually encrypting and decrypting values.

Constants

AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC

AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM

ALGORITHM_INDEXED Since: 1.14.0

ALGORITHM_UNINDEXED Since: 1.14.0

ALGORITHM_RANGE Since: 1.20.0

QUERY_TYPE_EQUALITY Since: 1.14.0

QUERY_TYPE_RANGE Since: 1.20.0

Methods

__construct(array $options)

No description

__wakeup()

No description

object|null
addKeyAltName(Binary $keyId, string $keyAltName)

Adds an alternate name to a key document

Binary
createDataKey(string $kmsProvider, array|null $options = null)

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

mixed
decrypt(Binary $keyVaultClient)

Decrypts an encrypted value (BSON binary of subtype 6).

object
deleteKey(Binary $keyId)

Deletes a key document

Binary
encrypt(mixed $value, array|null $options = null)

Encrypts a value with a given key and algorithm.

object
encryptExpression(array|object $expr, array|null $options = null)

Encrypts a Match Expression or Aggregate Expression to query a range index

object|null
getKey(Binary $keyId)

Gets a key document

object|null
getKeyByAltName(string $keyAltName)

Gets a key document by an alternate name

Cursor
getKeys()

Finds all key documents in the key vault collection.

object|null
removeKeyAltName(Binary $keyId, string $keyAltName)

Removes an alternate name from a key document

object
rewrapManyDataKey(array|object $filter, array|null $options = null)

Rewraps data keys

Details

at line 47
final __construct(array $options)

Since: 1.14.0

No description

Parameters

array $options

at line 49
final __wakeup()

No description

at line 60
final object|null addKeyAltName(Binary $keyId, string $keyAltName)

Since: 1.15.0

Adds an alternate name to a key document

Parameters

Binary $keyId

A MongoDB\BSON\Binary instance with subtype 4 (UUID) identifying the key document.
string $keyAltName

Alternate name to add to the key document.

Return Value

object|null

Returns the previous version of the key document, or null if no document matched.

Exceptions

InvalidArgumentException

at line 71
final Binary createDataKey(string $kmsProvider, array|null $options = null)

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

Parameters

string $kmsProvider

The KMS provider ("local" or "aws") that will be used to encrypt the new encryption key.
array|null $options [optional]

Return Value

Binary

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

Exceptions

InvalidArgumentException
EncryptionException

at line 81
final mixed decrypt(Binary $keyVaultClient)

Decrypts an encrypted value (BSON binary of subtype 6).

Parameters

Binary $keyVaultClient

A MongoDB\BSON\Binary instance with subtype 6 containing the encrypted value.

Return Value

mixed

Returns the decrypted value

Exceptions

InvalidArgumentException
EncryptionException

at line 91
final object deleteKey(Binary $keyId)

Since: 1.15.0

Deletes a key document

Parameters

Binary $keyId

A MongoDB\BSON\Binary instance with subtype 4 (UUID) identifying the key document.

Return Value

object

Returns the result of the internal deleteOne operation on the key vault collection.

Exceptions

InvalidArgumentException

at line 102
final Binary encrypt(mixed $value, array|null $options = null)

Encrypts a value with a given key and algorithm.

Parameters

mixed $value

The value to be encrypted. Any value that can be inserted into MongoDB can be encrypted using this method.
array|null $options [optional]

Return Value

Binary

Returns the encrypted value as MongoDB\BSON\Binary object with subtype 6.

Exceptions

InvalidArgumentException
EncryptionException

at line 139
final object encryptExpression(array|object $expr, array|null $options = null)

Since: 1.16.0

Encrypts a Match Expression or Aggregate Expression to query a range index

Parameters

array|object $expr

A BSON document containing the expression
array|null $options

Encryption options Option Type Description algorithm string The encryption algorithm to be used. This option is required. Specify one of the following ClientEncryption constants: MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED MongoDB\Driver\ClientEncryption::ALGORITHM_UNINDEXED MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE contentionFactor int The contention factor for evaluating queries with indexed, encrypted payloads. This option only applies and may only be specified when algorithm is MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED or MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE. keyAltName string Identifies a key vault collection document by keyAltName. This option is mutually exclusive with keyId and exactly one is required. keyId MongoDB\BSON\Binary Identifies a data key by _id. The value is a UUID (binary subtype 4). This option is mutually exclusive with keyAltName and exactly one is required. queryType string The query type for evaluating queries with indexed, encrypted payloads. Specify one of the following ClientEncryption constants: MongoDB\Driver\ClientEncryption::QUERY_TYPE_EQUALITY MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE This option only applies and may only be specified when algorithm is MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED or MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE. rangeOpts array Index options for a queryable encryption field supporting "range" queries. The options below must match the values set in the encryptedFields of the target collection. For double and decimal128 BSON field types, min, max, and precision must all be set, or all be unset. Range index options Option Type Description min mixed Required if precision is set. The minimum BSON value of the range. max mixed Required if precision is set. The maximum BSON value of the range. sparsity int Optional. Positive 64-bit integer. precision int Optional. Positive 32-bit integer specifying precision to use for explicit encryption. May only be set for double or decimal128 BSON field types. trimFactor int Optional. Positive 32-bit integer.

Return Value

object

Returns the encrypted expression as a BSON document

Exceptions

InvalidArgumentException

at line 149
final object|null getKey(Binary $keyId)

Since: 1.15.0

Gets a key document

Parameters

Binary $keyId

A MongoDB\BSON\Binary instance with subtype 4 (UUID) identifying the key document.

Return Value

object|null

Returns the key document, or null if no document matched.

Exceptions

InvalidArgumentException

at line 159
final object|null getKeyByAltName(string $keyAltName)

Since: 1.15.0

Gets a key document by an alternate name

Parameters

string $keyAltName

Alternate name for the key document.

Return Value

object|null

Returns the key document, or null if no document matched.

Exceptions

InvalidArgumentException

at line 168
final Cursor getKeys()

Since: 1.15.0

Finds all key documents in the key vault collection.

Return Value

Cursor

Returns MongoDB\Driver\Cursor on success.

Exceptions

InvalidArgumentException

at line 178
final object|null removeKeyAltName(Binary $keyId, string $keyAltName)

Since: 1.15.0

Removes an alternate name from a key document

Parameters

Binary $keyId

A MongoDB\BSON\Binary instance with subtype 4 (UUID) identifying the key document.
string $keyAltName

Alternate name to remove from the key document.

Return Value

object|null

Returns the previous version of the key document, or null if no document matched.

at line 211
final object rewrapManyDataKey(array|object $filter, array|null $options = null)

Since: 1.16.0

Rewraps data keys

Parameters

array|object $filter

The query predicate. An empty predicate will match all documents in the collection. When evaluating query criteria, MongoDB compares types and values according to its own comparison rules for BSON types, which differs from PHP's comparison and type juggling rules. When matching a special BSON type the query criteria should use the respective BSON class (e.g. use MongoDB\BSON\ObjectId to match an ObjectId).
array|null $options

RewrapManyDataKey options Option Type Description provider string The KMS provider (e.g. "local", "aws") that will be used to re-encrypt the matched data keys. If a KMS provider is not specified, matched data keys will be re-encrypted with their current KMS provider. masterKey array The masterKey identifies a KMS-specific key used to encrypt the new data key. This option should not be specified without the "provider" option. This option is required if "provider" is specified and not "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. delegated bool Optional. If true, this key should be decrypted by the KMIP server.

Return Value

object

Returns an object, which will have an optional bulkWriteResult property containing the result of the internal bulkWrite operation as an object. If no data keys matched the filter or the write was unacknowledged, the bulkWriteResult property will be null.