/ /

Referencia

Docs Home

/ /

Encriptación a nivel de campo

Encriptación a nivel de campo

Referencia

Esquemas de cifrado de CSFLE

La función de cifrado consultable de MongoDB está disponible (GA) en MongoDB 7.0 y versiones posteriores. Para obtener más información sobre el cifrado consultable y comparar sus ventajas con el cifrado a nivel de campo del lado del cliente, consulte Cifrado consultable.

Overview

Nota

Característica de la empresa

La función automática de cifrado a nivel de campo solo es compatible con MongoDB Enterprise 6.0 o posterior, y 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 utilizar al cifrar el campo actual.
Cifrar metadatos especifica opciones de cifrado heredables.

Para el 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 en el objeto de configuración de cifrado de nivel de campo del lado del cliente. Consulte "Conectarse a un clúster con el cifrado automático del lado del cliente habilitado" para ver un ejemplo.

Para los controladores oficiales de MongoDB, utilice el constructor de conexión de base de datos específicoMongoClient del controlador () para crear la conexión con las reglas de cifrado automático incluidas en el objeto de configuración de cifrado de nivel de campo del lado del cliente. Para obtener más información sobre las MongoClient opciones específicas de CSFLE, consulte la página del cliente de 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 cumple los siguientes requisitos:

encrypt no puede haber ningún campo hermano 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. En concreto, el cifrado automático a nivel de campo del lado del cliente no admite el cifrado de elementos individuales de una matriz.

El encrypt objeto solo puede contener los siguientes campos:

algorithm
bsonType
keyId

Incluir cualquier otro campo en el objeto encrypt genera 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 cifrado automático no puede construir el objeto encrypt completo utilizando los campos especificados para el objeto y cualquier clave heredada encryptMetadatarequerida, el cifrado automático falla y devuelve un error.

encrypt.algorithm

String

Indica el algoritmo de cifrado que se debe usar al cifrar valores <fieldName> de.Solo admite los siguientes algoritmos:

AEAD_AES_256_CBC_HMAC_SHA_512-Random
AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic

Para obtener documentación completa sobre los algoritmos de cifrado, consulte Campos y tipos de cifrado.

Si se omite, la Biblioteca Compartida de Cifrado Automático busca en todos los campos principales el ancestro más cercano que encryptMetadata.algorithm contenga una clave y hereda ese valor. Si no algorithm existe un ancestro, el cifrado automático a nivel de campo falla y devuelve un error.

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

encrypt.bsonType

Cadena | Matriz de cadenas

El tipo BSON del campo que se va a cifrar. Obligatorio si encrypt.algorithm AEAD_AES_256_CBC_HMAC_SHA_512-Deterministices.

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

double
decimal128
bool
object
array

Si o su valor encrypt.algorithm heredado AED_AES_256_CBC_HMAC_SHA_512-Random es, bsonType es opcional y puede especificar una matriz de tipos bson compatibles. Para los campos con,bsonType array objectu, el cliente cifra la matriz u objeto completo, no sus elementos individuales.

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

minKey
maxKey
null
undefined

encrypt.keyId

Matriz de UUID único

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

Especifique una cadena dentro de la matriz.

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

El valor o keyId su valor heredado debe existir en la colección de Key Vault especificada 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

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 de Cifrado Automático busca en todos los objetos principales un encryptMetadata objeto que especifique la opción que falta.

encryptMetadata Debe especificarse en subesquemas con bsonType: "object". No se puede especificar encryptMetadata en ningún subesquema de las palabras clave items o additionalItems. En concreto, el cifrado automático a nivel de campo del lado del cliente no admite el cifrado de elementos individuales de una matriz.

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 utiliza para cifrar un campo determinado. Si a un objetoencryptle falta el campoalgorithm, la Biblioteca Compartida de Cifrado Automático busca en todos los objetos principales para encontrar un objetoencryptMetadataque especifiqueencryptMetadata.algorithm.

Admite únicamente los siguientes algoritmos:

AEAD_AES_256_CBC_HMAC_SHA_512-Random
AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic

Para obtener documentación completa sobre los algoritmos de cifrado, consulte Campos y tipos de cifrado.

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

encryptMetadata.keyId

Matriz de UUID único

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

Especifique una cadena dentro de la matriz.

Si a un objetoencryptle falta el campokeyId, la biblioteca compartida de cifrado automático busca en todos los objetos principales para localizar un objetoencryptMetadataque especifiqueencryptMetadata.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.

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 de identificación personal (PII) que puede consultarse:

passportId
bloodType
insurance.policyNumber
insurance.provider

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

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

medicalRecords

El algoritmo de cifrado aleatorio garantiza que la salida cifrada de un valor sea siempre única. Esto evita que las consultas de un valor de campo específico devuelvan resultados significativos, a la vez que garantiza la máxima protección del contenido del campo. Por lo tanto, el algoritmo de cifrado aleatorio cumple con los requisitos de cifrado y consultabilidad 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 el 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 a nivel de campo del lado del cliente no permite cifrar elementos individuales de la matriz, el cifrado aleatorio permite cifrar todo el campo de la matriz, en lugar de sus elementos individuales. Las reglas de cifrado automático de ejemplo especifican cifrado aleatorio para el medicalRecords campo para cifrar toda la matriz. Si las reglas de cifrado automático encrypt especifican u encryptMetadata dentro medicalRecords.items de medicalRecords.additionalItems o, el cifrado automático a nivel de campo falla y devuelve un error.

Los 4.2controladores oficiales compatibles conmongosh MongoDB +,, y el shell heredado 4.2 o posterior mongo requieren la especificación de las reglas de cifrado automático como parte de la creación del objeto de conexión de base de datos:

mongoshPara, use el constructor para crear una conexión a la base de datos. Especifique las reglas de cifrado automático en Mongo() la schemaMap clave del parámetro. Consulte "Conectarse a un clúster con AutoEncryptionOpts el cifrado automático del lado del cliente habilitado" para ver un ejemplo completo.
Para los 4.2controladores oficiales compatibles con MongoDB +, utilice el constructor de conexión de base de datos específicoMongoClient del controlador () para crear la conexión con las reglas de cifrado automático incluidas en el objeto de configuración de cifrado de nivel de campo del lado del cliente. Consulte 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: campos múltiples 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 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 el 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.

mongoshPara, use el constructor para crear una conexión a la base de datos. Especifique las reglas de cifrado automático en Mongo() la schemaMap clave del parámetro. Consulte "Conectarse a un clúster con AutoEncryptionOpts el cifrado automático del lado del cliente habilitado" para ver un ejemplo completo.
Para los 4.2controladores oficiales compatibles con MongoDB +, utilice el constructor de conexión de base de datos específicoMongoClient del controlador () para crear la conexión con las reglas de cifrado automático incluidas en el objeto de configuración de cifrado de nivel de campo del lado del cliente. Consulte la referencia de la API del controlador para obtener documentación y tutoriales más completos.

Para obtener más información sobre su colección CMK y Key Vault, consulte la página de bóvedas de claves.

Para obtener más información sobre los algoritmos de cifrado, consulte la página Algoritmos de cifrado.

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

Esquema de cifrado: Cifrar con propiedades de patrón

Puede utilizar 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>" agregada al final del nombre del campo.

passportId_PIIString
bloodType_PIIString
medicalRecords_PIIArray
insurance.policyNumber_PIINumber
insurance.provider_PIIString

Puede usar la palabra clave patternProperties para configurar el cifrado de estos campos, sin identificar cada campo individualmente ni usar el nombre completo. Para ello, utilice expresiones regulares que coincidan con todos los campos que terminan con la etiqueta "_PII<type>".

El siguiente esquema JSON utiliza patternProperties y expresiones regulares para especificar qué campos 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 patternProperties palabra clave, consulte la palabra clave patternProperties.

Volver

Limitaciones de CSFLE

Cumplimiento del esquema