Mongo()

Nesta página

Descrição

AutoEncryptionOpts
api
Exemplos
Conecte-se a um MongoDB Cluster
Conecte-se a cluster que tenha a criptografia do lado do cliente habilitada
Conecte-se a um cluster com a criptografia automática do lado do cliente habilitada
Conectar-se a um cluster com a Stable API habilitada

Descrição

Mongo(host, autoEncryptionOpts, api)

Construtor JavaScript para instanciar uma conexão de banco de dados a partir do mongosh ou de um arquivo JavaScript.

O método Mongo() tem os seguintes parâmetros:

Parâmetro	Tipo	Descrição
`host`	string ou instância `Mongo`	Opcional. Host ou string de conexão. O host pode ser uma connection string ou na forma de `<host>` ou `<host><:port>`. A connection string pode estar na forma de uma instância `Mongo` . Se você especificar uma instância `Mongo`, o construtor `Mongo()` utilizará a connection string da instância mongo especificada. Se omitido, o `Mongo()` instancia uma conexão com a interface do localhost na porta `27017` padrão.
`autoEncryptionOpts`	documento	Opcional. Parâmetros de configuração para ativar criptografia de nível de campo do lado do cliente. `autoEncryptionOpts` substitui a configuração de criptografia de nível de campo do lado do cliente existente da conexão do banco de dados. Se omitido, o `Mongo()` herda a configuração de criptografia do nível de campo do lado do cliente da conexão do banco de dados atual. Consulte `AutoEncryptionOpts` para obter detalhes de uso e sintaxe.
`api`	documento	Opcional. Opções de configuração para ativar a API Stable. Consulte `api` para obter detalhes de uso e sintaxe.

Dica

Veja também:

Mongo.getDB() e a db.getMongo()

`AutoEncryptionOpts`

O documento autoEncryptionOpts especifica as opções de configuração para Criptografia no nível do campo do lado do cliente. Se a conexão do banco de dados tiver uma configuração de criptografia no nível do campo no lado do cliente já existente, a especificação de autoEncryptionOpts substitui essa configuração.

Por exemplo, iniciar mongosh com opções de linha de comando de criptografia em nível de campo do lado do cliente habilita a criptografia do lado do cliente para essa conexão. Novas conexões de banco de dados criadas usando Mongo() herdam as configurações de criptografia, a menos que Mongo() inclua autoEncryptionOpts.

O documento autoEncryptionOpts tem a seguinte sintaxe:

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

O documento autoEncryptionOpts recebe os seguintes parâmetros:

Parâmetro

Tipo

Descrição

keyVaultClient

Mongo() objeto de conexão.

(Opcional) O MongoDB cluster hospedando a coleção de cofre de chaves.

Especifique um objeto de conexão Mongo() apontando para o cluster:

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

Se keyVaultClient for omitido, o host especificado para o objeto Mongo() que contém o documento autoEncryptionOpts será utilizado como o host do key vault.

keyVaultNamespace

string

(Obrigatório) O namespace completo da coleção de cofre de chaves.

kmsProviders

documento

(Obrigatório) O Serviço de Gerenciamento de Chaves (KMS, na sigla em inglês) usado pela criptografia no nível do campo do lado do cliente para gerenciar uma Chave Mestra do Cliente (CMK, na sigla em inglês). A criptografia criptografia no nível do campo do lado do cliente usa a CMK para criptografar e descriptografar chaves de criptografia de dados.

A criptografia no nível do campo do lado do cliente oferece suporte aos seguintes provedores de KMS:

Se possível, considere a possibilidade de definir as credenciais disponibilizadas no kmsProviders como variáveis de ambiente e, em seguida, passá-las para mongosh utilizando a opção --eval. Isso minimiza as chances de vazamento de credenciais em logs. Consulte Como criar uma chave de dados para ver exemplos dessa abordagem para cada KMS compatível.

KMS do Amazon Web Services

IMPORTANTE: para suporte ao AWS KMS, use mongosh ou o MongoDB 4.2.2 ou mongo shell legado posterior.4 2O . .0 e 4.2.1 legado mongo não é compatível com o serviço AWS KMS devido a uma alteração inesperada no objeto de resposta KMS. Consulte SERVER-44721 para mais informações.

Especifique o documento aws para kmsProviders com os seguintes campos:

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

O accessKeyId especificado deve corresponder a um usuário do IAM com todas as permissões List e Read para o serviço KMS.

Em alguns ambientes, o Amazon Web Services SDK pode coletar credenciais automaticamente. Para habilitar o uso Amazon Web Services KMS sem fornecer credenciais explícitas para o Amazon Web Services SDK, você pode passar os detalhes do kmsProvider para o construtor do Mongo().

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

Azure Key Vault

Especifique o documento azure para kmsProviders com os seguintes campos:

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

Novidades na versão 5.0.

KMS do Google Cloud

Especifique o documento gcp para kmsProviders com os seguintes campos:

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

Novidades na versão 5.0.

Chave gerenciada localmente

Especifique o documento local para kmsProviders com o seguinte campo:

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

O key especificado deve ser uma string de 96 bytes codificada em base-64 sem caracteres newline.

schemaMap

documento

4 Opcional) As regras automáticas de criptografia no nível do campo do lado do cliente especificadas usando a sintaxe padrão do JSON schema e as palavras-chave específicas da criptografia. Esta opção é mutuamente exclusiva com explicitEncryptionOnly.

Para obter a documentação completa, consulte Esquemas de criptografia.

bypassAutoEncryption

booleano

(Opcional) Especifique true para ignorar as regras automáticas de criptografia em nível de campo do lado do cliente e realizar criptografia explícita (manual) por campo.

bypassQueryAnalysis

booleano

(Opcional) Especifique true para usar criptografia explícita em campos indexados sem a biblioteca crypt_shared. Para obter detalhes, consulte Opções do MongoClient para Queryable Encryption.

explicitEncryptionOnly

booleano

(Opcional) Especifique true para não usar criptografia nem descriptografia automáticas. Você pode utilizar getKeyVault() e getClientEncryption() para executar criptografia explícita. Esta opção é mutuamente exclusiva com schemaMap. Se omitido, o padrão é false.

tlsOptions

objeto

(Opcional) O caminho para o certificado do cliente TLS e o arquivo de chave privada no formato PEM (tlsCertificateKeyFile), do certificado de cliente TLS e da senha do arquivo de chave privada (tlsCertificateKeyFilePassword) ou do arquivo de autoridade de certificação TLS (tlsCAFile) para usar para conecte-se ao KMS no formato PEM. Para saber mais sobre essas opções, consulte Opções de TLS.

`api`

O parâmetro api especifica opções de configuração para a Stable API. É possível habilitar ou desabilitar o comportamento opcional usando as seguintes opções:

Opção	Tipo	Descrição
`version`	string	Especifica a versão da API. `"1"` é atualmente a única versão suportada.
`strict`	booleano	Se `true`: Usar um comando que não faz parte da versão declarada da API retorna um erro APIStrictError . Os índices que não são suportados pela Stable API são ignorados pelo planejador de query. Se você especificar `strict`, você também deverá especificar `version`. Se não for especificado, o padrão será `false`.
`deprecationErrors`	booleano	Se `true`, o uso de um comando ou comportamento que está obsoleto na versão da API especificada retornará um APIDeprecationError. Se você especificar `deprecationErrors`, também deverá especificar a `version`. Se não for especificado, o padrão será `false`.

O parâmetro api tem a seguinte sintaxe:

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

Exemplos

Conecte-se a um MongoDB Cluster

A operação a seguir cria um novo objeto de conexão a partir de uma sessão mongosh:

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

Execute operações no objeto cluster para interagir com o cluster mymongo.example.net:27017:

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

Conecte-se a cluster que tenha a criptografia do lado do cliente habilitada

Inicie o mongosh

Inicie o cliente mongosh .

mongosh --nodb

Gere sua chave

Para configurar a criptografia no nível do campo do lado do cliente para uma chave managed localmente, gere uma cadeia de 96 bytes codificada em base64 sem quebras de linha.

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

Criar as opções de criptografia em nível de campo do lado do cliente

Crie as opções de criptografia no nível do campo do lado do cliente usando a string de chave local gerada:

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

Crie seu cliente criptografado

Use o construtor Mongo() com as opções de criptografia no nível do campo do lado do cliente configuradas para criar uma conexão com o banco de dados. Substitua o URI do mongodb://myMongo.example.net pelo URI da string de conexão do cluster de destino.

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

Execute operações no objeto cluster para interagir com o cluster mymongo.example.net:27017 e realizar criptografia explícita:

// 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 Métodos de criptografia no nível de campo do lado do cliente para obter uma lista completa dos métodos de criptografia no nível do campo do lado do cliente.

Conecte-se a um cluster com a criptografia automática do lado do cliente habilitada

Para configurar a criptografia no nível do campo do lado do cliente para uma chave gerenciada localmente:

gerar uma string de 96 bytes codificada em base 64sem quebras de linha
use mongosh para carregar a chave

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

A operação a seguir cria um novo objeto de conexão em uma sessão mongosh. A opção AutoEncryptionOpts especifica as opções necessárias para ativar a criptografia automática do lado do cliente na coleção hr.employees:

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
)

Execute operações no objeto cluster para interagir com o cluster mymongo.example.net:27017 e utilizar a criptografia automática:

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

As regras de criptografia automática especificadas criptografam os campos taxid e taxid-short usando a chave de criptografia de dados e o algoritmo especificados. Somente os clientes configurados para o KMS correto e acesso à chave de criptografia de dados especificada podem descriptografar o campo.

A operação a seguir cria um novo objeto de conexão a partir de uma sessão mongosh . A opção mongo.tlsOptions habilita uma conexão utilizando KMIP como o provedor 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 Métodos de criptografia no nível de campo do lado do cliente para obter uma lista completa dos métodos de criptografia no nível do campo do lado do cliente.

Conectar-se a um cluster com a Stable API habilitada

A operação a seguir cria um novo objeto de conexão em uma sessão mongosh. A opção api ativa a API estável V1 e especifica que você não pode executar comandos ou comandos obsoletos fora da API estável.

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

Para interagir com o cluster mymongo.example.net:27017, execute operações no objeto cluster. Caso deseje ver uma lista completa dos comandos da Stable API, consulte a página Comandos da Stable API.

Voltar

Conecte

Mongo.getDB