客户端加密

在此页面上

安装

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

从 v 4.2开始， MongoDB 支持客户端加密。除了提供其他 MongoDB 加密功能外，客户端加密还允许管理员和开发人员加密特定数据字段。

通过字段级加密，开发者可以在客户端加密字段，无需任何服务器端配置或指令。客户端字段级加密支持的工作负载中，应用程序必须保证包括服务器管理员在内的未经授权方无法读取加密数据。

重要

本指南使用 Subscriber实现，如快速入门入门知识中所述。

安装

在项目中开始使用字段级加密的推荐方法是使用依赖项管理系统。除驱动程序外，字段级加密还需要其他软件包。

注意

有关如何安装Java Reactive Streams驾驶员的说明，请参阅安装指南。

libmongocrypt

有一个单独的 JAR 文件，其中包含libmongocrypt绑定。

如果您使用的是 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守护进程/进程正在运行。可以通过在extraOptions设置中设置mongocryptdURI ，在AutoEncryptionSettings类中配置特定的守护进程/进程 URI。

示例

以下示例是一个示例应用，它假设已在MongoDB中创建密钥和模式。该示例使用本地密钥，但您也可以使用Amazon Web Services / Azure / GCP KMS 。 encryptedField字段中的数据在插入时自动加密，在客户端端使用查找时自动解密。

代码示例来自 ClientSideEncryptionSimpleTour.java 驾驶员源代码Github 存储库中的文件。

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 schema映射。

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

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 Community的一项功能，不使用 mongocryptd 进程。显式加密由ClientEncryption类提供。

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

// 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) 。

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

...
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 配置

示例

注意

显式加密和解密

显式加密和自动解密

客户端加密