KeyVault.createKey()

On this page本页内容

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

KeyVault.createKey(keyManagementService, customerMasterKey, ["keyAltName"])

Adds a data encryption key to the key vault associated to the database connection. 将数据加密密钥添加到与数据库连接关联的密钥库中。Client-side field level encryption uses data encryption keys for supporting encryption and decryption of field values.客户端字段级加密使用数据加密密钥来支持字段值的加密和解密。

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

keyVault = db.getMongo().getKeyVault()
keyVault.createKey(
  keyManagementService,
  customerMasterKey,
  [ "keyAltName" ]
)
Parameter参数Type类型Description描述
keyManagementServicestring

Required必需

The Key Management Service (KMS) to use for retrieving the Customer Master Key (CMK). Accepts the following parameters:

  • aws for Amazon Web Services KMS. Requires specifying a Customer Master Key (CMK) string for customerMasterKey.

  • azure for Azure Key Vault. Requires specifying a Customer Master Key (CMK) document for customerMasterKey.

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

  • gcp for Google Cloud Platform KMS. Requires specifying a Customer Master Key (CMK) document for customerMasterKey.

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

  • local for a locally managed key.

If the database connection was not configured with the specified KMS, data encryption key creation fails.

customerMasterKeystring or document

The Customer Master Key (CMK) to use for encrypting the data encryption key. Required if keyManagementService is aws, azure, or gcp.

Provide the CMK as follows depending on your KMS provider:

  • For the Amazon Web Services KMS, specify the full Amazon Resource Name (ARN) of the master key as a single string.

  • For the Azure Key Vault KMS, specify a document containing the following key value pairs:

    • keyName - The Azure Key Vault Name
    • keyVaultEndpoint - The DNS name of the Azure Key Vault to use
    • keyVersion - Optional. The version of the key specified in keyName, if applicable

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

  • For the Google Cloud Platform KMS, specify a document containing the following key value pairs:

    • projectId - The GCP project name
    • location - The location of the KMS keyring
    • keyRing - The name of the KMS keyring (often 'global')
    • keyName - The name of the key to use
    • keyVersion - Optional. The version of the key specified in keyName, if applicable

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

createKey() requests that the KMS encrypt the data encryption key material using the specified CMK. If the CMK does not exist or if the ClientSideFieldLevelEncryptionOptions configuration does not have sufficient privileges to use the CMK, createKey() returns an error.

Changed in version 4.2.3.在版本4.2.3中更改。

This parameter has no effect if keyManagementService is local and can be safely omitted. Prior to MongoDB 4.2.3, if keyManagementService is local this parameter must be an empty string ".

keyAltNamearray of strings

Optional可选

The alternative name for the data encryption key. Use keyAltName to improve findability of a specific data encryption key, or as an analog to a comment.

The getKeyVault() method automatically creates a unique index on the keyAltNames field with a partial index filter for only documents where keyAltNames exists.

Returns:返回：The UUID unique identifier of the created data encryption key.创建的数据加密密钥的UUID唯一标识符。

Behavior行为

Requires Configuring 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:如果当前数据库连接未在启用客户端字段级加密的情况下启动，请执行以下任一操作：

Example示例

The following example is intended for rapid evaluation of client-side field level encryption. 以下示例用于快速评估客户端字段级加密。For specific examples of using KeyVault.createKey() with each supported KMS provider, see Create a Data Encryption Key.有关在每个受支持的KMS提供程序中使用KeyVault.createKey()的具体示例，请参阅创建数据加密密钥。

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:以下操作生成满足所述要求的密钥，并将其加载到mongoshell中：

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 keyVault object and use the KeyVault.createKey() method to create a new data encryption key using the locally managed key:检索keyVault对象并使用KeyVault.createKey()方法使用本地托管密钥创建新的数据加密密钥：

keyVault = encryptedClient.getKeyVault()
keyVault.createKey("local", ["data-encryption-key"])

If successful, createKey() returns the UUID of the new data encryption key. 如果成功，createKey()将返回新数据加密密钥的UUID。To retrieve the new data encryption key document from the key vault, either:要从密钥库中检索新的数据加密密钥文档，请执行以下操作之一：

←  getKeyVault()KeyVault.deleteKey() →