客户端加密

本页内容

安装

libmongocrypt
mongocryptd 配置
示例
显式加密和解密
显式加密和自动解密

从 v4.2 版本开始，MongoDB 支持客户端加密。客户端加密允许管理员和开发者加密特定的数据字段，并提供其他 MongoDB 加密功能。

使用字段级加密，开发者可以在客户端加密字段，而无需任何服务器端配置或指令。客户端字段级加密支持必须保证未经授权的第三方（包括服务器管理员）无法读取加密数据的负载。

重要

本指南使用Subscriber 实现，这些实现已在快速入门指南中描述.

安装

在项目中开始使用字段级加密的推荐方式是使用依赖管理系统。字段级加密除了驱动程序外还需要额外的包。

注意

有关安装Java Reactive Streams驱动程序的说明，请参阅安装指南。

libmongocrypt

存在一个包含 libmongocrypt 绑定的单独 JAR 文件。

如果您使用Maven来管理您的包，请将以下条目添加到您的 pom.xml 依赖列表中

<dependencies>
    <dependency>
        <groupId>org.mongodb</groupId>
        <artifactId>mongodb-crypt</artifactId>
        <version>1.2.1</version>
    </dependency>
</dependencies>

如果您使用 Gradle来管理您的包，请将以下条目添加到您的依赖列表中

dependencies {
    implementation 'org.mongodb:mongodb-crypt:1.2.1'
}

mongocryptd 配置

libmongocrypt 绑定需要 mongocryptd 守护进程或进程运行。可以在 AutoEncryptionSettings 类中配置特定的守护进程/进程 URI，通过在 extraOptions 设置中设置 mongocryptdURI 来实现。

示例

以下示例是一个假设键和模式已经创建在 MongoDB 中的示例应用程序。该示例使用本地密钥，但也可以使用 AWS/Azure/GCP 密钥管理服务。在 encryptedField 字段中的数据在插入时自动加密，在客户端使用 find 操作时自动解密。

代码示例来自驱动程序源代码 GitHub 存储库中的 ClientSideEncryptionSimpleTour.java 文件。

import com.mongodb.AutoEncryptionSettings;
import com.mongodb.MongoClientSettings;
import com.mongodb.reactivestreams.client.MongoClient;
import com.mongodb.reactivestreams.client.MongoClients;
import com.mongodb.reactivestreams.client.MongoCollection;
import org.bson.Document;
import java.security.SecureRandom;
import java.util.HashMap;
import java.util.Map;
public class ClientSideEncryptionSimpleTour {
    public static void main(final String[] args) {
        // This would have to be the same master key as was used to create the encryption key
        final byte[] localMasterKey = new byte[96];
        new SecureRandom().nextBytes(localMasterKey);
        Map<String, Map<String, Object>> kmsProviders = new HashMap<String, Map<String, Object>>() {{
           put("local", new HashMap<String, Object>() {{
               put("key", localMasterKey);
           }});
        }};
        String keyVaultNamespace = "admin.datakeys";
        AutoEncryptionSettings autoEncryptionSettings = AutoEncryptionSettings.builder()
                .keyVaultNamespace(keyVaultNamespace)
                .kmsProviders(kmsProviders)
                .build();
        MongoClientSettings clientSettings = MongoClientSettings.builder()
                .autoEncryptionSettings(autoEncryptionSettings)
                .build();
        MongoClient mongoClient = MongoClients.create(clientSettings);
        MongoCollection<Document> collection = mongoClient.getDatabase("test").getCollection("coll");
        ObservableSubscriber<Void> successSubscriber = new OperationSubscriber<>();
        collection.drop().subscribe(successSubscriber);
        successSubscriber.await();
        successSubscriber = new OperationSubscriber<>();
        collection.insertOne(new Document("encryptedField", "123456789")).subscribe(successSubscriber);
        successSubscriber.await();
        ObservableSubscriber<Document> documentSubscriber = new PrintDocumentSubscriber();
        collection.find().first().subscribe(documentSubscriber);
        documentSubscriber.await();
    }
}

注意

自动加密是 仅企业级 功能。

以下示例展示了如何配置 AutoEncryptionSettings 实例以创建新密钥并设置 JSON 模式映射。

代码示例来自MongoDB驱动源代码GitHub仓库中的ClientSideEncryptionAutoEncryptionSettingsTour.java文件。

import com.mongodb.ClientEncryptionSettings;
import com.mongodb.ConnectionString;
import com.mongodb.client.model.vault.DataKeyOptions;
import com.mongodb.client.vault.ClientEncryption;
import com.mongodb.client.vault.ClientEncryptions;
import org.bson.BsonBinary;
import org.bson.BsonDocument;
import java.util.Base64;
...
String keyVaultNamespace = "admin.datakeys";
ClientEncryptionSettings clientEncryptionSettings = ClientEncryptionSettings.builder()
    .keyVaultMongoClientSettings(MongoClientSettings.builder()
        .applyConnectionString(new ConnectionString("mongodb://localhost"))
        .build())
    .keyVaultNamespace(keyVaultNamespace)
    .kmsProviders(kmsProviders)
    .build();
ClientEncryption clientEncryption = ClientEncryptions.create(clientEncryptionSettings);
BsonBinary dataKeyId = clientEncryption.createDataKey("local", new DataKeyOptions());
final String base64DataKeyId = Base64.getEncoder().encodeToString(dataKeyId.getData());
final String dbName = "test";
final String collName = "coll";
AutoEncryptionSettings autoEncryptionSettings = AutoEncryptionSettings.builder()
    .keyVaultNamespace(keyVaultNamespace)
    .kmsProviders(kmsProviders)
    .schemaMap(new HashMap<String, BsonDocument>() {{
        put(dbName + "." + collName,
            // Need a schema that references the new data key
            BsonDocument.parse("{"
                + "  properties: {"
                + "    encryptedField: {"
                + "      encrypt: {"
                + "        keyId: [{"
                + "          \"$binary\": {"
                + "            \"base64\": \"" + base64DataKeyId + "\","
                + "            \"subType\": \"04\""
                + "          }"
                + "        }],"
                + "        bsonType: \"string\","
                + "        algorithm: \"AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic\""
                + "      }"
                + "    }"
                + "  },"
                + "  \"bsonType\": \"object\""
                + "}"));
}}).build();

显式加密和解密

显式加密和解密是MongoDB社区功能，不使用mongocryptd进程。显式加密由ClientEncryption类提供。

代码示例来自MongoDB驱动源代码GitHub仓库中的ClientSideEncryptionExplicitEncryptionAndDecryptionTour.java文件。

// This would have to be the same master key as was used to create the encryption key
final byte[] localMasterKey = new byte[96];
new SecureRandom().nextBytes(localMasterKey);
Map<String, Map<String, Object>> kmsProviders = new HashMap<String, Map<String, Object>>() {{
    put("local", new HashMap<String, Object>() {{
        put("key", localMasterKey);
    }});
}};
MongoNamespace keyVaultNamespace = new MongoNamespace("encryption.testKeyVault");
MongoClientSettings clientSettings = MongoClientSettings.builder().build();
MongoClient mongoClient = MongoClients.create(clientSettings);
// Set up the key vault for this example
MongoCollection<Document> keyVaultCollection = mongoClient
    .getDatabase(keyVaultNamespace.getDatabaseName())
    .getCollection(keyVaultNamespace.getCollectionName());
ObservableSubscriber<Void> successSubscriber = new OperationSubscriber<>();
keyVaultCollection.drop().subscribe(successSubscriber);
successSubscriber.await();
// Ensure that two data keys cannot share the same keyAltName.
ObservableSubscriber<String> indexSubscriber = new OperationSubscriber<>();
keyVaultCollection.createIndex(Indexes.ascending("keyAltNames"),
    new IndexOptions().unique(true)
        .partialFilterExpression(Filters.exists("keyAltNames")))
    .subscribe(indexSubscriber);
indexSubscriber.await();
MongoCollection<Document> collection = mongoClient.getDatabase("test").getCollection("coll");
successSubscriber = new OperationSubscriber<>();
collection.drop().subscribe(successSubscriber);
successSubscriber.await();
// Create the ClientEncryption instance
ClientEncryptionSettings clientEncryptionSettings = ClientEncryptionSettings.builder()
    .keyVaultMongoClientSettings(MongoClientSettings.builder()
        .applyConnectionString(new ConnectionString("mongodb://localhost"))
        .build())
    .keyVaultNamespace(keyVaultNamespace.getFullName())
    .kmsProviders(kmsProviders)
    .build();
ClientEncryption clientEncryption = ClientEncryptions.create(clientEncryptionSettings);
BsonBinary dataKeyId = clientEncryption.createDataKey("local", new DataKeyOptions());
// Explicitly encrypt a field
BsonBinary encryptedFieldValue = clientEncryption.encrypt(new BsonString("123456789"),
    new EncryptOptions("AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic").keyId(dataKeyId));
ObservableSubscriber<InsertOneResult> insertOneSubscriber = new OperationSubscriber<>();
collection.insertOne(new Document("encryptedField", encryptedFieldValue))
    .subscribe(insertOneSubscriber);
insertOneSubscriber.await();
ObservableSubscriber<Document> documentSubscriber = new OperationSubscriber<>();
collection.find().first().subscribe(documentSubscriber);
Document doc = documentSubscriber.get().get(0);
System.out.println(doc.toJson());
// Explicitly decrypt the field
System.out.println(
    clientEncryption.decrypt(new BsonBinary(doc.get("encryptedField", Binary.class).getData()))
);

显式加密和自动解密

尽管自动加密需要MongoDB 4.2企业版或MongoDB 4.2 Atlas集群，但自动解密对所有用户都提供支持。要在不启用自动加密的情况下配置自动解密，请设置bypassAutoEncryption(true)。

以下代码示例来自驱动源代码GitHub存储库中的ClientSideEncryptionExplicitEncryptionOnlyTour.java文件。

...
MongoClientSettings clientSettings = MongoClientSettings.builder()
    .autoEncryptionSettings(AutoEncryptionSettings.builder()
        .keyVaultNamespace(keyVaultNamespace.getFullName())
        .kmsProviders(kmsProviders)
        .bypassAutoEncryption(true)
        .build())
    .build();
MongoClient mongoClient = MongoClients.create(clientSettings);
...
// Explicitly encrypt a field
BsonBinary encryptedFieldValue = clientEncryption.encrypt(new BsonString("123456789"),
    new EncryptOptions("AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic").keyId(dataKeyId));
ObservableSubscriber<InsertOneResult> insertOneSubscriber = new OperationSubscriber<>();
collection.insertOne(new Document("encryptedField", encryptedFieldValue))
    .subscribe(insertOneSubscriber);
insertOneSubscriber.await();
ObservableSubscriber<Document> documentSubscriber = new OperationSubscriber<>();
collection.find().first().subscribe(documentSubscriber);
Document doc = documentSubscriber.get().get(0);
System.out.println(doc.toJson());

读取操作

写入操作

客户端加密.leafygreen-ui-m0pgrr{-webkit-align-self:center;-ms-flex-item-align:center;align-self:center;padding:0 10px;visibility:hidden;}.leafygreen-ui-a30zj9{color:#889397;vertical-align:middle;margin-top:-2px;}.css-fmznk8{margin-top:-85px;position:absolute;padding-bottom:2px;}

重要

安装

注意

libmongocrypt

mongocryptd 配置

示例

注意

显式加密和解密

显式加密和自动解密

客户端加密