/ /

Cifrado automático a nivel de campo en el lado del cliente

/ /

Encriptación a nivel de campo

Cifrado automático a nivel de campo en el lado del cliente

Docs Home

Manual de MongoDB

Seguridad

Encriptación a nivel de campo

Cifrado automático a nivel de campo en el lado del cliente

Reglas de cifrado automático

Esta versión de la documentación se archivó y ya no se admite. Para actualizar tu implementación de 5.0, consulta el Procedimientos de actualización de MongoDB.6.0

Nota

Característica de la empresa

La funcionalidad automática del cifrado a nivel de campo solo está disponible en MongoDB Enterprise 4.2 o posterior y en los clústeres de MongoDB Atlas 4.2 o posterior.

El cifrado automático de campos a nivel cliente requiere reglas especificadas por el usuario que identifican qué campos deben cifrarse y cómo cifrarlos. Las aplicaciones deben especificar las reglas de cifrado automático utilizando un subconjunto estricto de la Sintaxis estándar de JSON Schema Draft 4 y las siguientes palabras clave específicas de cifrado:

encrypt esquema Keyword - especifica las opciones de cifrado a utilizar al cifrar el campo actual.
encryptMetadata Palabra clave de esquema - especifica las opciones de cifrado heredables.

Considera una base de datos de MongoDB donde la colección employees en la base de datos hr contiene documentos que se asemejan a lo siguiente:

{
  "fname" : "Jo",
  "lname" : "Doe",
  "taxid" : "123-45-6789",
  "taxid-short" : "6789"
}

Los campos taxid y taxid-short contienen información de identificación personal (PII) que debe protegerse de vistas no autorizadas tanto en el cliente como en el servidor. Las siguientes reglas automáticas de cifrado para la colección hr.employees marcan los campos taxid y taxid-short para el cifrado automático de nivel de campo del lado del cliente. Oficialmente compatible con MongoDB 4.2y superior Loscontroladores, mongosh 4.2 mongo y el shell heredado o posterior configurados con estas reglas cifran automáticamente los taxid taxid-short campos y para operaciones de escritura o lectura en la hr.employees colección.

{
  "hr.employees": {
    "bsonType": "object",
    "properties": {
      "taxid": {
        "encrypt": {
          "keyId": [UUID("11d58b8a-0c6c-4d69-a0bd-70c6d9befae9")],
          "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512_Random",
          "bsonType" : "string"
        }
      },
      "taxid-short": {
        "encrypt": {
          "keyId": [UUID("2ee77064-5cc5-45a6-92e1-7de6616134a8")],
          "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
          "bsonType": "string"
        }
      }
    }
  }
}

Para el shell de MongoDB, utiliza el constructor Mongo() para crear la conexión a la base de datos con las reglas de encriptación automática incluidas como parte del objeto de configuración de encriptación a nivel de campo del lado del cliente. Consulta Conectar a un clúster con cifrado automático del lado del cliente habilitado para un ejemplo.
Para los controladores oficiales de MongoDB, utiliza el constructor de conexión de base de datos específico del controlador (por ejemplo, MongoClient) para crear la conexión a la base de datos con las reglas de encriptación automáticas incluidas como parte del objeto de configuración de encriptación a nivel de campo del lado del cliente. Consulta la referencia de la API del controlador para obtener documentación y tutoriales más completos.

Importante

El cifrado automático a nivel de campo en el lado del cliente admite un subconjunto estricto de la sintaxis de JSON schema únicamente para definir el comportamiento de cifrado. No especifique palabras clave de validación de documentos en las reglas de cifrado automático. Para definir reglas de validación de documentos, configura la validación de esquema del servidor.

`encrypt` Schema Keyword

"bsonType" : "object",
"properties" : {
  "<fieldName>" : {
    "encrypt" : {
      "algorithm" : "<string>",
      "bsonType" : "<string>" | [ "<string>" ],
      "keyId" : [ <UUID> ]
    }
  }
}

encrypt

Objeto

Indica que <fieldName> debe estar cifrado. El objeto encrypt tiene los siguientes requisitos:

encrypt no puede tener campos hermanos en el objeto <fieldName>. encrypt debe ser el único hijo del objeto <fieldName>.
encrypt no puede especificarse dentro de ningún subschema de las palabras clave items o additionalItems. Específicamente, el cifrado automático a nivel de campo del lado del cliente no admite el cifrado de elementos individuales de un arreglo.

El objeto encrypt puede contener únicamente los siguientes campos:

algorithm
bsonType
keyId

Incluir cualquier otro campo en el objeto encrypt resulta en errores al emitir operaciones de lectura o escritura cifradas automáticamente.

Si se omiten keyId o algorithm , la librería Compartida de Cifrado Automático verifica todo el árbol de campos principales e intenta construir esas opciones a partir del objeto encryptMetadata más cercano que especifique la opción. bsonType no se puede heredar y puede ser necesario dependiendo del valor de algorithm.

Si la Biblioteca Compartida de Encriptación Automática no puede construir el objeto completo encrypt usando los campos especificados para el objeto y cualquier clave requerida heredada de encryptMetadata, la encriptación automática falla y devuelve un error.

encrypt.algorithm

String

Indica qué algoritmo de cifrado utilizar al cifrar valores de <fieldName>. Admite los siguientes algoritmos únicamente:

AEAD_AES_256_CBC_HMAC_SHA_512-Random
AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic

Para obtener la documentación completa sobre los algoritmos de cifrado, consulte Algoritmos de cifrado.

Si se omite, la biblioteca compartida de cifrado automático busca en el árbol completo de campos principales la clave más cercana encryptMetadata.algorithm y hereda ese valor. Si no existe una clave algorithm principal, el cifrado automático a nivel de campo falla y devuelve un error.

Si encrypt.algorithm o su valor heredado es AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic, el objeto encrypt requiere el campo encrypt.bsonType.
Si encrypt.algorithm o su valor heredado es AEAD_AES_256_CBC_HMAC_SHA_512-Random, el objeto encrypt puede incluir el campo encrypt.bsonType.

encrypt.bsonType

string | arreglo de strings

El tipo BSON del campo que se cifra. Obligatorio si encrypt.algorithm es AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic.

Si encrypt.algorithm o su valor heredado es AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic, bsonType debe especificar un tipo único. bsonType no admite ninguno de los siguientes tipos BSON con el algoritmo de cifrado determinista:

double
decimal128
bool
object
array

Si encrypt.algorithm o su valor heredado es AED_AES_256_CBC_HMAC_SHA_512-Random, bsonType es opcional y puede especificar un arreglo de BSON types compatibles. Para campos con bsonType de array o object, el cliente cifra el arreglo u objeto completo y no sus elementos individuales.

encrypt.bsonType no admite los siguientes tipos independientemente de encrypt.algorithm o de su valor heredado:

minKey
maxKey
null
undefined

encrypt.keyId

Arreglo de UUID único

El UUID de la clave de cifrado de datos que se utilizará para cifrar los valores de los campos. El UUID es un BSON datos binarios elemento de subtipo 4.

Especifica una string dentro del arreglo.

Si se omite, la librería Compartida de Cifrado Automático comprueba todo el árbol de campos primarios en busca de la clave encryptMetadata.keyId más cercana y hereda ese valor. Si no existe un keyId primario, el cifrado automático a nivel de campo falla y devuelve un error.

El valor o keyId su valor heredado debe existir en el almacén de claves especificado como parte de las opciones de configuración del cifrado automático. Si la clave de cifrado de datos especificada no existe, el cifrado automático falla.

Los controladores oficiales de MongoDB tienen requisitos específicos del lenguaje para especificar el UUID. Consulte la documentación del controlador para obtener información completa sobre la implementación del cifrado a nivel de campo del lado del cliente.

`encryptMetadata` Schema Keyword

{
  "bsonType" : "object",
  "encryptMetadata" : {
    "algorithm" : "<string>",
    "keyId" : [ <UUID> ]
  },
  "properties" : {
    "encrypt" : {}
  }
}

encryptMetadata

Objeto

Define las opciones de cifrado que un encrypt objeto anidado en su hermano properties puede heredar. Si a un encrypt le falta una opción necesaria para el cifrado, la Biblioteca Compartida de Cifrado Automático busca en todo el árbol de objetos padre para encontrar un objeto que especifique la opción que encryptMetadata falta.

encryptMetadata debe especificarse en subschemas con bsonType: "object". encryptMetadata no puede especificarse a ningún subschema de las palabras clave items o additionalItems. En concreto, el cifrado automático a nivel de campo del lado del cliente no admite cifrar elementos individuales de un arreglo.

El encryptMetadata objeto solo puede contener los siguientes campos. Incluir cualquier otro campo en el encrypt objeto genera errores al ejecutar operaciones de lectura o escritura cifradas automáticamente:

algorithm
keyId

encryptMetadata.algorithm

String

El algoritmo de cifrado que se utilizará para cifrar un campo dado. Si a un objeto encrypt le falta el campo algorithm, la Librería compartida de cifrado automático busca en todo el árbol de objetos principales para localizar un objeto encryptMetadata que especifique encryptMetadata.algorithm.

Admite sólo los siguientes algoritmos:

AEAD_AES_256_CBC_HMAC_SHA_512-Random
AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic

Para obtener la documentación completa sobre los algoritmos de cifrado, consulte Algoritmos de cifrado.

Si se especifica AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic, cualquier objeto encrypt que herede ese valor debe especificar encrypt.bsonType.

encryptMetadata.keyId

Arreglo de UUID único

El UUID de una clave de cifrado de datos. El UUID es un elemento BSON datos binarios de subtipo 4.

Especifica una string dentro del arreglo.

Si a un objeto encrypt le falta el campo keyId, la Librería Compartida de Cifrado Automático busca en todo el árbol de objetos primarios para localizar un objeto encryptMetadata que especifique encryptMetadata.keyId.

La clave de cifrado de datos debe existir en el almacén de claves especificado como parte de las opciones de configuración de cifrado automático. Las opciones de configuración especificadas también deben incluir el acceso adecuado al Key Management Service (KMS) y la llave maestra de cliente (llave maestra de cliente) utilizados para crear la clave de datos. El cifrado automático falla si la clave de cifrado de datos no existe o si el cliente no puede descifrar la clave con el KMS y la llave maestra de cliente especificados.

Ejemplos

Cifrar automáticamente varios campos
Encripte automáticamente varios campos con herencia

Cifrar automáticamente varios campos

Considere una colección MedCo.patients donde cada documento tiene la siguiente estructura:

{
  "fname" : "<String>",
  "lname" : "<String>",
  "passportId" : "<String>",
  "bloodType" : "<String>",
  "medicalRecords" : [
    {<object>}
  ],
  "insurance" : {
    "policyNumber" : "<string>",
    "provider" : "<string>"
  }
}

Los siguientes campos contienen información personal identificable (PII) que puede ser consultado:

passportId
bloodType
insurance.policyNumber
insurance.provider

El algoritmo de cifrado determinístico garantiza que la salida cifrada de un valor permanezca estática. Esto permite que las queries para un valor específico devuelvan resultados significativos, a costo de una mayor susceptibilidad a la recuperación mediante análisis de frecuencia. Por lo tanto, el algoritmo de cifrado determinista cumple tanto los requisitos de cifrado como los de consultabilidad de los datos.

Los siguientes campos contienen información de identificación personal (PII) legalmente protegida que nunca puede ser consultada:

medicalRecords

El algoritmo de cifrado aleatorizado garantiza que el resultado cifrado de un valor siempre sea único. Esto impide que las consultas sobre un valor específico de campo devuelvan resultados significativos, al tiempo que se garantiza la máxima protección posible del contenido del campo. Por lo tanto, el algoritmo de cifrado aleatorizado cumple tanto con los requisitos de cifrado como de capacidad de consulta de los datos.

El siguiente esquema especifica reglas de cifrado automático que cumplen los requisitos anteriores para la colección MedCo.patients:

{
  "MedCo.patients" : {
    "bsonType" : "object",
    "properties" : {
      "passportId" : {
        "encrypt" : {
          "keyId" : [UUID("bffb361b-30d3-42c0-b7a4-d24a272b72e3")],
          "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
          "bsonType" : "string"
        }
      },
      "bloodType" : {
        "encrypt" : {
          "keyId" : [UUID("bffb361b-30d3-42c0-b7a4-d24a272b72e3")],
          "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
          "bsonType" : "string"
        }
      },
      "medicalRecords" : {
        "encrypt" : {
          "keyId" : [UUID("f3821212-e697-4d65-b740-4a6791697c6d")],
          "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Random",
          "bsonType" : "array"
        }
      },
      "insurance" : {
        "bsonType" : "object",
        "properties" : {
          "policyNumber" : {
            "encrypt" : {
              "keyId" : [UUID("bffb361b-30d3-42c0-b7a4-d24a272b72e3")],
              "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
              "bsonType" : "string"
            }
          },
          "provider" : {
            "encrypt" : {
              "keyId" : [UUID("bffb361b-30d3-42c0-b7a4-d24a272b72e3")],
              "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
              "bsonType" : "string"
            }
          }
        }
      }
    }
  }
}

Las reglas de cifrado automático anteriores marcan los campos passportId, bloodType, insurance.policyNumber, insurance.provider y medicalRecords para cifrado.

Los campos passportId, bloodType, insurance.policyNumber y provider requieren cifrado determinista utilizando la clave especificada.
El campo medicalRecords requiere cifrado aleatorio utilizando la clave especificada.

Aunque el cifrado en el lado del cliente a nivel de campo no soporta el cifrado de elementos individuales de un arreglo, el cifrado aleatorio admite el cifrado de todo el campo de arreglo en lugar de elementos individuales del campo. Las reglas de cifrado automático de ejemplo especifican el cifrado aleatorio para el campo medicalRecords para cifrar todo el arreglo. Si las reglas de cifrado automático especifican encrypt o encryptMetadata dentro de medicalRecords.items o medicalRecords.additionalItems, el cifrado automático a nivel de campo falla y devuelve errores.

Los controladores compatibles oficiales de MongoDB 4.2+ compatible, mongosh, y la shell heredada 4.2 o posterior mongo, requieren especificar las reglas de cifrado automático como parte de la creación del objeto de conexión a la base de datos:

Para mongosh, utiliza el constructor Mongo() para crear una conexión a la base de datos. Especifica las reglas de cifrado automático en la clave schemaMap del parámetro ClientSideFieldLevelEncryptionOptions. Consulta Conectarse a un clúster con el cifrado automático por parte del cliente activado para ver un ejemplo completo.
Para los controladores oficiales de MongoDB 4.2+ compatibles, utiliza el constructor de conexión a la base de datos específico del controlador (por ejemplo, MongoClient) para crear la conexión con la base de datos con las reglas de cifrado automático incluidas como parte del objeto de configuración de cifrado a nivel de campo del lado del cliente. Consulte la referencia API de drivers para una documentación y tutoriales más completos.

Para todos los clientes, el keyVault y el kmsProviders especificados en el parámetro de cifrado a nivel de campo del lado del cliente deben otorgar acceso tanto a las llaves de cifrado de datos especificadas en las reglas de cifrado automáticos como a la Llave Maestra de Cliente utilizada para cifrar las llaves de cifrado de datos.

Encripte automáticamente varios campos con herencia

Considere una colección MedCo.patients donde cada documento tiene la siguiente estructura:

{
  "fname" : "<String>",
  "lname" : "<String>",
  "passportId" : "<String>",
  "bloodType" : "<String>",
  "medicalRecords" : [
    {<object>}
  ],
  "insurance" : {
    "policyNumber" : "<string>",
    "provider" : "<string>"
  }
}

Los siguientes campos contienen datos privados que se pueden consultar:

passportId
bloodType
insurance.policyNumber
insurance.provider

Los siguientes campos contienen datos privados que nunca podrán ser consultados:

medicalRecords

El siguiente esquema especifica las reglas de cifrado automático que cumplen los requisitos de cifrado para la colección MedCo.patients:

{
  "MedCo.patients" : {
    "bsonType" : "object",
    "encryptMetadata" : {
      "keyId" : [UUID("6c512f5e-09bc-434f-b6db-c42eee30c6b1")],
      "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
    },
    "properties" : {
      "passportId" : {
        "encrypt" : {
          "bsonType" : "string"
        }
      },
      "bloodType" : {
        "encrypt" : {
          "bsonType" : "string"
        }
      },
      "medicalRecords" : {
        "encrypt" : {
          "keyId" : [UUID("6c512f5e-09bc-434f-b6db-c42eee30c6b1")],
          "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Random",
          "bsonType" : "array"
        }
      },
      "insurance" : {
        "bsonType" : "object",
        "properties" : {
          "policyNumber" : {
            "encrypt" : {
              "bsonType" : "string"
            }
          },
          "provider" : {
            "encrypt" : {
              "bsonType" : "string"
            }
          }
        }
      }
    }
  }
}

Las reglas de cifrado automático anteriores marcan los campos passportId, bloodType, insurance.policyNumber, insurance.provider y medicalRecords para cifrado.

Los campos passportId, bloodType, insurance.policyNumber y provider heredan la configuración de cifrado del campo encryptMetadata principal. Específicamente, estos campos heredan los valores algorithm y keyId que especifican el cifrado determinista con la clave de cifrado de datos indicada.
El campo medicalRecords requiere cifrado aleatorio con la clave especificada. Las opciones encrypt anulan las especificadas en el campo principal encryptMetadata.

Para mongosh, utiliza el constructor Mongo() para crear una conexión a la base de datos. Especifica las reglas de cifrado automático en la clave schemaMap del parámetro ClientSideFieldLevelEncryptionOptions. Consulta Conectarse a un clúster con el cifrado automático por parte del cliente activado para ver un ejemplo completo.
Para los controladores oficiales de MongoDB 4.2+ compatibles, utiliza el constructor de conexión a la base de datos específico del controlador (por ejemplo, MongoClient) para crear la conexión con la base de datos con las reglas de cifrado automático incluidas como parte del objeto de configuración de cifrado a nivel de campo del lado del cliente. Consulte la referencia API de drivers para una documentación y tutoriales más completos.

Volver

Cifrado automático a nivel de campo en el lado del cliente

Soporte de lectura/escritura con cifrado automático a nivel de campo

Nota

Característica de la empresa

Importante

encrypt Schema Keyword

encryptMetadata Schema Keyword

Ejemplos

Cifrar automáticamente varios campos

Encripte automáticamente varios campos con herencia

`encrypt` Schema Keyword

`encryptMetadata` Schema Keyword