ClientEncryption.encrypt() (método mongosh)

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

ClientEncryption.encrypt() encripta el value usando el keyId especificado y el algoritmo especificado por algorithm o encOptions. encrypt() admite el cifrado explícito (manual) de los valores de los campos.

Devuelve:	A `binary data` objeto con subtipo 6.

Compatibilidad

Este comando está disponible en implementaciones alojadas en los siguientes entornos:

MongoDB Atlas: El servicio totalmente gestionado para implementaciones de MongoDB en la nube

MongoDB Enterprise: La versión basada en suscripción y autogestionada de MongoDB
MongoDB Community: La versión de MongoDB con código fuente disponible, de uso gratuito y autogestionada.

Sintaxis

clientEncryption = db.getMongo().getClientEncryption()
clientEncryption.encrypt(
  keyId,
  value,
  algorithm or encOptions,
)

Parameter	Tipo	Descripción
`keyId`	`UUID`	La clave de cifrado de datos que se utilizará para cifrar el `value`. La UUID es un objeto BSON `binary data` con subtipo `4` que identifica una clave de cifrado de datos específica. Si la clave de cifrado de datos no existe en el almacén de claves configurado para la conexión a la base de datos, `encrypt()` devuelve un error. Consulte Colección de Bóvedas de Llaves para obtener más información sobre Key Vaults y llaves de cifrado de datos.
`value`	Ver Tipos BSON no compatibles.	El valor a cifrar.
`algorithm` or `encOptions`	string o documento	Para cifrar explícitamente campos con Cifrado a nivel de campo del lado del cliente: Especifica el `algorithm` como una string o `encOptions` como un documento que contenga el campo `algorithm`. Los algoritmos soportados son: `AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic` `AEAD_AES_256_CBC_HMAC_SHA_512-Random` Para ver ejemplos, consulta Configura el algoritmo de cifrado a nivel de campo en el lado del cliente. Para la documentación completa sobre los algoritmos de cifrado admitidos, consulta Campos y tipos de cifrado. Para encriptar explícitamente campos usando Queryable Encryption: Especifica el `algorithm` como una string o `encOptions` como un documento que contenga los campos: `algorithm`: El algoritmo de cifrado que se utiliza para cifrar el `value`. Los algoritmos compatibles son: `Indexed` `Unindexed` `contentionFactor`Obligatorio cuando `algorithm` se establece en `Indexed`. Relacionado con la frecuencia de los valores de este campo. `queryType`:El único tipo de consulta admitido actualmente es `"equality"`. `queryType` debe configurarse cuando el algoritmo no es `Indexed`. Para ejemplos, ver Configura el algoritmo de Queryable Encryption. Para obtener detalles sobre los algoritmos de cifrado admitidos, consulta Elección de Algoritmo.

Comportamiento

Los métodos mongosh de cifrado a nivel de campo del lado del cliente y Queryable Encryption requieren una conexión de base de datos configurada para el cifrado del lado del cliente. Si la conexión actual a la base de datos no se inició con el cifrado a nivel de campo del lado del cliente habilitado, entonces:

Utilice el constructor Mongo() de mongosh para establecer una conexión con las opciones de cifrado de campo requeridas del lado del cliente. El Mongo() método admite los siguientes proveedores de Servicios de Gestión de Claves (KMS) para la gestión de la Clave Maestra del Cliente (CMK):

Utilice las mongosh opciones de línea de comandos para establecer una conexión con las opciones requeridas. Estas opciones solo son compatibles con el proveedor KMS de Amazon Web Services para la gestión de CMK.

BSON types no admitidos

No puede utilizar para cifrar valores con los siguientes tipos encrypt() BSON:

minKey
maxKey
null
undefined

Si se encripta un campo utilizando AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic, encrypt() no es compatible con los siguientes tipos BSON:

double
decimal128
bool
object
array

Ejemplos

Encriptación a nivel de campo

El siguiente ejemplo utiliza un KMS gestionado localmente para la configuración de cifrado a nivel de campo en el lado del cliente.

Crea Tu Conexión Encriptada

Inicia mongosh
Ejecuta:
```
mongosh --nodb
```
--nodb significa no conectarse a una base de datos.
Generar un String
Genera una cadena base de 64 96bytes:
```
const TEST_LOCAL_KEY = require("crypto").randomBytes(96).toString("base64")
```

Crear un objeto de opciones de cifrado

Para crear un objeto de opciones de cifrado de nivel de campo del lado del cliente, utilice la string TEST_LOCAL_KEY del paso anterior:

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

Crear un objeto de cliente cifrado
Para crear un objeto cliente cifrado, utilice el constructor. Reemplace Mongo() el mongodb://myMongo.example.net URI con el URI de la cadena de conexión del clúster de destino. Por ejemplo:
```
encryptedClient = Mongo(
   "mongodb://myMongo.example.net:27017/?replSetName=myMongo",
   autoEncryptionOpts
)
```

Cifre sus datos

Recupere el objeto ClientEncryption y use el método ClientEncryption.encrypt() para cifrar un valor usando una llave de cifrado de datos UUID y el algoritmo de cifrado:

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

También puede especificar el algoritmo utilizando un documento con un 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" }
)

Resultados de ejemplo

Si tiene éxito, devuelve el valorencrypt() cifrado:

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

Para obtener la documentación completa sobre cómo iniciar conexiones MongoDB con el cifrado a nivel de campo en el lado del cliente activado, consulte Mongo().

Queryable Encryption

El siguiente ejemplo utiliza un KMS administrado localmente para la configuración de cifrado consultable.

Crea Tu Conexión Encriptada

Inicia mongosh
Inicie el cliente mongosh.
```
mongosh --nodb
```
Genere su clave
Para configurar el cifrado consultable para una clave administrada localmente, genere una cadena de 96bytes codificada en base64sin saltos de línea.
```
const TEST_LOCAL_KEY = require("crypto").randomBytes(96).toString("base64")
```
Crear las opciones de cifrado consultables
Crea las opciones de Queryable Encryption usando la string de clave local generada:
```
   var autoEncryptionOpts = {
   "keyVaultNamespace" : "encryption.__dataKeys",
   "kmsProviders" : {
      "local" : {
         "key" : BinData(0, TEST_LOCAL_KEY)
      }
   }
   }
```
Crea tu cliente cifrado
Utilice el Mongo() constructor con las opciones de Queryable Encryption configuradas para crear una conexión de base de datos. Reemplaza el URI mongodb://myMongo.example.net con el URI de cadena de conexión del clúster de destino.
```
encryptedClient = Mongo(
   "mongodb://myMongo.example.net:27017/?replSetName=myMongo",
   autoEncryptionOpts
)
```

Cifre sus datos

Recupere el objeto ClientEncryption y use el método ClientEncryption.encrypt() para cifrar un valor usando una llave de cifrado de datos UUID y el algoritmo de cifrado:

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

También puedes especificar el algoritmo utilizando un documento que contenga los 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
  }
)

Resultados de ejemplo

Si tiene éxito, devuelve el valorencrypt() cifrado:

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

Obtén más información

Para obtener la documentación completa sobre cómo iniciar conexiones MongoDB con el cifrado a nivel de campo en el lado del cliente activado, consulte Mongo().

Volver

ClientEncryption.createEncryptedCollection

ClientEncryption.encryptExpression