Navigation

Mongo()

On this page

Description

Changed in version 4.2.

Mongo(host, ClientSideFieldLevelEncryptionOptions)

JavaScript constructor to instantiate a database connection from the mongo shell or from a JavaScript file.

The Mongo() method has the following parameters:

Parameter Type Description
host string

Optional. The host, either in the form of <host> or <host><:port>.

If omitted, Mongo instantiates a connection to the localhost interface on the default port 27017.
ClientSideFieldLevelEncryptionOptions Document

Optional

New in version 4.2.

Configuration parameters for enabling Client-Side Field Level Encryption.

ClientSideFieldLevelEncryptionOptions overrides the existing client-side field level encryption configuration of the database connection. If omitted, Mongo() inherits the client-side field level encryption configuration of the current database connection.

For documentation of usage and syntax, see ClientSideFieldLevelEncryptionOptions.

See also

Mongo.getDB() and db.getMongo().

ClientSideFieldLevelEncryptionOptions

New in version 4.2.

The ClientSideFieldLevelEncryptionOptions document specifies configuration options for Client-Side Field Level Encryption. If the database connection has an existing client-side field level encryption configuration, specifying ClientSideFieldLevelEncryptionOptions overrides that configuration.

For example, starting the mongo shell with client-side field level encryption command-line options enables client-side encryption for that connection. New database connections created using Mongo() inherit the encryption settings unless Mongo() includes ClientSideFieldLevelEncryptionOptions.

The ClientSideFieldLevelEncryptionOptions document has the following syntax:

copy 
{
  "keyVaultClient" : <object>,
  "keyVaultNamespace" : "<string>",
  "kmsProvider" : <object>,
  "schemaMap" : <object>,
  "bypassAutoEncryption" : <boolean>
}

The ClientSideFieldLevelEncryptionOptions document takes the following parameters:

Parameter Type Description
keyVaultClient Mongo() connection object.

(Optional) The MongoDB cluster hosting the key vault collection. Omit to use the current database connection as the key vault host.

Specify a Mongo() connection object pointing to the cluster:

copy 
var keyVaultClient = Mongo(<MongoDB URI>);

var ClientSideFieldLevelEncryptionOptions = {
  "keyVaultClient" : keyVaultClient,
  "keyVaultNamespace" : "<database>.<collection>",
  "kmsProvider" : { ... }
}
keyVaultNamespace string (Required) The full namespace of the key vault collection.
kmsProvider document

(Required) The Key Management Service (KMS) used by client-side field level encryption for managing a Customer Master Key (CMK). Client-side field level encryption uses the CMK for encrypting and decrypting data encryption keys.

Client-side field level encryption either the Amazon Web Services KMS or a Locally Managed Key:

Amazon Web Services KMS

Important

For AWS KMS support, use the 4.2.2 mongo shell. The 4.2.0 and 4.2.1 mongo shell does not support the AWS KMS service due to an unexpected change in the KMS response object. See SERVER-44721 for more information on the issue.

Specify the aws document to kmsProvider with the following fields:

copy 
"kmsProvider" : {
   "aws" : {
     "accessKeyId" : "AWSAccessKeyId",
     "secretAccessKey" : "AWSSecretAccessKey"
   }
 }

The specified accessKeyId must correspond to an IAM user with all List and Read permissions for the KMS service.

Locally Managed Key

Specify the local document to kmsProvider with the following field:

copy 
"kmsProvider" : {
  "local" : {
     "key" : BinData(0, "<96 byte base-64 encoded key>")
  }
}

The specified key must be a base64-encoded 96-byte string with no newline characters.
schemaMap document

(Optional) The automatic client-side field level encryption rules specified using the JSON schema Draft 4 standard syntax and encryption-specific keywords.

For complete documentation, see Automatic Encryption Rules.
bypassAutoEncryption boolean (Optional) Specify true to bypass automatic client-side field level encryption rules and perform explicit (manual) per-field encryption.

Example

Connect to a MongoDB Cluster

The following operation creates a new connection object from the mongo shell:

copy 
cluster = Mongo("mongodb://mymongo.example.net:27017/?replicaSet=myMongoCluster")

Issue operations against the cluster object to interact with the mymongo.example.net:27017 cluster:

copy 
myDB = cluster.getDB("myDB"); //returns the database object
myColl = myDB.getCollection("myColl"); // returns the collection object

Connect to a MongoDB Cluster with Client-Side Encryption Enabled

Configuring client-side field level encryption for a locally managed key requires specifying a base64-encoded 96-byte string with no line breaks. The following operation generates a key that meets the stated requirements and loads it into the mongo shell:

copy 
TEST_LOCAL_KEY=$(echo "$(head -c 96 /dev/urandom | base64 | tr -d '\n')")

mongo --nodb --shell --eval "var TEST_LOCAL_KEY='$TEST_LOCAL_KEY'"

The following operation creates a new connection object from the mongo shell. The ClientSideFieldLevelEncryptionOptions option specifies the required options for enabling client-side field level encryption using a locally managed key:

copy 
var ClientSideFieldLevelEncryptionOptions = {
  "keyVaultNamespace" : "encryption.dataKeys",
  "kmsProviders" : {
    "local" : {
      "key" : BinData(0, TEST_LOCAL_KEY)
    }
  }
}

cluster = Mongo(
  "mongodb://mymongo.example.net:27017/?replicaSet=myMongoCluster",
  ClientSideFieldLevelEncryptionOptions
)

Issue operations against the cluster object to interact with the mymongo.example.net:27017 cluster and perform explicit encryption:

copy 
// returns the database object
myDB = cluster.getDB("myDB");

// returns the collection object
myColl = myDB.getCollection("myColl");

// returns object for managing data encryption keys
keyVault = cluster.getKeyVault();

// returns object for explicit encryption/decryption
clientEncryption = cluster.getClientEncryption();

See Client-Side Field Level Encryption Methods for a complete list of client-side field level encryption methods.

Connect to a MongoDB Cluster with Automatic Client-Side Encryption Enabled

Configuring client-side field level encryption for a locally managed key requires specifying a base64-encoded 96-byte string with no line breaks. The following operation generates a key that meets the stated requirements and loads it into the mongo shell:

copy 
TEST_LOCAL_KEY=$(echo "$(head -c 96 /dev/urandom | base64 | tr -d '\n')")

mongo --nodb --shell --eval "var TEST_LOCAL_KEY='$TEST_LOCAL_KEY'"

The following operation creates a new connection object from the mongo shell. The ClientSideFieldLevelEncryptionOptions option specifies the required options for enabling automatic client-side encryption on the hr.employees collection:

copy 
var ClientSideFieldLevelEncryptionOptions = {
  "keyVaultNamespace" : "encryption.dataKeys",
  "kmsProviders" : {
    "local" : {
      "key" : BinData(0,"BASE64-ENCODED-96-BYTE-LOCAL-KEY")
    }
  },
  schemaMap : {
    "hr.employees" : {
      "bsonType": "object",
      "properties" : {
        "taxid" : {
          "encrypt" : {
            "keyId" : [UUID("bffb361b-30d3-42c0-b7a4-d24a272b72e3")],
            "bsonType" : "string",
            "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Random"
          }
        },
        "taxid-short": {
          "encrypt": {
            "keyId": [UUID("33408ee9-e499-43f9-89fe-5f8533870617")],
            "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
            "bsonType": "string"
          }
        }
      }
    }
  }
}

cluster = Mongo(
  "mongodb://mymongo.example.net:27017/?replicaSet=myMongoCluster",
  ClientSideFieldLevelEncryptionOptions
)

Issue operations against the cluster object to interact with the mymongo.example.net:27017 cluster and utilize automatic encryption:

copy 
// returns the database object
myDB = cluster.getDB("myDB");

// returns the collection object
myColl = myDB.getCollection("myColl");

myColl.insertOne(
  {
    "name" : "J Doe",
    "taxid" : "123-45-6789",
    "taxid-short" : "6789"
  }
)

The specified automatic encryption rules encrypt the taxid and taxid-short fields using the specified data encryption key and algorithm. Only clients configured for the correct KMS and access to the specified data encryption key can decrypt the field.

See Client-Side Field Level Encryption Methods for a complete list of client-side field level encryption methods.

←   connect() Mongo.getDB()  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.