ClientEncryption.encrypt() (método mongosh)

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

ClientEncryption.encrypt() cifra el value utilizando el especificado keyId y el algoritmo especificado por algorithm encOptionso. admiteencrypt() el cifrado explícito (manual) de valores de campo.

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 `value`. El UUID es un `binary data` objeto BSON 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, devuelve`encrypt()` un error. Consulte Colecciones de almacenes de claves para obtener más información sobre almacenes de claves y claves de cifrado de datos.
`value`	Consulte Tipos BSON no admitidos.	El valor a cifrar.
`algorithm` or `encOptions`	string o documento	Para cifrar campos explícitamente con cifrado de nivel de campo del lado del cliente: Especifique `algorithm` como una cadena o `encOptions` como un documento que contiene 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, consulte Establecer el algoritmo de cifrado a nivel de campo del lado del cliente. Para obtener documentación completa sobre los algoritmos de cifrado admitidos, consulte Campos y tipos de cifrado. Para cifrar explícitamente campos con cifrado consultable: Especifique `algorithm` como una cadena o `encOptions` como un documento que contiene 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 ver ejemplos, consulte Establecer el algoritmo de cifrado consultable. Para obtener detalles sobre los algoritmos de cifrado admitidos, consulte Elección de algoritmo.

Comportamiento

Los métodos de cifrado de campo y consulta del lado del cliente requieren una conexión a la base de datos configurada para el cifrado del lado del cliente. Si la conexión a la base de datos actual no se inició con el cifrado de campo del lado del cliente habilitado, puede ocurrir lo mongosh siguiente:

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.

Tipos BSON no compatibles

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

minKey
maxKey
null
undefined

Si se cifra un campo utilizando,AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic encrypt() no admite los siguientes tipos BSON:

double
decimal128
bool
object
array

Ejemplos

Encriptación a nivel de campo

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

Crea tu conexión cifrada

Iniciar 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 a nivel de campo del lado del cliente, utilice la cadena 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 ClientEncryption objeto y utilice el método para cifrar un valor utilizando una ClientEncryption.encrypt() clave UUID de cifrado de datos específica y un 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 documentación completa sobre cómo iniciar conexiones MongoDB con el cifrado de nivel de campo del lado del cliente habilitado,Mongo() consulte.

Queryable Encryption

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

Crea tu conexión cifrada

Iniciar mongosh
Inicie el cliente mongosh.
```
mongosh --nodb
```
Genera tu 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
Cree las opciones de cifrado consultable utilizando la cadena de clave local generada:
```
   var autoEncryptionOpts = {
   "keyVaultNamespace" : "encryption.__dataKeys",
   "kmsProviders" : {
      "local" : {
         "key" : BinData(0, TEST_LOCAL_KEY)
      }
   }
   }
```
Crea tu cliente cifrado
Utilice el constructor con las opciones de cifrado consultables configuradas para crear una conexión a la base de datos. Reemplace Mongo() el mongodb://myMongo.example.net URI por el URI de la cadena de conexión del clúster de destino.
```
encryptedClient = Mongo(
   "mongodb://myMongo.example.net:27017/?replSetName=myMongo",
   autoEncryptionOpts
)
```

Cifre sus datos

Recupere el ClientEncryption objeto y utilice el método para cifrar un valor utilizando una ClientEncryption.encrypt() clave UUID de cifrado de datos específica y un 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: 8
  }
)

Resultados de ejemplo

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

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

Obtén más información

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

Volver

ClientEncryption.createEncryptedCollection

ClientEncryption.encryptExpression