Menu Docs

Página inicial do Docs → Desenvolver aplicações → Manual do MongoDB

ClientEncryption.encrypt()

Nesta página

  • Comportamento
  • Exemplo

Novidades na versão 4.2.

ClientEncryption.encrypt(encryptionKeyId, value, encryptionAlgorithm)

ClientEncryption.encrypt() criptografa value usando o encryptionKeyId e encryptionAlgorithm especificados. encrypt() suporta criptografia explícita (manual) de valores de campo.

encrypt() tem a seguinte sintaxe:

clientEncryption = db.getMongo().getClientEncryption()
clientEncryption.encrypt(
  encryptionKeyId,
  value,
  encryptionAlgorithm
)
Parâmetro
Tipo
Descrição
encryptionKeyId
UUID

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

O UUID é um objeto BSON binary data com subtipo 4 que identifica uma chave de criptografia de dados específica. Se a chave de criptografia de dados não existir no cofre de chave configurado para a conexão do banco de dados, encrypt() retornará um erro. Consulte Encryption Key Vault para obter mais informações sobre cofres de chaves e chaves de criptografia de dados.

value
Consulte Tipos de JSON não suportados.
O valor a ser criptografado.
encryptionAlgorithm
string

O algoritmo de criptografia para criptografar o value.

  • AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic

  • AEAD_AES_256_CBC_HMAC_SHA_512-Random

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

Retorna:Um binary data objeto com subtipo 6.

Comportamento

Habilite criptografia no nível do campo do lado do cliente na conexão do banco de dados

Os métodos de criptografia de nível de campo do lado do cliente mongo exigem uma conexão de reconhecimento de data center com a criptografia de nível de campo do lado do cliente habilitada. Se o reconhecimento de data center atual não foi iniciado com a criptografia de nível de campo do lado do cliente habilitada:

Tipos de BSON não suportados

encrypt() não suporta valores de criptografia com os seguintes tipos de BSON:

  • minKey

  • maxKey

  • null

  • undefined

Se criptografar um campo com AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic, encrypt() não suportará os seguintes tipos de BSON:

  • double

  • decimal128

  • bool

  • object

  • array

Exemplo

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

A configuração da criptografia em nível de campo do lado do cliente para uma chave managed localmente requer a especificação de uma cadeia de 96 bytes codificada em base64 sem quebras de linha. A operação a seguir gera uma chave que atende aos requisitos declarados e a carrega no shell mongo :

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

Crie o objeto de criptografia no nível do campo do lado do cliente usando a string de chave local gerada:

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

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

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

Recupere o objeto ClientEncryption e utilize o método ClientEncryption.encrypt() para criptografar um valor com uma chave de criptografia de dados UUID específica e o algoritmo de criptografia:

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

Se bem-sucedido, encrypt() retorna o valor codificado:

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

← getClientEncryption()
ClientEncryption.decrypt() →

Nesta página