Início rápido
Nesta página
Visão geral
Este guia mostra como criar um aplicativo que implementa o recurso Queryable Encryption do MongoDB para criptografar e descriptografar automaticamente campos de documentos.
Selecione o idioma do driver no menu suspenso à direita para saber como criar um aplicativo que criptografe e descriptografe automaticamente os campos do documento.
Importante
Não use este aplicativo de amostra em produção
Como as instruções deste tutorial incluem o armazenamento de uma chave de criptografia em um ambiente inseguro, você não deve usar uma versão não modificada desse aplicativo em produção. O uso desse aplicativo em produção está sujeito ao acesso não autorizado à chave de criptografia ou à perda da chave necessária para descriptografar seus dados. O objetivo deste tutorial é demonstrar como usar a Queryable Encryption sem precisar configurar um Sistema de Gerenciamento de Chaves.
Você pode usar um sistema de gerenciamento de chaves para armazenar com segurança sua chave de criptografia em um ambiente de produção. Um KMS é um serviço remoto que armazena e gerencia suas chaves de encriptação com segurança. Para saber como configurar um aplicativo habilitado para Queryable Encryption que usa um KMS, consulte os Tutoriais de Queryable Encryption.
Antes de começar
Para concluir e executar o código neste guia, você precisa configurar seu ambiente de desenvolvimento, como mostrado na página Requisitos de instalação.
Dica
Veja: Aplicação Completa
Para ver o código completo desse aplicativo de amostra, selecione a aba correspondente à sua linguagem de programação e siga o link fornecido. Cada repositório de aplicativo de amostra inclui um arquivo README.md
que você pode utilizar para saber como configurar seu ambiente e executar o aplicativo.
Procedimento
Atribua variáveis ao seu aplicativo
Os exemplos de código neste tutorial usam as seguintes variáveis para executar o fluxo de trabalho com Queryable Encryption:
kmsProviderName - O KMS que você está usando para armazenar sua Chave Mestre do Cliente. Defina esta variável como
"local"
para este tutorial.uri - URI de conexão do sistema do MongoDB . Defina seu URI de conexão na variável de ambiente
MONGODB_URI
ou substitua o valor diretamente.keyVaultDatabaseName - O banco de dados de dados no MongoDB onde suas chaves de criptografia de dados (DEKs) serão armazenadas. Defina esta variável como
"encryption"
.keyVaultCollectionName - A coleção no MongoDB onde seus DEKs serão armazenados. Defina essa variável como
"__keyVault"
, que é a convenção para ajudar a evitar dúvidas sobre uma collection de usuário.keyVaultNamespace - O namespace no MongoDB onde seus DEKs serão armazenados. Defina esta variável para os valores das variáveis
keyVaultDatabaseName
ekeyVaultCollectionName
, separados por um período.encryptedDatabaseName - O banco de dados no MongoDB em que seus dados criptografados serão armazenados. Defina esta variável como
"medicalRecords"
.encryptionCollectionName - A coleção no MongoDB onde seus dados criptografados serão armazenados. Defina esta variável como
"patients"
.
Você pode declarar essas variáveis usando o seguinte código:
// 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";
kmsProviderName - O KMS que você está usando para armazenar sua chave mestre do cliente. Defina este valor como
"local"
para este tutorial.keyVaultDatabaseName - O reconhecimento de data center no MongoDB onde seu diretório de dados (DEKs) serão armazenadas. Defina o valor de
keyVaultDatabaseName
para"encryption"
.keyVaultCollectionName - A coleção no MongoDB onde seus DEKs serão armazenados. Defina essa variável como
"__keyVault"
, que é a convenção para ajudar a evitar dúvidas sobre uma collection de usuário.keyVaultNamespace - O namespace no MongoDB onde seus DEKs serão armazenados. Defina
keyVaultNamespace
para um novo objetoCollectionNamespace
cujo nome são os valores das variáveiskeyVaultDatabaseName
ekeyVaultCollectionName
, separados por um ponto.encryptionDatabaseName - O reconhecimento de data center no MongoDB onde seus dados criptografados serão armazenados. Defina o valor de
encryptedDatabaseName
para"medicalRecords"
.encryptionCollectionName - A collection no MongoDB onde seus dados criptografados serão armazenados. Defina o valor de
encryptedCollectionName
para"patients"
.uri - URI de conexão de implantação do MongoDB. Defina seu URI de conexão no arquivo
appsettings.json
ou substitua o valor diretamente.
Você pode declarar essas variáveis usando o seguinte código:
// KMS provider name should be one of the following: "aws", "gcp", "azure", "kmip" or "local" const string kmsProviderName = "<your KMS provider name>"; const string keyVaultDatabaseName = "encryption"; const string keyVaultCollectionName = "__keyVault"; var keyVaultNamespace = CollectionNamespace.FromFullName($"{keyVaultDatabaseName}.{keyVaultCollectionName}"); const string encryptedDatabaseName = "medicalRecords"; const string encryptedCollectionName = "patients"; var appSettings = new ConfigurationBuilder().AddJsonFile("appsettings.json").Build(); var uri = appSettings["MongoDbUri"];
kmsProviderName - O KMS que você está usando para armazenar sua Chave Mestre do Cliente. Defina esta variável como
"local"
para este tutorial.uri - URI de conexão do sistema do MongoDB . Defina seu URI de conexão na variável de ambiente
MONGODB_URI
ou substitua o valor diretamente.keyVaultDatabaseName - O banco de dados de dados no MongoDB onde suas chaves de criptografia de dados (DEKs) serão armazenadas. Defina esta variável como
"encryption"
.keyVaultCollectionName - A coleção no MongoDB onde seus DEKs serão armazenados. Defina essa variável como
"__keyVault"
, que é a convenção para ajudar a evitar dúvidas sobre uma collection de usuário.keyVaultNamespace - O namespace no MongoDB onde seus DEKs serão armazenados. Defina esta variável para os valores das variáveis
keyVaultDatabaseName
ekeyVaultCollectionName
, separados por um período.encryptedDatabaseName - O banco de dados no MongoDB em que seus dados criptografados serão armazenados. Defina esta variável como
"medicalRecords"
.encryptionCollectionName - A coleção no MongoDB onde seus dados criptografados serão armazenados. Defina esta variável como
"patients"
.
Você pode declarar essas variáveis usando o seguinte código:
// KMS provider name should be one of the following: "aws", "gcp", "azure", "kmip" or "local" kmsProviderName := "<KMS provider name>" uri := os.Getenv("MONGODB_URI") // Your connection URI keyVaultDatabaseName := "encryption" keyVaultCollectionName := "__keyVault" keyVaultNamespace := keyVaultDatabaseName + "." + keyVaultCollectionName encryptedDatabaseName := "medicalRecords" encryptedCollectionName := "patients"
kmsProviderName - O KMS que você está usando para armazenar sua Chave Mestre do Cliente. Defina esta variável como
"local"
para este tutorial.uri - URI de conexão do sistema do MongoDB . Defina seu URI de conexão na variável de ambiente
MONGODB_URI
ou substitua o valor diretamente.keyVaultDatabaseName - O banco de dados de dados no MongoDB onde suas chaves de criptografia de dados (DEKs) serão armazenadas. Defina esta variável como
"encryption"
.keyVaultCollectionName - A coleção no MongoDB onde seus DEKs serão armazenados. Defina essa variável como
"__keyVault"
, que é a convenção para ajudar a evitar dúvidas sobre uma collection de usuário.keyVaultNamespace - O namespace no MongoDB onde seus DEKs serão armazenados. Defina esta variável para os valores das variáveis
keyVaultDatabaseName
ekeyVaultCollectionName
, separados por um período.encryptedDatabaseName - O banco de dados no MongoDB em que seus dados criptografados serão armazenados. Defina esta variável como
"medicalRecords"
.encryptionCollectionName - A coleção no MongoDB onde seus dados criptografados serão armazenados. Defina esta variável como
"patients"
.
Você pode declarar essas variáveis usando o seguinte código:
// KMS provider name should be one of the following: "aws", "gcp", "azure", "kmip" or "local" String kmsProviderName = "<KMS provider name>"; String uri = QueryableEncryptionHelpers.getEnv("MONGODB_URI"); // Your connection URI String keyVaultDatabaseName = "encryption"; String keyVaultCollectionName = "__keyVault"; String keyVaultNamespace = keyVaultDatabaseName + "." + keyVaultCollectionName; String encryptedDatabaseName = "medicalRecords"; String encryptedCollectionName = "patients";
kmsProviderName - O KMS que você está usando para armazenar sua Chave Mestre do Cliente. Defina esta variável como
"local"
para este tutorial.uri - URI de conexão do sistema do MongoDB . Defina seu URI de conexão na variável de ambiente
MONGODB_URI
ou substitua o valor diretamente.keyVaultDatabaseName - O banco de dados de dados no MongoDB onde suas chaves de criptografia de dados (DEKs) serão armazenadas. Defina esta variável como
"encryption"
.keyVaultCollectionName - A coleção no MongoDB onde seus DEKs serão armazenados. Defina essa variável como
"__keyVault"
, que é a convenção para ajudar a evitar dúvidas sobre uma collection de usuário.keyVaultNamespace - O namespace no MongoDB onde seus DEKs serão armazenados. Defina esta variável para os valores das variáveis
keyVaultDatabaseName
ekeyVaultCollectionName
, separados por um período.encryptedDatabaseName - O banco de dados no MongoDB em que seus dados criptografados serão armazenados. Defina esta variável como
"medicalRecords"
.encryptionCollectionName - A coleção no MongoDB onde seus dados criptografados serão armazenados. Defina esta variável como
"patients"
.
Você pode declarar essas variáveis usando o seguinte código:
// 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";
kms_provider_name - O KMS que você está usando para armazenar sua Chave Mestre do Cliente. Defina esta variável como
"local"
para este tutorial.uri - URI de conexão do sistema do MongoDB . Defina seu URI de conexão na variável de ambiente
MONGODB_URI
ou substitua o valor diretamente.key_vault_database_name - O banco de dados de dados no MongoDB onde suas chaves de criptografia de dados (DEKs) serão armazenadas. Defina esta variável como
"encryption"
.key_vault_collection_name - A coleção no MongoDB onde seus DEKs serão armazenados. Defina essa variável como
"__keyVault"
, que é a convenção para ajudar a evitar dúvidas sobre uma collection de usuário.key_vault_namespace - O namespace no MongoDB onde seus DEKs serão armazenados. Defina esta variável para os valores das variáveis
key_vault_database_name
ekey_vault_collection_name
, separados por um período.encryption_database_name - O banco de dados de dados no MongoDB onde seus dados criptografados serão armazenados. Defina esta variável como
"medicalRecords"
.encryption_collection_name - A coleção no MongoDB onde seus dados criptografados serão armazenados. Defina esta variável como
"patients"
.
Você pode declarar essas variáveis usando o seguinte código:
# KMS provider name should be one of the following: "aws", "gcp", "azure", "kmip" or "local" kms_provider_name = "<KMS provider name>" uri = os.environ['MONGODB_URI'] # Your connection URI key_vault_database_name = "encryption" key_vault_collection_name = "__keyVault" key_vault_namespace = f"{key_vault_database_name}.{key_vault_collection_name}" encrypted_database_name = "medicalRecords" encrypted_collection_name = "patients"
Importante
Permissões de namespace da coleção de cofre de chaves
Para concluir este tutorial, o usuário do banco de dados que seu aplicativo usa para se conectar ao MongoDB deve ter permissões dbAdmin
nos seguintes namespaces:
encryption.__keyVault
medicalRecords
database
Dica
Variáveis de ambiente
O código de exemplo neste tutorial faz referência a variáveis de ambiente que você precisa definir. Como alternativa, você pode substituir os valores diretamente no código.
Para saber como configurar essas variáveis de ambiente, consulte o readme.md incluído na aplicação de amostra no Github.
Dica
Variáveis de ambiente
O código de exemplo neste tutorial faz referência a variáveis de ambiente que você precisa definir. Como alternativa, você pode substituir os valores diretamente no código.
Para saber como configurar essas variáveis de ambiente, consulte o readme.md incluído na aplicação de amostra no Github.
Dica
Variáveis de ambiente
O código de exemplo neste tutorial faz referência a variáveis de ambiente que você precisa definir. Como alternativa, você pode substituir os valores diretamente no código.
Para saber como configurar essas variáveis de ambiente, consulte o readme.md incluído na aplicação de amostra no Github.
Dica
Variáveis de ambiente
O código de exemplo neste tutorial faz referência a variáveis de ambiente que você precisa definir. Como alternativa, você pode substituir os valores diretamente no código.
Para saber como configurar essas variáveis de ambiente, consulte o readme.md incluído na aplicação de amostra no Github.
Dica
Variáveis de ambiente
O código de exemplo neste tutorial faz referência a variáveis de ambiente que você precisa definir. Como alternativa, você pode substituir os valores diretamente no código.
Para saber como configurar essas variáveis de ambiente, consulte o readme.md incluído na aplicação de amostra no Github.
Dica
Variáveis de ambiente
O código de exemplo neste tutorial faz referência a variáveis de ambiente que você precisa definir. Como alternativa, você pode substituir os valores diretamente no código.
Para saber como configurar essas variáveis de ambiente, consulte o readme.md incluído na aplicação de amostra no Github.
Crie sua coleção criptografada
Criar uma chave mestra do cliente
Você deve criar uma chave mestra do cliente (CMK) para executar a Queryable Encryption.
Crie uma chave mestra do cliente de 96 bytes e salve-a em seu sistema de arquivos como o arquivo customer-master-key.txt
:
customerMasterKeyPath = "customer-master-key.txt"; if (!fs.existsSync(customerMasterKeyPath)) { fs.writeFileSync(customerMasterKeyPath, crypto.randomBytes(96)); }
using var randomNumberGenerator = RandomNumberGenerator.Create(); try { var bytes = new byte[96]; randomNumberGenerator.GetBytes(bytes); var localCustomerMasterKeyBase64 = Convert.ToBase64String(bytes); File.WriteAllText("customer-master-key.txt", localCustomerMasterKeyBase64); } catch (Exception e) { throw new Exception("Unable to write Customer Master Key file due to the following error: " + e.Message); }
key := make([]byte, 96) if _, err := rand.Read(key); err != nil { panic(fmt.Sprintf("Unable to create a random 96 byte data key: %v\n", err)) } if err := os.WriteFile("customer-master-key.txt", key, 0644); err != nil { panic(fmt.Sprintf("Unable to write key to file: %v\n", err)) }
byte[] localCustomerMasterKey = new byte[96]; new SecureRandom().nextBytes(localCustomerMasterKey); try (FileOutputStream stream = new FileOutputStream("customer-master-key.txt")) { stream.write(localCustomerMasterKey); // ...
if (!existsSync("./customer-master-key.txt")) { try { writeFileSync("customer-master-key.txt", randomBytes(96)); } catch (err) { throw new Error( `Unable to write Customer Master Key to file due to the following error: ${err}` ); } }
path = "customer-master-key.txt" file_bytes = os.urandom(96) with open(path, "wb") as f: f.write(file_bytes)
Aviso
Não use um arquivo de chave local em produção
Um arquivo de chave local em seu sistema de arquivos é inseguro e não é recomendado para produção. Em vez disso, você deve armazenar as chaves mestras do cliente em um sistema de gerenciamento de chaves remoto (KMS ).
Para saber como usar um KMS remoto em sua implementação do Queryable Encryption, consulte o Guia de tutoriais .
Dica
Gere uma chave mestra do cliente a partir da linha de comando
Use o seguinte comando para gerar uma chave mestra do cliente a partir de um shell Unix ou PowerShell:
Shell Unix:
echo $(head -c 96 /dev/urandom | base64 | tr -d '\n') PowerShell:
$r=[byte[]]::new(64);$g=[System.Security.Cryptography.RandomNumberGenerator]::Create();$g.GetBytes($r);[Convert]::ToBase64String($r)
Salve a saída do comando anterior em um arquivo denominado customer-master-key.txt
.
Recuperar a chave-mestre do cliente e especificar as configurações do provedor KMS
Recupere o conteúdo do arquivo de chave mestra do cliente que você gerou na etapa Criar uma chave mestra do cliente deste guia.
Passe o valor chave mestra do cliente para as configurações do seu provedor de KMS. O cliente usa essas configurações para descobrir a chave mestra do cliente. Defina o nome do provedor como local
para informar ao driver que você está usando um provedor de chaves local.
// WARNING: Do not use a local key file in a production application const localMasterKey = fs.readFileSync("./customer-master-key.txt"); kmsProviderCredentials = { local: { key: localMasterKey, }, };
// WARNING: Do not use a local key file in a production application var kmsProviderCredentials = new Dictionary<string, IReadOnlyDictionary<string, object>>(); try { var localCustomerMasterKeyBase64 = File.ReadAllText("customer-master-key.txt"); var localCustomerMasterKeyBytes = Convert.FromBase64String(localCustomerMasterKeyBase64); var localOptions = new Dictionary<string, object> { { "key", localCustomerMasterKeyBytes } }; kmsProviderCredentials.Add(kmsProvider, localOptions); }
key, err := os.ReadFile("customer-master-key.txt") if err != nil { panic(fmt.Sprintf("Could not read the Customer Master Key: %v", err)) } kmsProviderCredentials := map[string]map[string]interface{}{"local": {"key": key}}
byte[] localCustomerMasterKey = new byte[96]; try (FileInputStream fis = new FileInputStream("customer-master-key.txt")) { if (fis.read(localCustomerMasterKey) < 96) throw new Exception("Expected to read 96 bytes from the customer master key file"); } catch (Exception e) { throw new Exception("Unable to read the Customer Master Key due to the following error: " + e.getMessage()); } Map<String, Object> keyMap = new HashMap<String, Object>(); keyMap.put("key", localCustomerMasterKey); Map<String, Map<String, Object>> kmsProviderCredentials = new HashMap<String, Map<String, Object>>(); kmsProviderCredentials.put("local", keyMap);
// WARNING: Do not use a local key file in a production application const localMasterKey = readFileSync("./customer-master-key.txt"); kmsProviders = { local: { key: localMasterKey, }, };
path = "./customer-master-key.txt" with open(path, "rb") as f: local_master_key = f.read() kms_provider_credentials = { "local": { "key": local_master_key }, }
Definir suas opções de criptografia automática
Crie um objeto autoEncryptionOptions
que contenha as seguintes opções:
O namespace da sua coleção do Key Vault
O objeto
kmsProviderCredentials
, definido na etapa anterior
const autoEncryptionOptions = { keyVaultNamespace: keyVaultNamespace, kmsProviders: kmsProviderCredentials, };
Crie um objeto AutoEncryptionOptions
que contenha as seguintes opções:
O namespace da sua coleção do Key Vault
O objeto
kmsProviderCredentials
, definido na etapa anteriorO objeto
extraOptions
, que contém o caminho para sua Biblioteca Compartilhada de Criptografia Automática
var extraOptions = new Dictionary<string, object> { { "cryptSharedLibPath", _appSettings["CryptSharedLibPath"] } // Path to your Automatic Encryption Shared Library }; var autoEncryptionOptions = new AutoEncryptionOptions( keyVaultNamespace, kmsProviderCredentials, extraOptions: extraOptions);
Crie um objeto AutoEncryption
que contenha as seguintes opções:
O namespace da sua coleção do Key Vault
O objeto
kmsProviderCredentials
, definido na etapa anteriorO objeto
cryptSharedLibraryPath
, que contém o caminho para sua Biblioteca Compartilhada de Criptografia Automática
cryptSharedLibraryPath := map[string]interface{}{ "cryptSharedLibPath": os.Getenv("SHARED_LIB_PATH"), // Path to your Automatic Encryption Shared Library } autoEncryptionOptions := options.AutoEncryption(). SetKeyVaultNamespace(keyVaultNamespace). SetKmsProviders(kmsProviderCredentials). SetExtraOptions(cryptSharedLibraryPath)
Crie um objeto AutoEncryptionSettings
que contenha as seguintes opções:
O namespace da sua coleção do Key Vault
O objeto
kmsProviderCredentials
, definido na etapa anteriorO objeto
extraOptions
, que contém o caminho para sua Biblioteca Compartilhada de Criptografia Automática
Map<String, Object> extraOptions = new HashMap<String, Object>(); extraOptions.put("cryptSharedLibPath", getEnv("SHARED_LIB_PATH")); // Path to your Automatic Encryption Shared Library AutoEncryptionSettings autoEncryptionSettings = AutoEncryptionSettings.builder() .keyVaultNamespace(keyVaultNamespace) .kmsProviders(kmsProviderCredentials) .extraOptions(extraOptions) .build();
Crie um objeto autoEncryptionOptions
que contenha as seguintes opções:
O namespace da sua coleção do Key Vault
O objeto
kmsProviders
, definido na etapa anteriorO objeto
sharedLibraryPathOptions
, que contém o caminho para sua Biblioteca Compartilhada de Criptografia Automática
const extraOptions = { cryptSharedLibPath: process.env.SHARED_LIB_PATH, // Path to your Automatic Encryption Shared Library }; const autoEncryptionOptions = { keyVaultNamespace, kmsProviders, extraOptions, };
Crie um objeto AutoEncryptionOpts
que contenha as seguintes opções:
O objeto
kms_provider_credentials
, definido na etapa anteriorO namespace da sua coleção do Key Vault
O caminho para sua biblioteca compartilhada de criptografia automática
auto_encryption_options = AutoEncryptionOpts( kms_provider_credentials, key_vault_namespace, crypt_shared_lib_path=os.environ['SHARED_LIB_PATH'] # Path to your Automatic Encryption Shared Library> )
Observação
Opções de criptografia automática
As opções de criptografia automática fornecem informações de configuração para a Biblioteca compartilhada de criptografia automática, que modifica o comportamento do aplicativo ao acessar campos criptografados.
Para saber mais sobre a Biblioteca Compartilhada de Criptografia Automática, consulte a página Biblioteca Compartilhada de Criptografia Automática para Queryable Encryption.
Criar um cliente para configurar uma coleção criptografada
Para criar um cliente utilizado para criptografar e descriptografar dados em sua coleção, instancie um novo MongoClient
usando seu URI de conexão e suas opções de criptografia automática.
const encryptedClient = Mongo(uri, autoEncryptionOptions);
var clientSettings = MongoClientSettings.FromConnectionString(uri); clientSettings.AutoEncryptionOptions = qeHelpers.GetAutoEncryptionOptions( keyVaultNamespace, kmsProviderCredentials); var encryptedClient = new MongoClient(clientSettings);
encryptedClient, err := mongo.Connect( context.TODO(), options.Client().ApplyURI(uri).SetAutoEncryptionOptions(autoEncryptionOptions), ) if err != nil { panic(fmt.Sprintf("Unable to connect to MongoDB: %v\n", err)) } defer func() { _ = encryptedClient.Disconnect(context.TODO()) }()
MongoClientSettings clientSettings = MongoClientSettings.builder() .applyConnectionString(new ConnectionString(uri)) .autoEncryptionSettings(autoEncryptionSettings) .build(); try (MongoClient encryptedClient = MongoClients.create(clientSettings)) {
const encryptedClient = new MongoClient(uri, { autoEncryption: autoEncryptionOptions, });
encrypted_client = MongoClient( uri, auto_encryption_opts=auto_encryption_options)
Especifique campos para criptografia
Para criptografar um campo, adicione-o ao esquema de criptografia. Para habilitar queries em um campo, adicione a propriedade "queries". Crie o esquema de criptografia da seguinte forma:
const encryptedFieldsMap = { encryptedFields: { fields: [ { path: "patientRecord.ssn", bsonType: "string", queries: { queryType: "equality" }, }, { path: "patientRecord.billing", bsonType: "object", }, ], }, };
var encryptedFields = new BsonDocument { { "fields", new BsonArray { new BsonDocument { { "keyId", BsonNull.Value }, { "path", "record.ssn" }, { "bsonType", "string" }, { "queries", new BsonDocument("queryType", "equality") } }, new BsonDocument { { "keyId", BsonNull.Value }, { "path", "record.billing" }, { "bsonType", "object" } } } } };
encryptedFieldsMap := bson.M{ "fields": []bson.M{ bson.M{ "keyId": nil, "path": "patientRecord.ssn", "bsonType": "string", "queries": []bson.M{ { "queryType": "equality", }, }, }, bson.M{ "keyId": nil, "path": "patientRecord.billing", "bsonType": "object", }, }, }
BsonDocument encryptedFieldsMap = new BsonDocument().append("fields", new BsonArray(Arrays.asList( new BsonDocument() .append("keyId", new BsonNull()) .append("path", new BsonString("patientRecord.ssn")) .append("bsonType", new BsonString("string")) .append("queries", new BsonDocument() .append("queryType", new BsonString("equality"))), new BsonDocument() .append("keyId", new BsonNull()) .append("path", new BsonString("patientRecord.billing")) .append("bsonType", new BsonString("object")))));
const encryptedFieldsMap = { encryptedFields: { fields: [ { path: "patientRecord.ssn", bsonType: "string", queries: { queryType: "equality" }, }, { path: "patientRecord.billing", bsonType: "object", }, ], }, };
encrypted_fields_map = { "fields": [ { "path": "patientRecord.ssn", "bsonType": "string", "queries": [{"queryType": "equality"}] }, { "path": "patientRecord.billing", "bsonType": "object", } ] }
Observação
No exemplo de código anterior, os campos "ssn" e "billing" são criptografados, mas somente o campo "ssn" pode ser consultado.
Criar a coleção
Instancie ClientEncryption
para acessar a API e obter métodos assistentes de criptografia.
const clientEncryption = encryptedClient.getClientEncryption()
var clientEncryptionOptions = new ClientEncryptionOptions( keyVaultClient: keyVaultClient, keyVaultNamespace: keyVaultNamespace, kmsProviders: kmsProviderCredentials ); var clientEncryption = new ClientEncryption(clientEncryptionOptions);
opts := options.ClientEncryption(). SetKeyVaultNamespace(keyVaultNamespace). SetKmsProviders(kmsProviderCredentials) clientEncryption, err := mongo.NewClientEncryption(encryptedClient, opts) if err != nil { panic(fmt.Sprintf("Unable to create a ClientEncryption instance due to the following error: %s\n", err)) }
ClientEncryptionSettings clientEncryptionSettings = ClientEncryptionSettings.builder() .keyVaultMongoClientSettings(MongoClientSettings.builder() .applyConnectionString(new ConnectionString(uri)) .build()) .keyVaultNamespace(keyVaultNamespace) .kmsProviders(kmsProviderCredentials) .build(); ClientEncryption clientEncryption = ClientEncryptions.create(clientEncryptionSettings);
const clientEncryption = new ClientEncryption(encryptedClient, autoEncryptionOptions);
client_encryption = ClientEncryption( kms_providers=kms_provider_credentials, key_vault_namespace=key_vault_namespace, key_vault_client=encrypted_client, codec_options=CodecOptions(uuid_representation=STANDARD) )
Como você está usando uma chave mestra do cliente local, não é necessário fornecer as credenciais da chave mestra do cliente. Crie uma variável contendo um objeto vazio para usar no lugar das credenciais ao criar sua coleção criptografada.
customerMasterKeyCredentials = {};
var customerMasterKeyCredentials = new BsonDocument();
cmkCredentials := map[string]string{}
BsonDocument customerMasterKeyCredentials = new BsonDocument();
customerMasterKeyCredentials = {};
customer_master_key_credentials = {}
Crie sua coleção criptografada usando o método assistente de criptografia acessado por meio da classe ClientEncryption
. Este método gera automaticamente chaves de criptografia de dados para seus campos criptografados e cria a coleção criptografada:
await clientEncryption.createEncryptedCollection( encryptedDatabaseName, encryptedCollectionName, { provider: kmsProviderName, createCollectionOptions: encryptedFieldsMap, masterKey: customerMasterKeyCredentials, } );
A versão C# deste tutorial usa classes separadas como Modelo de dados Realm para representar a estrutura do documento. Adicione as seguintes classes Patient
, PatientRecord
e PatientBilling
ao seu projeto:
using MongoDB.Bson; using MongoDB.Bson.Serialization.Attributes; [ ]public class Patient { public ObjectId Id { get; set; } public string Name { get; set; } public PatientRecord Record { get; set; } }
public class PatientRecord { public string Ssn { get; set; } public PatientBilling Billing { get; set; } }
public class PatientBilling { public string CardType { get; set; } public long CardNumber { get; set; } }
Após adicionar essas classes, crie sua collection criptografada usando o método auxiliar de encryption acessado por meio da classe ClientEncryption
. Esse método gera automaticamente diretório de dados para seu campo criptografados e cria a collection criptografada:
var createCollectionOptions = new CreateCollectionOptions<Patient> { EncryptedFields = encryptedFields }; clientEncryption.CreateEncryptedCollection(patientDatabase, encryptedCollectionName, createCollectionOptions, kmsProviderName, customerMasterKeyCredentials);
Dica
Banco de dados vs. nome do banco de dados
O método que cria a coleção criptografada requer uma referência a um objeto de banco de dados em vez do nome do banco de dados. Você pode obter essa referência usando um método em seu objeto cliente.
A versão Go deste tutorial usa modelos de dados para representar a estrutura do documento. Adicione as seguintes estruturas ao seu projeto para representar os dados em sua collection:
type PatientDocument struct { PatientName string `bson:"patientName"` PatientID int32 `bson:"patientId"` PatientRecord PatientRecord `bson:"patientRecord"` }
type PatientRecord struct { SSN string `bson:"ssn"` Billing PaymentInfo `bson:"billing"` }
type PaymentInfo struct { Type string `bson:"type"` Number string `bson:"number"` }
Após adicionar essas classes, crie sua collection criptografada usando o método auxiliar de encryption acessado por meio da classe ClientEncryption
. Esse método gera automaticamente diretório de dados para seu campo criptografados e cria a collection criptografada:
createCollectionOptions := options.CreateCollection().SetEncryptedFields(encryptedFieldsMap) _, _, err = clientEncryption.CreateEncryptedCollection( context.TODO(), encryptedClient.Database(encryptedDatabaseName), encryptedCollectionName, createCollectionOptions, kmsProviderName, customerMasterKey, )
Dica
Banco de dados vs. nome do banco de dados
O método que cria a coleção criptografada requer uma referência a um objeto de banco de dados em vez do nome do banco de dados. Você pode obter essa referência usando um método em seu objeto cliente.
Crie sua coleção criptografada usando o método assistente de criptografia acessado por meio da classe ClientEncryption
. Este método gera automaticamente chaves de criptografia de dados para seus campos criptografados e cria a coleção criptografada:
CreateCollectionOptions createCollectionOptions = new CreateCollectionOptions().encryptedFields(encryptedFieldsMap); CreateEncryptedCollectionParams encryptedCollectionParams = new CreateEncryptedCollectionParams(kmsProviderName); encryptedCollectionParams.masterKey(customerMasterKeyCredentials); try { clientEncryption.createEncryptedCollection( encryptedClient.getDatabase(encryptedDatabaseName), encryptedCollectionName, createCollectionOptions, encryptedCollectionParams); }
Dica
Banco de dados vs. nome do banco de dados
O método que cria a coleção criptografada requer uma referência a um objeto de banco de dados em vez do nome do banco de dados. Você pode obter essa referência usando um método em seu objeto cliente.
Crie sua coleção criptografada usando o método assistente de criptografia acessado por meio da classe ClientEncryption
. Este método gera automaticamente chaves de criptografia de dados para seus campos criptografados e cria a coleção criptografada:
Observação
Importar ClientEncryption
Ao usar o driver Node.js v6.0 e posterior, você deve importar ClientEncryption
de mongodb
.
Para versões anteriores do driver, importe ClientEncryption
de mongodb-client-encryption
.
await clientEncryption.createEncryptedCollection( encryptedDatabase, encryptedCollectionName, { provider: kmsProviderName, createCollectionOptions: encryptedFieldsMap, masterKey: customerMasterKeyCredentials, } );
Dica
Banco de dados vs. nome do banco de dados
O método que cria a coleção criptografada requer uma referência a um objeto de banco de dados em vez do nome do banco de dados. Você pode obter essa referência usando um método em seu objeto cliente.
Crie sua coleção criptografada usando o método assistente de criptografia acessado por meio da classe ClientEncryption
. Este método gera automaticamente chaves de criptografia de dados para seus campos criptografados e cria a coleção criptografada:
client_encryption.create_encrypted_collection( encrypted_client[encrypted_database_name], encrypted_collection_name, encrypted_fields_map, kms_provider_name, customer_master_key_credentials, )
Dica
Banco de dados vs. nome do banco de dados
O método que cria a coleção criptografada requer uma referência a um objeto de banco de dados em vez do nome do banco de dados. Você pode obter essa referência usando um método em seu objeto cliente.
Inserir um documento com campos criptografados
Crie um documento de amostra que descreva as informações pessoais de um paciente. Use o cliente criptografado para inseri-lo na coleção patients
, conforme mostrado no exemplo a seguir:
const patientDocument = { patientName: "Jon Doe", patientId: 12345678, patientRecord: { ssn: "987-65-4320", billing: { type: "Visa", number: "4111111111111111", }, }, }; const encryptedCollection = encryptedClient.getDB(encryptedDatabaseName).getCollection(encryptedCollectionName); const insertResult = await encryptedCollection.insertOne(patientDocument);
Crie um documento de amostra que descreva as informações pessoais de um paciente. Use o cliente criptografado para inseri-lo na coleção patients
, conforme mostrado no exemplo a seguir:
var patient = new Patient { Name = "Jon Doe", Id = new ObjectId(), Record = new PatientRecord { Ssn = "987-65-4320", Billing = new PatientBilling { CardType = "Visa", CardNumber = 4111111111111111 } } }; var encryptedCollection = encryptedClient.GetDatabase(encryptedDatabaseName). GetCollection<Patient>(encryptedCollectionName); encryptedCollection.InsertOne(patient);
Crie um documento de amostra que descreva as informações pessoais de um paciente. Use o cliente criptografado para inseri-lo na coleção patients
, conforme mostrado no exemplo a seguir:
patientDocument := &PatientDocument{ PatientName: "John Doe", PatientID: 12345678, PatientRecord: PatientRecord{ SSN: "987-65-4320", Billing: PaymentInfo{ Type: "Visa", Number: "4111111111111111", }, }, } coll := encryptedClient.Database(encryptedDatabaseName).Collection(encryptedCollectionName) _, err = coll.InsertOne(context.TODO(), patientDocument) if err != nil { panic(fmt.Sprintf("Unable to insert the patientDocument: %s", err)) }
Este tutorial utiliza POJOs como modelos de dados para representar a estrutura do documento . Para configurar seu aplicação para usar POJOs, adicione o seguinte código:
CodecProvider pojoCodecProvider = PojoCodecProvider.builder().automatic(true).build(); CodecRegistry pojoCodecRegistry = fromRegistries(getDefaultCodecRegistry(), fromProviders(pojoCodecProvider));
Para saber mais sobre POJOs Java , consulte o artigo da wikipedário Objeto Java antigo simples.
Este tutorial usa os seguintes POJOs:
Patient
PatientRecord
PatientBilling
Você pode visualizar essas classes no pacote de modelos do aplicação Java completo .
Adicione estas classes POJO ao seu aplicação. Em seguida, crie uma instância de um Patient
que descreva as informações pessoais de um pai. Use o cliente criptografado para inseri-lo na collection patients
, conforme mostrado no exemplo a seguir:
MongoDatabase encryptedDb = encryptedClient.getDatabase(encryptedDatabaseName).withCodecRegistry(pojoCodecRegistry); MongoCollection<Patient> collection = encryptedDb.getCollection(encryptedCollectionName, Patient.class); PatientBilling patientBilling = new PatientBilling("Visa", "4111111111111111"); PatientRecord patientRecord = new PatientRecord("987-65-4320", patientBilling); Patient patientDocument = new Patient("Jon Doe", patientRecord); InsertOneResult result = collection.insertOne(patientDocument);
Crie um documento de amostra que descreva as informações pessoais de um paciente. Use o cliente criptografado para inseri-lo na coleção patients
, conforme mostrado no exemplo a seguir:
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);
Crie um documento de amostra que descreva as informações pessoais de um paciente. Use o cliente criptografado para inseri-lo na coleção patients
, conforme mostrado no exemplo a seguir:
patient_document = { "patientName": "Jon Doe", "patientId": 12345678, "patientRecord": { "ssn": "987-65-4320", "billing": { "type": "Visa", "number": "4111111111111111", }, }, } encrypted_collection = encrypted_client[encrypted_database_name][encrypted_collection_name] result = encrypted_collection.insert_one(patient_document)
Consulte um campo criptografado
A amostra de código a seguir executa uma query de localização em um campo criptografado e imprime os dados descriptografados:
const findResult = await encryptedCollection.findOne({ "patientRecord.ssn": "987-65-4320", }); console.log(findResult);
var ssnFilter = Builders<Patient>.Filter.Eq("record.ssn", patient.Record.Ssn); var findResult = await encryptedCollection.Find(ssnFilter).ToCursorAsync(); Console.WriteLine(findResult.FirstOrDefault().ToJson());
var findResult PatientDocument err = coll.FindOne( context.TODO(), bson.M{"patientRecord.ssn": "987-65-4320"}, ).Decode(&findResult)
Patient findResult = collection.find( new BsonDocument() .append("patientRecord.ssn", new BsonString("987-65-4320"))) .first(); System.out.println(findResult);
const findResult = await encryptedCollection.findOne({ "patientRecord.ssn": "987-65-4320", }); console.log(findResult);
find_result = encrypted_collection.find_one({ "patientRecord.ssn": "987-65-4320" }) print(find_result)
A saída do exemplo de código anterior deve ser semelhante a esta:
{ "_id": { "$oid": "648b384a722cb9b8392df76a" }, "name": "Jon Doe", "record": { "ssn": "987-65-4320", "billing": { "type": "Visa", "number": "4111111111111111" } }, "__safeContent__": [ { "$binary": { "base64": "L1NsYItk0Sg+oL66DBj6IYHbX7tveANQyrU2cvMzD9Y=", "subType": "00" } } ] }
Aviso
Não modifique o campo __safeContent__.
O campo __safeContent__
é essencial para o Queryable Encryption. Não modifique o conteúdo deste campo.
Saiba mais
Para exibir um tutorial sobre Queryable Encryption pronta para produção com um KMS remoto, consulte Tutoriais.
Para saber como funciona a Queryable Encryption, consulte a página Fundamentos.
Para saber mais sobre os tópicos mencionados neste guia, consulte os seguintes links:
Saiba mais sobre os componentes da Queryable Encryption na página Referência.
Saiba como funcionam as chaves mestras do cliente e as chaves de criptografia de dados na página Chaves e cofres de chaves.
Veja como os provedores de KMS gerenciam suas chaves Queryable Encryption na página Provedores de KMS.