MongoDB\Database::createEncryptedCollection()

On this page

Definition

Parameters
Return Values
Errors/Exceptions
Example
See Also

New in version 1.16.

Definition

MongoDB\Database::createEncryptedCollection()

Explicitly creates an encrypted collection.

function createEncryptedCollection(
    string $collectionName,
    MongoDB\Driver\ClientEncryption $clientEncryption,
    string $kmsProvider,
    ?array $masterKey,
    array $options
): array

This method will automatically create data keys for any encrypted fields where keyId is null. Data keys will be created using MongoDB\Driver\ClientEncryption::createDataKey() and the provided $kmsProvider and $masterKey parameters. A copy of the modified encryptedFields option will be returned in addition to the result from creating the collection.

This method does not affect any auto encryption settings on existing MongoDB\Client objects. Users must configure auto encryption after creating the encrypted collection with createEncryptedCollection().

Parameters

$collectionName : string

The name of the encrypted collection to create.

$clientEncryption : MongoDB\Driver\ClientEncryption

The ClientEncryption object used to create data keys.

$kmsProvider : string

KMS provider (e.g. "local", "aws") that will be used to encrypt new data keys. This corresponds to the $kmsProvider parameter for MongoDB\Driver\ClientEncryption::createDataKey().

$masterKey : array|null

KMS-specific key options that will be used to encrypt new data keys. This corresponds to the masterKey option for MongoDB\Driver\ClientEncryption::createDataKey().

If $kmsProvider is "local", this should be null.

$options : array

An array specifying the desired options.

The $options parameter supports the same options as MongoDB\Database::createCollection(). The encryptedFields option is required.

Return Values

A tuple (i.e. two-element array) containing the result document from the create command (an array or object according to the typeMap option) and the modified encryptedFields option.

Errors/Exceptions

MongoDB\Exception\CreateEncryptedCollectionException if any error is encountered creating data keys or the collection. The original exception and modified encryptedFields option can be accessed via the getPrevious() and getEncryptedFields() methods, respectively.

MongoDB\Exception\InvalidArgumentException for errors related to the parsing of parameters or options.

Example

The following example creates an encrypted users collection in the test database. The ssn field within the users collection will be defined as an encrypted string field.

<?php
// 96-byte master key used to encrypt/decrypt data keys
define('LOCAL_MASTERKEY', '...');
$client = new MongoDB\Client;
$clientEncryption = $client->createClientEncryption([
    'keyVaultNamespace' => 'keyvault.datakeys',
    'kmsProviders' => [
        'local' => ['key' => new MongoDB\BSON\Binary(base64_decode(LOCAL_MASTERKEY), 0)],
     ],
);
[$result, $encryptedFields] = $client->test->createEncryptedCollection(
    'users',
    $clientEncryption,
    'local',
    null,
    [
        'encryptedFields' => [
            'fields' => [
                ['path' => 'ssn', 'bsonType' => 'string', 'keyId' => null],
            ],
        ],
    ]
);

If the encrypted collection was successfully created, $result will contain the response document from the create command and $encryptedFields['fields'][0]['keyId'] will contain a MongoDB\BSON\Binary object with subtype 4 (i.e. UUID).

The modified encryptedFields option can then be used to construct a new MongoDB\Client with auto encryption enabled.

<?php
$encryptedClient = new MongoDB\Client(
    null, // Connection string
    [], // Additional connection string options
    [
        'autoEncryption' => [
            'keyVaultNamespace' => 'keyvault.datakeys',
            'kmsProviders' => [
                'local' => ['key' => new MongoDB\BSON\Binary(base64_decode(LOCAL_MASTERKEY), 0)],
             ],
             'encryptedFieldsMap' => [
                 'test.users' => $encryptedFields,
             ],
        ],
    ]
);

Definition

Parameters

Return Values

Errors/Exceptions

Example

See Also