Docs 菜单
Docs 主页
/
MongoDB Manual
/ / /

ClientEncryption.encrypt()

在此页面上

  • 语法
  • 行为
  • 示例
  • 了解详情
ClientEncryption.encrypt(keyId, value, algorithm or encOptions)

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

返回:binary data具有 子类型6 的 对象 。
clientEncryption = db.getMongo().getClientEncryption()
clientEncryption.encrypt(
keyId,
value,
algorithm or encOptions,
)
Parameter
类型
说明

keyId

UUID

用于加密 value 的数据加密密钥。

UUID 是具有子类型 的BSONbinary data 4对象,用于标识特定数据加密密钥。如果为数据库连接配置的密钥保管库中不存在数据加密密钥,encrypt() 将返回错误。有关密钥保管库和数据加密密钥的详细信息,请参阅密钥保管库集合。

value

要加密的值。

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方法需要为客户端加密配置数据库连接。 如果当前数据库连接不是在启用客户端字段级加密的情况下启动的,则:

or

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

  • minKey

  • maxKey

  • null

  • undefined

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

  • double

  • decimal128

  • bool

  • object

  • array

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

1
  1. 启动 mongosh

    运行:

    mongosh --nodb

    --nodb 表示不连接到数据库。

  2. 生成密钥string

    生成一个基本 64 96 字节的string :

    const TEST_LOCAL_KEY = require("crypto").randomBytes(96).toString("base64")
  3. 创建加密选项对象

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

    var autoEncryptionOpts = {
    "keyVaultNamespace" : "encryption.__dataKeys",
    "kmsProviders" : {
    "local" : {
    "key" : BinData(0, TEST_LOCAL_KEY)
    }
    }
    }
  4. 创建加密客户端对象

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

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

检索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 配置。

1
  1. 启动 mongosh

    启动mongosh客户端。

    mongosh --nodb
  2. 生成密钥

    要为本地管理的密钥配置Queryable Encryption ,请生成一个不带换行符的基本 64 编码的 96 字节string 。

    const TEST_LOCAL_KEY = require("crypto").randomBytes(96).toString("base64")
  3. 创建 Queryable Encryption 选项

    使用生成的本地密钥字符串创建 Queryable Encryption 选项:

    var autoEncryptionOpts = {
    "keyVaultNamespace" : "encryption.__dataKeys",
    "kmsProviders" : {
    "local" : {
    "key" : BinData(0, TEST_LOCAL_KEY)
    }
    }
    }
  4. 创建加密客户端

    使用配置了 Queryable Encryption 选项的 Mongo() 构造函数来创建数据库连接。将 mongodb://myMongo.example.net URI 替换为目标集群的连接字符串 URI

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

检索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: 4
}
)

如果成功, encrypt()将返回加密值:

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

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

后退

ClientEncryption.createEncryptedCollection