Tutorials >
Client-Side Encryption

Client-Side Encryption

On this page

Creating an Encryption Key
Automatic Encryption and Decryption
Specifying an Explicit Schema for Encryption
Manually Encrypting and Decrypting Values
Referencing Encryption Keys by an Alternative Name
Automatic Queryable Encryption

Client-Side Field Level Encryption allows administrators and developers to encrypt specific data fields in addition to other MongoDB encryption features.

Creating an Encryption Key

Note

The following examples use a local master key; however, other key providers such as AWS KMS are also an option. This master key is used to encrypt data keys that are stored locally. It is important that you keep this key secure.

To create an encryption key, create a MongoDB\Driver\ClientEncryption instance with encryption options and create a new data key. The method will return the key ID which can be used to reference the key later. You can also pass multiple alternate names for this key and reference the key by these names instead of the key ID. Creating a new data encryption key would typically be done on initial deployment, but depending on your use case you may want to use more than one encryption key or create them dynamically.

copy

<?php

use MongoDB\BSON\Binary;
use MongoDB\Client;
use MongoDB\Driver\ClientEncryption;

$localKey = new Binary('<binary key data (96 bytes)>', Binary::TYPE_GENERIC);

$clientEncryptionOpts = [
    'keyVaultNamespace' => 'encryption.__keyVault',
    'kmsProviders' => [
        'local' => ['key' => $localKey],
    ],
];

$client = new Client();
$clientEncryption = $client->createClientEncryption($clientEncryptionOpts);

// Create an encryption key with an alternate name
// To store the key ID for later use, you can use serialize or var_export
$keyId = $clientEncryption->createDataKey('local', ['keyAltNames' => ['my-encryption-key']]);

Automatic Encryption and Decryption

Note

Auto encryption is an enterprise only feature.

The following example sets up a collection with automatic encryption based on a $jsonSchema validator. The data in the encryptedField field is automatically encrypted on insertion and decrypted when reading on the client side.

copy

<?php

use MongoDB\BSON\Binary;
use MongoDB\Client;
use MongoDB\Driver\ClientEncryption;

$localKey = new Binary('<binary key data (96 bytes)>', Binary::TYPE_GENERIC);
$encryptionOpts = [
    'keyVaultNamespace' => 'encryption.__keyVault',
    'kmsProviders' => [
        'local' => ['key' => $localKey],
    ],
];

$client = new Client();

$database = $client->selectDatabase('test');
$database->dropCollection('coll'); // remove old data

// This uses the key ID from the first example. The key ID could be read from
// a configuration file.
$keyId = readDataKey();

$database->createCollection('coll', [
    'validator' => [
        '$jsonSchema' => [
            'bsonType' => 'object',
            'properties' => [
                'encryptedField' => [
                    'encrypt' => [
                        'keyId' => [$keyId],
                        'bsonType' => 'string',
                        'algorithm' => ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC,
                    ],
                ],
            ],
        ],
    ],
]);

$encryptedClient = new Client('mongodb://127.0.0.1', [], ['autoEncryption' => $encryptionOpts]);

$collection = $encryptedClient->selectCollection('test', 'coll');

$collection->insertOne(['encryptedField' => '123456789']);

var_dump($collection->findOne([]));

Specifying an Explicit Schema for Encryption

The following example uses the schemaMap encryption option to define encrypted fields.

Note

Supplying a schemaMap provides more security than relying on JSON schemas obtained from the server. It protects against a malicious server advertising a false JSON schema, which could trick the client into sending unencrypted data that should be encrypted.

copy

<?php

use MongoDB\BSON\Binary;
use MongoDB\Client;
use MongoDB\Driver\ClientEncryption;

$localKey = new Binary('<binary key data (96 bytes)>', Binary::TYPE_GENERIC);

$client = new Client();

// This uses the key ID from the first example. The key ID could be read from
// a configuration file.
$keyId = readDataKey();

$autoEncryptionOpts = [
    'keyVaultNamespace' => 'encryption.__keyVault',
    'kmsProviders' => [
        'local' => ['key' => $localKey],
    ],
    'schemaMap' => [
        'test.coll' => [
            'bsonType' => 'object',
            'properties' => [
                'encryptedField' => [
                    'encrypt' => [
                        'keyId' => [$keyId],
                        'bsonType' => 'string',
                        'algorithm' => ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC,
                    ],
                ],
            ],
        ],
    ],
];

$encryptedClient = new Client(null, [], ['autoEncryption' => $autoEncryptionOpts]);

$collection = $encryptedClient->selectCollection('test', 'coll');
$collection->drop(); // clear old data

$collection->insertOne(['encryptedField' => '123456789']);

var_dump($collection->findOne([]));

Manually Encrypting and Decrypting Values

In the MongoDB Community Edition, you will have to manually encrypt values before storing them in the database. The following example assumes that you have already created an encryption key in the key vault collection and explicitly encrypts and decrypts values in the document.

copy

<?php

use MongoDB\BSON\Binary;
use MongoDB\Client;
use MongoDB\Driver\ClientEncryption;

$localKey = new Binary('<binary key data (96 bytes)>', Binary::TYPE_GENERIC);

$clientEncryptionOpts = [
    'keyVaultNamespace' => 'encryption.__keyVault',
    'kmsProviders' => [
        'local' => ['key' => $localKey],
    ],
];

$client = new Client();
$clientEncryption = $client->createClientEncryption($clientEncryptionOpts);

// This uses the key ID from the first example. The key ID could be read from
// a configuration file.
$keyId = readDataKey();

$collection = $client->selectCollection('test', 'coll');
$collection->drop(); // clear old data

$encryptionOpts = [
    'keyId' => $keyId,
    'algorithm' => ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC,
];
$encryptedValue = $clientEncryption->encrypt('123456789', $encryptionOpts);

$collection->insertOne(['encryptedField' => $encryptedValue]);

$document = $collection->findOne();
var_dump($clientEncryption->decrypt($document->encryptedField));

Referencing Encryption Keys by an Alternative Name

While it is possible to create an encryption key every time data is encrypted, this is not the recommended approach. Instead, you should create your encryption keys depending on your use case, e.g. by creating a user-specific encryption key. To reference keys in your software, you can use the keyAltName attribute specified when creating the key. The following example creates an encryption key with an alternative name, which could be done when deploying the application. The software then encrypts data by referencing the key by its alternative name.

To use an alternate name when referencing an encryption key, use the keyAltName option instead of keyId.

copy

<?php

use MongoDB\BSON\Binary;
use MongoDB\Client;
use MongoDB\Driver\ClientEncryption;

$localKey = new Binary('<binary key data (96 bytes)>', Binary::TYPE_GENERIC);

$clientEncryptionOpts = [
    'keyVaultNamespace' => 'encryption.__keyVault',
    'kmsProviders' => [
        'local' => ['key' => $localKey],
    ],
];

$client = new Client();
$clientEncryption = $client->createClientEncryption($clientEncryptionOpts);

$collection = $client->selectCollection('test', 'coll');
$collection->drop(); // clear old data

// Reference the encryption key created in the first example by its
// alternative name
$encryptionOpts = [
    'keyAltName' => 'my-encryption-key',
    'algorithm' => ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC,
];
$encryptedValue = $clientEncryption->encrypt('123456789', $encryptionOpts);

$collection->insertOne(['encryptedField' => $encryptedValue]);

$document = $collection->findOne();
var_dump($clientEncryption->decrypt($document->encryptedField));

Automatic Queryable Encryption

Note

Automatic queryable encryption is an enterprise only feature and requires MongoDB 7.0+.

The following example uses a local key; however, other key providers such as AWS are also an option. The data in the encryptedIndexed and encryptedUnindexed fields will be automatically encrypted on insertion and decrypted when querying on the client side. Additionally, it is possible to query on the encryptedIndexed field.

copy

<?php

use MongoDB\BSON\Binary;
use MongoDB\Client;

$localKey = new Binary('<binary key data (96 bytes)>', Binary::TYPE_GENERIC);

$encryptionOpts = [
    'keyVaultNamespace' => 'encryption.__keyVault',
    'kmsProviders' => ['local' => ['key' => $localKey]],
];

$client = new Client();
$clientEncryption = $client->createClientEncryption($encryptionOpts);

// Create two data keys, one for each encrypted field
$dataKeyId1 = $clientEncryption->createDataKey('local');
$dataKeyId2 = $clientEncryption->createDataKey('local');

$autoEncryptionOpts = [
    'keyVaultNamespace' => 'encryption.__keyVault',
    'kmsProviders' => ['local' => ['key' => $localKey]],
    'encryptedFieldsMap' => [
        'test.coll' => [
            'fields' => [
                [
                    'path' => 'encryptedIndexed',
                    'bsonType' => 'string',
                    'keyId' => $dataKeyId1,
                    'queries' => ['queryType' => 'equality'],
                ],
                [
                    'path' => 'encryptedUnindexed',
                    'bsonType' => 'string',
                    'keyId' => $dataKeyId2,
                ],
            ],
        ],
    ],
];

$encryptedClient = new Client(null, [], ['autoEncryption' => $autoEncryptionOpts]);

/* Drop and create the collection under test. The createCollection() helper
 * will reference the client's encryptedFieldsMap and create additional,
 * internal collections automatically. */
$encryptedClient->selectDatabase('test')->dropCollection('coll');
$encryptedClient->selectDatabase('test')->createCollection('coll');
$encryptedCollection = $encryptedClient->selectCollection('test', 'coll');

/* Using a client with auto encryption, insert a document with encrypted
 * fields and assert that those fields are automatically decrypted when
 * querying. The encryptedIndexed and encryptedUnindexed fields should both
 * be strings. */
$indexedValue = 'indexedValue';
$unindexedValue = 'unindexedValue';

$encryptedCollection->insertOne([
    '_id' => 1,
    'encryptedIndexed' => $indexedValue,
    'encryptedUnindexed' => $unindexedValue,
]);

var_dump($encryptedCollection->findOne(['encryptedIndexed' => $indexedValue]));

/* Using a client without auto encryption, query for the same document and
 * assert that encrypted data is returned. The encryptedIndexed and
 * encryptedUnindexed fields should both be Binary objects. */
$unencryptedCollection = $client->selectCollection('test', 'coll');

var_dump($unencryptedCollection->findOne(['_id' => 1]));

← Decimal128 GridFS →