Mongo() (método mongosh)

Descripción

Mongo(host, autoEncryptionOpts, api)

Constructor de JavaScript para instanciar una conexión a la base de datos desde o desde un archivo mongosh JavaScript.

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

Parameter	Tipo	Descripción
`host`	string o instancia de `Mongo`	opcional. Host o cadena de conexión. El host puede ser una cadena de conexión o tener el `<host>` formato `<host><:port>` o. La cadena de conexión puede tener el formato de una `Mongo` instancia. Si especifica una `Mongo` instancia, el constructor utiliza la cadena de conexión de la instancia de Mongo `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 la encriptación 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 sobre el uso y la sintaxis.
`api`	Documento	opcional. Opciones de configuración para activar la Stable API. `api` Consulte para obtener detalles sobre el uso y la 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 documento autoEncryptionOpts especifica las opciones de configuración para encriptación en uso. Si tu conexión a la base de datos tiene una configuración de encriptación en uso existente, autoEncryptionOpts la reemplaza. MongoDB proporciona dos enfoques para la encriptación en uso: Cifrado de nivel de campo del lado del cliente y Queryable Encryption.

Por ejemplo, al comenzar mongosh con opciones de línea de comandos de cifrado 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 Mongo() autoEncryptionOptsa menos que 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 de MongoDB que aloja la Colección de Bóvedas de Llaves.

Especifique 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, se utiliza el host especificado para el objeto que contiene Mongo() el autoEncryptionOpts documento como host de la bóveda de claves.

keyVaultNamespace

string

(Obligatorio) El namespace completo de la colección del almacén de claves.

kmsProviders

Documento

(Obligatorio) El Servicio de Gestión de Claves (KMS) utilizado por el cifrado a nivel de campo del lado del cliente para gestionar una llave maestra de cliente (llave maestra de cliente). El cifrado a nivel de campo del lado del cliente utiliza la llave maestra de cliente 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 método para cada KMS compatible.

Amazon Web Services KMS

IMPORTANTE: Para obtener compatibilidad con AWS KMS, utilice mongosh o la 4 22 consola heredada de MongoDB.. o mongo posterior. Las 4 20 421 consolas heredadas.. y..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 obtener 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 IAM con todos los permisos List y Read para el servicio KMS.

En algunos entornos, el AWS SDK puede obtener credenciales automáticamente. Para habilitar el uso de AWS KMS sin proporcionar credenciales explícitas al AWS SDK, puedes pasar los detalles de kmsProvider al constructor de 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 para kmsProviders con el siguiente campo:

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

El key especificado debe ser una string de 96bytes codificada en base64sin caracteres de nueva línea.

schemaMap

Documento

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

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

bypassAutoEncryption

booleano

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

bypassQueryAnalysis

booleano

(Opcional) Especifique true para utilizar cifrado explícito en campos indexados sin la librería crypt_shared. Para obtener más detalles, consulte las Opciones de MongoClient para Queryable Encryption.

explicitEncryptionOnly

booleano

(Opcional) Especifica true para no usar ni el cifrado automático ni el descifrado automático. Puedes usar getKeyVault() y getClientEncryption() para realizar un cifrado explícito. Esta opción es mutuamente excluyente con schemaMap. Si se omite, por defecto false.

tlsOptions

Objeto

(Opcional) La ruta al certificado de cliente TLS y al archivo de llave privada en formato PEM (tlsCertificateKeyFile), la contraseña del certificado de cliente TLS y del archivo de llave privada (tlsCertificateKeyFilePassword), o el archivo de autoridad de certificación TLS (tlsCAFile) para conectarse al KMS en formato PEM. Para obtener más información sobre estas opciones, consulta Opciones de TLS.

encryptedFieldsMap

Documento

(Opcional) El mapa de namespaces de colección a documentos encryptedFields. encryptedFields es un documento BSON que describe los campos cifrados de Queryable Encryption. Si una colección está presente tanto en el schemaMap como en el encryptedFieldsMap, libmongocrypt errores en la inicialización.

Para obtener más información sobre los campos cifrados en Queryable Encryption, consulta Campos cifrados y consultas habilitadas.

`api`

El parámetro api especifica las opciones de configuración para la Stable API. Puede habilitar o deshabilitar comportamientos opcionales utilizando las siguientes opciones:

Opción	Tipo	Descripción
`version`	string	Especifica la versión de la API. Actualmente, `"1"` es la única versión soportada.
`strict`	booleano	En caso de que `true`: El uso de un comando que no forma parte de la versión declarada de la API devuelve un error APIStrictError. El planificador de query ignora los índices no compatibles con la Stable API. Si especificas `strict`, también debes especificar `version`. Si no se especifica, el valor por defecto es `false`.
`deprecationErrors`	booleano	Si `true`, usar un comando o comportamiento que está obsoleto en la versión de API especificada devuelve un APIDeprecationError. Si especifica `deprecationErrors`, también debe especificar `version`. Si no se especifica, el valor por defecto es `false`.

El parámetro api tiene la siguiente sintaxis:

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

Ejemplos

Conéctate a un clúster de MongoDB

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

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

Emite 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

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

Inicia mongosh

Inicie el cliente mongosh.

mongosh --nodb

Genere su clave

Para configurar el cifrado a nivel de campo del lado del cliente para una clave gestionada localmente, genera una string de 96 bytes codificada en base64 sin saltos de línea.

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

Crea 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 usando la string de clave local generada:

 let 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 nivel de campo del lado del cliente configuradas para crear una conexión a la base de datos. Reemplace Mongo() la mongodb://myMongo.example.net URI con la URI de la cadena de conexión del clúster de destino.

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

Ejecute operaciones sobre 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();

Consulta encriptación 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 en el lado del cliente con una clave gestionada localmente:

genera 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 dentro de 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 campos taxid y taxid-short utilizando la llave de cifrado de datos y el algoritmo especificados. Solo los clientes configurados para el KMS correcto y que tengan acceso a la llave de cifrado de datos especificada pueden descifrar el campo.

La siguiente operación crea un nuevo objeto de conexión dentro de una sesión.mongosh La mongo.tlsOptions opción habilita una conexión utilizando KMIP como proveedor 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
);

Consulta encriptación 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 la Stable API habilitada.

La siguiente operación crea un nuevo objeto de conexión dentro de una sesiónmongosh. La opciónapihabilita la API estable V1 y especifica que no se pueden ejecutar comandos obsoletos fuera de la API estable.

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

Para interactuar con el clúster mymongo.example.net:27017, realiza operaciones sobre el objeto cluster. Para ver una lista completa de órdenes de Stable API, consulta Órdenes de Stable API.

Volver

Conectar

Mongo.getDB