Mongo() (original) (raw)

Mongo(host, autoEncryptionOpts, api)

JavaScript constructor to instantiate a database connection frommongosh or from a JavaScript file.

The Mongo() method has the following parameters:

See also:

This method is available in deployments hosted in the following environments:

• MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud
• MongoDB Enterprise: The subscription-based, self-managed version of MongoDB
• MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB

The autoEncryptionOpts document specifies configuration options for In-Use Encryption. If your database connection has an existing in-use encryption configuration,autoEncryptionOpts overrides that configuration. MongoDB provides two approaches to In-Use Encryption: Client-Side Field Level Encryption and Queryable Encryption.

For example, starting mongoshwith 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 autoEncryptionOpts.

The autoEncryptionOpts document has the following syntax:

{

  "keyVaultClient" : <object>,

  "keyVaultNamespace" : "<string>",

  "kmsProviders" : <object>,

  "schemaMap" : <object>,

  "bypassAutoEncryption" : <boolean>,

  "tlsOptions": <object>,

  "encryptedFieldsMap": <object>

}

The autoEncryptionOpts document takes the following parameters:

The api parameter specifies configuration options for theStable API. You can enable or disable optional behavior using the following options:

The api parameter has the following syntax:

{ api: { version: <string>, strict: <boolean>, deprecationErrors: <boolean> } }

The following operation creates a new connection object from within amongosh session:

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

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

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

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

Start the mongosh client.

To configure client-side field level encryption for a locally managed key, generate a base64-encoded 96-byte string with no line breaks.

const TEST_LOCAL_KEY = require("crypto").randomBytes(96).toString("base64")

Create the client-side field level encryption options using the generated local key string:

 var autoEncryptionOpts = {

   "keyVaultNamespace" : "encryption.__dataKeys",

   "kmsProviders" : {

     "local" : {

       "key" : BinData(0, TEST_LOCAL_KEY)

     }

   }

 }

Use the Mongo() constructor with the client-side field level encryption options configured to create a database connection. Replace the mongodb://myMongo.example.net URI with the connection string URI of the target cluster.

encryptedClient = Mongo(

  "mongodb://myMongo.example.net:27017/?replSetName=myMongo",

   autoEncryptionOpts

)

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

// 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.

To configure client-side field level encryption for a locally managed key:

• generate a base64-encoded 96-byte string with no line breaks
• use mongosh to load the key

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

mongosh --nodb

The following operation creates a new connection object from within amongosh session. TheAutoEncryptionOpts option specifies the required options for enabling automatic client-side encryption on the hr.employees collection:

var autoEncryptionOpts = {

  "keyVaultNamespace" : "encryption.__dataKeys",

  "kmsProviders" : {

    "local" : {

      "key" : BinData(0, process.env["TEST_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",

  autoEncryptionOpts

)

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

// 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 andtaxid-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.

The following operation creates a new connection object from within amongosh session. The mongo.tlsOptions option enables a connection using KMIP as the KMS provider:

var csfleConnection = {

  keyVaultNamespace: "encryption.__keyVault",

  kmsProviders: { kmip: { endpoint: "kmip.example.com:123" } },

  tlsOptions: { kmip: { tlsCertificateKeyFile: "/path/to/client/cert-and-key-bundle.pem" } }

}

cluster = Mongo(

  "mongodb://mymongo.example.net:27017/?replicaSet=myMongoCluster",

  csfleConnection

);

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

The following operation creates a new connection object from within amongosh session. The api option enables Stable API V1 and specifies that you cannot run deprecated command or commands outside of the Stable API.

cluster = Mongo(

  "mongodb://mymongo.example.net:27017/?replicaSet=myMongoCluster",

   null,

   { api: { version: "1", strict: true, deprecationErrors: true } }

)

To interact with the mymongo.example.net:27017 cluster, issue operations against the cluster object. For a full list of Stable API commands, see Stable API Commands.