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.

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

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 documento `encryptedFields`. Consulte Etapas para obter detalhes sobre como configurar o documento `encryptedFields`.
`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

The mongosh client-side field level and queryable encryption methods require a database connection configured for client-side encryption. If the current database connection was not initiated with client-side field level encryption enabled, either:

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 provedor Amazon Web Services KMS para gerenciamento da chave mestra do cliente.

Comportamento wrapper

The db.createEncryptedCollection() method runs in the context of the current db and uses the same Queryable Encryption-enabled connection as the current mongosh session. Internally, it calls ClientEncryption.createEncryptedCollection() with the current database name, the specified collection name, and the provided options document.

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 coleção foi criada na localização desejada 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