db.createEncryptedCollection() (método mongosh)

Novidades na versão 7.0.

db.createEncryptedCollection(collName, options)

db.createEncryptedCollection() cria uma coleção criptografada especificada por collName no banco de dados atual.

Esse método é um wrapper em torno de ClientEncryption.createEncryptedCollection() que cria automaticamente chaves de dados se encryptedFields.fields[*].keyId for null ou for omitido na options.createCollectionOptions.encryptedFields definição.

Compatibilidade

Esse comando está disponível em implantações hospedadas nos seguintes ambientes:

MongoDB Atlas: o serviço totalmente gerenciado para implantações do MongoDB na nuvem

MongoDB Enterprise: a versão autogerenciada e baseada em assinatura do MongoDB
MongoDB Community: uma versão com código disponível, de uso gratuito e autogerenciada do MongoDB

Sintaxe

db.createEncryptedCollection() tem a seguinte sintaxe:

db.createEncryptedCollection(
   collName,
   {
      provider: kmsProviderName,
      createCollectionOptions: encryptedFieldsMap,
      masterKey: customerMasterKeyCredentials
   }
)

Campos de comando

db.createEncryptedCollection() usa estes campos:

Campo	Tipo	necessidade	Descrição
`collName`	string	Obrigatório	Nome da coleção a ser criptografada no banco de dados atual.
`options`	documento	Obrigatório	Opções para configurar a collection criptografada.
`options.provider`	string	Obrigatório	KMS que você está usando para armazenar sua chave mestra do cliente.
`options.createCollectionOptions`	documento	Obrigatório	Campos a serem criptografados. Deve conter um `encryptedFields` documento. Consulte Etapas para obter detalhes sobre como configurar o `encryptedFields` documento .
`options.masterKey`	documento	Opcional	Especifica as credenciais e os campos de identificação de chave necessários para acessar a chave mestre quando o provedor de KMS é AWS, GCP ou Azure. Opcional quando o provedor de KMS é `local`.

Comportamento

Os métodos de nível do campo no lado do cliente e Queryable Encryption do mongosh exigem uma conexão de banco de dados configurada para criptografia do lado do cliente. Se a conexão atual do banco de dados não tiver sido iniciada com a criptografia em nível de campo do lado do cliente ativada, faça o seguinte:

Utilize o construtor Mongo() do mongosh para estabelecer uma conexão com as opções de criptografia do nível do campo do lado do cliente exigido. O método Mongo() suporta os seguintes fornecedores de serviço de gerenciamento de chaves (KMS) para gerenciamento da chave mestra do cliente (CMK):

Utilize as opções da linha de comando do mongosh para estabelecer uma conexão com as opções exigidas. As opções de linha de comando são compatíveis apenas com o fornecedor Amazon Web Services KMS para gerenciamento da chave mestra do cliente.

Comportamento wrapper

O método é executado no contexto da db.createEncryptedCollection() atual db e usa a mesma conexão habilitada para Queryable Encryption que a mongosh sessão atual. Internamente, ele chama com o nome do banco de dados atual, o nome da coleção especificado e o documento de opções ClientEncryption.createEncryptedCollection() fornecido.

Quando options.createCollectionOptions.encryptedFields.fields[*].keyId é null ou omitido, o método cria automaticamente as chaves de dados necessárias no cofre de chaves e preenche os valores keyId correspondentes na definição encryptedFields da coleção criada.

Exemplo

O exemplo a seguir usa um KMS gerenciado localmente para a configuração de Queryable Encryption.

Crie sua conexão criptografada

Inicie o mongosh
Executar:
```
mongosh --nodb
```
--nodb significa não se conectar a um banco de dados de dados.
Gerar uma string de chave
Gere uma string base de 64 96bytes:
```
const TEST_LOCAL_KEY = require("crypto").randomBytes(96).toString("base64")
```

Criar um objeto de opções de criptografia

Para criar um objeto de opções de criptografia no nível do campo do lado do cliente , use a string TEST_LOCAL_KEY da etapa anterior:

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

Criar um objeto de cliente criptografado
Para criar um objeto de cliente criptografado, use o construtor Mongo() . Substitua o mongodb://myMongo.example.net URI pelo URI da string de conexão para o cluster de destino. Por exemplo:
```
encryptedClient = Mongo(
   "mongodb://myMongo.example.net:27017/?replSetName=myMongo",
   autoEncryptionOpts
)
```

Especifique quais campos criptografar

Crie um encryptedFieldsMap para especificar quais campos criptografar:

const encryptedFieldsMap = {
  encryptedFields: {
    fields: [
      {
        path: "secretField",
        bsonType: "string",
        queries: { queryType: "equality" },
        // keyId omitted; db.createEncryptedCollection() generates it
      },
    ],
  },
};

Crie sua coleção criptografada

Crie uma coleção enc.users criptografada usando o assistente no banco de dados atual:

const encDb = encryptedClient.getDB("enc");
let result = encDb.createEncryptedCollection(
  "users",
  {
    provider: "local",
    createCollectionOptions: encryptedFieldsMap,
    masterKey: {} // masterKey is optional when provider is local
  }
);

Verifique seu objeto de resultado

db.createEncryptedCollection() retorna um objeto de resultado que inclui o nome da coleção criada e a definição encryptedFields da coleção.

Verifique o valor de result.collection para confirmar que a collection foi criada no local desejado e, opcionalmente, inspecione o encryptedFields preenchido:

enc> result.collection
enc.users
enc> result.encryptedFields
{
  fields: [
    {
      path: "secretField",
      bsonType: "string",
      queries: { queryType: "equality", /* ... */ },
      keyId: UUID("...")
    }
  ]
}

Saiba mais

Para obter a documentação completa sobre como iniciar conexões do MongoDB com a criptografia no nível do campo do lado do cliente habilitada, consulte Mongo().
Para obter um exemplo completo de como criar e consultar uma collection criptografada, consulte Início Rápido da Queryable Encryption.

Voltar

db.createCollection

db.createView