在 Amazon Web Services 中使用自动 Queryable Encryption
Overview
本指南向您展示如何构建一个应用程序,该应用程序实施 MongoDB Queryable Encryption 功能以自动加密和解密文档字段,并使用 Amazon Web Services (AWS) KMS进行密钥管理。
在完成本指南中的步骤后,您应该具有:
由 Amazon Web Services KMS 托管的客户主密钥
有权访问 AWS KMS 中的客户主密钥的 AWS IAM 用户
有效的客户端应用程序,可使用客户主密钥插入具有加密字段的文档
开始之前
要完成并运行本指南中的代码,您需要按照安装要求页面中的步骤来设置开发环境。
提示
请参阅:完整应用程序
要查看此样本应用程序的完整代码,请选择与您的编程语言相对应的标签页,然后点击提供的链接。 每个样本应用程序存储库都包含一个 README.md
文件,您可以使用该文件来了解如何设置环境和运行应用程序。
设置 KMS
创建客户主密钥
登录AmazonAmazon Web Services Web Services管理控制台。
导航至Amazon WebAmazon Web ServicesKMS Services KMS控制台。
创建客户主密钥
按照有关创建对称 KMS 密钥的官方 AWS 文档,创建新的对称密钥。您创建的密钥是客户主密钥。选择有助于识别该密钥的名称和描述;这些字段不影响 CMK 功能或配置。
在密钥生成过程的 Usage Permissions步骤中,应用以下默认密钥策略,该策略使身份和访问管理 ( IAM ) 策略能够授予对您的客户主密钥的访问权限:
{ "Version": "2012-10-17", "Statement": [ { "Sid": "Enable IAM User Permissions", "Effect": "Allow", "Principal": { "AWS": "<ARN of your AWS account principal>" }, "Action": "kms:*", "Resource": "*" } ] }
重要
记录您的客户主密钥的 Amazon 资源名称 (ARN) 和区域。您将在本指南的后续步骤中用到它们。
创建 AWS IAM 用户
导航至AmazonAmazon Web Services Web Services IAM 控制台。
创建 IAM 用户
按照有关 添加用户 的 官方文档,在 管理控制台中创建新的编程 IAM 用户Amazon Web ServicesAmazon Web Services 。您将使用此IAM用户作为启用了 Queryable Encryption 的应用程序的服务帐户。 Amazon Web ServicesKMS您的应用程序使用 IAM 用户通过 进行身份验证,通过客户主密钥 (CMK) 对数据加密密钥 (DEK) 进行加密和解密。
重要
记录凭证
确保在创建 IAM 用户的最后一步记录以下 IAM 凭证:
访问密钥 ID
秘密访问密钥
您有一次机会记录这些凭证。如果在该步骤中没有记录这些凭证,则必须创建另一个 IAM 用户。
授予权限
向您的IAM用户授予远程主密钥的kms:Encrypt
和kms:Decrypt
权限。
重要
新的客户端IAM用户不应具有主密钥的管理权限。 为了确保数据安全,请遵循 最小权限原则。
以下内联策略允许 IAM 用户按照最小权限原则使用客户主密钥进行加密和解密:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": ["kms:Decrypt", "kms:Encrypt"], "Resource": "<the Amazon Resource Name (ARN) of your remote master key>" } ] }
要将上述政策应用于 IAM 用户,请遵守 AWS 文档中的添加 IAM 身份权限指南。
重要
在生产环境中使用 IAM 角色进行身份验证
将启用了 Queryable Encryption 的应用程序部署到生产环境时,请使用IAM角色而不是IAM用户对应用程序进行身份验证。
要了解有关 IAM 角色的更多信息,请参阅官方 AWS 文档中的以下页面:
创建应用程序
分配应用程序变量
本教程中的代码示例使用以下变量来执行 Queryable Encryption 工作流:
kmsProviderName - 您用于存储客户主密钥的KMS 。 在本教程中,将此变量设置为
"aws"
。uri - 您的MongoDB 部署连接 URI。 在
MONGODB_URI
环境变量中设置连接 URI 或直接替换该值。keyVaultDatabaseName - MongoDB 中将存储您的数据加密密钥 (DEK) 的数据库。将此变量设置为
"encryption"
。keyVaultCollectionName - MongoDB 中将存储您的 DEK 的集合。 将此变量设置为
"__keyVault"
。keyVaultNamespace - MongoDB中将存储您的 DEK 的命名空间。 将此变量设置为
keyVaultDatabaseName
和keyVaultCollectionName
变量的值,并用句点分隔。cryptoDatabaseName - MongoDB 中将存储您的加密数据的数据库。将此变量设置为
"medicalRecords"
。cryptoCollectionName - MongoDB 中将存储您的加密数据的集合。将此变量设置为
"patients"
。
您可以使用以下代码来声明这些变量:
// KMS provider name should be one of the following: "aws", "gcp", "azure", "kmip" or "local" const kmsProviderName = "<Your KMS Provider Name>"; const uri = process.env.MONGODB_URI; // Your connection URI const keyVaultDatabaseName = "encryption"; const keyVaultCollectionName = "__keyVault"; const keyVaultNamespace = `${keyVaultDatabaseName}.${keyVaultCollectionName}`; const encryptedDatabaseName = "medicalRecords"; const encryptedCollectionName = "patients";
kmsProviderName - 您用来存储客户主密钥的 KMS。 在本教程中,请将此值设置为
"aws"
。keyVaultDatabaseName - MongoDB 中将存储您的数据加密密钥 (DEK) 的数据库。 将
keyVaultDatabaseName
的值设置为"encryption"
。keyVaultCollectionName - MongoDB 中将存储您的 DEK 的集合。 将
keyVaultCollectionName
的值设置为"__keyVault"
。keyVaultNamespace - MongoDB 中将存储您的 DEK 的命名空间。 将
keyVaultNamespace
设置为新的CollectionNamespace
对象,其名称是keyVaultDatabaseName
和keyVaultCollectionName
变量的值,用句点分隔。cryptoDatabaseName - MongoDB 中将存储您的加密数据的数据库。 将
encryptedDatabaseName
的值设置为"medicalRecords"
。encryptedCollectionName - MongoDB 中将存储您的加密数据的 collection。将
encryptedCollectionName
的值设置为"patients"
。uri - 您的 MongoDB 部署连接 URI。 在
appsettings.json
文件中设置连接 URI 或直接替换该值。
您可以使用以下代码来声明这些变量:
// KMS provider name should be one of the following: "aws", "gcp", "azure", "kmip" or "local" const string kmsProviderName = "<your KMS provider name>"; const string keyVaultDatabaseName = "encryption"; const string keyVaultCollectionName = "__keyVault"; var keyVaultNamespace = CollectionNamespace.FromFullName($"{keyVaultDatabaseName}.{keyVaultCollectionName}"); const string encryptedDatabaseName = "medicalRecords"; const string encryptedCollectionName = "patients"; var appSettings = new ConfigurationBuilder().AddJsonFile("appsettings.json").Build(); var uri = appSettings["MongoDbUri"];
kmsProviderName - 您用于存储客户主密钥的KMS 。 在本教程中,将此变量设置为
"aws"
。uri - 您的MongoDB 部署连接 URI。 在
MONGODB_URI
环境变量中设置连接 URI 或直接替换该值。keyVaultDatabaseName - MongoDB 中将存储您的数据加密密钥 (DEK) 的数据库。将此变量设置为
"encryption"
。keyVaultCollectionName - MongoDB 中将存储您的 DEK 的集合。 将此变量设置为
"__keyVault"
。keyVaultNamespace - MongoDB中将存储您的 DEK 的命名空间。 将此变量设置为
keyVaultDatabaseName
和keyVaultCollectionName
变量的值,并用句点分隔。cryptoDatabaseName - MongoDB 中将存储您的加密数据的数据库。将此变量设置为
"medicalRecords"
。cryptoCollectionName - MongoDB 中将存储您的加密数据的集合。将此变量设置为
"patients"
。
您可以使用以下代码来声明这些变量:
// KMS provider name should be one of the following: "aws", "gcp", "azure", "kmip" or "local" kmsProviderName := "<KMS provider name>" uri := os.Getenv("MONGODB_URI") // Your connection URI keyVaultDatabaseName := "encryption" keyVaultCollectionName := "__keyVault" keyVaultNamespace := keyVaultDatabaseName + "." + keyVaultCollectionName encryptedDatabaseName := "medicalRecords" encryptedCollectionName := "patients"
kmsProviderName - 您用于存储客户主密钥的KMS 。 在本教程中,将此变量设置为
"aws"
。uri - 您的MongoDB 部署连接 URI。 在
MONGODB_URI
环境变量中设置连接 URI 或直接替换该值。keyVaultDatabaseName - MongoDB 中将存储您的数据加密密钥 (DEK) 的数据库。将此变量设置为
"encryption"
。keyVaultCollectionName - MongoDB 中将存储您的 DEK 的集合。 将此变量设置为
"__keyVault"
。keyVaultNamespace - MongoDB中将存储您的 DEK 的命名空间。 将此变量设置为
keyVaultDatabaseName
和keyVaultCollectionName
变量的值,并用句点分隔。cryptoDatabaseName - MongoDB 中将存储您的加密数据的数据库。将此变量设置为
"medicalRecords"
。cryptoCollectionName - MongoDB 中将存储您的加密数据的集合。将此变量设置为
"patients"
。
您可以使用以下代码来声明这些变量:
// KMS provider name should be one of the following: "aws", "gcp", "azure", "kmip" or "local" String kmsProviderName = "<KMS provider name>"; String uri = QueryableEncryptionHelpers.getEnv("MONGODB_URI"); // Your connection URI String keyVaultDatabaseName = "encryption"; String keyVaultCollectionName = "__keyVault"; String keyVaultNamespace = keyVaultDatabaseName + "." + keyVaultCollectionName; String encryptedDatabaseName = "medicalRecords"; String encryptedCollectionName = "patients";
kmsProviderName - 您用于存储客户主密钥的KMS 。 在本教程中,将此变量设置为
"aws"
。uri - 您的MongoDB 部署连接 URI。 在
MONGODB_URI
环境变量中设置连接 URI 或直接替换该值。keyVaultDatabaseName - MongoDB 中将存储您的数据加密密钥 (DEK) 的数据库。将此变量设置为
"encryption"
。keyVaultCollectionName - MongoDB 中将存储您的 DEK 的集合。 将此变量设置为
"__keyVault"
。keyVaultNamespace - MongoDB中将存储您的 DEK 的命名空间。 将此变量设置为
keyVaultDatabaseName
和keyVaultCollectionName
变量的值,并用句点分隔。cryptoDatabaseName - MongoDB 中将存储您的加密数据的数据库。将此变量设置为
"medicalRecords"
。cryptoCollectionName - MongoDB 中将存储您的加密数据的集合。将此变量设置为
"patients"
。
您可以使用以下代码来声明这些变量:
// KMS provider name should be one of the following: "aws", "gcp", "azure", "kmip" or "local" const kmsProviderName = "<Your KMS Provider Name>"; const uri = process.env.MONGODB_URI; // Your connection URI const keyVaultDatabaseName = "encryption"; const keyVaultCollectionName = "__keyVault"; const keyVaultNamespace = `${keyVaultDatabaseName}.${keyVaultCollectionName}`; const encryptedDatabaseName = "medicalRecords"; const encryptedCollectionName = "patients";
kms_provider_name - 您用来存储客户主密钥的KMS 。 在本教程中,将此变量设置为
"aws"
。uri - 您的MongoDB 部署连接 URI。 在
MONGODB_URI
环境变量中设置连接 URI 或直接替换该值。key_vault_database_name - MongoDB中将存储您的数据加密密钥 (DEK) 的数据库。 将此变量设置为
"encryption"
。key_vault_collection_name - MongoDB中将存储您的 DEK 的集合。 将此变量设置为
"__keyVault"
。key_vault_namespace - MongoDB中存储 DEK 的命名空间。 将此变量设置为
key_vault_database_name
和key_vault_collection_name
变量的值,并用句点分隔。encryption_database_name - MongoDB中将存储您的加密加密的数据库。 将此变量设置为
"medicalRecords"
。encryption_collection_name - MongoDB中将存储您的加密加密的集合。 将此变量设置为
"patients"
。
您可以使用以下代码来声明这些变量:
# KMS provider name should be one of the following: "aws", "gcp", "azure", "kmip" or "local" kms_provider_name = "<KMS provider name>" uri = os.environ['MONGODB_URI'] # Your connection URI key_vault_database_name = "encryption" key_vault_collection_name = "__keyVault" key_vault_namespace = f"{key_vault_database_name}.{key_vault_collection_name}" encrypted_database_name = "medicalRecords" encrypted_collection_name = "patients"
创建加密集合
添加 AWS KMS 凭证
创建一个包含Amazon Web Services KMS凭证的变量,其结构如下。 使用您在本教程的创建 IAM 用户步骤中创建的访问密钥ID和秘密访问密钥。
kmsProviderCredentials = { aws: { accessKeyId: process.env["AWS_ACCESS_KEY_ID"], // Your AWS access key ID secretAccessKey: process.env["AWS_SECRET_ACCESS_KEY"], // Your AWS secret access key }, };
var kmsProviderCredentials = new Dictionary<string, IReadOnlyDictionary<string, object>>(); var kmsOptions = new Dictionary<string, object> { { "accessKeyId", _appSettings["Aws:AccessKeyId"] }, // Your AWS access key ID { "secretAccessKey", _appSettings["Aws:SecretAccessKey"] } // Your AWS secret access key }; kmsProviderCredentials.Add(kmsProvider, kmsOptions);
kmsProviderCredentials := map[string]map[string]interface{}{ "aws": { "accessKeyId": os.Getenv("AWS_ACCESS_KEY_ID"), // AWS access key ID "secretAccessKey": os.Getenv("AWS_SECRET_ACCESS_KEY"), // AWS secret access key }, }
Map<String, Object> kmsProviderDetails = new HashMap<>(); kmsProviderDetails.put("accessKeyId", getEnv("AWS_ACCESS_KEY_ID")); // Your AWS access key ID kmsProviderDetails.put("secretAccessKey", getEnv("AWS_SECRET_ACCESS_KEY")); // Your AWS secret access key Map<String, Map<String, Object>> kmsProviderCredentials = new HashMap<String, Map<String, Object>>(); kmsProviderCredentials.put("aws", kmsProviderDetails);
kmsProviders = { aws: { accessKeyId: process.env.AWS_ACCESS_KEY_ID, // Your AWS access key ID secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY, // Your AWS secret access key }, };
kms_provider_credentials = { "aws": { "accessKeyId": os.environ['AWS_ACCESS_KEY_ID'], # Your AWS access key ID "secretAccessKey": os.environ['AWS_SECRET_ACCESS_KEY'] # Your AWS secret access key } }
重要
提醒:在生产环境中使用 IAM 角色进行身份验证
要使用 IAM 角色而不是 IAM 用户对应用程序进行身份验证,请在 KMS 提供程序对象中为凭证指定一个空对象。这会指示驱动程序自动从环境中检索凭证:
kmsProviders = { aws: { } };
kmsProviderCredentials.Add("aws", new Dictionary<string, object>);
kmsProviderCredentials := map[string]map[string]interface{}{ "aws": { }, }
kmsProviderCredentials.put("aws", new HashMap<>());
kmsProviders = { aws: { } };
kms_provider_credentials = { "aws": { } }
添加您的客户主密钥档案
创建一个包含以下结构的客户主密钥凭证的变量。 使用您在本教程的 创建客户主密钥 步骤中记录的 ARN 和地区。
customerMasterKeyCredentials = { key: process.env["AWS_KEY_ARN"], // Your AWS Key ARN region: process.env["AWS_KEY_REGION"], // Your AWS Key Region };
var customerMasterKeyCredentials = new BsonDocument { { "key", _appSettings["Aws:KeyArn"] }, // Your AWS Key ARN { "region", _appSettings["Aws:KeyRegion"] } // Your AWS Key Region };
customerMasterKeyCredentials := map[string]string{ "key": os.Getenv("AWS_KEY_ARN"), // Your AWS Key ARN "region": os.Getenv("AWS_KEY_REGION"), // Your AWS Key Region }
BsonDocument customerMasterKeyCredentials = new BsonDocument(); customerMasterKeyCredentials.put("provider", new BsonString(kmsProviderName)); customerMasterKeyCredentials.put("key", new BsonString(getEnv("AWS_KEY_ARN"))); // Your AWS Key ARN customerMasterKeyCredentials.put("region", new BsonString(getEnv("AWS_KEY_REGION"))); // Your AWS Key Region
customerMasterKeyCredentials = { key: process.env.AWS_KEY_ARN, // Your AWS Key ARN region: process.env.AWS_KEY_REGION, // Your AWS Key Region };
customer_master_key_credentials = { "key": os.environ['AWS_KEY_ARN'], # Your AWS Key ARN "region": os.environ['AWS_KEY_REGION'] # Your AWS Key Region }
设置自动加密选项
创建一个包含以下选项的autoEncryptionOptions
对象:
密钥保管库集合的命名空间
kmsProviderCredentials
对象,其中包含您的 Amazon Web Services KMS 档案
const autoEncryptionOptions = { keyVaultNamespace: keyVaultNamespace, kmsProviders: kmsProviderCredentials, };
创建一个包含以下选项的AutoEncryptionOptions
对象:
密钥保管库集合的命名空间
kmsProviderCredentials
对象,其中包含您的 Amazon Web Services KMS 档案extraOptions
对象,其中包含指向您的自动加密共享库的路径
var extraOptions = new Dictionary<string, object> { { "cryptSharedLibPath", _appSettings["CryptSharedLibPath"] } // Path to your Automatic Encryption Shared Library }; var autoEncryptionOptions = new AutoEncryptionOptions( keyVaultNamespace, kmsProviderCredentials, extraOptions: extraOptions);
创建一个包含以下选项的AutoEncryption
对象:
密钥保管库集合的命名空间
kmsProviderCredentials
对象,其中包含您的 Amazon Web Services KMS 档案cryptSharedLibraryPath
对象,其中包含指向您的自动加密共享库的路径
cryptSharedLibraryPath := map[string]interface{}{ "cryptSharedLibPath": os.Getenv("SHARED_LIB_PATH"), // Path to your Automatic Encryption Shared Library } autoEncryptionOptions := options.AutoEncryption(). SetKeyVaultNamespace(keyVaultNamespace). SetKmsProviders(kmsProviderCredentials). SetExtraOptions(cryptSharedLibraryPath)
创建一个包含以下选项的AutoEncryptionSettings
对象:
密钥保管库集合的命名空间
kmsProviderCredentials
对象,其中包含您的 Amazon Web Services KMS 档案extraOptions
对象,其中包含指向您的自动加密共享库的路径
Map<String, Object> extraOptions = new HashMap<String, Object>(); extraOptions.put("cryptSharedLibPath", getEnv("SHARED_LIB_PATH")); // Path to your Automatic Encryption Shared Library AutoEncryptionSettings autoEncryptionSettings = AutoEncryptionSettings.builder() .keyVaultNamespace(keyVaultNamespace) .kmsProviders(kmsProviderCredentials) .extraOptions(extraOptions) .build();
创建一个包含以下选项的autoEncryptionOptions
对象:
密钥保管库集合的命名空间
kmsProviders
对象,其中包含您的 Amazon Web Services KMS 档案sharedLibraryPathOptions
对象,其中包含指向您的自动加密共享库的路径
const extraOptions = { cryptSharedLibPath: process.env.SHARED_LIB_PATH, // Path to your Automatic Encryption Shared Library }; const autoEncryptionOptions = { keyVaultNamespace, kmsProviders, extraOptions, };
创建一个包含以下选项的AutoEncryptionOpts
对象:
kms_provider_credentials
对象,其中包含您的 Amazon Web Services KMS 档案密钥保管库集合的命名空间
自动加密共享库的路径
auto_encryption_options = AutoEncryptionOpts( kms_provider_credentials, key_vault_namespace, crypt_shared_lib_path=os.environ['SHARED_LIB_PATH'] # Path to your Automatic Encryption Shared Library> )
注意
自动加密选项
自动加密选项向自动加密共享库提供配置信息,这将修改应用程序在访问加密字段时的行为。
要了解有关自动加密共享库的更多信息,请参阅 Queryable Encryption 的自动加密共享库页面。
创建客户端以设置加密集合
要创建用于对集合中的数据进行加密和解密的客户端,请使用您的连接 URI 和自动加密选项实例化一个新的 MongoClient
。
const encryptedClient = Mongo(uri, autoEncryptionOptions);
var clientSettings = MongoClientSettings.FromConnectionString(uri); clientSettings.AutoEncryptionOptions = qeHelpers.GetAutoEncryptionOptions( keyVaultNamespace, kmsProviderCredentials); var encryptedClient = new MongoClient(clientSettings);
encryptedClient, err := mongo.Connect( context.TODO(), options.Client().ApplyURI(uri).SetAutoEncryptionOptions(autoEncryptionOptions), ) if err != nil { panic(fmt.Sprintf("Unable to connect to MongoDB: %v\n", err)) } defer func() { _ = encryptedClient.Disconnect(context.TODO()) }()
MongoClientSettings clientSettings = MongoClientSettings.builder() .applyConnectionString(new ConnectionString(uri)) .autoEncryptionSettings(autoEncryptionSettings) .build(); try (MongoClient encryptedClient = MongoClients.create(clientSettings)) {
const encryptedClient = new MongoClient(uri, { autoEncryption: autoEncryptionOptions, });
encrypted_client = MongoClient( uri, auto_encryption_opts=auto_encryption_options)
指定要加密的字段
如要加密字段,请将其添加到加密模式中。要启用对字段的查询,请添加“queries”属性。创建加密模式,如下所示:
const encryptedFieldsMap = { encryptedFields: { fields: [ { path: "patientRecord.ssn", bsonType: "string", queries: { queryType: "equality" }, }, { path: "patientRecord.billing", bsonType: "object", }, ], }, };
var encryptedFields = new BsonDocument { { "fields", new BsonArray { new BsonDocument { { "keyId", BsonNull.Value }, { "path", "record.ssn" }, { "bsonType", "string" }, { "queries", new BsonDocument("queryType", "equality") } }, new BsonDocument { { "keyId", BsonNull.Value }, { "path", "record.billing" }, { "bsonType", "object" } } } } };
encryptedFieldsMap := bson.M{ "fields": []bson.M{ bson.M{ "keyId": nil, "path": "patientRecord.ssn", "bsonType": "string", "queries": []bson.M{ { "queryType": "equality", }, }, }, bson.M{ "keyId": nil, "path": "patientRecord.billing", "bsonType": "object", }, }, }
BsonDocument encryptedFieldsMap = new BsonDocument().append("fields", new BsonArray(Arrays.asList( new BsonDocument() .append("keyId", new BsonNull()) .append("path", new BsonString("patientRecord.ssn")) .append("bsonType", new BsonString("string")) .append("queries", new BsonDocument() .append("queryType", new BsonString("equality"))), new BsonDocument() .append("keyId", new BsonNull()) .append("path", new BsonString("patientRecord.billing")) .append("bsonType", new BsonString("object")))));
const encryptedFieldsMap = { encryptedFields: { fields: [ { path: "patientRecord.ssn", bsonType: "string", queries: { queryType: "equality" }, }, { path: "patientRecord.billing", bsonType: "object", }, ], }, };
encrypted_fields_map = { "fields": [ { "path": "patientRecord.ssn", "bsonType": "string", "queries": [{"queryType": "equality"}] }, { "path": "patientRecord.billing", "bsonType": "object", } ] }
注意
在前面的代码示例中,“ssn”和“billing”字段都经过加密,但只能查询“ssn”字段。
创建集合
实例化 ClientEncryption
以访问加密辅助方法的 API。
const clientEncryption = encryptedClient.getClientEncryption()
var clientEncryptionOptions = new ClientEncryptionOptions( keyVaultClient: keyVaultClient, keyVaultNamespace: keyVaultNamespace, kmsProviders: kmsProviderCredentials ); var clientEncryption = new ClientEncryption(clientEncryptionOptions);
opts := options.ClientEncryption(). SetKeyVaultNamespace(keyVaultNamespace). SetKmsProviders(kmsProviderCredentials) clientEncryption, err := mongo.NewClientEncryption(encryptedClient, opts) if err != nil { panic(fmt.Sprintf("Unable to create a ClientEncryption instance due to the following error: %s\n", err)) }
ClientEncryptionSettings clientEncryptionSettings = ClientEncryptionSettings.builder() .keyVaultMongoClientSettings(MongoClientSettings.builder() .applyConnectionString(new ConnectionString(uri)) .build()) .keyVaultNamespace(keyVaultNamespace) .kmsProviders(kmsProviderCredentials) .build(); ClientEncryption clientEncryption = ClientEncryptions.create(clientEncryptionSettings);
const clientEncryption = new ClientEncryption(encryptedClient, autoEncryptionOptions);
client_encryption = ClientEncryption( kms_providers=kms_provider_credentials, key_vault_namespace=key_vault_namespace, key_vault_client=encrypted_client, codec_options=CodecOptions(uuid_representation=STANDARD) )
使用可通过ClientEncryption
类访问的加密助手方法创建加密集合。 此方法自动为加密字段生成数据加密密钥并创建加密集合:
await clientEncryption.createEncryptedCollection( encryptedDatabaseName, encryptedCollectionName, { provider: kmsProviderName, createCollectionOptions: encryptedFieldsMap, masterKey: customerMasterKeyCredentials, } );
本教程的 C# 版本使用单独的类作为 Realm 数据模型来表示文档结构。将以下Patient
、 PatientRecord
和PatientBilling
类添加到您的项目中:
using MongoDB.Bson; using MongoDB.Bson.Serialization.Attributes; [ ]public class Patient { public ObjectId Id { get; set; } public string Name { get; set; } public PatientRecord Record { get; set; } }
public class PatientRecord { public string Ssn { get; set; } public PatientBilling Billing { get; set; } }
public class PatientBilling { public string CardType { get; set; } public long CardNumber { get; set; } }
添加这些类后,使用可通过ClientEncryption
类访问的加密助手方法创建加密collection。此方法自动为字段生成数据加密密钥并创建加密collection:
var createCollectionOptions = new CreateCollectionOptions<Patient> { EncryptedFields = encryptedFields }; clientEncryption.CreateEncryptedCollection(patientDatabase, encryptedCollectionName, createCollectionOptions, kmsProviderName, customerMasterKeyCredentials);
提示
数据库与数据库名称
创建加密集合的方法需要引用数据库对象,而不是数据库名称。可以通过在客户端对象上使用方法来获取此引用。
本教程的Go版本使用数据模型来表示文档结构。 将以下结构体添加到项目中以表示集合中的数据:
type PatientDocument struct { PatientName string `bson:"patientName"` PatientID int32 `bson:"patientId"` PatientRecord PatientRecord `bson:"patientRecord"` }
type PatientRecord struct { SSN string `bson:"ssn"` Billing PaymentInfo `bson:"billing"` }
type PaymentInfo struct { Type string `bson:"type"` Number string `bson:"number"` }
添加这些类后,使用可通过ClientEncryption
类访问的加密助手方法创建加密collection。此方法自动为字段生成数据加密密钥并创建加密collection:
createCollectionOptions := options.CreateCollection().SetEncryptedFields(encryptedFieldsMap) _, _, err = clientEncryption.CreateEncryptedCollection( context.TODO(), encryptedClient.Database(encryptedDatabaseName), encryptedCollectionName, createCollectionOptions, kmsProviderName, customerMasterKey, )
提示
数据库与数据库名称
创建加密集合的方法需要引用数据库对象,而不是数据库名称。可以通过在客户端对象上使用方法来获取此引用。
使用可通过ClientEncryption
类访问的加密助手方法创建加密集合。 此方法自动为加密字段生成数据加密密钥并创建加密集合:
CreateCollectionOptions createCollectionOptions = new CreateCollectionOptions().encryptedFields(encryptedFieldsMap); CreateEncryptedCollectionParams encryptedCollectionParams = new CreateEncryptedCollectionParams(kmsProviderName); encryptedCollectionParams.masterKey(customerMasterKeyCredentials); try { clientEncryption.createEncryptedCollection( encryptedClient.getDatabase(encryptedDatabaseName), encryptedCollectionName, createCollectionOptions, encryptedCollectionParams); }
提示
数据库与数据库名称
创建加密集合的方法需要引用数据库对象,而不是数据库名称。可以通过在客户端对象上使用方法来获取此引用。
注意
导入 ClientEncryption
使用 Node.js 驱动程序 v6.0 及更高版本时,必须从 mongodb
导入 ClientEncryption
。
对于较早的驱动程序版本,请从 mongodb-client-encryption
导入 ClientEncryption
。
使用可通过ClientEncryption
类访问的加密助手方法创建加密集合。 此方法自动为加密字段生成数据加密密钥并创建加密集合:
await clientEncryption.createEncryptedCollection( encryptedDatabase, encryptedCollectionName, { provider: kmsProviderName, createCollectionOptions: encryptedFieldsMap, masterKey: customerMasterKeyCredentials, } );
提示
数据库与数据库名称
创建加密集合的方法需要引用数据库对象,而不是数据库名称。可以通过在客户端对象上使用方法来获取此引用。
使用可通过ClientEncryption
类访问的加密助手方法创建加密集合。 此方法自动为加密字段生成数据加密密钥并创建加密集合:
client_encryption.create_encrypted_collection( encrypted_client[encrypted_database_name], encrypted_collection_name, encrypted_fields_map, kms_provider_name, customer_master_key_credentials, )
提示
数据库与数据库名称
创建加密集合的方法需要引用数据库对象,而不是数据库名称。可以通过在客户端对象上使用方法来获取此引用。
插入具有加密字段的文档
创建描述患者个人信息的示例文档。使用加密的客户端将其插入到 patients
集合中,如以下示例所示:
const patientDocument = { patientName: "Jon Doe", patientId: 12345678, patientRecord: { ssn: "987-65-4320", billing: { type: "Visa", number: "4111111111111111", }, }, }; const encryptedCollection = encryptedClient.getDB(encryptedDatabaseName).getCollection(encryptedCollectionName); const insertResult = await encryptedCollection.insertOne(patientDocument);
创建描述患者个人信息的示例文档。使用加密的客户端将其插入到 patients
集合中,如以下示例所示:
var patient = new Patient { Name = "Jon Doe", Id = new ObjectId(), Record = new PatientRecord { Ssn = "987-65-4320", Billing = new PatientBilling { CardType = "Visa", CardNumber = 4111111111111111 } } }; var encryptedCollection = encryptedClient.GetDatabase(encryptedDatabaseName). GetCollection<Patient>(encryptedCollectionName); encryptedCollection.InsertOne(patient);
创建描述患者个人信息的示例文档。使用加密的客户端将其插入到 patients
集合中,如以下示例所示:
patientDocument := &PatientDocument{ PatientName: "John Doe", PatientID: 12345678, PatientRecord: PatientRecord{ SSN: "987-65-4320", Billing: PaymentInfo{ Type: "Visa", Number: "4111111111111111", }, }, } coll := encryptedClient.Database(encryptedDatabaseName).Collection(encryptedCollectionName) _, err = coll.InsertOne(context.TODO(), patientDocument) if err != nil { panic(fmt.Sprintf("Unable to insert the patientDocument: %s", err)) }
本教程使用 POJO 作为数据模型来表示文档结构。 要将应用程序设立为使用 POJO,请添加以下代码:
CodecProvider pojoCodecProvider = PojoCodecProvider.builder().automatic(true).build(); CodecRegistry pojoCodecRegistry = fromRegistries(getDefaultCodecRegistry(), fromProviders(pojoCodecProvider));
要学习;了解有关Java POJO 的更多信息,请参阅 维基百科文章“普通旧Java对象”。
本教程使用以下 POJO:
Patient
PatientRecord
PatientBilling
将这些 POJO 类添加到您的应用程序中。 然后,创建描述患者个人信息的Patient
实例。 使用加密客户端将其插入到patients
集合中,如以下示例所示:
MongoDatabase encryptedDb = encryptedClient.getDatabase(encryptedDatabaseName).withCodecRegistry(pojoCodecRegistry); MongoCollection<Patient> collection = encryptedDb.getCollection(encryptedCollectionName, Patient.class); PatientBilling patientBilling = new PatientBilling("Visa", "4111111111111111"); PatientRecord patientRecord = new PatientRecord("987-65-4320", patientBilling); Patient patientDocument = new Patient("Jon Doe", patientRecord); InsertOneResult result = collection.insertOne(patientDocument);
创建描述患者个人信息的示例文档。使用加密的客户端将其插入到 patients
集合中,如以下示例所示:
const patientDocument = { patientName: "Jon Doe", patientId: 12345678, patientRecord: { ssn: "987-65-4320", billing: { type: "Visa", number: "4111111111111111", }, }, }; const encryptedCollection = encryptedClient .db(encryptedDatabaseName) .collection(encryptedCollectionName); const result = await encryptedCollection.insertOne(patientDocument);
创建描述患者个人信息的示例文档。使用加密的客户端将其插入到 patients
集合中,如以下示例所示:
patient_document = { "patientName": "Jon Doe", "patientId": 12345678, "patientRecord": { "ssn": "987-65-4320", "billing": { "type": "Visa", "number": "4111111111111111", }, }, } encrypted_collection = encrypted_client[encrypted_database_name][encrypted_collection_name] result = encrypted_collection.insert_one(patient_document)
加密字段查询
下面的代码示例对加密字段执行查找查询,并打印解密后的数据:
const findResult = await encryptedCollection.findOne({ "patientRecord.ssn": "987-65-4320", }); console.log(findResult);
var ssnFilter = Builders<Patient>.Filter.Eq("record.ssn", patient.Record.Ssn); var findResult = await encryptedCollection.Find(ssnFilter).ToCursorAsync(); Console.WriteLine(findResult.FirstOrDefault().ToJson());
var findResult PatientDocument err = coll.FindOne( context.TODO(), bson.M{"patientRecord.ssn": "987-65-4320"}, ).Decode(&findResult)
Patient findResult = collection.find( new BsonDocument() .append("patientRecord.ssn", new BsonString("987-65-4320"))) .first(); System.out.println(findResult);
const findResult = await encryptedCollection.findOne({ "patientRecord.ssn": "987-65-4320", }); console.log(findResult);
find_result = encrypted_collection.find_one({ "patientRecord.ssn": "987-65-4320" }) print(find_result)
上述代码示例的输出应类似于以下内容:
{ "_id": { "$oid": "648b384a722cb9b8392df76a" }, "name": "Jon Doe", "record": { "ssn": "987-65-4320", "billing": { "type": "Visa", "number": "4111111111111111" } }, "__safeContent__": [ { "$binary": { "base64": "L1NsYItk0Sg+oL66DBj6IYHbX7tveANQyrU2cvMzD9Y=", "subType": "00" } } ] }
警告
不要修改 __safeContent__ 字段
__safeContent__
字段对于 Queryable Encryption 至关重要。请勿修改此字段的内容。
了解详情
如需了解 Queryable Encryption 的工作原理,请参阅基础知识。
如需详细了解本指南中提到的主题,请参阅以下链接: