Database Manual / Reference / mongosh Methods / In-Use Encryption

ClientEncryption.createEncryptedCollection() (mongosh method方法)

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

ClientEncryption.createEncryptedCollection(dbName, collName, clientEncOpts)
ClientEncryption.createEncryptedCollection creates an encrypted collection specified by collName on the database specified by dbName.dbName指定的数据库上创建由collName指定的加密集合。

Compatibility兼容性

This command is available in deployments hosted in the following environments:此命令在以下环境中托管的部署中可用:

  • MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud:云中MongoDB部署的完全托管服务
  • MongoDB Enterprise: The subscription-based, self-managed version of MongoDB:MongoDB的基于订阅的自我管理版本
  • MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB:MongoDB的源代码可用、免费使用和自我管理版本

Syntax语法

ClientEncryption.createEncryptedCollection has the following syntax:具有以下语法:

clientEncryption = db.getMongo().getClientEncryption()

clientEncryption.createEncryptedCollection(
dbName,
collName,
{
provider: kmsProviderName,
createCollectionOptions: encryptedFieldsMap,
masterKey: customerMasterKeyCredentials
}
)

Command Fields命令字段

createEncryptedCollection takes these fields:接受这些字段:

Field字段Type类型Necessity必要性Description描述
dbNamestring字符串Required必需Name of the database to encrypt.要加密的数据库的名称。
collNamestring字符串Required必需Name of the collection to encrypt.要加密的集合的名称。
clientEncOptsdocument文档Required必需Options to configure the encrypted collection.配置加密集合的选项。
clientEncOpts.providerstring字符串Required必需KMS you are using to store your Customer Master Key.您用于存储客户主键的KMS。
clientEncOpts.createCollectionOptionsdocument文档Required必需Fields to encrypt. See Steps for details on how to configure the encryptedFieldsMap object.要加密的字段。有关如何配置encryptedFieldsMap对象的详细信息,请参阅步骤
clientEncOpts.masterKeydocument文档Optional可选How to get the master key when the KMS Provider is AWS, GCP, or Azure.当KMS提供商是AWS、GCP或Azure时,如何获取主键。

Behavior行为

The mongosh client-side field level and queryable encryption methods require a database connection configured for client-side encryption. mongosh客户端字段级和可查询加密方法需要为客户端加密配置数据库连接。If the current database connection was not initiated with client-side field level encryption enabled, either:如果当前数据库连接不是在启用客户端字段级加密的情况下启动的,则:

  • Use the Mongo() constructor from the mongosh to establish a connection with the required client-side field level encryption options. The Mongo() method supports the following Key Management Service (KMS) providers for Customer Master Key (CMK) management:使用mongosh中的Mongo()构造函数与所需的客户端字段级加密选项建立连接。Mongo()方法支持以下用于客户主键(CMK)管理的键管理服务(KMS)提供程序:

or

Example示例

The following example uses a locally managed KMS for the Queryable Encryption configuration.以下示例使用本地管理的KMS进行可查询加密配置。

1

Create Your Encrypted Connection创建加密连接

  1. Start mongosh开始mongosh

    Run:运行:

    mongosh --nodb

    --nodb means don't connect to a database.意味着不要连接到数据库。

  2. Generate a Key String生成键字符串

    Generate a base 64 96-byte string:生成一个基本64 96字节的字符串:

    const TEST_LOCAL_KEY = require("crypto").randomBytes(96).toString("base64")
  3. Create an Encryption Options Object创建加密选项对象

    To create a client-side field level encryption options object, use the TEST_LOCAL_KEY string from the previous step:要创建客户端字段级加密选项对象,请使用上一步中的TEST_LOCAL_KEY字符串:

       var autoEncryptionOpts = {
    "keyVaultNamespace" : "encryption.__dataKeys",
    "kmsProviders" : {
    "local" : {
    "key" : BinData(0, TEST_LOCAL_KEY)
    }
    }
    }
  4. Create an Encrypted Client Object创建加密客户端对象

    To create an encrypted client object, use the Mongo() constructor. 要创建加密的客户端对象,请使用Mongo()构造函数。Replace the mongodb://myMongo.example.net URI with the connection string URI for the target cluster. For example:更换mongodb://myMongo.example.netURI,其中包含目标群集的连接字符串URI。例如:

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

Specify which Fields to Encrypt指定要加密的字段

Create an encryptedFieldsMaps to specify which fields to encrypt:创建encryptedFieldsMaps以指定要加密的字段:

const encryptedFieldsMap = {
encryptedFields: {
fields: [
{
path: "secretField",
bsonType: "string",
queries: { queryType: "equality" },
},
],
},
};
3

Create Your Encrypted Collection创建加密集合

Create an encrypted enc.users collection:创建加密的enc.users集合:

clientEncryption = encryptedClient.getClientEncryption();

var result = clientEncryption.createEncryptedCollection(
"enc",
"users",
{
provider: "local",
createCollectionOptions: encryptedFieldsMap,
masterKey: {} // masterKey is optional when provider is local
}
)
4

Check Your Result Object检查结果对象

createEncryptedCollection returns a large result object with many fields. Check the value of result.collection to confirm the collection was created in the desired location.返回一个包含许多字段的大型结果对象。检查result.collection的值,以确认该集合是在所需位置创建的。

enc> result.collection
enc.users

Learn More了解更多

  • For complete documentation on initiating MongoDB connections with client-side field level encryption enabled, see Mongo().有关启用客户端字段级加密启动MongoDB连接的完整文档,请参阅Mongo()
  • For a complete example of how to create and query an encrypted collection, see Queryable Encryption Quick Start.有关如何创建和查询加密集合的完整示例,请参阅可查询加密快速入门