Use Automatic Queryable Encryption with GCP在GCP中使用自动可查询加密
On this page本页内容
Overview概述Before You Get Started开始之前Set Up the KMS设置KMSRegister a GCP Service Account注册GCP服务帐户Create a GCP Customer Master Key创建GCP客户主键Create the Application创建应用程序Assign Your Application Variables分配应用程序变量Create your Encrypted Collection创建加密集合Insert a Document with Encrypted Fields插入带有加密字段的文档Query on an Encrypted Field对加密字段的查询Learn More了解更多信息
Overview概述
This guide shows you how to build an application that implements the MongoDB Queryable Encryption feature to automatically encrypt and decrypt document fields and use Google Cloud Key Management Service for key management.本指南向您展示了如何构建一个实现MongoDB可查询加密功能的应用程序,以自动加密和解密文档字段,并使用谷歌云键管理服务进行键管理。
After you complete the steps in this guide, you should have:完成本指南中的步骤后,您应该具备:
A CMK managed by Google Cloud Key Management Service由谷歌云键管理服务管理的CMKA working client application that inserts documents with encrypted fields using your CMK使用CMK插入具有加密字段的文档的工作客户端应用程序
Customer Master Keys客户主键
To learn more about the Customer Master Key, read the Keys and Key Vaults documentation.要了解有关客户主键的更多信息,请阅读键和键库文档。
Before You Get Started开始之前
To complete and run the code in this guide, you need to set up your development environment as shown in the Installation Requirements page.要完成并运行本指南中的代码,您需要设置开发环境,如安装要求页面中所示。
See: Full Application请参阅:完整应用程序
To see the complete code for this sample application, select the tab corresponding to your programming language and follow the provided link. Each sample application repository includes a 要查看此示例应用程序的完整代码,请选择与编程语言相对应的选项卡,然后单击提供的链接。每个示例应用程序存储库都包含一个README.md
file that you can use to learn how to set up your environment and run the application.README.md
文件,您可以使用该文件了解如何设置环境和运行应用程序。
Set Up the KMS设置KMS
Register a GCP Service Account注册GCP服务帐户
Register or log in to your existing account on Google Cloud
.在Google Cloud
上注册或登录您的现有帐户。
Create a service account for your project为您的项目创建服务帐户
To create a service account on Google Cloud, follow the Creating a service account要在谷歌云上创建服务帐户,请遵循谷歌官方文档中的创建服务帐户 guide in Google's official documentation.
指南。
Add a service account key添加服务帐户键
To add a service account key on Google Cloud, follow the Managing service account keys要在谷歌云上添加服务帐户键,请遵循谷歌官方文档中的管理服务帐户键 guide in Google's official documentation.
指南。
When creating your service account key, you receive a one-time download of the private key information. Make sure to download this file in either the PKCS12 or JSON format for use later in this tutorial.创建您的服务帐户键时,您将收到私钥信息的一次性下载。请确保以PKCS12或JSON格式下载此文件,以便在本教程稍后使用。
Create a GCP Customer Master Key创建GCP客户主键
Create a new Customer Master Key创建新的客户主键
Create a key ring and a symmetric key by following the Create a key按照谷歌官方文档中的创建键 guide from Google's official documentation.
指南创建键环和对称键。
This key is your Customer Master Key (CMK).此键是您的客户主键(CMK)。
Record the following details of your CMK for use in a future step of this tutorial.记录以下CMK的详细信息,以便在本教程的下一步中使用。
Required | ||
---|---|---|
key_name | Yes | |
key_ring | Yes | |
key_version | No | |
location | Yes | |
endpoint | No | cloudkms.googleapis.com .cloudkms.googleapis.com 。 |
Create the Application创建应用程序
Assign Your Application Variables分配应用程序变量
The code samples in this tutorial use the following variables to perform the Queryable Encryption workflow:本教程中的代码示例使用以下变量来执行Queryable Encryption工作流:
-
kmsProviderName -
The KMS you're using to store your Customer Master Key. Set this variable to用于存储客户主键的KMS。在本教程中将此变量设置为"gcp"
for this tutorial."gcp"
。 -
uri -
Your MongoDB deployment connection URI.您的MongoDB部署连接URI。Set your connection URI in the在MONGODB_URI
environment variable or replace the value directly.MONGODB_URI
环境变量中设置连接URI或直接替换该值。 -
keyVaultDatabaseName -
The database in MongoDB where your data encryption keys (DEKs) will be stored. Set this variable toMongoDB中存储数据加密键(DEK)的数据库。将此变量设置为"encryption"
."encryption"
。 -
keyVaultCollectionName -
The collection in MongoDB where your DEKs will be stored. Set this variable toMongoDB中存储您的DEK的集合。将此变量设置为"__keyVault"
."__keyVault"
。 -
keyVaultNamespace -
The namespace in MongoDB where your DEKs will be stored. Set this variable to the values of theMongoDB中存储DEK的命名空间。将此变量设置为keyVaultDatabaseName
andkeyVaultCollectionName
variables, separated by a period.keyVaultDatabaseName
和keyVaultCollectionName
变量的值,用句点分隔。 -
encryptedDatabaseName -
The database in MongoDB where your encrypted data will be stored. Set this variable toMongoDB中存储加密数据的数据库。将此变量设置为"medicalRecords"
."medicalRecords"
。 -
encryptedCollectionName -
The collection in MongoDB where your encrypted data will be stored. Set this variable toMongoDB中存储加密数据的集合。将此变量设置为"patients"
."patients"
。
You can declare these variables by using the following code:您可以使用以下代码声明这些变量:
// 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";
Key Vault Collection Namespace Permissions键保管库集合命名空间权限
The Key Vault collection is in the 键保管库集合处于encryption.__keyVault
namespace. encryption.__keyVault
命名空间。Ensure that the database user your application uses to connect to MongoDB has ReadWrite permissions on this namespace.确保应用程序用于连接MongoDB的数据库用户对此命名空间具有ReadWrite权限。
Environment Variables环境变量
The sample code in this tutorial references environment variables that you need to set. Alternatively, you can replace the values directly in the code.本教程中的示例代码引用了需要设置的环境变量。或者,您可以直接替换代码中的值。
To learn how you can setup these environment variables, see the README.md file included in the sample application on GitHub.要了解如何设置这些环境变量,请参阅GitHub上示例应用程序中包含的README.md文件。
Create your Encrypted Collection创建加密集合
Add Your Google Cloud Key Management Service Credentials添加您的谷歌云键管理服务凭据
Create a variable containing your Google Cloud Key Management Service credentials with the following structure:创建一个包含您的Google Cloud键管理服务凭据的变量,其结构如下:
kmsProviders = {
gcp: {
email: process.env.GCP_EMAIL, // Your GCP email
privateKey: process.env.GCP_PRIVATE_KEY, // Your GCP private key
},
};
Add your Customer Master Key Credentials添加您的客户主键凭据
Create a variable containing your Customer Master Key credentials with the following structure. 使用以下结构创建一个包含客户主键凭据的变量。Use the credentials you recorded in the Create a new Customer Master Key step of this tutorial.使用您在本教程的创建新客户主键步骤中记录的凭据。
customerMasterKeyCredentials = {
projectId: process.env.GCP_PROJECT_ID, // Your GCP Project ID
location: process.env.GCP_LOCATION, // Your GCP Key Location
keyRing: process.env.GCP_KEY_RING, // Your GCP Key Ring
keyName: process.env.GCP_KEY_NAME, // Your GCP Key Name
};
Set Your Automatic Encryption Options设置自动加密选项
Create an 创建一个包含以下选项的autoEncryptionOptions
object that contains the following options:autoEncryptionOptions
对象:
-
The namespace of your Key Vault collection键库集合的命名空间 -
ThekmsProviders
object, which contains your Google Cloud Key Management Service credentialskmsProviders
对象,其中包含您的Google Cloud键管理服务凭据 -
ThesharedLibraryPathOptions
object, which contains the path to your Automatic Encryption Shared LibrarysharedLibraryPathOptions
对象,它包含自动加密共享库的路径
const sharedLibraryPathOptions = {
cryptSharedLibPath: process.env.SHARED_LIB_PATH, // Path to your Automatic Encryption Shared Library
};
const autoEncryptionOptions = {
keyVaultNamespace,
kmsProviders,
sharedLibraryPathOptions,
};
Automatic Encryption Options自动加密选项
The automatic encryption options provide configuration information to the Automatic Encryption Shared Library, which modifies the application's behavior when accessing encrypted fields.自动加密选项为自动加密共享库提供配置信息,该库在访问加密字段时修改应用程序的行为。
To learn more about the Automatic Encryption Shared Library, see the Automatic Encryption Shared Library for Queryable Encryption page.要了解有关自动加密共享库的更多信息,请参阅可查询加密的自动加密共享库页。
Create a Client to Set Up an Encrypted Collection创建客户端以设置加密集合
To create a client used to encrypt and decrypt data in your collection, instantiate a new 要创建一个用于加密和解密集合中数据的客户端,请使用连接URI和自动加密选项实例化一个新的MongoClient
by using your connection URI and your automatic encryption options.MongoClient
。
const encryptedClient = new MongoClient(uri, {
autoEncryption: autoEncryptionOptions,
});
Specify Fields to Encrypt指定要加密的字段
To encrypt a field, add it to the encrypted fields map. To enable queries on a field, add the "queries" property. Create the encrypted fields map as follows:若要加密字段,请将其添加到加密字段映射中。要在字段上启用查询,请添加“查询”属性。按如下方式创建加密字段映射:
const encryptedFieldsMap = {
encryptedFields: {
fields: [
{
path: "patientRecord.ssn",
bsonType: "string",
queries: { queryType: "equality" },
},
{
path: "patientRecord.billing",
bsonType: "object",
},
],
},
};
In the previous code sample, both the "ssn" and "billing" fields are encrypted, but only the "ssn" field can be queried.在上一个代码示例中,“ssn”和“billing”字段都是加密的,但只能查询“ssn“字段。
Create the Collection创建集合
Instantiate 实例化ClientEncryption
to access the API for the encryption helper methods.ClientEncryption
以访问加密助手方法的API。
const clientEncryption = new ClientEncryption(client, autoEncryptionOptions);
Create your encrypted collection by using the encryption helper method accessed through the 使用通过ClientEncryption
class. This method automatically generates data encryption keys for your encrypted fields and creates the encrypted collection:ClientEncryption
类访问的加密助手方法创建加密的集合。此方法自动为加密字段生成数据加密键,并创建加密集合:
await clientEncryption.createEncryptedCollection(
encryptedDatabase,
encryptedCollectionName,
{
provider: kmsProviderName,
createCollectionOptions: encryptedFieldsMap,
masterKey: customerMasterKeyCredentials,
}
);
Database vs. Database Name数据库与数据库名称
The method that creates the encrypted collection requires a reference to a database object rather than the database name. You can obtain this reference by using a method on your client object.创建加密集合的方法需要对数据库对象的引用,而不是数据库名称。您可以通过在客户端对象上使用方法来获取此引用。
Insert a Document with Encrypted Fields插入带有加密字段的文档
Create a sample document that describes a patient's personal information. Use the encrypted client to insert it into the 创建描述患者个人信息的示例文档。使用加密客户端将其插入patients
collection, as shown in the following example: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);
Query on an Encrypted Field对加密字段的查询
The following code sample executes a find query on an encrypted field and prints the decrypted data:以下代码示例对加密字段执行查找查询,并打印解密的数据:
const findResult = await encryptedCollection.findOne({
"patientRecord.ssn": "987-65-4320",
});
console.log(findResult);
The output of the preceding code sample should look similar to the following:前面的代码示例的输出应该类似于以下内容:
{
"_id": {
"$oid": "648b384a722cb9b8392df76a"
},
"name": "Jon Doe",
"record": {
"ssn": "987-65-4320",
"billing": {
"type": "Visa",
"number": "4111111111111111"
}
},
"__safeContent__": [
{
"$binary": {
"base64": "L1NsYItk0Sg+oL66DBj6IYHbX7tveANQyrU2cvMzD9Y=",
"subType": "00"
}
}
]
}
Do not Modify the __safeContent__ Field不要修改__safeContent__
字段
The __safeContent__
field is essential to Queryable Encryption. Do not modify the contents of this field.__safeContent__
字段对于可查询加密至关重要。请勿修改此字段的内容。
Learn More了解更多信息
To learn how Queryable Encryption works, see Fundamentals.要了解可查询加密的工作原理,请参阅基础知识。
To learn more about the topics mentioned in this guide, see the following links:要了解有关本指南中提到的主题的更多信息,请参阅以下链接:
Learn more about Queryable Encryption components on the Reference page.在参考页面上了解有关可查询加密组件的更多信息。Learn how Customer Master Keys and Data Encryption Keys work on the Keys and Key Vaults page.在键和键库页面上了解客户主键和数据加密键的工作方式。See how KMS Providers manage your Queryable Encryption keys on the KMS Providers page.在KMS提供商页面上查看KMS提供商如何管理您的可查询加密键。