- Tutorials >
- In-Use Encryption
In-Use Encryption
On this page
Dependencies
To get started using in-use encryption in your project, the
PHP driver (i.e. mongodb
extension) will need
to be compiled with libmongocrypt
(enabled by default).
Additionally, either crypt_shared or mongocryptd are required in order to use automatic client-side encryption. Neither is required for explicit encryption.
mongocryptd
The mongocryptd binary is an alternative requirement for automatic client-side encryption and is included as a component in the MongoDB Enterprise Server package. For detailed installation instructions see the MongoDB documentation on mongocryptd.
mongocryptd performs the following:
- Parses the automatic encryption rules specified in the client configuration.
If the
schemaMap
auto encryption driver option contains invalid syntax, mongocryptd returns an error. - Uses the specified automatic encryption rules to mark fields in read and write operations for encryption.
- Rejects read/write operations that may return unexpected or incorrect results when applied to an encrypted field. For supported and unsupported operations, see Supported Operations for Automatic Encryption.
A client configured with auto encryption will automatically spawn the
mongocryptd process from the application’s PATH
. Applications can control
the spawning behavior via various auto encryption
driver options.
mongocryptd is only responsible for supporting automatic client-side encryption and does not itself perform any encryption or decryption.
Managing Encryption Keys
See also
Encryption Key Management in the MongoDB manual
Creating an Encryption Key
Note
The following examples use a local master key. While this is suitable for development, a production application should use a supported cloud provider (e.g. AWS KMS). The master key is used to encrypt locally stored data keys and thus it is very important that you keep this key secure.
To create an encryption key, create a MongoDB\Driver\ClientEncryption instance with encryption options and use the createDataKey() method. 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 (e.g. user-specific encryption keys) or create them dynamically.
Referencing Encryption Keys by an Alternative Name
To reference keys in your application, 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 script then encrypts data by referencing the key by its
alternative name using the keyAltName
option instead of keyId
.
Note
Prior to adding a new key alternate name, you must create a partial, unique
index on the keyAltNames
field. Client-Side Field Level Encryption
depends on server-enforced uniqueness of key alternate names.
Client-Side Field Level Encryption
Introduced in MongoDB 4.2, Client-Side Field Level Encryption allows an application to encrypt specific data fields in addition to pre-existing MongoDB encryption features such as Encryption at Rest and TLS/SSL (Transport Encryption).
With field level encryption, applications can encrypt fields in documents prior to transmitting data over the wire to the server. Client-side field level encryption supports workloads where applications must guarantee that unauthorized parties, including server administrators, cannot read the encrypted data.
Automatic Client-Side Field Level Encryption
Note
Automatic client-side field level encryption requires MongoDB 4.2+ Enterprise or a MongoDB 4.2+ Atlas cluster.
Automatic client-side field level encryption is enabled by creating a client and
specifying the autoEncryption
driver option.
The following examples demonstrate how to setup automatic client-side field
level encryption and use a
MongoDB\Driver\ClientEncryption
object to create a new encryption key.
Server-Side Field Level Encryption Enforcement
The MongoDB 4.2+ server supports using schema validation to enforce encryption of specific fields in a collection. This schema validation will prevent an application from inserting unencrypted values for any fields marked with the “encrypt” schema keyword.
The following example sets up a collection with automatic encryption using a
$jsonSchema
validator and
Encryption Schema syntax.
Data in the encryptedField
field is automatically encrypted on insertion and
decrypted when reading on the client side.
Providing Local Automatic Encryption Rules
The following example uses the schemaMap
auto encryption driver option to
define encrypted fields using a
strict subset of the JSON schema syntax.
Using schemaMap
in conjunction with a server-side schema
provides more security than relying entirely on a schema obtained from the
server. It protects against a malicious server advertising a false schema, which
could trick the client into sending unencrypted data that should be encrypted.
Note
Only Encryption Schema syntax
can be used with the schemaMap
option. Do not specify document validation
keywords in the automatic encryption rules. To define document validation
rules, configure schema validation.
Explicit Encryption
Explicit encryption is a MongoDB community feature and does not use crypt_shared or mongocryptd. Explicit encryption is provided by the MongoDB\Driver\ClientEncryption class.
Explicit Encryption with Automatic Decryption
Although automatic encryption requires MongoDB 4.2+ enterprise or a MongoDB 4.2+
Atlas cluster, automatic decryption is supported for all users. To configure
automatic decryption without automatic encryption set the
bypassAutoEncryption
auto encryption
driver option
when constructing a client.
Queryable Encryption
Introduced in MongoDB 7.0, Queryable Encryption is another form of in-use encryption. Data is encrypted client-side. Queryable Encryption supports indexed encrypted fields, which are further processed server-side.
Automatic Queryable Encryption
Note
Automatic queryable encryption requires MongoDB 7.0+ Enterprise or a MongoDB 7.0+ Atlas cluster.
Automatic encryption in Queryable Encryption utilizes crypt_shared
or
mongocryptd
to automatically encrypt and decrypt data client-side. 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.
Explicit Queryable Encryption
Note
Explicit queryable encryption requires MongoDB 7.0+.
Explicit encryption in Queryable Encryption is performed using the
MongoDBDriverClientEncryption::encrypt()
and decrypt() methods. Although
values must be explicitly encrypted (e.g. insertions, query criteria), automatic
decryption for queries is possible by configuring encryptedFields
on the
collection, as demonstrated in the following example: