Docs Home → MongoDB Shell

Client-Side Field Level Encryption客户端字段级加密

On this page本页内容

When working with a MongoDB Enterprise or MongoDB Atlas cluster, you can use mongosh to configure Client-Side Field Level Encryption and connect with encryption support. 在使用MongoDB Enterprise或MongoDB Atlas集群时，您可以使用mongosh配置客户端字段级加密并连接加密支持。Client-side field level encryption uses data encryption keys for supporting encryption and decryption of field values, and stores this encryption key material in a Key Management Service (KMS).客户端字段级加密使用数据加密密钥来支持字段值的加密和解密，并将此加密密钥材料存储在密钥管理服务（KMS）中。

mongosh supports the following KMS providers for use with client-side field level encryption:mongosh支持以下用于客户端字段级加密的KMS提供程序：

  • Amazon Web Services KMS亚马逊网络服务KMS
  • Azure Key Vault
  • Google Cloud Platform KMS
  • Locally Managed Keyfile

Create a Data Encryption Key创建数据加密密钥

The following procedure uses mongosh to create a data encryption key for use with client-side field level encryption and decryption.以下过程使用mongosh创建用于客户端字段级加密和解密的数据加密密钥。

Use the tabs below to select the KMS appropriate for your deployment:使用以下选项卡选择适合您部署的KMS：

1

Launch the mongosh Shell.启动mongosh Shell。

Create a mongosh session without connecting to a running database by using the --nodb option:使用--nodb选项在不连接到正在运行的数据库的情况下创建mongosh会话：

mongosh --nodb
2

Create the Encryption Configuration.创建加密配置。

Configuring client-side field level encryption for the AWS KMS requires an AWS Access Key ID and its associated Secret Access Key. 为AWS KMS配置客户端字段级加密需要一个AWS访问密钥ID及其关联的秘密访问密钥。The AWS Access Key must correspond to an IAM user with all List and Read permissions for the KMS service.AWS访问密钥必须与具有KMS服务的所有列表和读取权限的IAM用户相对应。

In mongosh, create a new AutoEncryptionOpts variable for storing the client-side field level encryption configuration, which contains these credentials:在mongosh中，创建一个新的AutoEncryptionOpts变量，用于存储客户端字段级加密配置，其中包含以下凭据：

var autoEncryptionOpts = {
  "keyVaultNamespace" : "encryption.__dataKeys",
  "kmsProviders" : {
    "aws" : {
      "accessKeyId" : "YOUR_AWS_ACCESS_KEY_ID",
      "secretAccessKey" : "YOUR_AWS_SECRET_ACCESS_KEY"
    }
  }
}

Fill in the values for YOUR_AWS_ACCESS_KEY_ID and YOUR_AWS_SECRET_ACCESS_KEY as appropriate.根据情况填写YOUR_AWS_ACCESS_KEY_ID和YOUR_AWS_SECRET_ACCESS_KEY的值。

3

Connect with Encryption Support.使用加密支持连接。

In mongosh, use the Mongo() constructor to establish a database connection to the target cluster. 在mongosh中，使用Mongo()构造函数建立到目标集群的数据库连接。Specify the AutoEncryptionOpts document as the second parameter to the Mongo() constructor to configure the connection for client-side field level encryption:指定AutoEncryptionOpts文档作为Mongo()构造函数的第二个参数，以配置客户端字段级加密的连接：

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

Replace the replaceMe.example.net URI with the connection string for the target cluster.将replaceMe.example.net URI替换为目标群集的连接字符串。

4

Create the Key Vault Object.创建密钥库对象。

Create the keyVault object using the getKeyVault() shell method:使用getKeyVault() shell方法创建keyVault对象：

keyVault = csfleDatabaseConnection.getKeyVault();
5

Create the Encryption Key.创建加密密钥。

Create the data encryption key using the createKey() shell method:使用createKey()shell方法创建数据加密密钥：

keyVault.createKey(
  "aws",
  { region: "regionname", key: "awsarn" },
  [ "keyAlternateName" ]
)

Where:其中：

  • The first parameter must be "aws" to specify the configured Amazon Web Services KMS.第一个参数必须是"aws"，以指定已配置的AmazonWebServices KMS。
  • The second parameter must be a document containing the following:第二个参数必须是包含以下内容的文档：

  • The third parameter may be an array of one or more keyAltNames for the data encryption key. Each key alternate name must be unique. 第三个参数可以是数据加密密钥的一个或多个keyAltNames的数组。每个密钥备用名称必须是唯一的。getKeyVault() creates a unique index on keyAltNames to enforce uniqueness on the field if one does not already exist. 在keyAltNames上创建一个唯一索引，以在字段不存在的情况下强制该字段的唯一性。Key alternate names facilitate data encryption key findability.密钥替换名称有助于数据加密密钥的可查找性。

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:要从密钥保管库中检索新的数据加密密钥文档，请执行以下操作之一：

  • Use getKey() to retrieve the created key by its UUID, or使用getKey()按UUID检索创建的密钥，或者
  • Use getKeyByAltName() to retrieve the key by its alternate name, if specified.如果已指定，请使用getKeyByAltName()按密钥的备用名称检索密钥。
1

Launch the mongosh Shell.启动mongosh Shell。

Create a mongosh session without connecting to a running database by using the --nodb option:使用--nodb选项在不连接到正在运行的数据库的情况下创建mongosh会话：

mongosh --nodb
2

Create the Encryption Configuration.创建加密配置。

Configuring client-side field level encryption for Azure Key Vault requires a valid Tenant ID, Client ID, and Client Secret.为Azure密钥保管库配置客户端字段级加密需要有效的租户ID、客户端ID和客户端机密。

In mongosh, create a new AutoEncryptionOpts variable for storing the client-side field level encryption configuration, which contains these credentials:在mongosh中，创建一个新的AutoEncryptionOpts变量，用于存储客户端字段级加密配置，其中包含以下凭据：

var autoEncryptionOpts = {
  "keyVaultNamespace" : "encryption.__dataKeys",
  "kmsProviders" : {
    "azure" : {
      "tenantId" : "YOUR_TENANT_ID",
      "clientId" : "YOUR_CLIENT_ID",
      "clientSecret" : "YOUR_CLIENT_SECRET"
    }
  }
}

Fill in the values for YOUR_TENANT_ID, YOUR_CLIENT_ID, and YOUR_CLIENT_SECRET as appropriate.根据需要填写YOUR_TENANT_ID、YOUR_CLIENT_ID和YOUR_CLINENT_SECRET的值。

3

Connect with Encryption Support.使用加密支持连接。

In mongosh, use the Mongo() constructor to establish a database connection to the target cluster. 在mongosh中，使用Mongo()构造函数建立到目标集群的数据库连接。Specify the AutoEncryptionOpts document as the second parameter to the Mongo() constructor to configure the connection for client-side field level encryption:指定AutoEncryptionOpts文档作为Mongo()构造函数的第二个参数，以配置客户端字段级加密的连接：

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

Replace the replaceMe.example.net URI with the connection string for the target cluster.将replaceMe.example.net URI替换为目标群集的连接字符串。

4

Create the Key Vault Object.创建密钥库对象。

Create the keyVault object using the getKeyVault() shell method:使用getKeyVault()shell方法创建keyVault对象：

keyVault = csfleDatabaseConnection.getKeyVault();
5

Create the Encryption Key.创建加密密钥。

Create the data encryption key using the createKey() shell method:使用createKey()shell方法创建数据加密密钥：

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

Where:其中：

  • The first parameter must be "azure" to specify the configured Azure Key Vault.第一个参数必须是"azure"才能指定配置的azure密钥保管库。
  • The second parameter must be a document containing:第二个参数必须是包含以下内容的文档：

    • the name of your Azure Key VaultAzure密钥保管库的名称Azure Key Vault
    • the DNS name of the Azure Key Vault to use (e.g. my-key-vault.vault.azure.net)要使用的Azure密钥保管库的DNS名称（例如，my-key-vault.vault.azure.net）
  • The third parameter may be an array of one or more keyAltNames for the data encryption key. 第三个参数可以是数据加密密钥的一个或多个keyAltNames的数组。Each key alternate name must be unique. getKeyVault() creates a unique index on keyAltNames to enforce uniqueness on the field if one does not already exist. 每个密钥备用名称必须是唯一的。getKeyVault()在keyAltNames上创建一个唯一索引，以在字段不存在的情况下强制字段的唯一性。Key alternate names facilitate data encryption key findability.密钥替换名称有助于数据加密密钥的可查找性。

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:要从密钥保管库中检索新的数据加密密钥文档，请执行以下操作之一：

  • Use getKey() to retrieve the created key by its UUID, or使用getKey()按UUID检索创建的密钥，或者
  • Use getKeyByAltName() to retrieve the key by its alternate name, if specified.如果已指定，请使用getKeyByAltName()按密钥的备用名称检索密钥。
1

Launch the mongosh Shell.启动mongosh Shell。

Create a mongosh session without connecting to a running database by using the --nodb option:使用--nodb选项在不连接到正在运行的数据库的情况下创建mongosh会话：

mongosh --nodb
2

Create the Encryption Configuration.创建加密配置。

Configuring client-side field level encryption for the GCP KMS requires your GCP Email and its associated Private Key.为GCP KMS配置客户端字段级加密需要GCP电子邮件及其相关私钥。

In mongosh, create a new AutoEncryptionOpts variable for storing the client-side field level encryption configuration, which contains these credentials:在mongosh中，创建一个新的AutoEncryptionOpts变量，用于存储客户端字段级加密配置，其中包含以下凭据：

var autoEncryptionOpts = {
  "keyVaultNamespace" : "encryption.__dataKeys",
  "kmsProviders" : {
    "gcp" : {
      "email" : "YOUR_GCP_EMAIL",
      "privateKey" : "YOUR_GCP_PRIVATEKEY"
    }
  }
}

Fill in the values for YOUR_GCP_EMAIL and YOUR_GCP_PRIVATEKEY as appropriate.根据需要填写YOUR_GCP_EMAIL和YOUR_GCPU_PRIVATEKEY的值。

3

Connect with Encryption Support.使用加密支持连接。

In mongosh, use the Mongo() constructor to establish a database connection to the target cluster. 在mongosh中，使用Mongo()构造函数建立到目标集群的数据库连接。Specify the AutoEncryptionOpts document as the second parameter to the Mongo() constructor to configure the connection for client-side field level encryption:指定AutoEncryptionOpts文档作为Mongo()构造函数的第二个参数，以配置客户端字段级加密的连接：

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

Replace the replaceMe.example.net URI with the connection string for the target cluster.将replaceMe.example.net URI替换为目标群集的连接字符串。

4

Create the Key Vault Object.创建密钥库对象。

Create the keyVault object using the getKeyVault() shell method:使用getKeyVault()shell方法创建getKeyVault()对象：

keyVault = csfleDatabaseConnection.getKeyVault();
5

Create the Encryption Key.创建加密密钥。

Create the data encryption key using the createKey() shell method:使用createKey()shell方法创建数据加密密钥：

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

Where:其中：

  • The first parameter must be "gcp" to specify the configured Google Cloud KMS.第一个参数必须是"gcp"才能指定已配置的Google Cloud KMS。
  • The second parameter must be a document containing第二个参数必须是包含

    • projectid is the name of your GCP project, such as my-project是你的GCP项目的名称，比如my-project
    • locationname is the location of the KMS keyring, such as 是KMS密钥环的位置，例如global
    • keyringname is the name of the KMS keyring, such as 是KMS密钥环的名称，例如my-keyring
    • keyname is the name of your key.是密钥的名称。
  • The third parameter may be an array of one or more keyAltNames for the data encryption key. Each key alternate name must be unique. 第三个参数可以是数据加密密钥的一个或多个keyAltNames的数组。每个密钥备用名称必须是唯一的。getKeyVault() creates a unique index on keyAltNames to enforce uniqueness on the field if one does not already exist. 在keyAltNames上创建一个唯一索引，以在字段不存在的情况下强制该字段的唯一性。Key alternate names facilitate data encryption key findability.密钥替换名称有助于数据加密密钥的可查找性。

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:要从密钥保管库中检索新的数据加密密钥文档，请执行以下操作之一：

  • Use getKey() to retrieve the created key by its UUID, or使用getKey()按UUID检索创建的密钥，或者
  • Use getKeyByAltName() to retrieve the key by its alternate name, if specified.如果已指定，请使用getKeyByAltName()按密钥的备用名称检索密钥。
1

Launch the mongosh Shell.启动mongosh Shell。

Create a mongosh session without connecting to a running database by using the --nodb option:使用--nodb选项在不连接到正在运行的数据库的情况下创建mongosh会话：

mongosh --nodb
2

Generate an Encryption Key.生成加密密钥。

To configure client-side field level encryption for a locally managed key, you must specify a base64-encoded 96-byte string with no line breaks. 若要为本地管理的密钥配置客户端字段级加密，必须指定一个不带换行符的base64编码的96字节字符串。Run the following command in mongosh to generate a key matching these requirements:在mongosh中运行以下命令以生成符合这些要求的密钥：

crypto.randomBytes(96).toString('base64')

You will need this key in the next step.下一步您将需要此密钥。

3

Create the Encryption Configuration.创建加密配置。

In mongosh, create a new AutoEncryptionOpts variable for storing the client-side field level encryption configuration, replacing MY_LOCAL_KEY with the key generated in step 1:在mongosh中，创建一个新的AutoEncryptionOpts变量，用于存储客户端字段级加密配置，用步骤1中生成的密钥替换MY_LOCAL_KEY：

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

Connect with Encryption Support.使用加密支持连接。

In mongosh, use the Mongo() constructor to establish a database connection to the target cluster. 在mongosh中，使用Mongo()构造函数建立到目标集群的数据库连接。Specify the AutoEncryptionOpts document as the second parameter to the Mongo() constructor to configure the connection for client-side field level encryption:指定AutoEncryptionOpts文档作为Mongo()构造函数的第二个参数，以配置客户端字段级加密的连接：

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

Create the Key Vault Object.创建密钥库对象。

Create the keyVault object using the getKeyVault() shell method:使用getKeyVault()shell方法创建keyVault对象：

keyVault = csfleDatabaseConnection.getKeyVault();
6

Create the Encryption Key.创建加密密钥。

Create the data encryption key using the createKey() shell method:使用createKey()shell方法创建数据加密密钥：

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

Where:其中：

  • The first parameter must be local to specify the configured Locally Managed Key.第一个参数必须是local，才能指定配置的本地托管密钥。
  • The second parameter may be an array of one or more keyAltNames for the data encryption key. 第二参数可以是数据加密密钥的一个或多个keyAltNames的数组。Each key alternate name must be unique. 每个密钥备用名称必须是唯一的。getKeyVault() creates a unique index on keyAltNames to enforce uniqueness on the field if one does not already exist. 在keyAltNames上创建一个唯一索引，以在字段不存在的情况下强制该字段的唯一性。Key alternate names facilitate data encryption key findability.密钥替换名称有助于数据加密密钥的可查找性。

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:要从密钥保管库中检索新的数据加密密钥文档，请执行以下操作之一：

  • Use getKey() to retrieve the created key by its UUID, or使用getKey()按UUID检索创建的密钥，或者
  • Use getKeyByAltName() to retrieve the key by its alternate name, if specified.如果已指定，请使用getKeyByAltName()按密钥的备用名称检索密钥。
Tip

See also: 另请参阅：