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

管理数据加密密钥

在此页面上

  • 创建数据加密密钥
  • 管理数据加密密钥的备用名称
  • 删除数据加密密钥
  • 检索现有数据加密密钥

4.2 版本中的新增功能

客户端字段级加密使用数据加密密钥进行加密和解密。 mongosh辅助方法 getKeyVault()返回一个密钥保管库对象,用于创建、修改和删除数据加密密钥。

本页介绍使用mongosh进行客户端字段级加密,而不涉及任何官方MongoDB 4.2 + 兼容驾驶员。 有关特定于驱动程序的数据加密密钥管理方法和语法,请参阅相关文档

以下过程使用mongosh创建数据加密密钥,用于客户端字段级加密和解密。 有关使用4.2 + 兼容驱动程序进行数据加密密钥管理的指导,请参阅驱动程序文档

使用以下标签页选择适合您部署的 KMS

1

为 AWS KMS 配置客户端字段级加密需要一个 AWS 访问密钥 ID 及其相关的秘密访问密钥。AWS 访问密钥必须与具有 KMS 服务的所有列出读取 权限的 IAM 用户相对应。

为了降低这些凭证泄漏到日志中的风险,以下过程使用环境变量将这些值传递到mongosh中。

首先,确保已根据平台文档配置以下环境变量:

  • AWS_ACCESS_KEY_ID

  • AWS_SECRET_ACCESS_KEY

接下来,使用mongosh --eval--shell--nodb 选项创建 会话:

mongosh --eval "
var AWS_ACCESS_KEY_ID = '$AWS_ACCESS_KEY_ID'
var AWS_SECRET_ACCESS_KEY = '$AWS_SECRET_ACCESS_KEY'
" \
--shell --nodb

此示例在不连接MongoDB 数据库的情况下打开mongosh--eval选项将 { mongosh } 中的AWS_ACCESS_KEY_IDAWS_SECRET_ACCESS_KEY变量设置为相应环境变量的值。 Amazon Web ServicesCLI也支持指定的变量。

2

mongosh中,创建新的ClientSideFieldLevelEncryptionOptions变量,用于存储客户端字段级加密配置文档:

var ClientSideFieldLevelEncryptionOptions = {
"keyVaultNamespace" : "encryption.__dataKeys",
"kmsProviders" : {
"aws" : {
"accessKeyId" : AWS_ACCESS_KEY_ID,
"secretAccessKey" : AWS_SECRET_ACCESS_KEY
}
}
}
3

mongosh中,使用Mongo()构造函数建立与目标集群的数据库连接。 将ClientSideFieldLevelEncryptionOptions文档指定为Mongo()构造函数的第二个参数,为客户端字段级加密配置连接:

csfleDatabaseConnection = Mongo(
"mongodb://replaceMe.example.net:27017/?replicaSet=myMongoCluster",
ClientSideFieldLevelEncryptionOptions
)

replaceMe.example.net URI替换为目标集群的连接string 。

使用 csfleDatabaseConnection对象访问权限客户端字段级加密shell方法。

有关建立为客户端字段级加密配置的数据库连接的完整文档,请参阅Mongo()构造函数参考。

4

csfleDatabaseConnection数据库连接对象上使用getKeyVault()方法创建keyVault对象:

keyVault = csfleDatabaseConnection.getKeyVault();

重要

客户端字段级加密取决于服务器强制执行的密钥备用名称的唯一性。 如果不存在唯一索引, getKeyVault()会在keyAltNames上创建唯一索引。 请勿 删除 创建的 唯一索引 getKeyVault()

5

keyVault对象使用KeyVault.createKey()方法,在密钥保管库中创建新的数据加密密钥:

keyVault.createKey(
"aws",
"arn:aws:kms:region:account:key/keystring",
[ "keyAlternateName" ]
)

其中:

  • 第一个参数必须"aws" 才能指定已配置的 Amazon Web Services KMS。

  • 第二个参数 必须 是完整的 Amazon 资源名称 (ARN) 客户主密钥 (CMK) 的 ID。MongoDB 使用指定的 CMK 来加密数据加密密钥。

  • 第三个参数可以是数据加密密钥的一个或多个keyAltNames的大量。 每个密钥备用名称必须是唯一的。 getKeyVault()keyAltNames上创建唯一索引,以实施字段的唯一性(如果尚不存在)。 密钥备用名称有利于数据加密密钥的查找。

如果成功, createKey()将返回新数据加密密钥的UUIDUUID是具有子类型4的BSON Binary (BinData)对象,用于唯一标识数据加密密钥。 UUID string是根本的二进制数据的十六进制表示形式。

如果要向官方MongoDB驱动程序提供数据加密密钥以配置自动客户端字段级加密,则必须使用 UUID string的 base64 表示形式。

您可以在mongosh中运行以下操作,将 UUID 十六进制string转换为其 base64 表示形式:

UUID("b4b41b33-5c97-412e-a02b-743498346079").base64()

向此命令提供您自己的数据加密密钥的UUID ,如上面createKey()返回的那样,或如检索现有数据加密密钥中所述。

1

为 Azure Key Vault 配置客户端字段级加密需要有效的租户 ID、客户端 ID 和客户端密钥。

为了降低这些凭证泄漏到日志中的风险,以下过程使用环境变量将这些值传递到mongosh中。

首先,确保已根据平台文档配置以下环境变量:

  • AZURE_TENANT_ID

  • AZURE_CLIENT_ID

  • AZURE_CLIENT_SECRET

接下来,使用mongosh --eval--shell--nodb 选项创建 会话:

mongosh --eval "
var AZURE_TENANT_ID = '$AZURE_TENANT_ID'
var AZURE_CLIENT_ID = '$AZURE_CLIENT_ID'
var AZURE_CLIENT_SECRET = '$AZURE_CLIENT_SECRET'
" \
--shell --nodb

此示例在不连接MongoDB 数据库的情况下打开mongosh--eval选项将 { mongosh } 中的AZURE_TENANT_IDAZURE_CLIENT_IDAZURE_CLIENT_SECRET变量设置为相应环境变量的值。

2

mongosh中,创建新的ClientSideFieldLevelEncryptionOptions变量,用于存储客户端字段级加密配置文档:

var ClientSideFieldLevelEncryptionOptions = {
"keyVaultNamespace" : "encryption.__dataKeys",
"kmsProviders" : {
"azure" : {
"tenantId" : AZURE_TENANT_ID,
"clientId" : AZURE_CLIENT_ID,
"clientSecret" : AZURE_CLIENT_SECRET
}
}
}
3

mongosh中,使用Mongo()构造函数建立与目标集群的数据库连接。 将ClientSideFieldLevelEncryptionOptions文档指定为Mongo()构造函数的第二个参数,为客户端字段级加密配置连接:

csfleDatabaseConnection = Mongo(
"mongodb://replaceMe.example.net:27017/?replicaSet=myMongoCluster",
ClientSideFieldLevelEncryptionOptions
)

replaceMe.example.net URI替换为目标集群的连接string 。

使用 csfleDatabaseConnection对象访问权限客户端字段级加密shell方法。

有关建立为客户端字段级加密配置的数据库连接的完整文档,请参阅Mongo()构造函数参考。

4

csfleDatabaseConnection数据库连接对象上使用getKeyVault()方法创建keyVault对象:

keyVault = csfleDatabaseConnection.getKeyVault();

重要

客户端字段级加密取决于服务器强制执行的密钥备用名称的唯一性。 如果不存在唯一索引, getKeyVault()会在keyAltNames上创建唯一索引。 请勿 删除 创建的 唯一索引 getKeyVault()

5

keyVault对象使用KeyVault.createKey()方法,在密钥保管库中创建新的数据加密密钥:

keyVault.createKey(
"azure",
{ keyName: "keyvaultname", keyVaultEndpoint: "endpointname" },
[ "keyAlternateName" ]
)

其中:

  • 第一个参数必须"azure"才能指定已配置的Azure Key Vault。

  • 第二个参数必须是包含以下内容的文档:

  • 第三个参数可以是数据加密密钥的一个或多个keyAltNames的大量。 每个密钥备用名称必须是唯一的。 getKeyVault()keyAltNames上创建唯一索引,以实施字段的唯一性(如果尚不存在)。 密钥备用名称有利于数据加密密钥的查找。

如果成功, createKey()将返回新数据加密密钥的UUIDUUID是具有子类型4的BSON Binary (BinData)对象,用于唯一标识数据加密密钥。 UUID string是根本的二进制数据的十六进制表示形式。

如果要向官方MongoDB驱动程序提供数据加密密钥以配置自动客户端字段级加密,则必须使用 UUID string的 base64 表示形式。

您可以在mongosh中运行以下操作,将 UUID 十六进制string转换为其 base64 表示形式:

UUID("b4b41b33-5c97-412e-a02b-743498346079").base64()

向此命令提供您自己的数据加密密钥的UUID ,如上面createKey()返回的那样,或如检索现有数据加密密钥中所述。

1

为GCP KMS配置客户端字段级加密需要GCP电子邮件及其关联的私钥。

为了降低这些凭证泄漏到日志中的风险,以下过程使用环境变量将这些值传递到mongosh中。

首先,确保已根据平台文档配置以下环境变量:

  • GCP_EMAIL

  • GCP_PRIVATEKEY

接下来,使用mongosh --eval--shell--nodb 选项创建 会话:

mongosh --eval "
var GCP_EMAIL = '$GCP_EMAIL'
var GCP_PRIVATEKEY = '$GCP_PRIVATEKEY'
" \
--shell --nodb

此示例在不连接MongoDB 数据库的情况下打开mongosh--eval选项将 { mongosh } 中的GCP_EMAILGCP_PRIVATEKEY变量设置为相应环境变量的值。

2

mongosh中,创建新的ClientSideFieldLevelEncryptionOptions变量,用于存储客户端字段级加密配置文档:

var ClientSideFieldLevelEncryptionOptions = {
"keyVaultNamespace" : "encryption.__dataKeys",
"kmsProviders" : {
"gcp" : {
"email" : GCP_EMAIL,
"privateKey" : GCP_PRIVATEKEY
}
}
}
3

mongosh中,使用Mongo()构造函数建立与目标集群的数据库连接。 将ClientSideFieldLevelEncryptionOptions文档指定为Mongo()构造函数的第二个参数,为客户端字段级加密配置连接:

csfleDatabaseConnection = Mongo(
"mongodb://replaceMe.example.net:27017/?replicaSet=myMongoCluster",
ClientSideFieldLevelEncryptionOptions
)

replaceMe.example.net URI替换为目标集群的连接string 。

使用 csfleDatabaseConnection对象访问权限客户端字段级加密shell方法。

有关建立为客户端字段级加密配置的数据库连接的完整文档,请参阅Mongo()构造函数参考。

4

csfleDatabaseConnection数据库连接对象上使用getKeyVault()方法创建keyVault对象:

keyVault = csfleDatabaseConnection.getKeyVault();

重要

客户端字段级加密取决于服务器强制执行的密钥备用名称的唯一性。 如果不存在唯一索引, getKeyVault()会在keyAltNames上创建唯一索引。 请勿 删除 创建的 唯一索引 getKeyVault()

5

keyVault对象使用KeyVault.createKey()方法,在密钥保管库中创建新的数据加密密钥:

keyVault.createKey(
"gcp",
{
projectId: "projectid",
location: "locationname",
keyRing: "keyringname",
keyName: "keyname"
},
[ "keyAlternateName" ]
)

其中:

  • 第一个参数必须"gcp",以指定已配置的Google Cloud Platform KMS 。

  • 第二个参数必须是包含以下内容的文档

    • projectid 是GCP项目的名称,例如 my-project

    • locationname 是KMS密钥环的位置,例如 global

    • keyringname 是KMS密钥环的名称,例如 my-keyring

    • keyname 是密钥的名称。

  • 第三个参数可以是数据加密密钥的一个或多个keyAltNames的大量。 每个密钥备用名称必须是唯一的。 getKeyVault()keyAltNames上创建唯一索引,以实施字段的唯一性(如果尚不存在)。 密钥备用名称有利于数据加密密钥的查找。

如果成功, createKey()将返回新数据加密密钥的UUIDUUID是具有子类型4的BSON Binary (BinData)对象,用于唯一标识数据加密密钥。 UUID string是根本的二进制数据的十六进制表示形式。

如果要向官方MongoDB驱动程序提供数据加密密钥以配置自动客户端字段级加密,则必须使用 UUID string的 base64 表示形式。

您可以在mongosh中运行以下操作,将 UUID 十六进制string转换为其 base64 表示形式:

UUID("b4b41b33-5c97-412e-a02b-743498346079").base64()

向此命令提供您自己的数据加密密钥的UUID ,如上面createKey()返回的那样,或如检索现有数据加密密钥中所述。

1

为本地管理的密钥配置客户端字段级加密需要指定一个没有换行符的基本 64 编码的 96 字节string 。

为了降低这些凭证泄漏到日志中的风险,以下过程使用环境变量将这些值传递到mongosh中。

以下操作生成满足所述要求的密钥并将其添加到用户的~/.profile中。 如果键DEV_LOCAL_KEY已存在,请跳过此操作。

echo "export DEV_LOCAL_KEY=\"$(head -c 96 /dev/urandom | base64 | tr -d '\n')\"" >> ~/.profile

托管操作系统可能需要注销并重新登录才能刷新加载的环境变量。 或者,可以使用命令 source ~/.profile 手动刷新shell 。

注意

特定的托管操作系统或shell可能有不同的过程来设置持久环境变量。 请根据您的托管操作系统或shell的文档了解更具体的过程。

2

使用mongosh --eval--shell--nodb 选项创建 会话:

mongosh --eval "var LOCAL_KEY = '$DEV_LOCAL_KEY' " \
--shell --nodb

该示例会自动打开mongosh ,而无需连接到MongoDB 数据库。 --eval选项将mongosh中的LOCAL_KEY变量设置为相应环境变量的值。

3

mongosh中,创建新的ClientSideFieldLevelEncryptionOptions变量,用于存储客户端字段级加密配置文档:

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

mongosh中,使用Mongo()构造函数建立与目标集群的数据库连接。 将ClientSideFieldLevelEncryptionOptions文档指定为Mongo()构造函数的第二个参数,为客户端字段级加密配置连接:

csfleDatabaseConnection = Mongo(
"mongodb://replaceMe.example.net:27017/?replicaSet=myMongoCluster",
ClientSideFieldLevelEncryptionOptions
)

replaceMe.example.net URI替换为目标集群的连接string 。

使用 csfleDatabaseConnection对象访问权限客户端字段级加密shell方法。

有关建立为客户端字段级加密配置的数据库连接的完整文档,请参阅Mongo()构造函数参考。

5

csfleDatabaseConnection数据库连接对象上使用getKeyVault()方法创建keyVault对象:

keyVault = csfleDatabaseConnection.getKeyVault();

重要

客户端字段级加密取决于服务器强制执行的密钥备用名称的唯一性。 如果不存在唯一索引, getKeyVault()会在keyAltNames上创建唯一索引。 请勿 删除 创建的 唯一索引 getKeyVault()

6

keyVault对象使用KeyVault.createKey()方法,在密钥保管库中创建新的数据加密密钥:

keyVault.createKey(
"local",
[ "keyAlternateName" ]
)

其中:

  • 第一个参数必须local 才能指定配置的本地管理密钥。

  • 第二个参数可以是数据加密密钥的一个或多个keyAltNames的大量。 每个密钥备用名称必须是唯一的。 getKeyVault()keyAltNames上创建唯一索引,以实施字段的唯一性(如果尚不存在)。 密钥备用名称有利于数据加密密钥的查找。

如果成功, createKey()将返回新数据加密密钥的UUIDUUID是具有子类型4的BSON Binary (BinData)对象,用于唯一标识数据加密密钥。 UUID string是根本的二进制数据的十六进制表示形式。

如果要向官方MongoDB驱动程序提供数据加密密钥以配置自动客户端字段级加密,则必须使用 UUID string的 base64 表示形式。

您可以在mongosh中运行以下操作,将 UUID 十六进制string转换为其 base64 表示形式:

UUID("b4b41b33-5c97-412e-a02b-743498346079").base64()

向此命令提供您自己的数据加密密钥的UUID ,如上面createKey()返回的那样,或如检索现有数据加密密钥中所述。

以下过程使用mongosh管理数据加密密钥的备用名称。 有关使用4.2 + 兼容驱动程序进行数据加密密钥管理的指导,请参阅驱动程序文档

如果仍在上述“mongosh 创建数据加密密钥” 步骤中配置的 会话中,则可以直接跳到步骤5 。

使用以下标签页选择适合您部署的KMS

1

为 AWS KMS 配置客户端字段级加密需要一个 AWS 访问密钥 ID 及其相关的秘密访问密钥。AWS 访问密钥必须与具有 KMS 服务的所有列出读取 权限的 IAM 用户相对应。

为了降低这些凭证泄漏到日志中的风险,以下过程使用环境变量将这些值传递到mongosh中。

首先,确保已根据平台文档配置以下环境变量:

  • AWS_ACCESS_KEY_ID

  • AWS_SECRET_ACCESS_KEY

接下来,使用mongosh --eval--shell--nodb 选项创建 会话:

mongosh --eval "
var AWS_ACCESS_KEY_ID = '$AWS_ACCESS_KEY_ID'
var AWS_SECRET_ACCESS_KEY = '$AWS_SECRET_ACCESS_KEY'
" \
--shell --nodb

此示例在不连接MongoDB 数据库的情况下打开mongosh--eval选项将 { mongosh } 中的AWS_ACCESS_KEY_IDAWS_SECRET_ACCESS_KEY变量设置为相应环境变量的值。 Amazon Web ServicesCLI也支持指定的变量。

2

mongosh中,创建新的ClientSideFieldLevelEncryptionOptions变量,用于存储客户端字段级加密配置文档:

var ClientSideFieldLevelEncryptionOptions = {
"keyVaultNamespace" : "encryption.__dataKeys",
"kmsProviders" : {
"aws" : {
"accessKeyId" : AWS_ACCESS_KEY_ID,
"secretAccessKey" : AWS_SECRET_ACCESS_KEY
}
}
}
3

mongosh中,使用Mongo()构造函数建立与目标集群的数据库连接。 将ClientSideFieldLevelEncryptionOptions文档指定为Mongo()构造函数的第二个参数,为客户端字段级加密配置连接:

csfleDatabaseConnection = Mongo(
"mongodb://replaceMe.example.net:27017/?replicaSet=myMongoCluster",
ClientSideFieldLevelEncryptionOptions
)

replaceMe.example.net URI替换为目标集群的连接string 。

使用 csfleDatabaseConnection对象访问权限客户端字段级加密shell方法。

有关建立为客户端字段级加密配置的数据库连接的完整文档,请参阅Mongo()构造函数参考。

4

csfleDatabaseConnection数据库连接对象上使用getKeyVault()方法创建keyVault对象:

keyVault = csfleDatabaseConnection.getKeyVault();

重要

客户端字段级加密取决于服务器强制执行的密钥备用名称的唯一性。 如果不存在唯一索引, getKeyVault()会在keyAltNames上创建唯一索引。 请勿 删除 创建的 唯一索引 getKeyVault()

5

使用以下步骤添加或删除现有的密钥备用名称。

添加密钥备用名称

重要

客户端字段级加密取决于服务器强制执行的密钥备用名称的唯一性。 在添加新的密钥备用名称之前,请验证keyAltNames上是否存在唯一索引。 如果删除了唯一索引,则必须在添加任何键备用名称之前重新创建该索引。

使用KeyVault.addKeyAlternateName()为数据加密密钥添加新的备用名称:

keyVault.addKeyAlternateName(
UUID("<Replace Me With The UUID Of The Key To Modify"),
"NewKeyAltNameForMyFirstCSFLEDataKey"
)

其中:

  • 第一个参数必须是要修改的数据加密密钥的UUID

  • 第二个参数必须是唯一的string 。 getKeyVault()keyAltNames上创建唯一索引,以实施密钥备用名称的唯一性。

KeyVault.addKeyAlternateName()返回修改的数据加密密钥文档。 使用KeyVault.getKey()检索修改后的数据加密密钥。

删除密钥备用名称

使用KeyVault.removeKeyAlternateName()从数据加密密钥中删除密钥备用名称:

keyVault.removeKeyAlternateName(
UUID("<Replace Me With The UUID Of The Key To Modify"),
"NewKeyAltNameForMyFirstCSFLEDataKey"
)

其中:

  • 第一个参数必须是要修改的数据加密密钥的UUID

  • 第二个参数必须是string键备用名称。

KeyVault.removeKeyAlternateName()返回修改的数据加密密钥。 使用KeyVault.getKey()检索修改后的数据加密密钥。

1

为 Azure Key Vault 配置客户端字段级加密需要有效的租户 ID、客户端 ID 和客户端密钥。

为了降低这些凭证泄漏到日志中的风险,以下过程使用环境变量将这些值传递到mongosh中。

首先,确保已根据平台文档配置以下环境变量:

  • AZURE_TENANT_ID

  • AZURE_CLIENT_ID

  • AZURE_CLIENT_SECRET

接下来,使用mongosh --eval--shell--nodb 选项创建 会话:

mongosh --eval "
var AZURE_TENANT_ID = '$AZURE_TENANT_ID'
var AZURE_CLIENT_ID = '$AZURE_CLIENT_ID'
var AZURE_CLIENT_SECRET = '$AZURE_CLIENT_SECRET'
" \
--shell --nodb

此示例在不连接MongoDB 数据库的情况下打开mongosh--eval选项将 { mongosh } 中的AZURE_TENANT_IDAZURE_CLIENT_IDAZURE_CLIENT_SECRET变量设置为相应环境变量的值。

2

mongosh中,创建新的ClientSideFieldLevelEncryptionOptions变量,用于存储客户端字段级加密配置文档:

var ClientSideFieldLevelEncryptionOptions = {
"keyVaultNamespace" : "encryption.__dataKeys",
"kmsProviders" : {
"azure" : {
"tenantId" : AZURE_TENANT_ID,
"clientId" : AZURE_CLIENT_ID,
"clientSecret" : AZURE_CLIENT_SECRET
}
}
}
3

mongosh中,使用Mongo()构造函数建立与目标集群的数据库连接。 将ClientSideFieldLevelEncryptionOptions文档指定为Mongo()构造函数的第二个参数,为客户端字段级加密配置连接:

csfleDatabaseConnection = Mongo(
"mongodb://replaceMe.example.net:27017/?replicaSet=myMongoCluster",
ClientSideFieldLevelEncryptionOptions
)

replaceMe.example.net URI替换为目标集群的连接string 。

使用 csfleDatabaseConnection对象访问权限客户端字段级加密shell方法。

有关建立为客户端字段级加密配置的数据库连接的完整文档,请参阅Mongo()构造函数参考。

4

csfleDatabaseConnection数据库连接对象上使用getKeyVault()方法创建keyVault对象:

keyVault = csfleDatabaseConnection.getKeyVault();

重要

客户端字段级加密取决于服务器强制执行的密钥备用名称的唯一性。 如果不存在唯一索引, getKeyVault()会在keyAltNames上创建唯一索引。 请勿 删除 创建的 唯一索引 getKeyVault()

5

使用以下步骤添加或删除现有的密钥备用名称。

添加密钥备用名称

重要

客户端字段级加密取决于服务器强制执行的密钥备用名称的唯一性。 在添加新的密钥备用名称之前,请验证keyAltNames上是否存在唯一索引。 如果删除了唯一索引,则必须在添加任何键备用名称之前重新创建该索引。

使用KeyVault.addKeyAlternateName()为数据加密密钥添加新的备用名称:

keyVault.addKeyAlternateName(
UUID("<Replace Me With The UUID Of The Key To Modify"),
"NewKeyAltNameForMyFirstCSFLEDataKey"
)

其中:

  • 第一个参数必须是要修改的数据加密密钥的UUID

  • 第二个参数必须是唯一的string 。 getKeyVault()keyAltNames上创建唯一索引,以实施密钥备用名称的唯一性。

KeyVault.addKeyAlternateName()返回修改的数据加密密钥文档。 使用KeyVault.getKey()检索修改后的数据加密密钥。

删除密钥备用名称

使用KeyVault.removeKeyAlternateName()从数据加密密钥中删除密钥备用名称:

keyVault.removeKeyAlternateName(
UUID("<Replace Me With The UUID Of The Key To Modify"),
"NewKeyAltNameForMyFirstCSFLEDataKey"
)

其中:

  • 第一个参数必须是要修改的数据加密密钥的UUID

  • 第二个参数必须是string键备用名称。

KeyVault.removeKeyAlternateName()返回修改的数据加密密钥。 使用KeyVault.getKey()检索修改后的数据加密密钥。

1

为GCP KMS配置客户端字段级加密需要GCP电子邮件及其关联的私钥。

为了降低这些凭证泄漏到日志中的风险,以下过程使用环境变量将这些值传递到mongosh中。

首先,确保已根据平台文档配置以下环境变量:

  • GCP_EMAIL

  • GCP_PRIVATEKEY

接下来,使用mongosh --eval--shell--nodb 选项创建 会话:

mongosh --eval "
var GCP_EMAIL = '$GCP_EMAIL'
var GCP_PRIVATEKEY = '$GCP_PRIVATEKEY'
" \
--shell --nodb

此示例在不连接MongoDB 数据库的情况下打开mongosh--eval选项将 { mongosh } 中的GCP_EMAILGCP_PRIVATEKEY变量设置为相应环境变量的值。

2

mongosh中,创建新的ClientSideFieldLevelEncryptionOptions变量,用于存储客户端字段级加密配置文档:

var ClientSideFieldLevelEncryptionOptions = {
"keyVaultNamespace" : "encryption.__dataKeys",
"kmsProviders" : {
"gcp" : {
"email" : GCP_EMAIL,
"privateKey" : GCP_PRIVATEKEY
}
}
}
3

mongosh中,使用Mongo()构造函数建立与目标集群的数据库连接。 将ClientSideFieldLevelEncryptionOptions文档指定为Mongo()构造函数的第二个参数,为客户端字段级加密配置连接:

csfleDatabaseConnection = Mongo(
"mongodb://replaceMe.example.net:27017/?replicaSet=myMongoCluster",
ClientSideFieldLevelEncryptionOptions
)

replaceMe.example.net URI替换为目标集群的连接string 。

使用 csfleDatabaseConnection对象访问权限客户端字段级加密shell方法。

有关建立为客户端字段级加密配置的数据库连接的完整文档,请参阅Mongo()构造函数参考。

4

csfleDatabaseConnection数据库连接对象上使用getKeyVault()方法创建keyVault对象:

keyVault = csfleDatabaseConnection.getKeyVault();

重要

客户端字段级加密取决于服务器强制执行的密钥备用名称的唯一性。 如果不存在唯一索引, getKeyVault()会在keyAltNames上创建唯一索引。 请勿 删除 创建的 唯一索引 getKeyVault()

5

使用以下步骤添加或删除现有的密钥备用名称。

添加密钥备用名称

重要

客户端字段级加密取决于服务器强制执行的密钥备用名称的唯一性。 在添加新的密钥备用名称之前,请验证keyAltNames上是否存在唯一索引。 如果删除了唯一索引,则必须在添加任何键备用名称之前重新创建该索引。

使用KeyVault.addKeyAlternateName()为数据加密密钥添加新的备用名称:

keyVault.addKeyAlternateName(
UUID("<Replace Me With The UUID Of The Key To Modify"),
"NewKeyAltNameForMyFirstCSFLEDataKey"
)

其中:

  • 第一个参数必须是要修改的数据加密密钥的UUID

  • 第二个参数必须是唯一的string 。 getKeyVault()keyAltNames上创建唯一索引,以实施密钥备用名称的唯一性。

KeyVault.addKeyAlternateName()返回修改的数据加密密钥文档。 使用KeyVault.getKey()检索修改后的数据加密密钥。

删除密钥备用名称

使用KeyVault.removeKeyAlternateName()从数据加密密钥中删除密钥备用名称:

keyVault.removeKeyAlternateName(
UUID("<Replace Me With The UUID Of The Key To Modify"),
"NewKeyAltNameForMyFirstCSFLEDataKey"
)

其中:

  • 第一个参数必须是要修改的数据加密密钥的UUID

  • 第二个参数必须是string键备用名称。

KeyVault.removeKeyAlternateName()返回修改的数据加密密钥。 使用KeyVault.getKey()检索修改后的数据加密密钥。

1

为本地管理的密钥配置客户端字段级加密需要指定一个没有换行符的基本 64 编码的 96 字节string 。

为了降低这些凭证泄漏到日志中的风险,以下过程使用环境变量将这些值传递到mongosh中。

以下操作生成满足所述要求的密钥并将其添加到用户的~/.profile中。 如果键DEV_LOCAL_KEY已存在,请跳过此操作。

echo "export DEV_LOCAL_KEY=\"$(head -c 96 /dev/urandom | base64 | tr -d '\n')\"" >> ~/.profile

托管操作系统可能需要注销并重新登录才能刷新加载的环境变量。 或者,可以使用命令 source ~/.profile 手动刷新shell 。

注意

特定的托管操作系统或shell可能有不同的过程来设置持久环境变量。 请根据您的托管操作系统或shell的文档了解更具体的过程。

2

使用mongosh --eval--shell--nodb 选项创建 会话:

mongosh --eval "var LOCAL_KEY = '$DEV_LOCAL_KEY' " \
--shell --nodb

该示例会自动打开mongosh ,而无需连接到MongoDB 数据库。 --eval选项将mongosh中的LOCAL_KEY变量设置为相应环境变量的值。

3

mongosh中,创建新的ClientSideFieldLevelEncryptionOptions变量,用于存储客户端字段级加密配置文档:

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

mongosh中,使用Mongo()构造函数建立与目标集群的数据库连接。 将ClientSideFieldLevelEncryptionOptions文档指定为Mongo()构造函数的第二个参数,为客户端字段级加密配置连接:

csfleDatabaseConnection = Mongo(
"mongodb://replaceMe.example.net:27017/?replicaSet=myMongoCluster",
ClientSideFieldLevelEncryptionOptions
)

replaceMe.example.net URI替换为目标集群的连接string 。

使用 csfleDatabaseConnection对象访问权限客户端字段级加密shell方法。

有关建立为客户端字段级加密配置的数据库连接的完整文档,请参阅Mongo()构造函数参考。

5

csfleDatabaseConnection数据库连接对象上使用getKeyVault()方法创建keyVault对象:

keyVault = csfleDatabaseConnection.getKeyVault();

重要

客户端字段级加密取决于服务器强制执行的密钥备用名称的唯一性。 如果不存在唯一索引, getKeyVault()会在keyAltNames上创建唯一索引。 请勿 删除 创建的 唯一索引 getKeyVault()

6

使用以下步骤添加或删除现有的密钥备用名称。

添加密钥备用名称

重要

客户端字段级加密取决于服务器强制执行的密钥备用名称的唯一性。 在添加新的密钥备用名称之前,请验证keyAltNames上是否存在唯一索引。 如果删除了唯一索引,则必须在添加任何键备用名称之前重新创建该索引。

使用KeyVault.addKeyAlternateName()为数据加密密钥添加新的备用名称:

keyVault.addKeyAlternateName(
UUID("<Replace Me With The UUID Of The Key To Modify"),
"NewKeyAltNameForMyFirstCSFLEDataKey"
)

其中:

  • 第一个参数必须是要修改的数据加密密钥的UUID

  • 第二个参数必须是唯一的string 。 getKeyVault()keyAltNames上创建唯一索引,以实施密钥备用名称的唯一性。

KeyVault.addKeyAlternateName()返回修改的数据加密密钥文档。 使用KeyVault.getKey()检索修改后的数据加密密钥。

删除密钥备用名称

使用KeyVault.removeKeyAlternateName()从数据加密密钥中删除密钥备用名称:

keyVault.removeKeyAlternateName(
UUID("<Replace Me With The UUID Of The Key To Modify"),
"NewKeyAltNameForMyFirstCSFLEDataKey"
)

其中:

  • 第一个参数必须是要修改的数据加密密钥的UUID

  • 第二个参数必须是string键备用名称。

KeyVault.removeKeyAlternateName()返回修改的数据加密密钥。 使用KeyVault.getKey()检索修改后的数据加密密钥。

警告

删除数据加密密钥会使使用该密钥加密的所有字段永久不可读。

以下过程使用mongosh从密钥保管库中删除数据加密密钥。 有关使用4.2 + 兼容驾驶员进行数据加密密钥管理的指导,请参阅驾驶员文档

如果仍在上述“mongosh 创建数据加密密钥” 步骤中配置的 会话中,则可以直接跳到步骤5 。

使用以下标签页选择适合您部署的KMS

1

为 AWS KMS 配置客户端字段级加密需要一个 AWS 访问密钥 ID 及其相关的秘密访问密钥。AWS 访问密钥必须与具有 KMS 服务的所有列出读取 权限的 IAM 用户相对应。

为了降低这些凭证泄漏到日志中的风险,以下过程使用环境变量将这些值传递到mongosh中。

首先,确保已根据平台文档配置以下环境变量:

  • AWS_ACCESS_KEY_ID

  • AWS_SECRET_ACCESS_KEY

接下来,使用mongosh --eval--shell--nodb 选项创建 会话:

mongosh --eval "
var AWS_ACCESS_KEY_ID = '$AWS_ACCESS_KEY_ID'
var AWS_SECRET_ACCESS_KEY = '$AWS_SECRET_ACCESS_KEY'
" \
--shell --nodb

此示例在不连接MongoDB 数据库的情况下打开mongosh--eval选项将 { mongosh } 中的AWS_ACCESS_KEY_IDAWS_SECRET_ACCESS_KEY变量设置为相应环境变量的值。 Amazon Web ServicesCLI也支持指定的变量。

2

mongosh中,创建新的ClientSideFieldLevelEncryptionOptions变量,用于存储客户端字段级加密配置文档:

var ClientSideFieldLevelEncryptionOptions = {
"keyVaultNamespace" : "encryption.__dataKeys",
"kmsProviders" : {
"aws" : {
"accessKeyId" : AWS_ACCESS_KEY_ID,
"secretAccessKey" : AWS_SECRET_ACCESS_KEY
}
}
}
3

mongosh中,使用Mongo()构造函数建立与目标集群的数据库连接。 将ClientSideFieldLevelEncryptionOptions文档指定为Mongo()构造函数的第二个参数,为客户端字段级加密配置连接:

csfleDatabaseConnection = Mongo(
"mongodb://replaceMe.example.net:27017/?replicaSet=myMongoCluster",
ClientSideFieldLevelEncryptionOptions
)

replaceMe.example.net URI替换为目标集群的连接string 。

使用 csfleDatabaseConnection对象访问权限客户端字段级加密shell方法。

有关建立为客户端字段级加密配置的数据库连接的完整文档,请参阅Mongo()构造函数参考。

4

csfleDatabaseConnection数据库连接对象上使用getKeyVault()方法创建keyVault对象:

keyVault = csfleDatabaseConnection.getKeyVault();

重要

客户端字段级加密取决于服务器强制执行的密钥备用名称的唯一性。 如果不存在唯一索引, getKeyVault()会在keyAltNames上创建唯一索引。 请勿 删除 创建的 唯一索引 getKeyVault()

5

使用keyVault对象上的KeyVault.deleteKey()方法从密钥保管库中删除数据密钥:

keyVault.deleteKey(UUID("<Replace Me With The UUID Of The Key To Delete"))
1

为 Azure Key Vault 配置客户端字段级加密需要有效的租户 ID、客户端 ID 和客户端密钥。

为了降低这些凭证泄漏到日志中的风险,以下过程使用环境变量将这些值传递到mongosh中。

首先,确保已根据平台文档配置以下环境变量:

  • AZURE_TENANT_ID

  • AZURE_CLIENT_ID

  • AZURE_CLIENT_SECRET

接下来,使用mongosh --eval--shell--nodb 选项创建 会话:

mongosh --eval "
var AZURE_TENANT_ID = '$AZURE_TENANT_ID'
var AZURE_CLIENT_ID = '$AZURE_CLIENT_ID'
var AZURE_CLIENT_SECRET = '$AZURE_CLIENT_SECRET'
" \
--shell --nodb

此示例在不连接MongoDB 数据库的情况下打开mongosh--eval选项将 { mongosh } 中的AZURE_TENANT_IDAZURE_CLIENT_IDAZURE_CLIENT_SECRET变量设置为相应环境变量的值。

2

mongosh中,创建新的ClientSideFieldLevelEncryptionOptions变量,用于存储客户端字段级加密配置文档:

var ClientSideFieldLevelEncryptionOptions = {
"keyVaultNamespace" : "encryption.__dataKeys",
"kmsProviders" : {
"azure" : {
"tenantId" : AZURE_TENANT_ID,
"clientId" : AZURE_CLIENT_ID,
"clientSecret" : AZURE_CLIENT_SECRET
}
}
}
3

mongosh中,使用Mongo()构造函数建立与目标集群的数据库连接。 将ClientSideFieldLevelEncryptionOptions文档指定为Mongo()构造函数的第二个参数,为客户端字段级加密配置连接:

csfleDatabaseConnection = Mongo(
"mongodb://replaceMe.example.net:27017/?replicaSet=myMongoCluster",
ClientSideFieldLevelEncryptionOptions
)

replaceMe.example.net URI替换为目标集群的连接string 。

使用 csfleDatabaseConnection对象访问权限客户端字段级加密shell方法。

有关建立为客户端字段级加密配置的数据库连接的完整文档,请参阅Mongo()构造函数参考。

4

csfleDatabaseConnection数据库连接对象上使用getKeyVault()方法创建keyVault对象:

keyVault = csfleDatabaseConnection.getKeyVault();

重要

客户端字段级加密取决于服务器强制执行的密钥备用名称的唯一性。 如果不存在唯一索引, getKeyVault()会在keyAltNames上创建唯一索引。 请勿 删除 创建的 唯一索引 getKeyVault()

5

使用keyVault对象上的KeyVault.deleteKey()方法从密钥保管库中删除数据密钥:

keyVault.deleteKey(UUID("<Replace Me With The UUID Of The Key To Delete"))
1

为GCP KMS配置客户端字段级加密需要GCP电子邮件及其关联的私钥。

为了降低这些凭证泄漏到日志中的风险,以下过程使用环境变量将这些值传递到mongosh中。

首先,确保已根据平台文档配置以下环境变量:

  • GCP_EMAIL

  • GCP_PRIVATEKEY

接下来,使用mongosh --eval--shell--nodb 选项创建 会话:

mongosh --eval "
var GCP_EMAIL = '$GCP_EMAIL'
var GCP_PRIVATEKEY = '$GCP_PRIVATEKEY'
" \
--shell --nodb

此示例在不连接MongoDB 数据库的情况下打开mongosh--eval选项将 { mongosh } 中的GCP_EMAILGCP_PRIVATEKEY变量设置为相应环境变量的值。

2

mongosh中,创建新的ClientSideFieldLevelEncryptionOptions变量,用于存储客户端字段级加密配置文档:

var ClientSideFieldLevelEncryptionOptions = {
"keyVaultNamespace" : "encryption.__dataKeys",
"kmsProviders" : {
"gcp" : {
"email" : GCP_EMAIL,
"privateKey" : GCP_PRIVATEKEY
}
}
}
3

mongosh中,使用Mongo()构造函数建立与目标集群的数据库连接。 将ClientSideFieldLevelEncryptionOptions文档指定为Mongo()构造函数的第二个参数,为客户端字段级加密配置连接:

csfleDatabaseConnection = Mongo(
"mongodb://replaceMe.example.net:27017/?replicaSet=myMongoCluster",
ClientSideFieldLevelEncryptionOptions
)

replaceMe.example.net URI替换为目标集群的连接string 。

使用 csfleDatabaseConnection对象访问权限客户端字段级加密shell方法。

有关建立为客户端字段级加密配置的数据库连接的完整文档,请参阅Mongo()构造函数参考。

4

csfleDatabaseConnection数据库连接对象上使用getKeyVault()方法创建keyVault对象:

keyVault = csfleDatabaseConnection.getKeyVault();

重要

客户端字段级加密取决于服务器强制执行的密钥备用名称的唯一性。 如果不存在唯一索引, getKeyVault()会在keyAltNames上创建唯一索引。 请勿 删除 创建的 唯一索引 getKeyVault()

5

使用keyVault对象上的KeyVault.deleteKey()方法从密钥保管库中删除数据密钥:

keyVault.deleteKey(UUID("<Replace Me With The UUID Of The Key To Delete"))
1

为本地管理的密钥配置客户端字段级加密需要指定一个没有换行符的基本 64 编码的 96 字节string 。

为了降低这些凭证泄漏到日志中的风险,以下过程使用环境变量将这些值传递到mongosh中。

以下操作生成满足所述要求的密钥并将其添加到用户的~/.profile中。 如果键DEV_LOCAL_KEY已存在,请跳过此操作。

echo "export DEV_LOCAL_KEY=\"$(head -c 96 /dev/urandom | base64 | tr -d '\n')\"" >> ~/.profile

托管操作系统可能需要注销并重新登录才能刷新加载的环境变量。 或者,可以使用命令 source ~/.profile 手动刷新shell 。

注意

特定的托管操作系统或shell可能有不同的过程来设置持久环境变量。 请根据您的托管操作系统或shell的文档了解更具体的过程。

2

使用mongosh --eval--shell--nodb 选项创建 会话:

mongosh --eval "var LOCAL_KEY = '$DEV_LOCAL_KEY' " \
--shell --nodb

该示例会自动打开mongosh ,而无需连接到MongoDB 数据库。 --eval选项将mongosh中的LOCAL_KEY变量设置为相应环境变量的值。

3

mongosh中,创建新的ClientSideFieldLevelEncryptionOptions变量,用于存储客户端字段级加密配置文档:

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

mongosh中,使用Mongo()构造函数建立与目标集群的数据库连接。 将ClientSideFieldLevelEncryptionOptions文档指定为Mongo()构造函数的第二个参数,为客户端字段级加密配置连接:

csfleDatabaseConnection = Mongo(
"mongodb://replaceMe.example.net:27017/?replicaSet=myMongoCluster",
ClientSideFieldLevelEncryptionOptions
)

replaceMe.example.net URI替换为目标集群的连接string 。

使用 csfleDatabaseConnection对象访问权限客户端字段级加密shell方法。

有关建立为客户端字段级加密配置的数据库连接的完整文档,请参阅Mongo()构造函数参考。

5

csfleDatabaseConnection数据库连接对象上使用getKeyVault()方法创建keyVault对象:

keyVault = csfleDatabaseConnection.getKeyVault();

重要

客户端字段级加密取决于服务器强制执行的密钥备用名称的唯一性。 如果不存在唯一索引, getKeyVault()会在keyAltNames上创建唯一索引。 请勿 删除 创建的 唯一索引 getKeyVault()

6

使用keyVault对象上的KeyVault.deleteKey()方法从密钥保管库中删除数据密钥:

keyVault.deleteKey(UUID("<Replace Me With The UUID Of The Key To Delete"))

要从密钥保管库检索现有的数据加密密钥文档,请执行以下任一操作:

如果向官方 4.2+ 兼容驱动程序提供数据加密密钥以配置自动客户端字段级加密,则必须使用 UUID string的 base64 表示形式。

您可以在mongosh中运行以下操作,将 UUID 十六进制string转换为其 base64 表示形式:

UUID("b4b41b33-5c97-412e-a02b-743498346079").base64()

为此命令提供您自己的数据加密密钥的UUID

后退

主密钥和数据加密密钥管理