ClientEncryption.encrypt()

On this page本页内容

New in version 4.2.在版本4.2中新增。

ClientEncryption.encrypt(encryptionKeyId, value, encryptionAlgorithm)

ClientEncryption.encrypt() encrypts the value using the specified encryptionKeyId and encryptionAlgorithm. 使用指定的encryptionKeyId和encryptingAlgorithm对value进行加密。encrypt() supports explicit (manual) encryption of field values.支持字段值的显式（手动）加密。

encrypt() has the following syntax:具有以下语法：

clientEncryption = db.getMongo().getClientEncryption()
clientEncryption.encrypt(
  encryptionKeyId,
  value,
  encryptionAlgorithm
)
Parameter参数Type类型Description描述
encryptionKeyIdUUID

The data encryption key to use for encrypting the value.用于加密value的数据加密密钥。

The UUID is a BSON binary data object with subtype 4 that identifies a specific data encryption key. UUID是一个BSONbinary data对象，其子类型为4，用于标识特定的数据加密密钥。If the data encryption key does not exist in the key vault configured for the database connection, encrypt() returns an error. 如果为数据库连接配置的密钥库中不存在数据加密密钥，encrypt()将返回错误。See Encryption Key Vault for more information on key vaults and data encryption keys.有关密钥库和数据加密密钥的详细信息，请参阅加密密钥库。

valueSee Unsupported BSON Types.请参阅不支持的BSON类型。The value to encrypt.要加密的值。
encryptionAlgorithmstring

The encryption algorithm to use for encrypting the value.用于加密value的加密算法。

  • AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic
  • AEAD_AES_256_CBC_HMAC_SHA_512-Random

For complete documentation on the supported encryption algorithms, see Encryption Algorithms.有关支持的加密算法的完整文档，请参阅加密算法。
Returns:返回：A binary data object with subtype 6.子类型为6的binary data对象。

Behavior行为

Enable Client-Side Field Level Encryption on Database Connection在数据库连接上启用客户端字段级加密

The mongo client-side field level encryption methods require a database connection with client-side field level encryption enabled. mongo客户端字段级加密方法需要启用客户端字段级密码的数据库连接。If the current database connection was not initiated with client-side field level encryption enabled, either:如果当前数据库连接未在启用客户端字段级加密的情况下启动，请执行以下任一操作：

Unsupported BSON Types不支持的BSON类型

encrypt() does not supports encrypting values with the following BSON types:不支持使用以下BSON类型加密值：

  • minKey
  • maxKey
  • null
  • undefined

If encrypting a field using AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic, encrypt() does not support the following BSON types:如果使用AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic加密字段，encrypt()不支持以下BSON类型：

  • double
  • decimal128
  • bool
  • object
  • array
  • javascriptWithScope (Deprecated)

Example示例

The following example uses a locally managed KMS for the client-side field level encryption configuration.以下示例将本地管理的KMS用于客户端字段级加密配置。

Configuring client-side field level encryption for a locally managed key requires specifying a base64-encoded 96-byte string with no line breaks. 为本地管理的密钥配置客户端字段级加密需要指定不带换行符的base64编码的96字节字符串。The following operation generates a key that meets the stated requirements and loads it into the mongo shell:以下操作生成满足所述要求的密钥并将其加载到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'"

Create the client-side field level encryption object using the generated local key string:使用生成的本地密钥字符串创建客户端字段级加密对象：

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

Use the Mongo() constructor to create a database connection with the client-side field level encryption options. 使用Mongo()构造函数创建具有客户端字段级加密选项的数据库连接。Replace the mongodb://myMongo.example.net URI with the connection string URI of the target cluster.更换mongodb://myMongo.example.net具有目标群集的连接字符串URI的URI。

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

Retrieve the ClientEncryption object and use the ClientEncryption.encrypt() method to encrypt a value using a specific data encryption key UUID and encryption algorithm:检索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"
)

If sucessful, encrypt() returns the encrypted value:如果成功，encrypt()将返回加密值：

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

For complete documentation on initiating MongoDB connections with client-side field level encryption enabled, see Mongo().有关在启用客户端字段级加密的情况下启动MongoDB连接的完整文档，请参阅Mongo()。

←  getClientEncryption()ClientEncryption.decrypt() →