KeyVault.createKey()

在此页面上

行为

例子

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

将数据加密密钥添加到与数据库连接关联的密钥保管库。客户端字段级加密使用数据加密密钥来支持字段值的加密和解密。

createKey() 通过以下语法实现：

keyVault = db.getMongo().getKeyVault()
keyVault.createKey(
  keyManagementService,
  customerMasterKey,
  [ "keyAltName" ]
)

Parameter	类型	说明
`keyManagementService`	字符串	必需用于检索客户主密钥 (CMK) 的密钥管理服务 (KMS )。接受以下参数： `aws` 用于Amazon Web Services KMS 。需要为`customerMasterKey`指定客户主密钥 (CMK) 字符串。 `azure` 用于Azure Key Vault 。需要为`customerMasterKey`指定客户主密钥 (CMK) 文档。版本 5.0 中的新增功能。 `gcp` 用于Google Cloud Platform KMS 。需要为`customerMasterKey`指定客户主密钥 (CMK) 文档。版本 5.0 中的新增功能。 `local` 用于本地托管的密钥。如果未为`database connection`配置指定的 KMS，则数据加密密钥创建将失败。
`customerMasterKey`	字符串或文档	用于加密数据加密密钥的客户主密钥 (CMK)。如果`keyManagementService`为`aws` 、 `azure`或`gcp` ，则为必填项。根据您的 KMS 提供商，按如下方式提供客户主密钥：对于Amazon Web ServicesKMS ，请指定完整的资源名称Amazon (ARN) 作为单个string 的主密钥。对于Azure Key Vault KMS，请指定包含以下键值对的文档： `keyName` - Azure Key Vault 名称 `keyVaultEndpoint` - 要使用的 Azure Key Vault 的 DNS 名称 `keyVersion` — 可选。 `keyName`中指定的密钥版本（如果适用）版本 5.0 中的新增功能。对于Google Cloud Platform KMS ，请指定包含以下键值对的文档： `projectId` - GCP 项目名称 `location` - KMS 密钥环的位置 `keyRing` - KMS 密钥环的名称（通常为“全局”） `keyName` - 要使用的密钥的名称 `keyVersion` — 可选。 `keyName`中指定的密钥版本（如果适用）版本 5.0 中的新增功能。 `createKey()`请求KMS使用指定的集合扫描加密数据加密密钥材料。如果集合扫描不存在，或者`AutoEncryptionOpts`配置没有足够的特权来使用集合扫描，则`createKey()`会返回错误。如果`keyManagementService`为`local` ，则此参数无效，可以安全地省略。
`keyAltName`	字符串数组	Optional 数据加密密钥的替代名称。使用`keyAltName`提高特定数据加密密钥的可查找性，或作为注释的模拟。 `getKeyVault()`方法自动在`keyAltNames`字段上创建唯一索引，并使用仅针对存在`keyAltNames`的文档的部分索引筛选器。
`options`	文档	Optional 指定新密钥选项的文档。 `options`具有以下字段： `masterKey`：用于加密数据的新主密钥。 `keyAltNames`：备用名称数组，每个主密钥一个。 `keyMaterial`：用于创建密钥的 bindata。

返回：	创建的数据加密密钥的`UUID`唯一标识符。

行为

需要在数据库连接上配置客户端字段级加密

mongosh 客户端字段级加密方法需要启用客户端字段级加密的数据库连接。如果当前数据库连接在启动时未启用客户端字段级加密，则任选以下其一：

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

例子

以下示例用于快速评估客户端字段级加密。有关将KeyVault.createKey()与每个受支持的 KMS提供程序结合使用的具体示例，请参阅创建数据密钥。

为本地管理的密钥配置客户端字段级加密：

生成不带换行符的 base64 编码的 96 字节字符串
使用 mongosh 加载密钥

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

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

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

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

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

检索keyVault对象并使用KeyVault.createKey()方法，利用本地托管的密钥创建新的数据加密密钥密钥：

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

如果成功， createKey()将返回新数据加密密钥的UUID 。要从密钥保管库检索新的数据加密密钥文档，请执行以下任一操作：

使用getKey()检索UUID创建的密钥。
-或-
使用getKeyByAltName()按备用名称检索密钥。

后退

KeyVault.createDataKey

来年

KeyVault.deleteKey