Docs Home / mongosh

Field Level Encryption字段级加密

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

mongosh supports the following KMS providers for use with Queryable Encryption and CSFLE:支持以下KMS提供程序与可查询加密和CSFLE一起使用：

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

The following procedure uses mongosh to create a data encryption key for field level encryption.以下过程使用mongosh为字段级加密创建数据加密键。

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

Amazon Web Services KMS
1

Launch the mongosh Shell.启动mongoshShell。

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. The AWS Access Key must correspond to an IAM user with all List and Read permissions for the KMS service.为AWS KMS配置客户端字段级加密需要AWS访问键ID及其关联的键访问键。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_ACCES_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"，以指定配置的Amazon Web Services 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. getKeyVault()在keyAltNames上创建一个唯一索引，以在字段不存在的情况下强制其唯一性。Key alternate names facilitate data encryption key findability.键备用名称便于数据加密键的查找。

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

  • 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()按其备用名称检索键。
Azure Key Vault
1

Launch the mongosh Shell.启动mongoshShell。

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_TENNT_ID、YOUR_CLIENT_ID和YOUR_CLIENT_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键库的名称

    • 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. 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. Key alternate names facilitate data encryption key findability.getKeyVault()在keyAltNames上创建一个唯一索引，以在字段不存在的情况下强制其唯一性。键备用名称便于数据加密键的查找。

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

  • 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()按其备用名称检索键。
Google Cloud 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 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_GCP-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方法创建keyVault对象：

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 是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. getKeyVault()在keyAltNames上创建一个唯一索引，以在字段不存在的情况下强制其唯一性。Key alternate names facilitate data encryption key findability.键备用名称便于数据加密键的查找。

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

  • 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()按其备用名称检索键。
Local Keyfile
1

Launch the mongosh Shell.启动mongoshShell。

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. Run the following command in mongosh to generate a key matching these requirements:要为本地管理的键配置客户端字段级加密，您必须指定一个没有换行符的base64编码的96字节字符串。在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. Key alternate names facilitate data encryption key findability.每个键备用名称必须唯一。getKeyVault()在keyAltNames上创建一个唯一索引，以在字段不存在的情况下强制其唯一性。键备用名称便于数据加密键的查找。

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

  • 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