通过 KMIP 使用客户端字段级自动加密

在此页面上

Overview

开始之前
设置 KMS
配置符合 KMIP 的密钥提供商
指定您的证书
创建应用程序
在密钥保管库集合上创建唯一索引
创建数据加密密钥
配置 MongoClient
插入具有加密字段的文档
检索加密文档
了解详情

Overview

本指南介绍如何使用符合 Key Management Interoperability Protocol (KMIP) 的提供商来构建支持客户端字段级加密 (CSFLE) 的应用程序。

在完成本指南中的步骤后，您应该具有：

在 KMIP兼容提供商上托管的客户主密钥。
一个有效的客户端应用程序，使用客户主密钥插入加密文档。

开始之前

要完成并运行本指南中的代码，您需要按照安装要求页面所示设立开发环境。

在本指南中，代码示例使用占位符文本。在运行示例之前，请用您自己的值替换这些占位符。

例如：

dek_id := "<Your Base64 DEK ID>"

您可以将引号之间的内容替换为您的 DEK ID。

dek_id := "abc123"

从页面右侧的 Select your language（选择语言）下拉菜单中，选择要查看代码示例的编程语言。

提示

请参阅：完整应用程序

要查看本教程的完整可运行应用程序代码，请访问以下链接：

设置 KMS

注意

mongod 初创企业读取 KMIP 配置。默认情况下，服务器使用 KMIP 协议版本 1.2。

要连接到版本 1.0 或 1.1 的 KMIP 服务器，请使用useLegacyProtocol设置。

// You are viewing the C# driver code examples.
// Use the dropdown menu to select a different driver.

// You are viewing the Golang driver code examples.
// Use the dropdown menu to select a different driver.

// You are viewing the Java synchronous driver code examples.
// Use the dropdown menu to select a different driver.

// You are viewing the Node.js driver code examples.
// Use the dropdown menu to select a different driver.

# You are viewing the Python driver code examples.
# Use the dropdown menu to select a different driver.

配置符合 KMIP 的密钥提供商

要将 MongoDB 驱动程序客户端连接到KMIP兼容密钥提供商，您必须配置KMIP兼容密钥提供商，使其接受客户端的 TLS 证书。

有关如何接受客户端证书的信息，请参阅符合KMIP的密钥提供商的文档。

指定您的证书

客户端必须通过 TLS 连接到KMIP兼容密钥提供商，并提供KMIP兼容密钥提供商接受的客户端证书：

MakeDataKey.cs

var tlsOptions = new Dictionary<string, SslSettings>();
var sslSettings = new SslSettings();
var clientCertificate = new X509Certificate2("<path to your pkcs12 client certificate file>");
sslSettings.ClientCertificates = new List<X509Certificate>() {
    clientCertificate,
 };
tlsOptions.Add(provider, sslSettings);

重要

客户端证书必须采用 pks 12格式。您可以通过以下命令使用 openssl 转换证书：

openssl pcks12 -export -out "<new pcks12 certificate>" -in "<certificate to convert>" \
-name "<new certificate name>" -password "<new certificate password>"

make-data-key.go

tlsConfig := make(map[string]*tls.Config)
tlsOpts := map[string]interface{}{
	"tlsCertificateKeyFile": "<path to your client certificate file>",
	"tlsCAFile":             "<path to file containing your Certificate Authority certificate>",
}
kmipConfig, err := options.BuildTLSConfig(tlsOpts)
tlsConfig["kmip"] = kmipConfig

重要

您必须使用带有 ECDSA 密钥的证书使用Go驾驶员时。

指定以下Java系统属性来配置客户端的 TLS 连接：

-Djavax.net.ssl.keyStoreType=pkcs12
-Djavax.net.ssl.keyStore=<path to pkcs12 KeyStore containing your client certificate>
-Djavax.net.ssl.keyStorePassword=<KeyStore password>

注意

使用 SSLContext 配置客户端

如果您希望使用 SSL 上下文配置客户端应用程序，请使用 kmsProviderSslContextMap 方法。

make_data_key.js

const tlsOptions = {
  kmip: {
    tlsCAFile:
      "<path to file containing your Certificate Authority certificate>",
    tlsCertificateKeyFile: "<path to your client certificate file>",
  },
};

make_data_key.py

tls_options = {
    "kmip": {
        "tlsCAFile": "<path to file containing your Certificate Authority certificate>",
        "tlsCertificateKeyFile": "<path to your client certificate file>",
    }
}

创建应用程序

选择与您在应用程序中使用的 MongoDB 驱动程序相对应的标签页，查看相关代码示例。

在密钥保管库集合上创建唯一索引

在你的encryption.__keyVaultcollection中的keyAltNames字段上创建唯一索引。

选择与所需的 MongoDB 驱动程序对应的标签页：

MakeDataKey.cs

var connectionString = "<Your MongoDB URI>";
var keyVaultNamespace = CollectionNamespace.FromFullName("encryption.__keyVault");
var keyVaultClient = new MongoClient(connectionString);
var indexOptions = new CreateIndexOptions<BsonDocument>();
indexOptions.Unique = true;
indexOptions.PartialFilterExpression = new BsonDocument { { "keyAltNames", new BsonDocument { { "$exists", new BsonBoolean(true) } } } };
var builder = Builders<BsonDocument>.IndexKeys;
var indexKeysDocument = builder.Ascending("keyAltNames");
var indexModel = new CreateIndexModel<BsonDocument>(indexKeysDocument, indexOptions);
var keyVaultDatabase = keyVaultClient.GetDatabase(keyVaultNamespace.DatabaseNamespace.ToString());
// Drop the Key Vault Collection in case you created this collection
// in a previous run of this application.  
keyVaultDatabase.DropCollection(keyVaultNamespace.CollectionName);
// Drop the database storing your encrypted fields as all
// the DEKs encrypting those fields were deleted in the preceding line.
keyVaultClient.GetDatabase("medicalRecords").DropCollection("patients");
var keyVaultCollection = keyVaultDatabase.GetCollection<BsonDocument>(keyVaultNamespace.CollectionName.ToString());
keyVaultCollection.Indexes.CreateOne(indexModel);

insert-encrypted-document.go

uri := "<Your MongoDB URI>"
keyVaultClient, err := mongo.Connect(context.TODO(), options.Client().ApplyURI(uri))
if err != nil {
	return fmt.Errorf("Connect error for regular client: %v", err)
}
defer func() {
	_ = keyVaultClient.Disconnect(context.TODO())
}()
keyVaultColl := "__keyVault"
keyVaultDb := "encryption"
keyVaultNamespace := keyVaultDb + "." + keyVaultColl
keyVaultIndex := mongo.IndexModel{
	Keys: bson.D{{"keyAltNames", 1}},
	Options: options.Index().
		SetUnique(true).
		SetPartialFilterExpression(bson.D{
			{"keyAltNames", bson.D{
				{"$exists", true},
			}},
		}),
}
// Drop the Key Vault Collection in case you created this collection
// in a previous run of this application.
if err = keyVaultClient.Database(keyVaultDb).Collection(keyVaultColl).Drop(context.TODO()); err != nil {
	log.Fatalf("Collection.Drop error: %v", err)
}
// Drop the database storing your encrypted fields as all
// the DEKs encrypting those fields were deleted in the preceding line.
if err = keyVaultClient.Database("medicalRecords").Collection("patients").Drop(context.TODO()); err != nil {
	log.Fatalf("Collection.Drop error: %v", err)
}
_, err = keyVaultClient.Database(keyVaultDb).Collection(keyVaultColl).Indexes().CreateOne(context.TODO(), keyVaultIndex)
if err != nil {
	panic(err)
}

MakeDataKey.java

String connectionString = "<Your MongoDB URI>";
String keyVaultDb = "encryption";
String keyVaultColl = "__keyVault";
String keyVaultNamespace = keyVaultDb + "." + keyVaultColl;
MongoClient keyVaultClient = MongoClients.create(connectionString);
// Drop the Key Vault Collection in case you created this collection
// in a previous run of this application.
keyVaultClient.getDatabase(keyVaultDb).getCollection(keyVaultColl).drop();
// Drop the database storing your encrypted fields as all
// the DEKs encrypting those fields were deleted in the preceding line.
keyVaultClient.getDatabase("medicalRecords").getCollection("patients").drop();
MongoCollection keyVaultCollection = keyVaultClient.getDatabase(keyVaultDb).getCollection(keyVaultColl);
IndexOptions indexOpts = new IndexOptions().partialFilterExpression(new BsonDocument("keyAltNames", new BsonDocument("$exists", new BsonBoolean(true) ))).unique(true);
keyVaultCollection.createIndex(new BsonDocument("keyAltNames", new BsonInt32(1)), indexOpts);
keyVaultClient.close();

make_data_key.js

const uri = "<Your Connection String>";
const keyVaultDatabase = "encryption";
const keyVaultCollection = "__keyVault";
const keyVaultNamespace = `${keyVaultDatabase}.${keyVaultCollection}`;
const keyVaultClient = new MongoClient(uri);
await keyVaultClient.connect();
const keyVaultDB = keyVaultClient.db(keyVaultDatabase);
// Drop the Key Vault Collection in case you created this collection
// in a previous run of this application.
await keyVaultDB.dropDatabase();
// Drop the database storing your encrypted fields as all
// the DEKs encrypting those fields were deleted in the preceding line.
await keyVaultClient.db("medicalRecords").dropDatabase();
const keyVaultColl = keyVaultDB.collection(keyVaultCollection);
await keyVaultColl.createIndex(
  { keyAltNames: 1 },
  {
    unique: true,
    partialFilterExpression: { keyAltNames: { $exists: true } },
  }
);

make_data_key.py

connection_string = "<your connection string here>"
key_vault_coll = "__keyVault"
key_vault_db = "encryption"
key_vault_namespace = f"{key_vault_db}.{key_vault_coll}"
key_vault_client = MongoClient(connection_string)
# Drop the Key Vault Collection in case you created this collection
# in a previous run of this application.
key_vault_client.drop_database(key_vault_db)
# Drop the database storing your encrypted fields as all
# the DEKs encrypting those fields were deleted in the preceding line.
key_vault_client["medicalRecords"].drop_collection("patients")
key_vault_client[key_vault_db][key_vault_coll].create_index(
    [("keyAltNames", ASCENDING)],
    unique=True,
    partialFilterExpression={"keyAltNames": {"$exists": True}},
)

创建数据加密密钥

添加您的端点

指定符合KMIP的密钥提供商的 URI 端点：

MakeDataKey.cs

var kmsProviders = new Dictionary<string, IReadOnlyDictionary<string, object>>();
var provider = "kmip";
var kmipKmsOptions = new Dictionary<string, object>
{
   { "endpoint", "<endpoint for your KMIP-compliant key provider>" },
};
kmsProviders.Add(provider, kmipKmsOptions);

make-data-key.go

provider := "kmip"
kmsProviders := map[string]map[string]interface{}{
	provider: {
		"endpoint": "<endpoint for your KMIP-compliant key provider>",
	},
}

MakeDataKey.java

String kmsProvider = "kmip";
Map<String, Map<String, Object>> kmsProviders = new HashMap<String, Map<String, Object>>();
Map<String, Object> providerDetails = new HashMap<>();
providerDetails.put("endpoint", "<endpoint for your KMIP-compliant key provider>");
kmsProviders.put(kmsProvider, providerDetails);

make_data_key.js

const provider = "kmip";
const kmsProviders = {
  kmip: {
    endpoint: "<endpoint for your KMIP-compliant key provider>",
  },
};

make_data_key.py

provider = "kmip"
kms_providers = {
    provider: {"endpoint": "<endpoint for your KMIP-compliant key provider>"}
}

添加您的密钥信息

以下代码会提示符合KMIP的提供商自动生成客户主密钥：

MakeDataKey.cs

var dataKeyOptions = new DataKeyOptions(
    masterKey: new BsonDocument { } // an empty key object prompts your KMIP-compliant key provider to generate a new Customer Master Key
);

make-data-key.go

masterKey := map[string]interface{}{} // an empty key object prompts your KMIP-compliant key provider to generate a new Customer Master Key

MakeDataKey.java

BsonDocument masterKeyProperties = new BsonDocument(); // an empty key object prompts your KMIP-compliant key provider to generate a new Customer Master Key

make_data_key.js

const masterKey = {}; // an empty key object prompts your KMIP-compliant key provider to generate a new Customer Master Key

make_data_key.py

master_key = (
    {}
)  # an empty key object prompts your KMIP-compliant key provider to generate a new Customer Master Key

生成数据加密密钥

MakeDataKey.cs

var clientEncryptionOptions = new ClientEncryptionOptions(
    keyVaultClient: keyVaultClient,
    keyVaultNamespace: keyVaultNamespace,
    kmsProviders: kmsProviders,
    tlsOptions: tlsOptions
    );
var clientEncryption = new ClientEncryption(clientEncryptionOptions);
var dataKeyId = clientEncryption.CreateDataKey(provider, dataKeyOptions, CancellationToken.None);
var dataKeyIdBase64 = Convert.ToBase64String(GuidConverter.ToBytes(dataKeyId, GuidRepresentation.Standard));
Console.WriteLine($"DataKeyId [base64]: {dataKeyIdBase64}");

make-data-key.go

clientEncryptionOpts := options.ClientEncryption().SetKeyVaultNamespace(keyVaultNamespace).
	SetKmsProviders(kmsProviders).SetTLSConfig(tlsConfig)
clientEnc, err := mongo.NewClientEncryption(keyVaultClient, clientEncryptionOpts)
if err != nil {
	return fmt.Errorf("NewClientEncryption error %v", err)
}
defer func() {
	_ = clientEnc.Close(context.TODO())
}()
dataKeyOpts := options.DataKey().
	SetMasterKey(masterKey)
dataKeyID, err := clientEnc.CreateDataKey(context.TODO(), provider, dataKeyOpts)
if err != nil {
	return fmt.Errorf("create data key error %v", err)
}
fmt.Printf("DataKeyId [base64]: %s\n", base64.StdEncoding.EncodeToString(dataKeyID.Data))

MakeDataKey.java

ClientEncryptionSettings clientEncryptionSettings = ClientEncryptionSettings.builder()
        .keyVaultMongoClientSettings(MongoClientSettings.builder()
                .applyConnectionString(new ConnectionString(connectionString))
                .build())
        .keyVaultNamespace(keyVaultNamespace)
        .kmsProviders(kmsProviders)
        .build();
MongoClient regularClient = MongoClients.create(connectionString);
ClientEncryption clientEncryption = ClientEncryptions.create(clientEncryptionSettings);
BsonBinary dataKeyId = clientEncryption.createDataKey(kmsProvider, new DataKeyOptions().masterKey(masterKeyProperties));
String base64DataKeyId = Base64.getEncoder().encodeToString(dataKeyId.getData());
System.out.println("DataKeyId [base64]: " + base64DataKeyId);
clientEncryption.close();

make_data_key.js

const client = new MongoClient(uri, {
  useNewUrlParser: true,
  useUnifiedTopology: true,
});
await client.connect();
const encryption = new ClientEncryption(client, {
  keyVaultNamespace,
  kmsProviders,
  tlsOptions,
});
const key = await encryption.createDataKey(provider, {
  masterKey: masterKey,
});
console.log("DataKeyId [base64]: ", key.toString("base64"));
await keyVaultClient.close();
await client.close();

make_data_key.py

key_vault_database = "encryption"
key_vault_collection = "__keyVault"
key_vault_namespace = f"{key_vault_database}.{key_vault_collection}"
client = MongoClient(connection_string)
client_encryption = ClientEncryption(
    kms_providers,  # pass in the kms_providers variable from the previous step
    key_vault_namespace,
    client,
    CodecOptions(uuid_representation=STANDARD),
    kms_tls_options=tls_options,
)
data_key_id = client_encryption.create_data_key(provider, master_key)
base_64_data_key_id = base64.b64encode(data_key_id)
print("DataKeyId [base64]: ", base_64_data_key_id)

提示

请参阅：完整代码

要查看制作数据加密密钥的完整代码，请参阅我们的 Github 存储库。

配置 MongoClient

指定密钥保管库集合命名空间

指定 encryption.__keyVault 以作为密钥保管库集合命名空间。

InsertEncryptedDocument.cs

var keyVaultNamespace = CollectionNamespace.FromFullName("encryption.__keyVault");

insert-encrypted-document.go

keyVaultNamespace := "encryption.__keyVault"

InsertEncryptedDocument.java

String keyVaultNamespace = "encryption.__keyVault";

insert_encrypted_document.js

const keyVaultNamespace = "encryption.__keyVault";

insert_encrypted_document.py

key_vault_namespace = "encryption.__keyVault"

指定您的 KMIP 端点

在kmsProviders对象中指定kmip ，并输入KMIP兼容密钥提供程序的 URI 端点：

InsertEncryptedDocument.cs

var kmsProviders = new Dictionary<string, IReadOnlyDictionary<string, object>>();
var provider = "kmip";
var kmipKmsOptions = new Dictionary<string, object>
{
   { "endpoint", "<endpoint for your KMIP-compliant key provider>" },
};
kmsProviders.Add(provider, kmipKmsOptions);

insert-encrypted-document.go

provider := "kmip"
kmsProviders := map[string]map[string]interface{}{
	provider: {
		"endpoint": "<endpoint for your KMIP-compliant key provider>",
	},
}

InsertEncryptedDocument.java

String kmsProvider = "kmip";
Map<String, Map<String, Object>> kmsProviders = new HashMap<String, Map<String, Object>>();
Map<String, Object> providerDetails = new HashMap<>();
providerDetails.put("endpoint", "<endpoint for your KMIP-compliant key provider>");
kmsProviders.put(kmsProvider, providerDetails);

insert_encrypted_document.js

const provider = "kmip";
const kmsProviders = {
  kmip: {
    endpoint: "<endpoint for your KMIP-compliant key provider>",
  },
};

insert_encrypted_document.py

provider = "kmip"
kms_providers = {
    provider: {"endpoint": "<endpoint for your KMIP-compliant key provider>"}
}

为集合创建加密模式

创建加密模式，指定客户端应用程序加密文档字段的方式：

提示

添加数据加密密钥 Base64 ID

请务必更新以下代码以包含您的基本64 DEK ID。您在本指南的“生成数据加密密钥”步骤中收到了该值。

InsertEncryptedDocument.cs

var keyId = "<Your base64 DEK ID here>";
var schema = new BsonDocument
{
   { "bsonType", "object" },
   {
       "encryptMetadata",
       new BsonDocument("keyId", new BsonArray(new[] { new BsonBinaryData(Convert.FromBase64String(keyId), BsonBinarySubType.UuidStandard) }))
   },
   {
       "properties",
       new BsonDocument
       {
           {
               "ssn", new BsonDocument
               {
                   {
                       "encrypt", new BsonDocument
                       {
                           { "bsonType", "int" },
                           { "algorithm", "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic" }
                       }
                   }
               }
           },
           {
               "bloodType", new BsonDocument
               {
                   {
                       "encrypt", new BsonDocument
                       {
                           { "bsonType", "string" },
                           { "algorithm", "AEAD_AES_256_CBC_HMAC_SHA_512-Random" }
                       }
                   }
               }
           },
           {
               "medicalRecords", new BsonDocument
               {
                   {
                       "encrypt", new BsonDocument
                       {
                           { "bsonType", "array" },
                           { "algorithm", "AEAD_AES_256_CBC_HMAC_SHA_512-Random" }
                       }
                   }
               }
           },
           {
               "insurance", new BsonDocument
               {
                   { "bsonType", "object" },
                   {
                       "properties", new BsonDocument
                       {
                           {
                               "policyNumber", new BsonDocument
                               {
                                   {
                                       "encrypt", new BsonDocument
                                       {
                                           { "bsonType", "int" },
                                           { "algorithm", "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic" }
                                       }
                                   }
                               }
                           }
                       }
                   }
               }
           }
       }
   }
};
var schemaMap = new Dictionary<string, BsonDocument>();
schemaMap.Add(dbNamespace, schema);

insert-encrypted-document.go

dek_id := "<Your Base64 DEK ID>"
schema_template := `{
	"bsonType": "object",
	"encryptMetadata": {
		"keyId": [
			{
				"$binary": {
					"base64": "%s",
					"subType": "04"
				}
			}
		]
	},
	"properties": {
		"insurance": {
			"bsonType": "object",
			"properties": {
				"policyNumber": {
					"encrypt": {
						"bsonType": "int",
						"algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
					}
				}
			}
		},
		"medicalRecords": {
			"encrypt": {
				"bsonType": "array",
				"algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Random"
			}
		},
		"bloodType": {
			"encrypt": {
				"bsonType": "string",
				"algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Random"
			}
		},
		"ssn": {
			"encrypt": {
				"bsonType": "int",
				"algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
			}
		}
	}
}`
schema := fmt.Sprintf(schema_template, dek_id)
var schemaDoc bson.Raw
if err := bson.UnmarshalExtJSON([]byte(schema), true, &schemaDoc); err != nil {
	return fmt.Errorf("UnmarshalExtJSON error: %v", err)
}
schemaMap := map[string]interface{}{
	dbName + "." + collName: schemaDoc,
}

InsertEncryptedDocument.java

String dekId = "<paste-base-64-encoded-data-encryption-key-id>>";
Document jsonSchema = new Document().append("bsonType", "object").append("encryptMetadata",
        new Document().append("keyId", new ArrayList<>((Arrays.asList(new Document().append("$binary", new Document()
                .append("base64", dekId)
                .append("subType", "04")))))))
        .append("properties", new Document()
                .append("ssn", new Document().append("encrypt", new Document()
                        .append("bsonType", "int")
                        .append("algorithm", "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic")))
                .append("bloodType", new Document().append("encrypt", new Document()
                        .append("bsonType", "string")
                        .append("algorithm", "AEAD_AES_256_CBC_HMAC_SHA_512-Random")))
                .append("medicalRecords", new Document().append("encrypt", new Document()
                        .append("bsonType", "array")
                        .append("algorithm", "AEAD_AES_256_CBC_HMAC_SHA_512-Random")))
                .append("insurance", new Document()
                        .append("bsonType", "object")
                        .append("properties",
                                new Document().append("policyNumber", new Document().append("encrypt", new Document()
                                        .append("bsonType", "int")
                                        .append("algorithm", "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"))))));
HashMap<String, BsonDocument> schemaMap = new HashMap<String, BsonDocument>();
schemaMap.put("medicalRecords.patients", BsonDocument.parse(jsonSchema.toJson()));

insert_encrypted_document.js

dataKey = "<Your base64 DEK ID>";
const schema = {
  bsonType: "object",
  encryptMetadata: {
    keyId: [new Binary(Buffer.from(dataKey, "base64"), 4)],
  },
  properties: {
    insurance: {
      bsonType: "object",
      properties: {
        policyNumber: {
          encrypt: {
            bsonType: "int",
            algorithm: "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
          },
        },
      },
    },
    medicalRecords: {
      encrypt: {
        bsonType: "array",
        algorithm: "AEAD_AES_256_CBC_HMAC_SHA_512-Random",
      },
    },
    bloodType: {
      encrypt: {
        bsonType: "string",
        algorithm: "AEAD_AES_256_CBC_HMAC_SHA_512-Random",
      },
    },
    ssn: {
      encrypt: {
        bsonType: "int",
        algorithm: "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
      },
    },
  },
};
var patientSchema = {};
patientSchema[namespace] = schema;

insert_encrypted_document.py

dek_id = b"<paste-base-64-encoded-data-encryption-key-id>"
json_schema = {
    "bsonType": "object",
    "encryptMetadata": {"keyId": [Binary(base64.b64decode(dek_id), UUID_SUBTYPE)]},
    "properties": {
        "insurance": {
            "bsonType": "object",
            "properties": {
                "policyNumber": {
                    "encrypt": {
                        "bsonType": "int",
                        "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
                    }
                }
            },
        },
        "medicalRecords": {
            "encrypt": {
                "bsonType": "array",
                "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Random",
            }
        },
        "bloodType": {
            "encrypt": {
                "bsonType": "string",
                "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Random",
            }
        },
        "ssn": {
            "encrypt": {
                "bsonType": "int",
                "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
            }
        },
    },
}
patient_schema = {"medicalRecords.patients": json_schema}
patient_schema = {"medicalRecords.patients": json_schema}

提示

关于模式的进一步阅读

要查看有关如何构建在此步骤中使用的模式的深入说明，请参阅加密模式指南。

要查看加密模式支持的所有加密规则列表，请参阅CSFLE 加密模式指南。

指定自动加密共享库位置

InsertEncryptedDocument.cs

var mongoBinariesPath = "<Full path to your Automatic Encryption Shared Library>";
var extraOptions = new Dictionary<string, object>()
{
   { "cryptSharedLibPath", mongoBinariesPath },
};

insert-encrypted-document.go

extraOptions := map[string]interface{}{
	"cryptSharedLibPath": "<Full path to your Automatic Encryption Shared Library>",
}

InsertEncryptedDocument.java

Map<String, Object> extraOptions = new HashMap<String, Object>();
extraOptions.put("cryptSharedLibPath", "<Full path to your Automatic Encryption Shared Library>"));

insert_encrypted_document.js

const extraOptions = {
  cryptSharedLibPath: "<Full path to your Automatic Encryption Shared Library>",
};

insert_encrypted_document.py

extra_options = {
    "cryptSharedLibPath": "<Full path to your Automatic Encryption Shared Library>"
}

注意

自动加密选项

自动加密选项向自动加密共享库提供配置信息，这将修改应用程序在访问加密字段时的行为。

要了解有关自动加密共享库的更多信息，请参阅 CSFLE 的自动加密共享库页面。

创建 MongoClient

使用以下自动加密设置实例化 MongoDB 客户端对象：

InsertEncryptedDocument.cs

var clientSettings = MongoClientSettings.FromConnectionString(connectionString);
var autoEncryptionOptions = new AutoEncryptionOptions(
    keyVaultNamespace: keyVaultNamespace,
    kmsProviders: kmsProviders,
    schemaMap: schemaMap,
    extraOptions: extraOptions,
    tlsOptions: tlsOptions
    );
clientSettings.AutoEncryptionOptions = autoEncryptionOptions;
var secureClient = new MongoClient(clientSettings);

insert-encrypted-document.go

autoEncryptionOpts := options.AutoEncryption().
	SetKmsProviders(kmsProviders).
	SetKeyVaultNamespace(keyVaultNamespace).
	SetSchemaMap(schemaMap).
	SetExtraOptions(extraOptions).SetTLSConfig(tlsConfig)
secureClient, err := mongo.Connect(context.TODO(), options.Client().ApplyURI(uri).SetAutoEncryptionOptions(autoEncryptionOpts))
if err != nil {
	return fmt.Errorf("Connect error for encrypted client: %v", err)
}
defer func() {
	_ = secureClient.Disconnect(context.TODO())
}()

InsertEncryptedDocument.java

MongoClientSettings clientSettings = MongoClientSettings.builder()
    .applyConnectionString(new ConnectionString(connectionString))
    .autoEncryptionSettings(AutoEncryptionSettings.builder()
        .keyVaultNamespace(keyVaultNamespace)
        .kmsProviders(kmsProviders)
        .schemaMap(schemaMap)
        .extraOptions(extraOptions)
        .build())
    .build();
MongoClient mongoClientSecure = MongoClients.create(clientSettings);

insert_encrypted_document.js

const secureClient = new MongoClient(connectionString, {
  useNewUrlParser: true,
  useUnifiedTopology: true,
  autoEncryption: {
    keyVaultNamespace,
    kmsProviders,
    schemaMap: patientSchema,
    extraOptions: extraOptions,
    tlsOptions,
  },
});

insert_encrypted_document.py

fle_opts = AutoEncryptionOpts(
    kms_providers,
    key_vault_namespace,
    schema_map=patient_schema,
    kms_tls_options=tls_options,
    **extra_options
)
secureClient = MongoClient(connection_string, auto_encryption_opts=fle_opts)

插入具有加密字段的文档

使用启用了 CSFLE 的MongoClient实例，通过以下代码片段将加密文档插入到medicalRecords.patients命名空间中：

InsertEncryptedDocument.cs

var sampleDocFields = new BsonDocument
{
    { "name", "Jon Doe" },
    { "ssn", 145014000 },
    { "bloodType", "AB-" },
    {
        "medicalRecords", new BsonArray
        {
            new BsonDocument("weight", 180),
            new BsonDocument("bloodPressure", "120/80")
        }
    },
    {
        "insurance", new BsonDocument
        {
            { "policyNumber", 123142 },
            { "provider", "MaestCare" }
        }
    }
};
// Construct an auto-encrypting client
var secureCollection = secureClient.GetDatabase(db).GetCollection<BsonDocument>(coll);
// Insert a document into the collection
secureCollection.InsertOne(sampleDocFields);

insert-encrypted-document.go

test_patient := map[string]interface{}{
	"name":      "Jon Doe",
	"ssn":       241014209,
	"bloodType": "AB+",
	"medicalRecords": []map[string]interface{}{{
		"weight":        180,
		"bloodPressure": "120/80",
	}},
	"insurance": map[string]interface{}{
		"provider":     "MaestCare",
		"policyNumber": 123142,
	},
}
if _, err := secureClient.Database(dbName).Collection(collName).InsertOne(context.TODO(), test_patient); err != nil {
	return fmt.Errorf("InsertOne error: %v", err)
}

注意

您可以将带有bson标签的结构体直接传递给驱动程序进行编码，而无需创建原始 BSON 文档。

InsertEncryptedDocument.java

ArrayList<Document> medicalRecords = new ArrayList<>();
medicalRecords.add(new Document().append("weight", "180"));
medicalRecords.add(new Document().append("bloodPressure", "120/80"));
Document insurance = new Document()
.append("policyNumber", 123142)
.append("provider",  "MaestCare");
Document patient = new Document()
    .append("name", "Jon Doe")
    .append("ssn", 241014209)
    .append("bloodType", "AB+")
    .append("medicalRecords", medicalRecords)
    .append("insurance", insurance);
mongoClientSecure.getDatabase(recordsDb).getCollection(recordsColl).insertOne(patient);

insert_encrypted_document.js

try {
  const writeResult = await secureClient
    .db(db)
    .collection(coll)
    .insertOne({
      name: "Jon Doe",
      ssn: 241014209,
      bloodType: "AB+",
      medicalRecords: [{ weight: 180, bloodPressure: "120/80" }],
      insurance: {
        policyNumber: 123142,
        provider: "MaestCare",
      },
    });
} catch (writeError) {
  console.error("writeError occurred:", writeError);
}

insert_encrypted_document.py

def insert_patient(
    collection, name, ssn, blood_type, medical_records, policy_number, provider
):
    insurance = {"policyNumber": policy_number, "provider": provider}
    doc = {
        "name": name,
        "ssn": ssn,
        "bloodType": blood_type,
        "medicalRecords": medical_records,
        "insurance": insurance,
    }
    collection.insert_one(doc)
medical_record = [{"weight": 180, "bloodPressure": "120/80"}]
insert_patient(
    secureClient.medicalRecords.patients,
    "Jon Doe",
    241014209,
    "AB+",
    medical_record,
    123142,
    "MaestCare",
)

在您插入文档时，启用了 CSFLE 的客户端对文档字段进行加密，以使其类似于以下内容：

{
  "_id": { "$oid": "<_id of your document>" },
  "name": "Jon Doe",
  "ssn": {
    "$binary": "<cipher-text>",
    "$type": "6"
  },
  "bloodType": {
    "$binary": "<cipher-text>",
    "$type": "6"
  },
  "medicalRecords": {
    "$binary": "<cipher-text>",
    "$type": "6"
  },
  "insurance": {
    "provider": "MaestCare",
    "policyNumber": {
      "$binary": "<cipher-text>",
      "$type": "6"
    }
  }
}

提示

请参阅：完整代码

要查看插入加密文档的完整代码，请参阅我们的Github存储库

要查看插入加密文档的完整代码，请参阅我们的Github存储库。

检索加密文档

检索在本指南的“插入具有加密字段的文档”步骤中插入的加密文档。

为了显示 CSFLE 的功能，以下代码片段使用配置为自动 CSFLE 的客户端以及未配置为自动 CSFLE 的客户端来查询文档。

InsertEncryptedDocument.cs

Console.WriteLine("Finding a document with regular (non-encrypted) client.");
var filter = Builders<BsonDocument>.Filter.Eq("name", "Jon Doe");
var regularResult = regularCollection.Find(filter).Limit(1).ToList()[0];
Console.WriteLine($"\n{regularResult}\n");
Console.WriteLine("Finding a document with encrypted client, searching on an encrypted field");
var ssnFilter = Builders<BsonDocument>.Filter.Eq("ssn", 145014000);
var secureResult = secureCollection.Find(ssnFilter).Limit(1).First();
Console.WriteLine($"\n{secureResult}\n");

insert-encrypted-document.go

fmt.Println("Finding a document with regular (non-encrypted) client.")
var resultRegular bson.M
err = regularClient.Database(dbName).Collection(collName).FindOne(context.TODO(), bson.D{{"name", "Jon Doe"}}).Decode(&resultRegular)
if err != nil {
	panic(err)
}
outputRegular, err := json.MarshalIndent(resultRegular, "", "    ")
if err != nil {
	panic(err)
}
fmt.Printf("%s\n", outputRegular)
fmt.Println("Finding a document with encrypted client, searching on an encrypted field")
var resultSecure bson.M
err = secureClient.Database(dbName).Collection(collName).FindOne(context.TODO(), bson.D{{"ssn", "241014209"}}).Decode(&resultSecure)
if err != nil {
	panic(err)
}
outputSecure, err := json.MarshalIndent(resultSecure, "", "    ")
if err != nil {
	panic(err)
}
fmt.Printf("%s\n", outputSecure)

InsertEncryptedDocument.java

System.out.println("Finding a document with regular (non-encrypted) client.");
Document docRegular = mongoClientRegular.getDatabase(recordsDb).getCollection(recordsColl).find(eq("name", "Jon Doe")).first();
System.out.println(docRegular.toJson());
System.out.println("Finding a document with encrypted client, searching on an encrypted field");
Document docSecure = mongoClientSecure.getDatabase(recordsDb).getCollection(recordsColl).find(eq("ssn", 241014209)).first();
System.out.println(docSecure.toJson());

insert_encrypted_document.js

console.log("Finding a document with regular (non-encrypted) client.");
console.log(
  await regularClient.db(db).collection(coll).findOne({ name: /Jon/ })
);
console.log(
  "Finding a document with encrypted client, searching on an encrypted field"
);
console.log(
  await secureClient.db(db).collection(coll).findOne({ ssn: "241014209" })
);

insert_encrypted_document.py

print("Finding a document with regular (non-encrypted) client.")
result = regularClient.medicalRecords.patients.find_one({"name": "Jon Doe"})
pprint.pprint(result)
print("Finding a document with encrypted client, searching on an encrypted field")
pprint.pprint(secureClient.medicalRecords.patients.find_one({"ssn": 241014209}))

上述代码片段的输出应如下所示：

Finding a document with regular (non-encrypted) client.
{
  _id: new ObjectId("629a452e0861b3130887103a"),
  name: 'Jon Doe',
  ssn: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e7910c20697e5f4fa95710aafc9153f0a3dc769c8a132a604b468732ff1f4d8349ded3244b59cbfb41444a210f28b21ea1b6c737508d9d30e8baa30c1d8070c4d5e26", "hex"), 6),
  bloodType: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e79022e238536dfd8caadb4d7751ac940e0f195addd7e5c67b61022d02faa90283ab69e02303c7e4001d1996128428bf037dea8bbf59fbb20c583cbcff2bf3e2519b4", "hex"), 6),
  'key-id': 'demo-data-key',
  medicalRecords: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e790405163a3207cff175455106f57eef14e5610c49a99bcbd14a7db9c5284e45e3ee30c149354015f941440bf54725d6492fb3b8704bc7c411cff6c868e4e13c58233c3d5ed9593eca4e4d027d76d3705b6d1f3b3c9e2ceee195fd944b553eb27eee69e5e67c338f146f8445995664980bf0", "hex"), 6),
  insurance: {
    policyNumber: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e79108decd85c05be3fec099e015f9d26d9234605dc959cc1a19b63072f7ffda99db38c7b487de0572a03b2139ac3ee163bcc40c8508f366ce92a5dd36e38b3c742f7", "hex"), 6),
    provider: 'MaestCare'
  }
}
Finding a document with encrypted client, searching on an encrypted field
{
  _id: new ObjectId("629a452e0861b3130887103a"),
  name: 'Jon Doe',
  ssn: 241014209,
  bloodType: 'AB+',
  'key-id': 'demo-data-key',
  medicalRecords: [ { weight: 180, bloodPressure: '120/80' } ],
  insurance: { policyNumber: 123142, provider: 'MaestCare' }
}

提示

请参阅：完整代码

要查看插入加密文档的完整代码，请参阅我们的Github存储库

要查看插入加密文档的完整代码，请参阅我们的Github存储库。

了解详情

如需了解 CSFLE 的工作原理，请参阅基础知识。

如需详细了解本指南中提到的主题，请参阅以下链接：

有关 CSFLE 组件的更多信息，请参阅参考页面。
访问密钥和密钥保管库页面，了解客户主密钥和数据加密密钥的工作原理。
在 CSFLE KMS 提供者页面上了解 KMS 提供者如何管理您的 CSFLE 密钥。

后退

Use GCP

来年

参考