Mongo()

Description

Changed in version 4.2.

  • Mongo(host, ClientSideFieldLevelEncryptionOptions)
  • JavaScript constructor to instantiate a database connection from themongo shell or from a JavaScript file.

The Mongo() method has the following parameters:

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

If omitted, Mongo instantiates a connection to thelocalhost interface on the default port 27017.ClientSideFieldLevelEncryptionOptionsDocumentOptional

New in version 4.2.

Configuration parameters for enablingClient-Side Field Level Encryption.

beta

Client-Side Field Level Encryption is available as a beta. The contentsof this page may change during the beta period.

ClientSideFieldLevelEncryptionOptions overrides the existingclient-side field level encryption configuration of the databaseconnection. If omitted, Mongo() inherits the client-sidefield level encryption configuration of the current databaseconnection.

For documentation of usage and syntax, seeClientSideFieldLevelEncryptionOptions.

See also

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

ClientSideFieldLevelEncryptionOptions

New in version 4.2.

The ClientSideFieldLevelEncryptionOptions document specifies configurationoptions for Client-Side Field Level Encryption. If the databaseconnection has an existing client-side field level encryption configuration,specifying ClientSideFieldLevelEncryptionOptions overrides thatconfiguration.

For example, starting the mongo shellwith client-side field level encryption command-line options enablesclient-side encryption for that connection. New database connectionscreated using Mongo() inherit the encryption settings unlessMongo() includes ClientSideFieldLevelEncryptionOptions.

The ClientSideFieldLevelEncryptionOptions document has the followingsyntax:

  1. {
  2.   "keyVaultClient" : <object>,
  3.   "keyVaultNamespace" : "<string>",
  4.   "kmsProvider" : <object>,
  5.   "schemaMap" : <object>,
  6.   "bypassAutoEncryption" : <boolean>
  7. }

The ClientSideFieldLevelEncryptionOptions document takes the followingparameters:

ParameterTypeDescription
keyVaultClientMongo() 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 thecluster:
  1. var keyVaultClient = Mongo(<MongoDB URI>);var ClientSideFieldLevelEncryptionOptions = {  "keyVaultClient" : keyVaultClient,  "keyVaultNamespace" : "<database>.<collection>",  "kmsProvider" : { … }}
keyVaultNamespacestring(Required) The full namespace of the key vault collection.
kmsProviderdocument(Required) The Key Management Service (KMS) used byclient-side field level encryption for managing a Customer MasterKey (CMK). Client-side field level encryption uses the CMK forencrypting and decrypting data keys.Client-side field level encryption either the Amazon Web ServicesKMS or a Locally Managed Key:- Amazon Web Services KMS-WarningThe 4.2.0 and 4.2.1 mongo shell does not support theAWS KMS service due to an unexpected change in the KMS responseobject. Previously functional applications using themongo shell to perform client-side field levelencryption using AWS KMS may now return errors during encryptionoperations. Official MongoDB 4.2-compatible drivers withclient-side field level encryption support are unaffected.SERVER-44721 documents the issue and isscheduled for the future 4.2.2 release.Specify the aws document to kmsProvider with thefollowing fields:
  1. "kmsProvider" : {   "aws" : {     "accessKeyId" : "AWSAccessKeyId",     "secretAccessKey" : "AWSSecretAccessKey"   } }
The specified accessKeyId must correspond to an IAM userwith all List and Read permissions for the KMS service.- Locally Managed Key-Specify the local document to kmsProvider with thefollowing field:
  1. "kmsProvider" : {  "local" : {     "key" : BinData(0, "<96 byte base-64 encoded key>")  }}
The specified key must be a base64-encoded96-byte string with no newline characters.
schemaMapdocument(Optional) The automatic client-side field level encryption rulesspecified using the JSON schema Draft 4 standard syntax andencryption-specific keywords.For complete documentation, seeAutomatic Encryption Rules.
bypassAutoEncryptionboolean(Optional) Specify true to bypass automatic client-side fieldlevel encryption rules and perform explicit (manual) per-fieldencryption.

Example

Connect to a MongoDB Cluster

The following operation creates a new connection object from themongo shell:

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

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

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

Connect to a MongoDB Cluster with Client-Side Encryption Enabled

Configuring client-side field level encryption for a locallymanaged key requires specifying abase64-encoded 96-byte string with no line breaks. The followingoperation generates a key that meets the stated requirements and loadsit into the mongo shell:

  1. TEST_LOCAL_KEY=$(echo "$(head -c 96 /dev/urandom | base64 | tr -d '\n')")
  2.  
  3. mongo --nodb --shell --eval "var TEST_LOCAL_KEY='$TEST_LOCAL_KEY'"

The following operation creates a new connection object from themongo shell. TheClientSideFieldLevelEncryptionOptions option specifiesthe required options for enabling client-side field level encryptionusing a locally managed key:

  1. var ClientSideFieldLevelEncryptionOptions = {
  2.   "keyVaultNamespace" : "encryption.dataKeys",
  3.   "kmsProviders" : {
  4.     "local" : {
  5.       "key" : BinData(0, TEST_LOCAL_KEY)
  6.     }
  7.   }
  8. }
  9.  
  10. cluster = Mongo(
  11.   "mongodb://mymongo.example.net:27017/?replicaSet="myMongoCluster",
  12.   ClientSideFieldLevelEncryptionOptions
  13. )

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

  1. // returns the database object
  2. myDB = cluster.getDB("myDB");
  3.  
  4. // returns the collection object
  5. myColl = myDB.myColl("myColl");
  6.  
  7. // returns object for managing data keys
  8. keyVault = cluster.getKeyVault();
  9.  
  10. // returns object for explicit encryption/decryption
  11. clientEncryption = cluster.getClientEncryption();

See Client-Side Field Level Encryption Methods fora 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 locallymanaged key requires specifying abase64-encoded 96-byte string with no line breaks. The followingoperation generates a key that meets the stated requirements and loadsit into the mongo shell:

  1. TEST_LOCAL_KEY=$(echo "$(head -c 96 /dev/urandom | base64 | tr -d '\n')")
  2.  
  3. mongo --nodb --shell --eval "var TEST_LOCAL_KEY='$TEST_LOCAL_KEY'"

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

  1. var ClientSideFieldLevelEncryptionOptions = {
  2.   "keyVaultNamespace" : "encryption.dataKeys",
  3.   "kmsProviders" : {
  4.     "local" : {
  5.       "key" : BinData(0,"BASE64-ENCODED-96-BYTE-LOCAL-KEY")
  6.     }
  7.   },
  8.   schemaMap : {
  9.     "hr.employees" : {
  10.       "bsonType": "object",
  11.       "properties" : {
  12.         "taxid" : {
  13.           "encrypt" : {
  14.             "keyId" : [UUID("bffb361b-30d3-42c0-b7a4-d24a272b72e3")],
  15.             "bsonType" : "string",
  16.             "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Random"
  17.           }
  18.         },
  19.         "taxid-short": {
  20.           "encrypt": {
  21.             "keyId": [UUID("33408ee9-e499-43f9-89fe-5f8533870617")],
  22.             "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512_Deterministic",
  23.             "bsonType": "string"
  24.           }
  25.         }
  26.       }
  27.     }
  28.   }
  29. }
  30.  
  31. cluster = Mongo(
  32.   "mongodb://mymongo.example.net:27017/?replicaSet="myMongoCluster",
  33.   ClientSideFieldLevelEncryptionOptions
  34. )

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

  1. // returns the database object
  2. myDB = cluster.getDB("myDB");
  3.  
  4. // returns the collection object
  5. myColl = myDB.myColl("myColl");
  6.  
  7. myColl.insertOne(
  8.   {
  9.     "name" : "J Doe",
  10.     "taxid" : "123-45-6789",
  11.     "taxid-short" : "6789"
  12.   }
  13. )

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

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