在 Azure 中使用自动 Queryable Encryption
在此页面上
概述
本指南介绍如何使用 Azure Key Vault 构建启用了 Queryable Encryption 的应用程序。
在完成本指南中的步骤后,您应该具有:
托管在 Azure Key Vault 实例上的客户主密钥。
一个有效的客户端应用程序,使用客户主密钥插入加密文档。
开始之前
要完成并运行本指南中的代码,您需要按照安装要求页面所示设置开发环境。
提示
请参阅:完整应用程序
要查看您在本指南中创建的应用程序的完整代码,请选择与您的编程语言相对应的标签页,然后点击提供的链接:
设置 KMS
向 Azure 注册您的应用程序
登录到 Azure
向 Azure Active Directory 注册您的应用程序
要在 Azure Active Directory 上注册应用程序,请按照 Microsoft 官方文档 注册应用程序到 Microsoft 身份平台 快速入门。
重要
记录凭证
确保记录以下凭证:
租户 ID
客户 ID
客户端密钥
在本教程的后面部分,您将需要它们来构造 kmsProviders
对象。
创建客户主密钥
创建 Azure Key Vault 和客户主密钥
要创建新的 Azure Key Vault 实例和客户主密钥,请遵循 Microsoft 官方文档 使用 Azure 门户从 Azure Key Vault 设置和检索密钥 快速入门。
重要
记录凭证
确保记录以下凭证:
密钥名称
密钥标识符(本指南后面称为
keyVaultEndpoint
)keyVersion
在本教程的后面内容中,您将需要它们来构造dataKeyOpts
对象。
创建应用程序
创建你的数据加密密钥和加密collection
添加 Azure Key Vault 档案
将服务帐户凭证添加到启用了 Queryable Encryption 的客户端代码中。
选择与所需的 MongoDB 驱动程序对应的标签页:
提示
您在本指南的“向 Azure 注册应用程序”步骤中记录了 Azure Key Vault 档案。
提示
了解详情
要了解有关 Azure Key Vault 的 KMS 提供商对象的更多信息,请参阅Azure Key Vault。
添加您的密钥信息
更新以下代码以指定客户主密钥:
提示
您在本指南的 创建客户主密钥 步骤中记录了客户主密钥的 ARN 和地区。
创建数据加密密钥
使用 MongoDB 连接字符串和密钥保管库集合命名空间构建客户端,并创建数据加密密钥:
注意
密钥保管库集合命名空间权限
本指南中的“密钥保管库集合”是encryption
数据库中的__keyVault
集合。 确保应用程序用于连接到 MongoDB 的数据库用户对encryption.__keyVault
命名空间具有ReadWrite权限。
提示
了解详情
要查看显示使用 Azure Key Vault 时客户端应用程序如何创建数据加密密钥的图表,请参阅架构。
要详细了解创建使用 Azure Key Vault 中托管的客户主密钥加密的数据加密密钥的选项,请参阅kmsProviders 对象和dataKeyOpts 对象。
提示
请参阅:完整代码
配置 MongoClient 以进行加密读取和写入
指定自动加密共享库位置
注意
自动加密选项
自动加密选项向自动加密共享库提供配置信息,这将修改应用程序在访问加密字段时的行为。
要了解有关自动加密共享库的更多信息,请参阅 Queryable Encryption 的自动加密共享库页面。
插入具有加密字段的文档
使用已启用 Queryable Encryption 的实例MongoClient
,通过以下代码段将加密文档插入到命名空间medicalRecords.patients
中:
插入文档时,启用了 Queryable Encryption 的客户端会对文档的字段进行加密,如下所示:
{ "_id": { "$oid": "<_id value>" }, "firstName": "Jon", "lastName": "Doe", "patientId": { "$binary": { "base64": "<ciphertext>", "subType": "06" } }, "address": "157 Electric Ave.", "patientRecord": { "ssn": { "$binary": { "base64": "<ciphertext>", "subType": "06" } }, "billing": { "$binary": { "base64": "<ciphertext>", "subType": "06" } } }, "medications": { "$binary": { "base64": "<ciphertext>", "subType": "06" } }, "__safeContent__": [ { "$binary": { "base64": "<ciphertext>", "subType": "00" } }, { "$binary": { "base64": "<ciphertext>", "subType": "00" } } ] }
警告
不要修改 __safeContent__ 字段
__safeContent__
字段对于 Queryable Encryption 至关重要。请勿修改此字段的内容。
提示
请参阅:完整代码
检索加密文档
检索在本指南的“插入具有加密字段的文档”步骤中插入的加密文档。
为了显示 Queryable Encryption 的功能,以下代码片段使用配置为自动 Queryable Encryption 的客户端以及未配置为自动 Queryable Encryption 的客户端来查询您的文档。
上述代码片段的输出应如下所示:
Finding a document with regular (non-encrypted) client. { _id: new ObjectId("628eabeb37590e84ea742665"), firstName: 'Jon', lastName: 'Doe', patientId: new Binary(Buffer.from("0798810acc0f4f46c9a76883cee80fca12102e9ddcbcdae46a821fa108a8155a850f2d0919475b6531ada68973d436a199b537a05a98a708c36d2bfec4979d59cbe66878865ce19e392d3e4789d309bdacc336e32efcc851806ae0a41b355288c10d01e39147e1c40d919c41913a0c9d2d3fad0d0d1d2873c4fc82c6c22f27b517df5f3131b331b96ed16a7c5cf89e09082a2d898c2dcd73da91d08760ba74a70077b2d0fdbbe1eea75655a19fcc397812325ad40b102cbd16b8d36b22e11e3f93404f24a8ff68cfdec3c22b0e787cb30078a5227b2a", "hex"), 6), address: '157 Electric Ave.', patientRecord: { ssn: new Binary(Buffer.from("07e8b69630c32f4a00a542af768f8abcf50223edd812ff20b0ecb046ee1a9f5a0eef8d85d99cd26076411129942752516ee605c55aadce73f3d44d81ea6ddbbb8134b108a9deb40d8cab9cb4f08ef210ab0c9d2ea4347f9d235b861baf29751e60abcf059eb5c120305bd5ac05a4e07ac8ccfa6d37283f4cdbfeb7a8accb65b71857d486b5cf55e354d6a95e287d9e2dd65f3f9d9c4c9d0bdb1f26c4bd549d7be77db81796be293e08b2223bac67b212423c4e06568578b5bd7a3c33cedc1b291bcda0b27e005144d344563711a489f24b8e9b65bbb721d3a0e9d9b227a0cec0cbad", "hex"), 6), billing: new Binary(Buffer.from("06808ae69d4caa49cf90bb688f386f097f03f870a7b8fcebb1980c9ee5488b1f0f68558fc2163adcd92d00ea5f349f56ed34e7b391f54c48ed2760b4bde73022fc818dc7486a4e046b92ce9c82e00333c7779d9d6bb476713a20632b593b7de54812662cfc4d174d05451d3f4195514e12edba", "hex"), 6) }, medications: new Binary(Buffer.from("06665ec15d38254dc4aa16da856789d33404f27bfea53e0d2fa4deaff166989ab33f469644d89c29112d33b41dbe54ec2d89c43f3de52cdc5d454e8694046216f533614fa7b42b7c5406d6518f7ed8f9e3ce52fda6c8b2146d0f8cc51e21a3467183697e1735a9f60c18e173c1916101", "hex"), 6), __safeContent__: [ new Binary(Buffer.from("3044b134ad0f7c8a90dab1e05bb8b296a8ede540796bd7403ab47693cdba1b26", "hex"), 0), new Binary(Buffer.from("a22ddf9a5657cdd56bef72febbba44371899e6486962a1c07d682082c4e65712", "hex"), 0) ] } Finding a document with encrypted client, searching on an encrypted field { _id: new ObjectId("628eaca1dcf9b63e2f43162d"), firstName: 'Jon', lastName: 'Doe', patientId: 12345678, address: '157 Electric Ave.', patientRecord: { ssn: '987-65-4320', billing: { type: 'Visa', number: '4111111111111111' } }, medications: [ 'Atorvastatin', 'Levothyroxine' ], __safeContent__: [ new Binary(Buffer.from("fbdc6cfe3b4659693650bfc60baced27dcb42b793efe09da0ded54d60a9d5a1f", "hex"), 0), new Binary(Buffer.from("0f92ff92bf904a858ef6fd5b1e508187f523e791f51d8b64596461b38ebb1791", "hex"), 0) ] }
提示
请参阅:完整代码
了解详情
如需了解 Queryable Encryption 的工作原理,请参阅基础知识。
如需详细了解本指南中提到的主题,请参阅以下链接: