Para agentes de IA: um índice de documentação está disponível em https://www.mongodb.com/pt-br/docs/llms.txt — as versões de markdown de todas as páginas estão disponíveis anexando .md a qualquer caminho de URL.
Menu Docs

ClientEncryption.encrypt() (método mongosh)

ClientEncryption.encrypt(keyId, value, algorithm or encOptions)

ClientEncryption.encrypt() encrypts the value using the specified keyId and the algorithm specified by algorithm or encOptions. encrypt() supports explicit (manual) encryption of field values.

Retorna:

Um objeto binary data com subtipo.6

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

clientEncryption = db.getMongo().getClientEncryption()
clientEncryption.encrypt(
keyId,
value,
algorithm or encOptions,
)
Parâmetro
Tipo
Descrição

keyId

UUID

A chave de criptografia de dados para utilizar para criptografar value.

The UUID is a BSON binary data object with subtype 4 that identifies a specific data encryption key. If the data encryption key does not exist in the key vault configured for the database connection, encrypt() returns an error. See Key Vault Collections for more information on key vaults and data encryption keys.

value

O valor a ser criptografado.

algorithm ou encOptions

string ou documento

  • Para criptografar campos explicitamente com criptografia no nível do campo do lado do cliente:

    Especifique o algorithm como uma string ou encOptions como um documento contendo o campo algorithm.

    Os algoritmos suportados são:

    • AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic

    • AEAD_AES_256_CBC_HMAC_SHA_512-Random

    Para obter exemplos, consulte Definir o algoritmo de criptografia no nível do campo do lado do cliente.

    Para obter a documentação completa sobre os algoritmos de criptografia suportados, consulte Campos e tipos de criptografia.

  • Para criptografar campos explicitamente com Queryable Encryption:

    Especifique o algorithm como uma string ou encOptions como um documento contendo os campos:

    • algorithm: o algoritmo de criptografia para criptografar o value. Os algoritmos suportados são:

      • Indexed

      • Unindexed

    • contentionFactor: obrigatório quando algorithm está definido como Indexed. Relacionado à frequência dos valores para este campo.

    • queryType: o único tipo de query suportado no momento é "equality". queryType deve ser definido quando o algoritmo não for Indexed.

    Para obter exemplos, consulte Definir o algoritmo de criptografia do Queryable Encryption.

    Para obter detalhes sobre os algoritmos de criptografia suportados, consulte Escolha do algoritmo.

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:

ou

You cannot use encrypt() to encrypt values with the following BSON types:

  • minKey

  • maxKey

  • null

  • undefined

If encrypting a field using AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic, encrypt() does not support the following BSON types:

  • double

  • decimal128

  • bool

  • object

  • array

O exemplo a seguir usa um KMS managed localmente para a configuração de criptografia no nível do campo do lado do cliente.

1
  1. Inicie o mongosh

    Executar:

    mongosh --nodb

    --nodb significa não se conectar a um banco de dados de dados.

  2. Gerar uma string de chave

    Gere uma string base de 64 96bytes:

    const TEST_LOCAL_KEY = require("crypto").randomBytes(96).toString("base64")
  3. 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)
    }
    }
    }
  4. 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
    )
2

Retrieve the ClientEncryption object and use the ClientEncryption.encrypt() method to encrypt a value using a specific data encryption key UUID and encryption algorithm:

clientEncryption = encryptedClient.getClientEncryption();
clientEncryption.encrypt(
UUID("64e2d87d-f168-493c-bbdf-a394535a2cb9"),
"123-45-6789",
"AEAD_AES_256_CBC_HMAC_SHA_512-Random"
)

Você também pode especificar o algoritmo usando um documento com um campo algorithm:

clientEncryption = encryptedClient.getClientEncryption();
clientEncryption.encrypt(
UUID("64e2d87d-f168-493c-bbdf-a394535a2cb9"),
"123-45-6789",
{ algorithm: "AEAD_AES_256_CBC_HMAC_SHA_512-Random" }
)

If successful, encrypt() returns the encrypted value:

BinData(6,"AmTi2H3xaEk8u9+jlFNaLLkC3Q/+kmwDbbWrq+h9nuv9W+u7A5a0UnpULBNZH+Q21fAztPpU09wpKPrju9dKfpN1Afpj1/ZhFcH6LYZOWSBBOAuUNjPLxMNSYOOuITuuYWo=")

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().

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

1
  1. Inicie o mongosh

    Inicie o cliente mongosh .

    mongosh --nodb
  2. Gere sua chave

    Para configurar a Queryable Encryption para uma chave gerenciada localmente, gere uma string64de bytes codificada de base 96sem quebras de linha.

    const TEST_LOCAL_KEY = require("crypto").randomBytes(96).toString("base64")
  3. Criar as opções de Queryable Encryption

    Crie as opções de Queryable Encryption usando a string de chave local gerada:

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

    Use o construtor Mongo() com as opções de Queryable Encryption 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
    )
2

Retrieve the ClientEncryption object and use the ClientEncryption.encrypt() method to encrypt a value using a specific data encryption key UUID and encryption algorithm:

const eDB = "encrypted"
const eKV = "__keyVault"
const clientEncryption = encryptedClient.getClientEncryption();
const keyVaultClient = Mongo().getDB(eDB).getCollection(eKV)
const dek = keyVaultClient.findOne({ keyAltNames: "dataKey1" })
clientEncryption.encrypt(
dek._id,
"123-45-6789",
"Unindexed"
)

Você também pode especificar o algoritmo usando um documento contendo os campos:

  • algorithm

  • queryType

  • contentionFactor

const eDB = "encrypted"
const eKV = "__keyVault"
const clientEncryption = encryptedClient.getClientEncryption();
const keyVaultClient = Mongo().getDB(eDB).getCollection(eKV)
const dek = keyVaultClient.findOne({ keyAltNames: "dataKey1" })
clientEncryption.encrypt(
dek._id,
"123-45-6789",
{
algorithm: "Indexed",
queryType: "equality",
contentionFactor: 4
}
)

If successful, encrypt() returns the encrypted value:

Binary(Buffer.from("05b100000005640020000000005ab3581a43e39a8e855b1ac87013e841735c09d19ae86535eea718dd56122ba50573002000000000703d2cba9832d90436c6c92eb232aa5b968cdcd7a3138570bc87ef0a9eb3a0e905630020000000009cb61df010b1bb54670a5ad979f25f4c48889059dfd8920782cf03dd27d1a50b05650020000000003f5acea703ea357d3eea4c6a5b19139a580089341424a247839fd4d5cf0d312a12636d00040000000000000000", "hex"), 6)

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().