Join us at MongoDB.local London on 7 May to unlock new possibilities for your data. Use WEB50 to save 50%.
Register now >
Docs Menu
Docs Home
/ /
Referencia
Docs Home
/ /
Encriptación a nivel de campo
/
Referencia
Docs Home
/
Manual de base de datos
/
Seguridad
/
Encriptación
/
Encriptación en uso
/
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 la sintaxis estándar del borrador del esquema JSON.4 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:

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

Si se keyId omiten o,algorithm la biblioteca compartida 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 Shared Library no puede construir el objeto completo encrypt utilizando los campos especificados para el objeto y cualquier clave encryptMetadataheredada necesaria, el cifrado automático 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 librería compartida revisa todos los campos principales en busca del ancestro más cercano que contenga una clave encryptMetadata.algorithm y hereda ese valor. Si no existe un algorithm principal, el cifrado automático a nivel de campo falla y retorna 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 encriptar 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 revisa todos los campos principales en busca del ancestro más cercano que contenga una clave encryptMetadata.keyId y hereda ese valor. Si no existe un keyId principal, el cifrado automático a nivel de campo falla y retorna un error.

El keyId u 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 su hermano properties puede heredar. Si a un encrypt le falta una opción necesaria para el cifrado, la Biblioteca Compartida busca en todos los objetos principales un objeto que especifique la opción que encryptMetadata 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:

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 busca en todos los objetos padre 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 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.

encryptkeyIdSi a un objeto le falta el campo, la Librería Compartida busca en todos los objetos parentales para localizar un objeto que especifique encryptMetadataencryptMetadata.keyId.

La clave de cifrado de datos debe existir en la colección de Key Vault especificada como parte de las opciones de configuración de cifrado automático. Estas opciones también deben incluir el acceso adecuado al Servicio de administración de claves (KMS) y a la Clave maestra del cliente (CMK) utilizadas 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 descifrarla con el KMS y la CMK especificados.

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.

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 el cifrado a nivel de campo en el lado del cliente no admite el cifrado de elementos individuales del arreglo, el cifrado aleatorio admite el cifrado de todo el campo de arreglo en lugar de elementos individuales en el 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 especificaron 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 compatibles con MongoDB 4.2+, mongosh, y la 4.2 o la shell heredada mongo posterior 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 AutoEncryptionOpts. Consulta Conectarse a un clúster con el cifrado automático por parte del cliente activado para ver un ejemplo completo.

  • Para los drivers compatibles oficiales de MongoDB 4.2+, utiliza el constructor de conexión específica del driver (MongoClient) para crear la conexión a la base de datos con las reglas de cifrado automáticos incluidas como parte del objeto de configuración de cifrado a nivel de campo en el lado del cliente. 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 de cifrado de nivel de campo del lado del cliente 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

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 datos privados que nunca podrán ser consultados:

  • 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 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.

Si bien el cifrado a nivel de campo en el lado del cliente no admite el cifrado de elementos individuales del arreglo, el cifrado aleatorio admite el cifrado de todo el campo de arreglo en lugar de elementos individuales en el 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 especificaron 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 compatibles con MongoDB 4.2+, mongosh, y la 4.2 o la shell heredada mongo posterior 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 AutoEncryptionOpts. Consulta Conectarse a un clúster con el cifrado automático por parte del cliente activado para ver un ejemplo completo.

  • Para los drivers compatibles oficiales de MongoDB 4.2+, utiliza el constructor de conexión específica del driver (MongoClient) para crear la conexión a la base de datos con las reglas de cifrado automáticos incluidas como parte del objeto de configuración de cifrado a nivel de campo en el lado del cliente. 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 de cifrado de nivel de campo del lado del cliente 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.

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

Next

Cumplimiento del esquema

En esta página