ClientEncryption.encrypt()

在此页面上

兼容性

语法
行为
示例
了解详情

ClientEncryption.encrypt(keyId, value, algorithm or encOptions)

ClientEncryption.encrypt()使用指定的keyId以及algorithm或encOptions指定的算法对value进行加密。 encrypt()支持对字段值进行显式（手动）加密。

返回：	`binary data`具有子类型6 的对象。

兼容性

此命令可用于以下环境中托管的部署：

MongoDB Atlas：用于云中 MongoDB 部署的完全托管服务

MongoDB Enterprise：基于订阅、自我管理的 MongoDB 版本
MongoDB Community：源代码可用、免费使用且可自行管理的 MongoDB 版本

语法

clientEncryption = db.getMongo().getClientEncryption()
clientEncryption.encrypt(
  keyId,
  value,
  algorithm or encOptions,
)

Parameter	类型	说明
`keyId`	`UUID`	用于加密 `value` 的数据加密密钥。 UUID 是具有子类型的BSON`binary data` `4`对象，用于标识特定数据加密密钥。如果为数据库连接配置的密钥保管库中不存在数据加密密钥，`encrypt()` 将返回错误。有关密钥保管库和数据加密密钥的详细信息，请参阅密钥保管库集合。
`value`	请参阅不支持的BSON类型。	要加密的值。
`algorithm` or `encOptions`	字符串或文档	要使用客户端字段级加密对字段进行显式加密，请执行以下操作：将 `algorithm` 指定为字符串，或将 `encOptions` 指定为包含字段 `algorithm` 的文档。支持的算法包括： `AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic` `AEAD_AES_256_CBC_HMAC_SHA_512-Random` 有关示例，请参阅设置客户端字段级加密算法。有关支持的加密算法的完整文档，请参阅字段和加密类型。要使用 Queryable Encryption 对字段进行显式加密，请执行以下操作：将 `algorithm` 指定为字符串，或将 `encOptions` 指定为包含字段的文档： `algorithm`：用于加密 `value` 的加密算法。支持的算法包括： `Indexed` `Unindexed` `contentionFactor`：当 `algorithm` 设置为 `Indexed` 时必需。与此字段的值的频率相关。 `queryType`：目前唯一支持的查询类型是 `"equality"`。当算法不是 `Indexed` 时，必须设置 `queryType`。有关示例，请参阅设置Queryable Encryption算法。有关支持的加密算法的详细信息，请参阅算法选择。

行为

mongosh客户端字段级别和可查询Queryable Encryption方法需要为客户端加密配置数据库连接。如果当前数据库连接不是在启用客户端字段级加密的情况下启动的，则：

使用 mongosh 中的 Mongo() 构造函数与所需的客户端字段级加密选项建立连接。Mongo() 方法支持以下用于“客户主密钥”(KMS) 管理的“密钥管理服务”(CMK) 提供商：

使用 mongosh 命令行选项，用所需选项建立连接。命令行选项仅支持用于 CMK 管理的 Amazon Web Services KMS 提供商。

不支持的 BSON 类型

不能使用encrypt()来加密具有以下BSON types的值：

minKey
maxKey
null
undefined

如果使用 AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic 加密字段， encrypt()不支持以下BSON types ：

double
decimal128
bool
object
array

示例

客户端字段级加密 (Client-Side Field Level Encryption)

以下示例使用本地托管的 KMS 进行客户端字段级加密配置。

创建加密连接

启动 mongosh
运行：
```
mongosh --nodb
```
--nodb 表示不连接到数据库。
生成密钥string
生成一个基本 64 96 字节的string ：
```
const TEST_LOCAL_KEY = require("crypto").randomBytes(96).toString("base64")
```

创建加密选项对象

要创建客户端字段级加密选项对象，请使用上一步中的 TEST_LOCAL_KEY string ：

   var autoEncryptionOpts = {
      "keyVaultNamespace" : "encryption.__dataKeys",
      "kmsProviders" : {
         "local" : {
            "key" : BinData(0, TEST_LOCAL_KEY)
         }
      }
   }

创建加密客户端对象
要创建加密的客户端对象，请使用Mongo()构造函数。将 mongodb://myMongo.example.net URI 替换为目标集群的连接string URI 。示例：
```
encryptedClient = Mongo(
   "mongodb://myMongo.example.net:27017/?replSetName=myMongo",
   autoEncryptionOpts
)
```

加密您的数据

检索ClientEncryption对象并使用ClientEncryption.encrypt()方法，通过特定数据加密密钥UUID和加密算法对值进行加密：

clientEncryption = encryptedClient.getClientEncryption();
clientEncryption.encrypt(
  UUID("64e2d87d-f168-493c-bbdf-a394535a2cb9"),
  "123-45-6789",
  "AEAD_AES_256_CBC_HMAC_SHA_512-Random"
)

还可以使用带有 algorithm 字段的文档来指定算法：

clientEncryption = encryptedClient.getClientEncryption();
clientEncryption.encrypt(
  UUID("64e2d87d-f168-493c-bbdf-a394535a2cb9"),
  "123-45-6789",
  { algorithm: "AEAD_AES_256_CBC_HMAC_SHA_512-Random" }
)

结果示例

如果成功， encrypt()将返回加密值：

BinData(6,"AmTi2H3xaEk8u9+jlFNaLLkC3Q/+kmwDbbWrq+h9nuv9W+u7A5a0UnpULBNZH+Q21fAztPpU09wpKPrju9dKfpN1Afpj1/ZhFcH6LYZOWSBBOAuUNjPLxMNSYOOuITuuYWo=")

有关在启用客户端字段级加密的情况下启动 MongoDB 连接的完整文档，请参阅Mongo() 。

可查询加密

以下示例使用本地托管的 KMS 进行 Queryable Encryption 配置。

创建加密连接

启动 mongosh
启动mongosh客户端。
```
mongosh --nodb
```
生成密钥
要为本地管理的密钥配置Queryable Encryption ，请生成一个不带换行符的基本 64 编码的 96 字节string 。
```
const TEST_LOCAL_KEY = require("crypto").randomBytes(96).toString("base64")
```
创建 Queryable Encryption 选项
使用生成的本地密钥字符串创建 Queryable Encryption 选项：
```
   var autoEncryptionOpts = {
   "keyVaultNamespace" : "encryption.__dataKeys",
   "kmsProviders" : {
      "local" : {
         "key" : BinData(0, TEST_LOCAL_KEY)
      }
   }
   }
```
创建加密客户端
使用配置了 Queryable Encryption 选项的 Mongo() 构造函数来创建数据库连接。将 mongodb://myMongo.example.net URI 替换为目标集群的连接字符串 URI。
```
encryptedClient = Mongo(
   "mongodb://myMongo.example.net:27017/?replSetName=myMongo",
   autoEncryptionOpts
)
```

加密您的数据

检索ClientEncryption对象并使用ClientEncryption.encrypt()方法，通过特定数据加密密钥UUID和加密算法对值进行加密：

const eDB = "encrypted"
const eKV = "__keyVault"
const clientEncryption = encryptedClient.getClientEncryption();
const keyVaultClient = Mongo().getDB(eDB).getCollection(eKV)
const dek = keyVaultClient.findOne({ keyAltNames: "dataKey1" })
clientEncryption.encrypt(
  dek._id,
  "123-45-6789",
  "Unindexed"
)

还可以使用包含字段的文档来指定算法：

algorithm
queryType
contentionFactor

const eDB = "encrypted"
const eKV = "__keyVault"
const clientEncryption = encryptedClient.getClientEncryption();
const keyVaultClient = Mongo().getDB(eDB).getCollection(eKV)
const dek = keyVaultClient.findOne({ keyAltNames: "dataKey1" })
clientEncryption.encrypt(
  dek._id,
  "123-45-6789",
  {
    algorithm: "Indexed",
    queryType: "equality",
    contentionFactor: 8
  }
)

结果示例

如果成功， encrypt()将返回加密值：

Binary(Buffer.from("05b100000005640020000000005ab3581a43e39a8e855b1ac87013e841735c09d19ae86535eea718dd56122ba50573002000000000703d2cba9832d90436c6c92eb232aa5b968cdcd7a3138570bc87ef0a9eb3a0e905630020000000009cb61df010b1bb54670a5ad979f25f4c48889059dfd8920782cf03dd27d1a50b05650020000000003f5acea703ea357d3eea4c6a5b19139a580089341424a247839fd4d5cf0d312a12636d00040000000000000000", "hex"), 6)

了解详情

有关在启用客户端字段级加密的情况下启动 MongoDB 连接的完整文档，请参阅Mongo() 。

后退

ClientEncryption.createEncryptedCollection

来年

ClientEncryption.decrypt