Mongo() (método mongosh)

Descripción

Mongo(host, autoEncryptionOpts, api)

Constructor de JavaScript para crear una instancia de una conexión de base de datos desde mongosh o desde un archivo JavaScript.

El método Mongo() tiene los siguientes parámetros:

Parameter	Tipo	Descripción
`host`	cadena o instancia `Mongo`	Opcional. Host o cadena de conexión. El host puede ser una cadena de conexión o tener el formato `<host>` o `<host><:port>`. La cadena de conexión puede tener el formato de una instancia `Mongo`. Si especifica una instancia `Mongo`, `Mongo()` El constructor utiliza la cadena de conexión de la instancia de Mongo especificada. Si se omite, instancia una conexión a la interfaz localhost en el`Mongo()` puerto `27017` predeterminado.
`autoEncryptionOpts`	Documento	Opcional. Parámetros de configuración para habilitar el cifrado en uso. `autoEncryptionOpts` Anula la configuración de cifrado en uso de la conexión a la base de datos. Si se omite, `Mongo()` hereda la configuración de cifrado en uso de la conexión a la base de datos actual. `AutoEncryptionOpts` Consulte para obtener detalles de uso y sintaxis.
`api`	Documento	Opcional.Opciones de configuración para habilitar la API estable. `api` Consulte para obtener detalles de uso y sintaxis.

Tip

Mongo.getDB() y db.getMongo()

Compatibilidad

Este método está disponible en implementaciones alojadas en los siguientes entornos:

MongoDB Atlas: El servicio totalmente gestionado para implementaciones de MongoDB en la nube

MongoDB Enterprise: La versión basada en suscripción y autogestionada de MongoDB
MongoDB Community: La versión de MongoDB con código fuente disponible, de uso gratuito y autogestionada.

`AutoEncryptionOpts`

El autoEncryptionOpts documento especifica las opciones de configuración para el cifrado en uso. Si su conexión a la base de datos ya tiene una configuración de cifrado en uso, laautoEncryptionOpts anula. MongoDB ofrece dos enfoques para el cifrado en uso: cifrado a nivel de campo del lado del cliente y cifrado consultable.

Por ejemplo, al iniciar mongosh con las opciones de línea de comandos de cifrado a nivel de campo del lado del cliente, se habilita el cifrado del lado del cliente para esa conexión. Las nuevas conexiones de base de datos creadas con Mongo() heredan la configuración de cifrado,a menos Mongo() que autoEncryptionOpts incluya.

El documento autoEncryptionOpts tiene la siguiente sintaxis:

{
  "keyVaultClient" : <object>,
  "keyVaultNamespace" : "<string>",
  "kmsProviders" : <object>,
  "schemaMap" : <object>,
  "bypassAutoEncryption" : <boolean>,
  "tlsOptions": <object>,
  "encryptedFieldsMap": <object>
}

El documento autoEncryptionOpts toma los siguientes parámetros:

Parameter

Tipo

Descripción

keyVaultClient

Mongo() objeto de conexión.

(Opcional) El clúster MongoDB que aloja la colección de bóveda de claves.

Especifica un Mongo() objeto de conexión que apunte al clúster:

var keyVaultClient = Mongo(<MongoDB URI>);
var autoEncryptionOptions = {
  "keyVaultClient" : keyVaultClient,
  "keyVaultNamespace" : "<database>.<collection>",
  "kmsProviders" : { ... }
}

Si keyVaultClient se omite, el host especificado para el objeto que contiene Mongo() el autoEncryptionOpts documento se utiliza como host del almacén de claves.

keyVaultNamespace

string

(Obligatorio) El espacio de nombres completo de la colección de bóveda de claves.

kmsProviders

Documento

(Obligatorio) El Servicio de Gestión de Claves (KMS) que utiliza el cifrado de campo del lado del cliente para gestionar una Clave Maestra de Cliente (CMK). El cifrado de campo del lado del cliente utiliza la CMK para cifrar y descifrar las claves de cifrado de datos.

La encriptación a nivel de campo del lado del cliente admite los siguientes proveedores de KMS:

Si es posible, considere definir las credenciales proporcionadas en kmsProviders como variables de entorno y luego pasarlas a mongosh mediante la opción. Esto minimiza --eval la posibilidad de que las credenciales se filtren en los registros. Consulte Crear una clave de datos para ver ejemplos de este enfoque para cada KMS compatible.

Amazon Web Services KMS

IMPORTANTE: Para la compatibilidad con mongosh AWS KMS, utilice o el 4.2.2 shell heredado de MongoDB o mongo posterior. Los shells 4 heredados,,2 0 y,4 2y1 mongo no son compatibles con el servicio AWS KMS debido a un cambio inesperado en el objeto de respuesta de KMS.Consulte SERVER-44721 Para más información.

Especifique el documento aws a kmsProviders con los siguientes campos:

"kmsProviders" : {
   "aws" : {
     "accessKeyId" : "AWSAccessKeyId",
     "secretAccessKey" : "AWSSecretAccessKey"
   }
 }

El accessKeyId especificado debe corresponder a un usuario de IAM con todos los permisos List y Read para el servicio KMS.

En algunos entornos, el SDK de AWS puede obtener credenciales automáticamente. Para habilitar el uso de AWS KMS sin proporcionar credenciales explícitas al SDK de AWS, puede pasar los detalles kmsProvider al constructor Mongo().

{
  "kmsProviders" : { "aws" : { } }
}

Azure Key Vault

Especifique el documento azure a kmsProviders con los siguientes campos:

"kmsProviders" : {
  "azure" : {
    "tenantId" : "AzureTenantId",
    "clientId" : "AzureClientId",
    "clientSecret" : "AzureClientSecret"
  }
}

Nuevo en la versión 5.0.

Google Cloud KMS

Especifique el documento gcp a kmsProviders con los siguientes campos:

"kmsProviders" : {
  "gcp" : {
    "email" : "GCPEmail",
    "privateKey" : "GCPPrivateKey"
  }
}

Nuevo en la versión 5.0.

Clave gestionada localmente

Especifique el documento local a kmsProviders con el siguiente campo:

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

El especificado key debe ser una64 96cadena de bytes codificada en base sin caracteres de nueva línea.

schemaMap

Documento

(Opcional) Las reglas de cifrado automático a nivel de campo del lado del 4 cliente, especificadas mediante la sintaxis estándar del borrador del esquema JSON y palabras clave específicas de cifrado. Esta opción es mutuamente excluyente explicitEncryptionOnly con. Si hay una colección presente tanto en schemaMap como encryptedFieldsMap en, libmongocrypt genera un error al inicializar.

Para ver la documentación completa, consulta Esquemas de cifrado.

bypassAutoEncryption

booleano

(Opcional) Especifique true para omitir las reglas de cifrado automático a nivel de campo del lado del cliente y realizar un cifrado explícito (manual) por campo.

bypassQueryAnalysis

booleano

(Opcional) Especifique true para usar cifrado explícito en campos indexados sin la crypt_shared biblioteca. Para más información,consulte Opciones de MongoClient para cifrado consultable.

explicitEncryptionOnly

booleano

(Opcional) Especifique true para no usar ni cifrado ni descifrado automáticos. Puede usar getKeyVault() y para realizar cifrado explícito. Esta opción es mutuamente getClientEncryption() excluyente schemaMap con. Si se omite, el valor false predeterminado es.

tlsOptions

Objeto

(Opcional) La ruta al certificado de cliente TLS y al archivo de clave privada en formato PEMtlsCertificateKeyFile (), la contraseña del certificado de cliente TLS y del archivo de clave privadatlsCertificateKeyFilePassword () o el archivo de la autoridad de certificación TLS ()tlsCAFile que se usará para conectarse al KMS en formato PEM. Para obtener más información sobre estas opciones, consulte Opciones TLS.

encryptedFieldsMap

Documento

(Opcional) La asignación de espacios de nombres de colección a encryptedFields documentos. encryptedFields es un documento BSON que describe los campos cifrados de Queryable Encryption. Si una colección está presente tanto en schemaMap como encryptedFieldsMap en, libmongocrypt genera errores al inicializarse.

Para obtener más información sobre los campos cifrados en el cifrado consultable, consulte Campos cifrados y consultas habilitadas.

`api`

El api parámetro especifica las opciones de configuración de la API estable. Puede habilitar o deshabilitar el comportamiento opcional mediante las siguientes opciones:

Opción	Tipo	Descripción
`version`	string	Especifica la versión de la API. `"1"` es actualmente la única versión compatible.
`strict`	booleano	Si `true`: El uso de un comando que no es parte de la versión de API declarada devuelve un error APIStrictError. El planificador de consultas ignora losíndices que no son compatibles con la API estable. Si especifica `strict`, también debe especificar `version`. Si no se especifica, el valor predeterminado es `false`.
`deprecationErrors`	booleano	Si `true` es, al usar un comando o comportamiento obsoleto en la versión de API especificada, se devuelve un error APIDeprecationError. Si `deprecationErrors` especifica, también debe `version` especificar. Si no se especifica, el valor predeterminado es `false`.

El parámetro api tiene la siguiente sintaxis:

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

Ejemplos

Conectarse a un clúster de MongoDB

La siguiente operación crea un nuevo objeto de conexión desde dentro de una mongosh sesión:

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

Emita operaciones contra el objeto cluster para interactuar con el clúster mymongo.example.net:27017:

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

Conectarse a un clúster con cifrado del lado del cliente habilitado

Iniciar mongosh

Inicie el cliente mongosh.

mongosh --nodb

Genera tu clave

Para configurar el cifrado a nivel de campo del lado del cliente para una clave administrada localmente, genere una cadena de 96bytes codificada en base64sin saltos de línea.

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

Crear las opciones de cifrado a nivel de campo del lado del cliente

Cree las opciones de cifrado a nivel de campo del lado del cliente utilizando la cadena de clave local generada:

 var autoEncryptionOpts = {
   "keyVaultNamespace" : "encryption.__dataKeys",
   "kmsProviders" : {
     "local" : {
       "key" : BinData(0, TEST_LOCAL_KEY)
     }
   }
 }

Crea tu cliente cifrado

Utilice el constructor con las opciones de cifrado de campo del lado del cliente configuradas para crear una conexión a la base de datos. Reemplace Mongo() el mongodb://myMongo.example.net URI por el URI de la cadena de conexión del clúster de destino.

encryptedClient = Mongo(
  "mongodb://myMongo.example.net:27017/?replSetName=myMongo",
   autoEncryptionOpts
)

Emita operaciones contra el objeto cluster para interactuar con el clúster mymongo.example.net:27017 y realizar un cifrado explícito:

// 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();

Consulte Cifrado en uso para obtener una lista completa de los métodos de cifrado a nivel de campo del lado del cliente.

Conéctate a un clúster con cifrado del lado del cliente automático habilitado

Para configurar el cifrado a nivel de campo del lado del cliente para una clave administrada localmente:

generar una cadena de 96bytes codificada en base64sin saltos de línea
use para cargar la mongosh clave

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

La siguiente operación crea un nuevo objeto de conexión desde una mongosh sesión. La opción especifica las AutoEncryptionOpts opciones necesarias para habilitar el cifrado automático del lado del hr.employees cliente en la colección:

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
)

Emite operaciones contra el objeto cluster para interactuar con el clúster mymongo.example.net:27017 y utilizar el cifrado automático:

// 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"
  }
)

Las reglas de cifrado automático especificadas cifran los taxid campos taxid-short y utilizando la clave y el algoritmo de cifrado de datos especificados. Solo los clientes configurados para el KMS correcto y con acceso a la clave de cifrado de datos especificada pueden descifrar el campo.

La siguiente operación crea un nuevo objeto de conexión desde una sesión.mongosh La mongo.tlsOptions opción habilita una conexión usando KMIP como proveedor de KMS:

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
);

Consulte Cifrado en uso para obtener una lista completa de los métodos de cifrado a nivel de campo del lado del cliente.

Conectarse a un clúster con la API estable habilitada

La siguiente operación crea un nuevo objeto de conexión desde dentro de una mongosh sesión. La opción api habilita la Stable API v1 y especifica que no se puede ejecutar ningún comando obsoleto ni ningún comando fuera de la Stable API.

cluster = Mongo(
  "mongodb://mymongo.example.net:27017/?replicaSet=myMongoCluster",
   null,
   { api: { version: "1", strict: true, deprecationErrors: true } }
)

Para interactuar con el mymongo.example.net:27017 clúster, ejecute operaciones contra el cluster objeto. Para obtener una lista completa de los comandos de la API estable, consulte Comandos de la API estable.

Volver

Conectar

Mongo.getDB