对于 AI 代理:可在 https://www.mongodb.com/zh-cn/docs/llms.txt 获取文档索引—通过在任何 URL 路径后添加 .md 可获取所有页面的 Markdown 版本。

CSFLE 快速入门

本指南向您展示如何使用自动客户端字段级加密 (CSFLE) 和 MongoDB 驱动程序来加密文档。

完成本指南后,您应该具备以下知识和软件:

  • 了解配置驱动程序以加密文档字段的步骤。

  • 一个有效但不适合生产的客户端应用程序,它利用自动客户端字段级加密。

重要

请勿在生产中使用此应用程序

由于此示例应用程序在应用程序的文件系统上存储了加密密钥,因此您可能会遇到未经授权访问该密钥或丢失解密数据的密钥的风险。

要查看演示如何创建支持 CSFLE 的生产就绪应用程序的教程,请参阅 CSFLE 教程。

要完成并运行本指南中的代码,您需要按照安装要求页面中的步骤来设置开发环境。

从页面右侧的 Select your language 下拉菜单中选择您想要查看其代码示例的编程语言。

要查看示例应用程序的完整代码,请在语言选择器中选择您的编程语言。

// You are viewing the .NET/C# driver code examples.// Use the dropdown menu to select a different driver.
1

您必须创建客户主密钥 ( CMK ) 才能执行 CSFLE。

创建 96 字节的客户主密钥并将其保存在本地密钥提供商(即您的文件系统)中,作为文件master-key.txt :

const fs = require("fs");const crypto = require("crypto");try { fs.writeFileSync("master-key.txt", crypto.randomBytes(96));} catch (err) { console.error(err);}

警告

保护生产环境中的本地密钥文件

我们建议您将客户数主密钥存储在远程密钥管理系统( KMS ) 中。要学习;了解如何在Queryable Encryption实施中使用远程KMS ,请参阅Queryable Encryption教程指南。

如果选择在生产中使用本地密钥提供商,请格外小心,不要将其存储在文件系统中。 请考虑使用 sidecar进程将密钥注入到客户端应用程序中,或使用其他确保密钥安全的方法。

提示

从命令行生成 CMK

使用以下命令从 Unix Shell 或 PowerShell 生成 CMK :

  • Unix/macOS Shell:

    echo $(head -c 96 /dev/urandom | base64 | tr -d '\n')
  • PowerShell:

    $r=[byte[]]::new(64);$g=[System.Security.Cryptography.RandomNumberGenerator]::Create();$g.GetBytes($r);[Convert]::ToBase64String($r)

将上述命令的输出保存到名为 customer-master-key.txt 的文件中。

提示

请参阅:完整代码

要查看制作客户主密钥的完整代码,请参阅我们的Github存储库。

2

在encryption.__keyVault命名空间中的keyAltNames字段上创建部分唯一索引。 对于存在keyAltNames的文档,此索引应具有partialFilterExpression 。

客户端字段级加密取决于服务器强制执行的密钥备用名称的唯一性。

选择与所需的 MongoDB 驱动程序对应的标签页:

var connectionString = "<Your MongoDB URI>";var keyVaultNamespace = CollectionNamespace.FromFullName("encryption.__keyVault");var keyVaultClient = new MongoClient(connectionString);var indexOptions = new CreateIndexOptions<BsonDocument>();indexOptions.Unique = true;indexOptions.PartialFilterExpression = new BsonDocument { { "keyAltNames", new BsonDocument { { "$exists", new BsonBoolean(true) } } } };var builder = Builders<BsonDocument>.IndexKeys;var indexKeysDocument = builder.Ascending("keyAltNames");var indexModel = new CreateIndexModel<BsonDocument>(indexKeysDocument, indexOptions);var keyVaultDatabase = keyVaultClient.GetDatabase(keyVaultNamespace.DatabaseNamespace.ToString());// Drop the Key Vault Collection in case you created this collection// in a previous run of this application. keyVaultDatabase.DropCollection(keyVaultNamespace.CollectionName);// Drop the database storing your encrypted fields as all// the DEKs encrypting those fields were deleted in the preceding line.keyVaultClient.GetDatabase("medicalRecords").DropCollection("patients");var keyVaultCollection = keyVaultDatabase.GetCollection<BsonDocument>(keyVaultNamespace.CollectionName.ToString());keyVaultCollection.Indexes.CreateOne(indexModel);
3
  1. 读取客户主密钥并指定 KMS 提供商设置

    检索您在本指南的创建客户主密钥步骤中生成的客户主密钥文件的内容。

    在您的 KMS 提供商设置中使用 客户主密钥 值。客户端使用这些设置来发现 客户主密钥。由于您使用的是本地密钥提供商,请将提供商名称设置为 local。

    var kmsProviders = new Dictionary<string, IReadOnlyDictionary<string, object>>();var provider = "local";string localMasterKeyBase64Read = File.ReadAllText("master-key.txt");var localMasterKeyBytes = Convert.FromBase64String(localMasterKeyBase64Read);var localOptions = new Dictionary<string, object>{ { "key", localMasterKeyBytes }};kmsProviders.Add("local", localOptions);
  2. 创建数据加密密钥

    使用 MongoDB 连接字符串和密钥保管库集合命名空间构建客户端,并创建数据加密密钥:

    注意

    密钥保管库集合命名空间权限

    要完成本教程,您的应用程序用于连接到 MongoDB 的数据库用户必须具有对以下命名空间的dbAdmin权限:

    • encryption.__keyVault

    • medicalRecords database

    var clientEncryptionOptions = new ClientEncryptionOptions( keyVaultClient: keyVaultClient, keyVaultNamespace: keyVaultNamespace, kmsProviders: kmsProviders ); var clientEncryption = new ClientEncryption(clientEncryptionOptions);var dataKeyOptions = new DataKeyOptions();var dataKeyId = clientEncryption.CreateDataKey(provider, dataKeyOptions, CancellationToken.None);var dataKeyIdBase64 = Convert.ToBase64String(GuidConverter.ToBytes(dataKeyId, GuidRepresentation.Standard));Console.WriteLine($"DataKeyId [base64]: {dataKeyIdBase64}");

    上述代码的输出应类似于以下内容:

    DataKeyId [base64]: 3k13WkSZSLy7kwAAP4HDyQ==

提示

请参阅:完整代码

要查看制作数据加密密钥的完整代码,请参阅我们的 Github 存储库。

4
  1. 指定密钥保管库集合命名空间

    指定 encryption.__keyVault 以作为密钥保管库集合命名空间。

    var keyVaultNamespace = CollectionNamespace.FromFullName("encryption.__keyVault");
  2. 指定本地客户主密钥

    指定 KMS 提供商并指定内联密钥:

    var kmsProviders = new Dictionary<string, IReadOnlyDictionary<string, object>>();var provider = "local";var localMasterKeyPath = "master-key.txt";string localMasterKeyBase64Read = File.ReadAllText(localMasterKeyPath);var localMasterKeyBytes = Convert.FromBase64String(localMasterKeyBase64Read);var localOptions = new Dictionary<string, object>{ { "key", localMasterKeyBytes }};kmsProviders.Add(provider, localOptions);
  3. 为集合创建加密模式

    提示

    添加数据加密密钥 Base64 ID

    请务必更新以下代码以包含 Base64 DEK ID。您在本指南的生成数据加密密钥步骤中获得了该值。

    var keyId = "<Your base64 DEK ID here>";var schema = new BsonDocument{ { "bsonType", "object" }, { "encryptMetadata", new BsonDocument("keyId", new BsonArray(new[] { new BsonBinaryData(Convert.FromBase64String(keyId), BsonBinarySubType.UuidStandard) })) }, { "properties", new BsonDocument { { "ssn", new BsonDocument { { "encrypt", new BsonDocument { { "bsonType", "int" }, { "algorithm", "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic" } } } } }, { "bloodType", new BsonDocument { { "encrypt", new BsonDocument { { "bsonType", "string" }, { "algorithm", "AEAD_AES_256_CBC_HMAC_SHA_512-Random" } } } } }, { "medicalRecords", new BsonDocument { { "encrypt", new BsonDocument { { "bsonType", "array" }, { "algorithm", "AEAD_AES_256_CBC_HMAC_SHA_512-Random" } } } } }, { "insurance", new BsonDocument { { "bsonType", "object" }, { "properties", new BsonDocument { { "policyNumber", new BsonDocument { { "encrypt", new BsonDocument { { "bsonType", "int" }, { "algorithm", "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic" } } } } } } } } } } }};var schemaMap = new Dictionary<string, BsonDocument>();schemaMap.Add(dbNamespace, schema);
  4. 指定自动加密共享库位置

    var mongoBinariesPath = "<Full path to your Automatic Encryption Shared Library>";var extraOptions = new Dictionary<string, object>(){ { "cryptSharedLibPath", mongoBinariesPath },};

    注意

    自动加密选项

    自动加密选项向自动加密共享库提供配置信息,这将修改应用程序在访问加密字段时的行为。

    要学习;了解有关自动加密共享库的更多信息,请参阅安装和配置 CSFLE 查询分析组件页面。

  5. 创建 MongoClient

    使用以下自动加密设置实例化 MongoDB 客户端对象:

    MongoClientSettings.Extensions.AddAutoEncryption(); // .NET/C# Driver v3.0 or later onlyvar clientSettings = MongoClientSettings.FromConnectionString(connectionString);var autoEncryptionOptions = new AutoEncryptionOptions( keyVaultNamespace: keyVaultNamespace, kmsProviders: kmsProviders, schemaMap: schemaMap, extraOptions: extraOptions );clientSettings.AutoEncryptionOptions = autoEncryptionOptions;var secureClient = new MongoClient(clientSettings);
5

使用启用了 CSFLE 的 MongoClient 实例,通过以下代码片段将具有加密字段的文档插入到 medicalRecords.patients 命名空间中:

var sampleDocFields = new BsonDocument{ { "name", "Jon Doe" }, { "ssn", 145014000 }, { "bloodType", "AB-" }, { "medicalRecords", new BsonArray { new BsonDocument("weight", 180), new BsonDocument("bloodPressure", "120/80") } }, { "insurance", new BsonDocument { { "policyNumber", 123142 }, { "provider", "MaestCare" } } }}; // Construct an auto-encrypting clientvar secureCollection = secureClient.GetDatabase(db).GetCollection<BsonDocument>(coll); // Insert a document into the collectionsecureCollection.InsertOne(sampleDocFields);

在您插入文档时,启用了 CSFLE 的客户端对文档字段进行加密,以使其类似于以下内容:

{ "_id": { "$oid": "<_id of your document>" }, "name": "Jon Doe", "ssn": { "$binary": "<cipher-text>", "$type": "6" }, "bloodType": { "$binary": "<cipher-text>", "$type": "6" }, "medicalRecords": { "$binary": "<cipher-text>", "$type": "6" }, "insurance": { "provider": "MaestCare", "policyNumber": { "$binary": "<cipher-text>", "$type": "6" } }}

提示

请参阅:完整代码

要查看用于插入带加密字段的文档的完整代码,请访问我们的 Github 存储库

6

检索您在本指南的插入具有加密字段的文档步骤中插入的具有加密字段的文档。

为了显示 CSFLE 的功能,以下代码片段使用配置为自动 CSFLE 的客户端以及未配置为自动 CSFLE 的客户端来查询文档。

Console.WriteLine("Finding a document with regular (non-encrypted) client.");var filter = Builders<BsonDocument>.Filter.Eq("name", "Jon Doe");var regularResult = regularCollection.Find(filter).Limit(1).ToList()[0];Console.WriteLine($"\n{regularResult}\n"); Console.WriteLine("Finding a document with encrypted client");var ssnFilter = Builders<BsonDocument>.Filter.Eq("name", "Jon Doe");var secureResult = secureCollection.Find(ssnFilter).Limit(1).First();Console.WriteLine($"\n{secureResult}\n");

上述代码片段的输出应如下所示:

Finding a document with regular (non-encrypted) client. { _id: new ObjectId("629a452e0861b3130887103a"), name: 'Jon Doe', ssn: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e7910c20697e5f4fa95710aafc9153f0a3dc769c8a132a604b468732ff1f4d8349ded3244b59cbfb41444a210f28b21ea1b6c737508d9d30e8baa30c1d8070c4d5e26", "hex"), 6), bloodType: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e79022e238536dfd8caadb4d7751ac940e0f195addd7e5c67b61022d02faa90283ab69e02303c7e4001d1996128428bf037dea8bbf59fbb20c583cbcff2bf3e2519b4", "hex"), 6), 'key-id': 'demo-data-key', medicalRecords: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e790405163a3207cff175455106f57eef14e5610c49a99bcbd14a7db9c5284e45e3ee30c149354015f941440bf54725d6492fb3b8704bc7c411cff6c868e4e13c58233c3d5ed9593eca4e4d027d76d3705b6d1f3b3c9e2ceee195fd944b553eb27eee69e5e67c338f146f8445995664980bf0", "hex"), 6), insurance: { policyNumber: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e79108decd85c05be3fec099e015f9d26d9234605dc959cc1a19b63072f7ffda99db38c7b487de0572a03b2139ac3ee163bcc40c8508f366ce92a5dd36e38b3c742f7", "hex"), 6), provider: 'MaestCare' }} Finding a document with encrypted client { _id: new ObjectId("629a452e0861b3130887103a"), name: 'Jon Doe', ssn: 241014209, bloodType: 'AB+', 'key-id': 'demo-data-key', medicalRecords: [ { weight: 180, bloodPressure: '120/80' } ], insurance: { policyNumber: 123142, provider: 'MaestCare' }}

提示

请参阅:完整代码

要查看查找带有加密字段的文档的完整代码,请参阅我们的 Github 存储库

要查看有关具有远程KMS的可投入生产的 CSFLE 教程,请参阅 CSFLE 教程。

要学习;了解CSFLE 的工作原理,请参阅 CSFLE 基础知识。

如需详细了解本指南中提到的主题,请参阅以下链接: