/ /

Referencia

Docs Home

/ /

Encriptación a nivel de campo

Encriptación a nivel de campo

Referencia

Esquemas de cifrado de CSFLE

Overview

Nota

Característica de la empresa

La funcionalidad automática de encriptación a nivel de campo solo está disponible en MongoDB Enterprise 6.0 o posterior, y en las clusters de MongoDB Atlas 6.0 o posterior.

Los esquemas de cifrado contienen reglas especificadas por el usuario que identifican qué campos deben cifrarse y cómo hacerlo. Las aplicaciones deben especificar las reglas de cifrado automático utilizando un subconjunto estricto de... Borrador de esquema JSON 4 sintaxis estándar y las siguientes palabras clave específicas de cifrado:

Cifrar especifica las opciones de cifrado a usar al cifrar el campo actual.
Cifrar metadatos especifica opciones de cifrado heredables.

Para la shell de MongoDB, utilice el Mongo() constructor para crear la conexión a la base de datos con las reglas de cifrado automático incluidas como parte del cifrado a nivel de campo del lado del cliente objeto de configuración. Consulta Conectar a un clúster con cifrado en el lado del cliente automático habilitado como ejemplo.

Para los drivers oficiales de MongoDB, utiliza el constructor de conexión de base de datos específico del driver (MongoClient) para crear la conexión de base de datos con las reglas de cifrado automático incluidas como parte del objeto de configuración de lado del cliente cifrado a nivel de campo. Para obtener más información sobre las opciones específicas de CSFLE MongoClient, consulte la página de cliente mongo.

Importante

No especifique palabras clave de validación de esquema en su esquema de cifrado

No especifique palabras clave de validación de esquema en las reglas de cifrado automático. Para definir reglas de validación de esquema, configure la validación de esquema.

Definición

encrypt

Objeto

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

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 se puede especificar dentro de ningún subesquema 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 biblioteca compartida de cifrado automático verifica todos los campos principales e intenta construir esas opciones a partir del objeto más cercano encryptMetadata que especifique la opción. nobsonType se puede heredar y puede ser necesario según el valor algorithm de.

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 una documentación completa sobre los algoritmos de cifrado, vea Campos y tipos de cifrado.

Si se omite, la Biblioteca Compartida de cifrado automático revisa todos los campos ascendentes para encontrar el ancestro más cercano que contenga una clave encryptMetadata.algorithm y hereda ese valor. Si no existe un ancestro algorithm, 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

string (puntero JSON) | arreglo de un solo UUID

Si utilizas un UUID, especifica un UUID dentro de un arreglo. Este es el UUID de la clave de cifrado de datos que se utilizará para cifrar los valores de los campos. El UUID es un elemento BSON datos binarios de subtipo 4.
Si usas una string, utiliza un puntero JSON que haga referencia a un nombre alternativo de clave.

Si se omite, la Biblioteca Compartida de cifrado automático revisa todos los campos ascendentes para encontrar el ancestro más cercano que contenga una clave encryptMetadata.keyId y hereda ese valor. Si no existe un ancestro keyId, el cifrado automático a nivel de campo falla y devuelve un error.

El keyId o su valor heredado debe existir en la Colección de Bóvedas de Llaves especificada como parte de las opciones de configuración de cifrado automático. Si la llave 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

Objeto

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

Define las opciones de cifrado que un encrypt objeto anidado en el objeto paralelo properties puede heredar. Si a un encrypt le falta una opción requerida para admitir el cifrado, la Librería compartida de cifrado automático busca en todos los objetos principales para localizar un objeto encryptMetadata que especifique la opción que falta.

encryptMetadata debe especificarse en subesquemas con bsonType: "object". encryptMetadata no se puede especificar para ningún subschema de las palabras clave items o additionalItems. Específicamente, la encriptación automática a nivel de campo en el lado del cliente no admite el cifrado de 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 todos los objetos ascendentes para encontrar 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 una documentación completa sobre los algoritmos de cifrado, vea Campos y tipos 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 llave de cifrado de datos. El UUID es un BSON datos binarios elemento de subtipo 4.

Especifica una string dentro del arreglo.

Si a un objeto encrypt le falta el keyId, la librería compartida de cifrado automático busca en todos los objetos padre para localizar un objeto encryptMetadata que especifique encryptMetadata.keyId.

La llave de cifrado de datos debe existir en la Colección de Bóvedas de Llaves especificada como parte de las opciones de configuración de cifrado automático. Las opciones de configuración especificadas deben también incluir el acceso adecuado al Servicio de administración de claves (KMS) y la llave maestra de cliente (llave maestra de cliente) utilizadas para crear la clave de datos. El cifrado automático falla si la llave 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

Esquema de cifrado: campos múltiples

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.

Si bien Queryable Encryption no admite el cifrado de elementos individuales de arreglos, el cifrado aleatorio admite el cifrado de toda el campo de arreglo en lugar de los elementos individuales en el campo. El ejemplo de reglas de cifrado automáticas especifica 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 un error.

Los controladores oficiales de MongoDB, mongosh, y la shell heredada mongo requieren especificar las reglas de cifrado automático como parte del proceso de creación del objeto de conexión de 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 AutoEncryptionOpts. 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, utiliza el constructor de conexión a base de datos específico del controlador (MongoClient) para crear la conexión a base de datos con las reglas de cifrado automático incluidas como parte del objeto de configuración de Queryable Encryption. Remítase a la referencia de la API del controlador para obtener documentación y tutoriales más completos.

Para todos los clientes, los keyVault y kmsProviders especificados en el parámetro Cifrado consultable deben otorgar acceso tanto a las claves de cifrado de datos especificadas en las reglas de cifrado automático como a la clave maestra del cliente utilizada para cifrar las claves de cifrado de datos.

Esquema de cifrado - Múltiples 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 passportId bloodTypeinsurance.policyNumber provider campos,, y heredan su configuración de cifrado del encryptMetadata campo principal. En concreto, heredan los algorithm valores y que especifican el cifrado determinista con la clave de cifrado de datos especificada.keyId
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 AutoEncryptionOpts. 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, utiliza el constructor de conexión a base de datos específico del controlador (MongoClient) para crear la conexión a base de datos con las reglas de cifrado automático incluidas como parte del objeto de configuración de Queryable Encryption. Remítase a la referencia de la API del controlador para obtener documentación y tutoriales más completos.

Para aprender más sobre su llave maestra de cliente y la Colección de Bóvedas de Llaves, consulte la página de key vaults.

Para aprender más sobre algoritmos de cifrado, consulta la página Algoritmos de cifrado.

Para obtener más información sobre las opciones específicas de MongoClient de CSFLE, consulta la página del mongo cliente.

Esquema de cifrado: Cifrar con propiedades de patrón

Puede usar la palabra clave patternProperties en su esquema de cifrado para definir reglas de cifrado para todos los campos con nombres que coincidan con una expresión regular.

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

{
  "fname" : "<string>",
  "lname" : "<string>",
  "passportId_PIIString" : "<string>",
  "bloodType_PIIString" : "<string>",
  "medicalRecords_PIIArray" : [
    {<object>}
  ],
  "insurance" : {
    "policyNumber_PIINumber" : "<number>",
    "provider_PIIString" : "<string>"
  }
}

Los campos que contienen datos privados se identifican mediante una etiqueta "_PII<type>" añadida al final del nombre del campo.

passportId_PIIString
bloodType_PIIString
medicalRecords_PIIArray
insurance.policyNumber_PIINumber
insurance.provider_PIIString

Puedes utilizar la palabra clave patternProperties para configurar estos campos para el cifrado, sin identificar cada campo individualmente y sin usar el nombre completo del campo. Haga esto usando expresiones regulares que coincidan con todos los campos que terminan con la etiqueta "_PII".<type>

El siguiente JSON schema usa patternProperties y expresiones regulares para especificar qué campos se deben cifrar.

{
  "MedCo.patients": {
  "bsonType": "object",
  "patternProperties": {
    "_PIIString$": {
      "encrypt": {
        "keyId": [UUID("6c512f5e-09bc-434f-b6db-c42eee30c6b1")],
        "bsonType": "string",
        "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
      },
    },
    "_PIIArray$": {
      "encrypt": {
        "keyId": [UUID("6c512f5e-09bc-434f-b6db-c42eee30c6b1")],
        "bsonType": "array",
        "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Random",
      },
    },
    "insurance": {
      "bsonType": "object",
      "patternProperties": {
        "_PIINumber$": {
          "encrypt": {
            "keyId": [UUID("6c512f5e-09bc-434f-b6db-c42eee30c6b1")],
            "bsonType": "int",
            "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
          },
        },
        "_PIIString$": {
          "encrypt": {
            "keyId": [UUID("6c512f5e-09bc-434f-b6db-c42eee30c6b1")],
            "bsonType": "string",
            "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
          },
        },
      },
    },
  },
  },
}

Las reglas de cifrado automático anteriores marcan los campos passportId_PIIString, bloodType_PIIString, medicalRecords_PIIArray, insurance.policyNumber_PIINumber, insurance.provider_PIIString para cifrado.

Para obtener más información sobre la palabra clave patternProperties, consulte Palabra clave patternProperties.

Volver

Limitaciones de CSFLE

Aplicación de esquemas del lado del servidor de CSFLE