MongoDB connections

DataMasque masks MongoDB collections in place.

• Required privileges
• Encrypted connections
  • Publicly trusted certificates (e.g. MongoDB Atlas)
  • Custom or private CAs
  • Rotating a certificate
• Masked numbers
• Field names with a dot or a leading $
• Truncate a collection

Required privileges

A DataMasque connection for MongoDB requires:

• A user with readWrite role on the target database.

use admin
db.createUser({
  user: "<connection user>",
  pwd: "<password>",
  roles: [{ role: "readWrite", db: "<target database>" }]
})

MongoDB connections use the following parameters:

• Host: The hostname of the MongoDB server.
• Port: The MongoDB server port (default: 27017).
• Database: The database to connect to and mask.
• User / Password: Credentials for authentication. Optional when the MongoDB instance does not require authentication. If a user is provided, a password is also required.
• Authentication Database: The database used to authenticate the supplied user. Defaults to admin.
• Enable TLS/SSL: Connect to the server using TLS. When enabled without a CA certificate, the system CA trust store is used for verification.
• MongoDB CA Certificate: An optional CA certificate used to trust a custom or private CA (for example, the Amazon RDS CA required by Amazon DocumentDB). Shown under Advanced Settings once TLS is enabled. See MongoDB Encrypted Connections.
• Direct Connection: Connect directly to a single MongoDB instance rather than discovering members of a replica set.

Encrypted connections

DataMasque supports encrypted connections to MongoDB databases. Enable TLS/SSL on the connection to connect over TLS.

Publicly trusted certificates (e.g. MongoDB Atlas)

When TLS is enabled without a CA certificate, the system CA trust store is used to verify the server. This is sufficient for any server that presents a publicly trusted certificate, such as MongoDB Atlas or Azure Cosmos DB — no certificate upload is required. Simply enable TLS/SSL and leave the MongoDB CA Certificate unset.

Custom or private CAs

To trust a server whose certificate is not publicly trusted, upload a CA certificate through the Files interface and select it as the MongoDB CA Certificate under Advanced Settings on the connection. The certificate is only used when TLS is enabled; selecting one while TLS is disabled is rejected.

The certificate must be uploaded as a .zip file containing a single ca.pem file:

File Name	Description
ca.pem	The certificate(s) used to verify the server, in PEM format.

What ca.pem should contain depends on how the server's certificate was issued:

The server certificate is…	Put this in ca.pem
Self-signed	The server's own certificate (it acts as its own trust anchor).
Issued by a private/internal CA	That CA's certificate (the issuer).
Issued via one or more intermediate CAs	The full chain: the root CA plus every intermediate CA, concatenated into ca.pem.

If you are unsure, include the full chain (the root CA and all intermediates). ca.pem must be in PEM format, i.e. one or more -----BEGIN CERTIFICATE----- blocks.

Client certificates (mutual TLS) are not supported; the uploaded certificate is used only to verify the server.

This is the trust path required by Amazon DocumentDB, which presents a certificate signed by the Amazon RDS CA. Download the Amazon RDS CA bundle, package it as ca.pem inside a .zip, and select it on the connection. See AWS's documentation: https://docs.aws.amazon.com/documentdb/latest/developerguide/security.encryption.ssl.html.

Rotating a certificate

Connection fileset names must be unique, so re-uploading a file with the same name is rejected. To rotate the CA certificate a connection uses:

1. Upload the new certificate as a new fileset (with a new, unique name).
2. Edit the connection and select the new certificate as the MongoDB CA Certificate.
3. Delete the old fileset from the Files page.

Masked numbers

A masked number in a top-level field is written back as the BSON number type that can hold it. When no BSON number type can hold it, the number is written as a String. The table below is for top-level fields.

A number inside a nested document or array, such as one masked with a json mask, goes through JSON on its way back. It keeps the type of the original value where the masked number still fits it. A masked integer past the Int64 range, or a decimal that a Decimal128 cannot hold, has no exact JSON form there, so it is written as a Double and can lose digits.

The masked value is…	It is written as…
An integer that fits in an Int32	Int32, or Int64 when the field was an Int64
An integer too large for an Int32 that fits in an Int64	Int64
An integer too large for an Int64	String
A decimal with at most 34 significant digits, not counting trailing zeros	Decimal128
A decimal with more than 34 significant digits	String
A float	Double

An Int32 field whose masked value is too large for an Int32 therefore becomes an Int64. A mask that keeps the digits of an Int64 near its maximum of 9223372036854775807, such as imitate_unique, can produce an integer past that maximum, which is written as a String. A field masked this way can then hold a mix of numbers and strings, so a query that filters or sorts the field by type does not see the strings as numbers.

Field names with a dot or a leading $

A rule names a field whose name holds a dot or starts with $ in quotes, such as column: '"a.b"', and masks that top-level field, not a nested one. DataMasque writes such a field back with an update pipeline and $setField, which needs MongoDB 5.0 or later.

Amazon DocumentDB and Azure Cosmos DB for MongoDB may not support $setField. There, a document that holds such a field fails to be written, and the run reports the write error; no other field is changed in its place. Documents whose field names are all ordinary are written as before.

Truncate a collection

The truncate_table task empties a collection in the connection's database:

tasks:
  - type: truncate_table
    table: audit_log

• The task deletes all documents in the collection. The collection, its indexes, its validation rules and its sharding configuration stay in place.
• MongoDB has no truncate command, so the task deletes the documents one at a time on the server. The time the task takes increases with the number of documents. Each deletion also goes to the oplog.
• The task fails if the collection does not exist.
• table names a collection in the connection's database. A database prefix such as otherdb.audit_log is refused. To name a collection that contains a dot, put the name in double quotes, for example table: '"audit.log"'.
• The readWrite role in Required privileges is sufficient.