Menu Docs
Página inicial do Docs
/
Manual do MongoDB
/ / / / /

Usar Queryable Encryption automática com Amazon Web Services

Nesta página

  • Visão geral
  • Antes de começar
  • Configurar o KMS
  • Criar a Chave Mestre do Cliente
  • Criar um usuário AWS IAM
  • Criar o aplicativo
  • Atribua variáveis ao seu aplicativo
  • Crie sua coleção criptografada
  • Inserir um documento com campos criptografados
  • Consulte um campo criptografado
  • Saiba mais

Este guia mostra como criar um aplicativo que implementa o recurso MongoDB Queryable Encryption para criptografar e descriptografar automaticamente os campos do documento e usar o Amazon Web Services (AWS) KMS para gerenciamento de chaves.

Depois de concluir as etapas deste guia, você deverá ter:

  • Uma chave mestre do cliente gerenciada pelo AWS KMS

  • Um usuário do AWS IAM com permissões para acessar a chave mestra do cliente no AWS KMS

  • Uma aplicação cliente funcional que insere documentos com campos criptografados usando sua Chave Mestre do Cliente

Dica

chave mestra do cliente

Para saber mais sobre a chave mestra do cliente, leia a documentação Keys and Key Vaults .

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.

Aplicação mongosh completa

1
1
2
3

Crie uma nova chave simétrica seguindo a documentação oficial da AWS sobre Criação de chaves KMS simétricas. A chave que você cria é a chave mestre do cliente. Escolha um nome e uma descrição que o ajudem a identificá-lo; esses campos não afetam a funcionalidade ou a configuração da CMK.

Na etapa Usage Permissions do processo de geração de chaves, aplique a seguinte política de chave padrão que habilita políticas de gerenciamento de identidade e acesso (IAM) para conceder acesso à sua chave mestre do cliente:

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Enable IAM User Permissions",
"Effect": "Allow",
"Principal": {
"AWS": "<ARN of your AWS account principal>"
},
"Action": "kms:*",
"Resource": "*"
}
]
}

Importante

Registre o nome do recurso da Amazon (ARN) e a região da sua chave mestra do cliente. Você os usará nas etapas posteriores deste guia.

Dica

Políticas de chaves

Para saber mais sobre as principais políticas, consulte Principais políticas no AWS KMS na documentação oficial da AWS.

2
2

Criar um novo usuário programático do IAM no console de gerenciamento do Amazon Web Services seguindo a documentação oficial do Amazon Web Services sobre como adicionar um usuário. Você usará esse usuário do IAM como uma conta de serviço para seu aplicativo habilitado para Queryable Encryption. Seu aplicativo se autentica com o Amazon Web Services KMS usando o usuário do IAM para criptografar e descriptografar suas DEKs (chaves de criptografia de dados) com sua chave mestra do cliente (CMK).

Importante

Registre suas Credenciais

Certifique-se de registrar as seguintes credenciais do IAM na etapa final da criação do seu usuário do IAM:

  • ID da chave de acesso

  • chave de acesso secreta

Você tem uma oportunidade de registrar essas credenciais. Se você não registrar essas credenciais durante essa etapa, deverá criar outro usuário do IAM .

3

Conceda ao seu usuário do IAM permissões kms:Encrypt e kms:Decrypt para sua chave mestre remota.

Importante

O novo usuário do cliente IAM não deve ter permissões administrativas para a chave mestre. Para manter seus dados seguros, siga o principal de privilégio mínimo.

A política em linha a seguir permite que um usuário do IAM criptografe e descriptografe com a chave mestra do cliente com o mínimo de privilégios possível:

Observação

Chave mestra remota ARN

A política a seguir requer o ARN da chave gerada na etapa Criar a chave mestra deste guia.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["kms:Decrypt", "kms:Encrypt"],
"Resource": "<the Amazon Resource Name (ARN) of your remote master key>"
}
]
}

Para aplicar a política anterior ao seu usuário do IAM, siga o guia Adicionando permissões de identidade do IAM na documentação da AWS.

Importante

Autenticar com funções IAM em produção

Ao implantar seu aplicativo habilitado para Queryable Encryption em um ambiente de produção, autentique seu aplicativo usando uma função do IAM em vez de um usuário do IAM .

Para saber mais sobre roles do IAM, consulte as seguintes páginas na documentação oficial da AWS:

1

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 "aws" 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 collection no MongoDB onde seus DEKs serão armazenados. Configure esta variável para "__keyVault".

  • keyVaultNamespace - O namespace no MongoDB onde seus DEKs serão armazenados. Defina esta variável para os valores das variáveis keyVaultDatabaseName e keyVaultCollectionName , 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 "aws" 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 collection no MongoDB onde seus DEKs serão armazenados. Defina o valor de keyVaultCollectionName para "__keyVault".

  • keyVaultNamespace - O namespace no MongoDB onde seus DEKs serão armazenados. Defina keyVaultNamespace para um novo objeto CollectionNamespace cujo nome são os valores das variáveis keyVaultDatabaseName e keyVaultCollectionName , 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 "aws" 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 collection no MongoDB onde seus DEKs serão armazenados. Configure esta variável para "__keyVault".

  • keyVaultNamespace - O namespace no MongoDB onde seus DEKs serão armazenados. Defina esta variável para os valores das variáveis keyVaultDatabaseName e keyVaultCollectionName , 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 "aws" 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 collection no MongoDB onde seus DEKs serão armazenados. Configure esta variável para "__keyVault".

  • keyVaultNamespace - O namespace no MongoDB onde seus DEKs serão armazenados. Defina esta variável para os valores das variáveis keyVaultDatabaseName e keyVaultCollectionName , 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 "aws" 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 collection no MongoDB onde seus DEKs serão armazenados. Configure esta variável para "__keyVault".

  • keyVaultNamespace - O namespace no MongoDB onde seus DEKs serão armazenados. Defina esta variável para os valores das variáveis keyVaultDatabaseName e keyVaultCollectionName , 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 "aws" 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 esta variável como "__keyVault".

  • 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 e key_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

A collection de cofre de chaves está no namespace encryption.__keyVault . Certifique-se de que o trigger de banco de dados que sua aplicação usa para se conectar ao MongoDB tenha permissões de ReadWrite nesse namespace.

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.

2
1

Crie uma variável contendo suas credenciais do Amazon Web Services KMS com a seguinte estrutura. Use o ID da chave de acesso e a chave de acesso secreta que você criou na etapa Criar um usuário do IAM deste tutorial.

kmsProviderCredentials = {
aws: {
accessKeyId: process.env["AWS_ACCESS_KEY_ID"], // Your AWS access key ID
secretAccessKey: process.env["AWS_SECRET_ACCESS_KEY"], // Your AWS secret access key
},
};
var kmsProviderCredentials = new Dictionary<string, IReadOnlyDictionary<string, object>>();
var kmsOptions = new Dictionary<string, object>
{
{ "accessKeyId", _appSettings["Aws:AccessKeyId"] }, // Your AWS access key ID
{ "secretAccessKey", _appSettings["Aws:SecretAccessKey"] } // Your AWS secret access key
};
kmsProviderCredentials.Add(kmsProvider, kmsOptions);
kmsProviderCredentials := map[string]map[string]interface{}{
"aws": {
"accessKeyId": os.Getenv("AWS_ACCESS_KEY_ID"), // AWS access key ID
"secretAccessKey": os.Getenv("AWS_SECRET_ACCESS_KEY"), // AWS secret access key
},
}
Map<String, Object> kmsProviderDetails = new HashMap<>();
kmsProviderDetails.put("accessKeyId", getEnv("AWS_ACCESS_KEY_ID")); // Your AWS access key ID
kmsProviderDetails.put("secretAccessKey", getEnv("AWS_SECRET_ACCESS_KEY")); // Your AWS secret access key
Map<String, Map<String, Object>> kmsProviderCredentials = new HashMap<String, Map<String, Object>>();
kmsProviderCredentials.put("aws", kmsProviderDetails);
kmsProviders = {
aws: {
accessKeyId: process.env.AWS_ACCESS_KEY_ID, // Your AWS access key ID
secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY, // Your AWS secret access key
},
};
kms_provider_credentials = {
"aws": {
"accessKeyId": os.environ['AWS_ACCESS_KEY_ID'], # Your AWS access key ID
"secretAccessKey": os.environ['AWS_SECRET_ACCESS_KEY'] # Your AWS secret access key
}
}

Importante

Lembrete: autenticar com funções IAM em produção

Para utilizar um papel IAM em vez de um usuário IAM para autenticar seu aplicativo, especifique um objeto vazio para suas credenciais em seu objeto do provedor de KMS. Isso instrui o condutor a recuperar automaticamente as credenciais do ambiente:

kmsProviders = {
aws: { }
};
kmsProviderCredentials.Add("aws", new Dictionary<string, object>);
kmsProviderCredentials := map[string]map[string]interface{}{
"aws": { },
}
kmsProviderCredentials.put("aws", new HashMap<>());
kmsProviders = {
aws: { }
};
kms_provider_credentials = {
"aws": { }
}
2

Crie uma variável contendo suas credenciais da Chave Mestre do Cliente com a seguinte estrutura. Use o ARN e a região que você registrou na etapa Criar uma chave mestra do cliente deste tutorial.

customerMasterKeyCredentials = {
key: process.env["AWS_KEY_ARN"], // Your AWS Key ARN
region: process.env["AWS_KEY_REGION"], // Your AWS Key Region
};
var customerMasterKeyCredentials = new BsonDocument
{
{ "key", _appSettings["Aws:KeyArn"] }, // Your AWS Key ARN
{ "region", _appSettings["Aws:KeyRegion"] } // Your AWS Key Region
};
customerMasterKeyCredentials := map[string]string{
"key": os.Getenv("AWS_KEY_ARN"), // Your AWS Key ARN
"region": os.Getenv("AWS_KEY_REGION"), // Your AWS Key Region
}
BsonDocument customerMasterKeyCredentials = new BsonDocument();
customerMasterKeyCredentials.put("provider", new BsonString(kmsProviderName));
customerMasterKeyCredentials.put("key", new BsonString(getEnv("AWS_KEY_ARN"))); // Your AWS Key ARN
customerMasterKeyCredentials.put("region", new BsonString(getEnv("AWS_KEY_REGION"))); // Your AWS Key Region
customerMasterKeyCredentials = {
key: process.env.AWS_KEY_ARN, // Your AWS Key ARN
region: process.env.AWS_KEY_REGION, // Your AWS Key Region
};
customer_master_key_credentials = {
"key": os.environ['AWS_KEY_ARN'], # Your AWS Key ARN
"region": os.environ['AWS_KEY_REGION'] # Your AWS Key Region
}
3

Crie um objeto autoEncryptionOptions que contenha as seguintes opções:

  • O namespace da sua coleção do Key Vault

  • O objeto kmsProviderCredentials , que contém suas credenciais do Amazon Web Services KMS

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 , que contém suas credenciais do Amazon Web Services KMS

  • O 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 , que contém suas credenciais do Amazon Web Services KMS

  • O 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 , que contém suas credenciais do Amazon Web Services KMS

  • O 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 , que contém suas credenciais do Amazon Web Services KMS

  • O 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 , que contém suas credenciais do Amazon Web Services KMS

  • O 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.

4

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)
5

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.

6

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

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;
[BsonIgnoreExtraElements]
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.

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.

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(
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.

3

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)
4

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.

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.

Voltar

Tutorials