CSFLE 加密模式

概述

企业版特证

字段级加密的自动特性仅在 MongoDB Enterprise 4.2 或更高版本以及 MongoDB Atlas 4.2 或更高版本的集群中可用

4.2版中的新功能。

加密模式包含用户指定的规则，这些规则标识哪些字段必须加密以及如何加密这些字段。应用程序必须使用一个严格的子集指定自动加密规则JSON Schema Draft 4 标准语法以及以下特定于加密的关键字：

  • 加密 指定加密当前字段时要使用的加密选项。
  • 加密元数据指定可继承的加密选项。

对于 MongoDB 4.2+ shell，使用Mongo()构造函数创建数据库连接，自动加密规则包含在 Client-Side Field Level Encryption 配置对象中。 有关示例，请参阅连接到启用了自动客户端加密的集群。

对于官方 MongoDB 4.2+ 兼容驱动程序，使用驱动程序特定的数据库连接构造函数 ( MongoClient) 创建数据库连接，自动加密规则包含在客户端字段级加密配置对象中。要了解有关 CSFLE 特定 MongoClient选项的更多信息，请参阅mongo 客户端页面。

重要的:

不要在加密模式中指定文档验证关键字

不要 在自动加密规则中指定文档验证关键字。要定义文档验证规则，请配置 模式验证。

定义

encrypt

目的

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

表示<fieldName>必须加密。该encrypt 对象具有以下要求：

  • encrypt对象中不能有任何同级字段 <fieldName>。encrypt必须是对象的唯一子对象 <fieldName>。
  • encrypt``items不能在或关键字的任何子模式中指定 additionalItems。具体来说，自动客户端字段级加密不支持加密数组的单个元素。

该对象只能encrypt包含以下字段：

algorithm

bsonType

keyId

在发出自动加密的读取或写入操作时，在对象中包含任何其他字段encrypt会导致错误

如果keyId或者 algorithm被省略时， 为 CSFLE 安装和配置 mongocryptd检查父字段的完整树并尝试从最近的构建这些选项 encryptMetadata指定选项的对象。bsonType不能被继承，可能需要根据值 algorithm.

如果无法使用为对象指定的字段和任何必需的 继承密钥mongocryptd构造完整对象，则自动加密失败并返回错误。encrypt``encryptMetadata

encrypt.algorithm

指示在加密 的值时要使用的加密算法<fieldName>。仅支持以下算法 ：

  • AEAD_AES_256_CBC_HMAC_SHA_512-Random
  • AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic

有关加密算法的完整文档，请参阅 字段和加密类型。

如果省略，Install and Configure mongocryptd for CSFLE将检查父字段的完整树以查找最近的encryptMetadata.algorithm键并继承该值。如果没有父母 algorithm存在，自动字段级加密失败并返回错误。

  • 如果encrypt.algorithm或其继承值为 AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic，则该 encrypt对象需要encrypt.bsonType场地。
  • 如果encrypt.algorithm或其继承值为 AEAD_AES_256_CBC_HMAC_SHA_512-Random，则该encrypt对象可能包括 encrypt.bsonType场地。

encrypt.bsonType

字符串 | 字符串数组

被加密字段的BSON 类型。如果需要encrypt.algorithm是 AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic

如果encrypt.algorithm或其继承值是 AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic，bsonType 必须指定单一类型。 bsonType不支持 以下任何具有确定性加密算法的 BSON 类型：

  • double
  • decimal128
  • bool
  • object
  • array
  • javascriptWithScope（已弃用）

如果encrypt.algorithm或其继承值是 AED_AES_256_CBC_HMAC_SHA_512-Random,bsonType是可选的，可以指定支持的 bson 类型的数组。对于带有bsonTypeofarray或 的字段object，客户端加密整个数组或对象而不是它们的单个元素。

'encrypt.bsonType不支持以下类型不管encrypt.algorithm或其继承值：

  • minKey
  • maxKey
  • null
  • undefined

encrypt.keyId

单个 UUID 数组

用于加密字段值的数据加密密钥的 UUID。UUID 是一个 BSON二进制数据子类型的元素4。

在数组中指定一个字符串。

如果省略，Install and Configure mongocryptd for CSFLE将检查父字段的完整树以查找最近的 encryptMetadata.keyId键并继承该值。如果没有父母 keyId存在，自动字段级加密失败并返回错误。

这keyId或其继承值必须存在于作为自动加密配置选项 的一部分指定的 Key Vault 集合中 。如果指定的数据加密密钥不存在，则自动加密失败。

官方 MongoDB 4.2+ 兼容驱动程序对指定 UUID 有特定于语言的要求。请参阅 驱动程序文档 以获取有关实现客户端字段级加密的完整文档。

encryptMetadata

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

定义加密选项encrypt 嵌套在兄弟中的对象properties可以继承。如果 encrypt缺少支持加密所需的选项，mongocryptd搜索整个父对象树以找到一个encryptMetadata指定缺失选项的对象。

encryptMetadata必须在带有 的子模式中指定bsonType: "object"。encryptMetadata不能指定给items或additionalItems关键字的任何子模式。具体来说，自动客户端字段级加密不支持加密数组的单个元素。

该对象只能encryptMetadata包含以下字段。在发出自动加密的读取或写入操作时，在对象中包含任何其他字段会导致错误：encrypt

encryptMetadata.algorithm

String

用于加密给定字段的加密算法。如果 encrypt对象丢失 algorithm字段，mongocryptd 搜索整个父对象树以找到一个 encryptMetadata指定的对象 encryptMetadata.algorithm.

仅支持以下算法：

  • AEAD_AES_256_CBC_HMAC_SHA_512-Random
  • AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic

有关加密算法的完整文档，请参阅 字段和加密类型。

如果指定AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic，任何encrypt继承该值的对象都必须指定 encrypt.bsonType.

encryptMetadata.keyId

单个 UUID 数组

数据加密密钥的 UUID。UUID 是一个 BSON二进制数据子类型的元素4。

在数组中指定一个字符串。

如果encrypt对象丢失 keyId字段，mongocryptd 搜索整个父对象树以找到一个encryptMetadata指定的对象encryptMetadata.keyId.

数据加密密钥必须存在于作为自动加密配置选项的一部分指定的 Key Vault 集合中。指定的配置选项还必须包括对用于创建数据密钥的密钥管理服务 (KMS)和客户主密钥 (CMK)的适当访问 。如果数据加密密钥不存在或客户端无法使用指定的 KMS 和 CMK 解密密钥，则自动加密失败。

官方 MongoDB 4.2+ 兼容驱动程序对指定 UUID 有特定于语言的要求。请参阅 驱动程序文档 以获取有关实现客户端字段级加密的完整文档。

例子

加密模式 - 多个字段

考虑一个集合MedCo.patients，其中每个文档都具有以下结构：

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

以下字段包含可以查询的个人身份信息 (PII)：

  • passportId
  • bloodType
  • insurance.policyNumber
  • insurance.provider

确定性加密算法 保证值的加密输出保持静态。这允许查询特定值以增加对频率分析恢复的敏感性为代价返回有意义的结果。因此，确定性加密算法同时满足数据的加密和可查询性要求

以下字段包含可能永远不会被查询的受法律保护的个人身份信息 (PII)：

  • medicalRecords

随机加密算法保证了一个值的加密输出始终是唯一的。这可以防止对特定字段值的查询返回有意义的结果，同时支持对字段内容的最高可能保护。因此，随机加密算法同时满足了数据的加密和可查询性要求。

以下模式指定了满足上述集合要求的自动加密规则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"
            }
          }
        }
      }
    }
  }
}

以上自动加密规则将passportId、 bloodType、insurance.policyNumber、insurance.provider、 和medicalRecords字段标记为加密。

  • 、、和 字段需要使用指定密钥进行确定性加密passportId。bloodType``insurance.policyNumber``provider
  • 该medicalRecords字段需要使用指定密钥进行随机加密。

虽然客户端字段级加密不支持加密单个数组元素，但随机加密支持加密整个 数组字段而不是字段中的单个元素。示例自动加密规则为 medicalRecords字段指定随机加密以加密整个数组。如果指定了自动加密规则encrypt或者 encryptMetadata在medicalRecords.items或 中medicalRecords.additionalItems，自动字段级加密失败并返回错误。

官方 MongoDB 4.2+ 兼容驱动程序，mongosh，以及 4.2 或更高版本的旧版mongoshell 需要指定自动加密规则作为创建数据库连接对象的一部分：

  • 对于mongosh，使用Mongo() 构造函数创建数据库连接。schemaMap为参数的key 指定自动加密规则AutoEncryptionOpts。 有关完整示例，请参阅 连接到启用了自动客户端加密的集群。
  • 对于官方 MongoDB 4.2+ 兼容驱动程序，使用驱动程序特定的数据库连接构造函数 ( MongoClient) 创建数据库连接，自动加密规则包含在客户端字段级加密配置对象中。参考驱动程序 API 参考以获得更完整的文档和教程。

对于所有客户端，指定给客户端字段级加密参数的keyVault和必须授予对自动加密规则中指定的数据加密密钥和用于加密数据加密密钥的客户主密钥的访问权限。kmsProviders

加密模式 - 具有继承性的多个字段

考虑一个集合MedCo.patients，其中每个文档都具有以下结构：

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

以下字段包含可能被查询的私有数据：

  • passportId
  • bloodType
  • insurance.policyNumber
  • insurance.provider

确定性加密算法 保证值的加密输出保持静态。这允许查询特定值以增加对频率分析恢复的敏感性为代价返回有意义的结果。因此，确定性加密算法同时满足数据的加密和可查询性要求。

以下字段包含可能永远不会被查询的私有数据：

  • medicalRecords

随机加密算法保证了一个值的加密输出始终是唯一的。这可以防止对特定字段值的查询返回有意义的结果，同时支持对字段内容的最高可能保护。因此，随机加密算法同时满足了数据的加密和可查询性要求。

以下模式指定满足集合加密要求的自动加密规则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"
            }
          }
        }
      }
    }
  }
}

以上自动加密规则将passportId、 bloodType、insurance.policyNumber、insurance.provider、 和medicalRecords字段标记为加密。

  • passportId、bloodType、insurance.policyNumber和 字段provider从父 encryptMetadata字段继承其加密设置。具体来说，这些字段继承了algorithm和 keyId使用指定的数据加密密钥指定确定性加密的值。
  • 该medicalRecords字段需要使用指定密钥进行随机加密。这些encrypt选项会覆盖父encryptMetadata字段中指定的选项。

虽然客户端字段级加密不支持加密单个数组元素，但随机加密支持加密整个 数组字段而不是字段中的单个元素。示例自动加密规则为 medicalRecords字段指定随机加密以加密整个数组。如果指定了自动加密规则encrypt或者 encryptMetadata在medicalRecords.items或 中medicalRecords.additionalItems，自动字段级加密失败并返回错误。

官方 MongoDB 4.2+ 兼容驱动程序，mongosh，以及 4.2 或更高版本的旧版mongoshell 需要指定自动加密规则作为创建数据库连接对象的一部分：

  • 对于mongosh，使用Mongo() 构造函数创建数据库连接。schemaMap为参数的key 指定自动加密规则AutoEncryptionOpts。 有关完整示例，请参阅 连接到启用了自动客户端加密的集群。
  • 对于官方 MongoDB 4.2+ 兼容驱动程序，使用驱动程序特定的数据库连接构造函数 ( MongoClient) 创建数据库连接，自动加密规则包含在客户端字段级加密配置对象中。参考驱动程序 API 参考以获得更完整的文档和教程。

对于所有客户端，指定给客户端字段级加密参数的keyVault和必须授予对自动加密规则中指定的数据加密密钥和用于加密数据加密密钥的客户主密钥的访问权限。kmsProviders

要详细了解您的 CMK 和 Key Vault 集合，请参阅密钥保管库页面。

要了解有关加密算法的更多信息，请参阅加密算法页面。

要了解有关 CSFLE 特定MongoClient选项的更多信息，请参阅mongo 客户端页面。

加密模式 - 使用模式属性加密

patternProperties您可以在加密模式中使用关键字来为名称与正则表达式匹配的所有字段定义加密规则。

考虑一个集合MedCo.patients，其中每个文档都具有以下结构：

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

包含私有数据的字段由附加在字段名称末尾的“_PII”标记标识。

  • passportId_PIIString
  • bloodType_PIIString
  • medicalRecords_PIIArray
  • insurance.policyNumber_PIINumber
  • insurance.provider_PIIString

您可以使用patternProperties关键字来配置这些字段以进行加密，而无需单独标识每个字段，也无需使用完整的字段名称。通过使用匹配所有以“_PII”标记结尾的字段的正则表达式来执行此操作。

以下 JSON 架构使用patternProperties正则表达式来指定要加密的字段。

{
  "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",
          },
        },
      },
    },
  },
  },
}

以上自动加密规则将passportId_PIIString, bloodType_PIIString, medicalRecords_PIIArray, insurance.policyNumber_PIINumber, insurance.provider_PIIString字段标记为加密。

要了解有关patternProperties关键字的更多信息，请参阅 patternProperties 关键字。

译者：韩鹏帅

原文：CSFLE Encryption Schemas

Copyright © 上海锦木信息技术有限公司 all right reserved，powered by Gitbook文件修订时间： 2023-09-01 17:10:26

results matching ""

    No results matching ""