ClientEncryption.encrypt()

在此页面上

兼容性

语法
行为
例子

MongoDB 5.0 已于 10 月 2024结束生命周期。不再支持此版本的文档。要升级5.0 部署，请参阅 MongoDB.6 0升级过程。

ClientEncryption.encrypt(encryptionKeyId, value, encryptionAlgorithm)

ClientEncryption.encrypt()valueencryptionKeyId使用指定的和encryptionAlgorithm 加密。encrypt()支持对字段值进行显式（手动）加密。

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

兼容性

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

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

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

语法

clientEncryption = db.getMongo().getClientEncryption()
clientEncryption.encrypt(
  encryptionKeyId,
  value,
  encryptionAlgorithm
)

Parameter	类型	说明
`encryptionKeyId`	`UUID`	用于加密 `value` 的数据加密密钥。 UUID 是具有子类型的BSON`binary data` `4`对象，用于标识特定数据加密密钥。如果为数据库连接配置的密钥保管库中不存在数据加密密钥，`encrypt()` 将返回错误。有关密钥保管库和数据加密密钥的详细信息，请参阅加密密钥保管库。
`value`	请参阅不支持的BSON 类型。	要加密的值。
`encryptionAlgorithm`	字符串	用于加密`value`的加密算法。 `AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic` `AEAD_AES_256_CBC_HMAC_SHA_512-Random` 有关支持的加密算法的完整文档，请参阅加密算法。

行为

在数据库连接上启用客户端字段级加密

mongo客户端字段级加密方法需要启用客户端字段级加密的数据库连接。如果当前数据库连接不是在启用客户端字段级加密的情况下启动的，则：

使用 ShellMongo()mongo 中的构造函数与所需的客户端字段级加密选项建立连接。Mongo()方法支持以下用于客户主密钥 (CMK) 管理的密钥管理服务 (KMS) 提供商：
or
使用mongo Shell命令行选项，通过所需选项建立连接。命令行选项仅支持用于客户主密钥管理的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

例子

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

为本地托管的密钥配置客户端字段级加密需要指定一个不带换行符的 base64 编码的 96 字节字符串。以下操作生成满足所述要求的密钥并将其加载到mongo shell：

TEST_LOCAL_KEY=$(echo "$(head -c 96 /dev/urandom | base64 | tr -d '\n')")
mongosh --nodb --shell --eval "var TEST_LOCAL_KEY='$TEST_LOCAL_KEY'"

使用生成的本地密钥字符串创建客户端字段级加密对象：

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

使用Mongo()构造函数创建具有客户端字段级加密选项的数据库连接。将mongodb://myMongo.example.net URI 替换为目标集群的连接字符串 URI 。

encryptedClient = Mongo(
  "mongodb://myMongo.example.net:27017/?replSetName=myMongo",
  ClientSideFieldLevelEncryptionOptions
)

检索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"
)

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

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

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

后退

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

来年

ClientEncryption.decrypt