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

Gerenciamento das chaves de criptografia

Nesta página

  • Componentes de criptografia
  • Serviços de gerenciamento de chaves suportados
  • Gerenciar o nome alternativo de uma Data Encryption Key (DEK)
  • Criar uma Data Encryption Key (DEK) com um nome alternativo
  • Usar nomes alternativos de Chaves em um esquema de criptografia automática
  • Procedimento: girar chaves de encriptação usando o Mongo Shell
  • Excluir uma Data Encryption Key (DEK)
  • Saiba mais

Neste guia, você pode aprender como gerenciar suas chaves de encriptação com um Sistema de gerenciamento de chaves (KMS) em seu aplicativo habilitado para criptografia no nível do campo (CSFLE) do lado do cliente.

O MongoDB usa os seguintes componentes para executar a criptografia no nível do campo do lado do cliente:

  • Data Encryption Keys (DEK)s

  • Chaves mestras do cliente (CMK)s

  • Key Vault collections

  • Sistema de Gerenciamento de Chaves (KMS)

Para saber mais sobre chaves e cofres de chaves, consulteChaves de encriptação ecofres de chaves .

A criptografia de nível de campo do lado do cliente oferece suporte aos seguintes provedores de sistema de gerenciamento de chaves:

  • KMS do Amazon Web Services

  • Azure Key Vault

  • KMS do Google Cloud

  • Qualquer sistema de gerenciamento de chaves compatível com KMIP

  • Provedor de chaves local

A versão do protocolo KMIP padrão é 1.2. Você pode configurar o MongoDB para usar a versão KMIP 1.0 ou 1.1 no arquivo de configuração do servidor MongoDB.

Para saber mais sobre esses fornecedores, incluindo diagramas que mostram como seu aplicação os utiliza para executar a criptografia no nível do campo do lado do cliente, consulte Fornecedores KMS.

Você pode atribuir nomes alternativos a uma Data Encryption Key (DEK) para facilitar a referência à chave. Atribuir nomes alternativos permite executar as seguintes ações:

  • Fazer referência a uma DEK de outras formas do que pelo campo _id.

  • Atribua dinamicamente DEKs no tempo de execução.

Importante

Pré-requisitos

Antes de adicionar um novo nome alternativo da chave, você deve criar um índice único parcial no campo keyAltNames. Esse índice precisa ter uma partialFilterExpression para documentos onde existem keyAltNames.

A criptografia do nível do campo no lado do cliente depende da singularidade imposta pelo servidor dos principais nomes alternativos.

Para saber como criar um índice parcial, consulte Índices parciais.

O exemplo a seguir cria uma Chave de criptografia de dados com um nome alternativo. Selecione a guia que corresponde ao idioma do seu driver:

var autoEncryptionOpts = {
keyVaultNamespace: keyVaultNamespace,
kmsProviders: kmsProviders,
};
var encryptedClient = Mongo(
connectionString,
autoEncryptionOpts
);
var clientEncryption = encryptedClient.getClientEncryption();
var masterKey = {
"<Your dataKeyOpts Key>": "<Your dataKeyOpts Value>",
};
var keyVault = encryptedClient.getKeyVault();
var keyId = keyVault.createKey("aws", masterKey, ["<Your Key Alt Name>"]);
var keyVaultClient = new MongoClient(connectionString);
var clientEncryptionOptions = new ClientEncryptionOptions(
keyVaultClient: keyVaultClient,
keyVaultNamespace: keyVaultNamespace,
kmsProviders: kmsProviders);
var clientEncryption = new ClientEncryption(clientEncryptionOptions);
var dataKeyOptions = new DataKeyOptions(
alternateKeyNames: new[] { "<Your Key Alt Name>" },
masterKey: new BsonDocument
{
{ "<Your dataKeyOpts Keys>", "<Your dataKeyOpts Values>" },
});
var dataKeyId = clientEncryption.CreateDataKey("<Your KMS Provider>", dataKeyOptions, CancellationToken.None);
clientEncryptionOpts := options.ClientEncryption().SetKeyVaultNamespace(KeyVaultNamespace).SetKmsProviders(kmsProviders)
keyVaultClient, err := mongo.Connect(context.TODO(), options.Client().ApplyURI(URI))
if err != nil {
return fmt.Errorf("Client connect error %v", err)
}
clientEnc, err := mongo.NewClientEncryption(keyVaultClient, clientEncryptionOpts)
if err != nil {
return fmt.Errorf("NewClientEncryption error %v", err)
}
defer func() {
_ = clientEnc.Close(context.TODO())
}()
masterKey := map[string]interface{}{
"<Your dataKeyOpts Key>": "<Your dataKeyOpts Value>",
}
dataKeyOpts := options.DataKey().
SetMasterKey(masterKey).
SetKeyAltNames([]string{"<Your Key Alt Name>"})
dataKeyID, err := clientEnc.CreateDataKey(context.TODO(), provider, dataKeyOpts)
if err != nil {
return fmt.Errorf("create data key error %v", err)
}
ClientEncryptionSettings clientEncryptionSettings = ClientEncryptionSettings.builder()
.keyVaultMongoClientSettings(MongoClientSettings.builder()
.applyConnectionString(new ConnectionString(connectionString))
.build())
.keyVaultNamespace(keyVaultNamespace)
.kmsProviders(kmsProviders)
.build();
ClientEncryption clientEncryption = ClientEncryptions.create(clientEncryptionSettings);
BsonDocument masterKeyProperties = new BsonDocument();
masterKeyProperties.put("provider", new BsonString("<Your KMS Provider>"));
masterKeyProperties.put("<Your dataKeyOpts Key>", new BsonString("<Your dataKeyOpts Value>"));
List keyAltNames = new ArrayList<String>();
keyAltNames.add("<Your Key Alt Name>");
BsonBinary dataKeyId = clientEncryption.createDataKey(kmsProvider, new DataKeyOptions().masterKey(masterKeyProperties).keyAltNames(keyAltNames));
const encryption = new ClientEncryption(client, {
keyVaultNamespace,
kmsProviders,
});
const masterKey = {
"<Your dataKeyOpts Key>": "<Your dataKeyOpts Value>",
};
const key = await encryption.createDataKey(provider, {
masterKey: masterKey,
keyAltNames: ["<Your Key Alt Name>"],
});
client = MongoClient(connection_string)
client_encryption = ClientEncryption(
kms_providers,
key_vault_namespace,
client,
CodecOptions(uuid_representation=STANDARD),
)
master_key={ "<Your dataKeyOpts Key>" : "<Your dataKeyOpts Value>"}
data_key_id = client_encryption.create_data_key(provider, master_key, key_alt_names=["<Your Key Alt Name>"])

Para saber mais sobre os objetos dataKeyOpts e kmsProviders , consulte Provedores de KMS.

Os esquemas de criptografia contêm regras especificadas pelo usuário que identificam quais campos devem ser criptografados e como criptografar esses campos. Em suas regras de criptografia, você pode especificar nomes de chaves alternativos para a chave de encriptação de dados que criptografa seu campo.

Você deve se referir a um nome alternativo de chave com um ponteiro JSON. Um ponteiro JSON é uma string prefixada com um caractere "/" que pode ser usada para acessar um valor de campo específico no mesmo documento ou em outro documento. Use ponteiros JSON para referenciar um campo em sua query ou documento de atualização que contém o valor do nome alternativo da chave.

Importante

Não é possível usar nome alternativo para um campo criptografado de forma determinística

Você não pode referenciar uma DEK pelo nome alternativo ao criptografar um campo com o algoritmo de criptografia determinístico. Para criptografar seu campo deterministicamente, você deve especificar o _id da chave que deseja usar para criptografar seu campo.

Considere o seguinte esquema de criptografia que criptografa o campo salary:

{
"<database>.<collection>": {
"bsonType": "object",
"properties": {
"salary": {
"encrypt": {
"bsonType": "int",
"keyId": "/fieldWithAltName",
"algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Random"
}
}
}
}
}

O campo keyId do esquema contém um ponteiro JSON para referenciar o campo fieldWithAltName dentro dos documentos sendo codificados.

O valor de fieldWithAltName do documento abaixo é my-alt-name:

{
"name": "Jon Doe",
"salary": 45000,
"fieldWithAltName": "my-alt-name"
}

O campo salary é criptografado pela DEK que tem o nome alternativo my-alt-name.

Você pode usar nomes de chave alternativos para definir dinamicamente a chave de criptografia de dados de um campo em tempo de execução. Use essa funcionalidade para criptografar documentos individuais com diferentes DEKs usando o mesmo esquema de criptografia.

Por exemplo, considere os seguintes documentos:

{
"name": "Jon Doe",
"salary": 45000,
"fieldWithAltName": "my-alt-name"
},
{
"name": "Jane Smith",
"salary": 70000,
"fieldWithAltName": "my-other-alt-name"
}

Você insere os documentos anteriores utilizando um cliente habilitado para CSFLE configurada com o esquema de criptografia do exemplo anterior.

No esquema de criptografia, o campo salary.encrypt.keyId contém um ponteiro JSON no campo fieldWithAltName do documento inserido. Como resultado, os campos salary nos dois documentos de exemplo são criptografados usando uma DEK específica para o documento individual. As chaves são atribuídas dinamicamente no tempo de execução.

Com a versão 1.5 e posterior do Mongo Shell, você pode girar chaves de encriptação usando o método rewrapManyDataKey . O método rewrapManyDataKey descriptografa automaticamente diversas chaves de dados e as criptografa novamente usando uma chave mestra do cliente especificada. Em seguida, ele atualiza as chaves giradas na key vault collection. Este método permite girar chaves de encriptação com base em dois argumentos opcionais:

  • Um filtro utilizado para especificar quais chaves devem ser rotacionadas. Se nenhuma chave de dados corresponder ao filtro fornecido, nenhuma chave será rotacionada. Omita o filtro para rotacionar todas as chaves na sua Key Vault Collection.

  • Um objeto que representa uma nova CMK. Omitir este objeto para rotacionar as chaves de dados usando suas CMKs atuais.

O rewrapManyDataKey utiliza a seguinte sintaxe:

keyVault = db.getKeyVault()
keyVault.rewrapManyDataKey(
{
"<Your custom filter>"
},
{
provider: "<KMS provider>",
masterKey: {
"<dataKeyOpts Key>" : "<dataKeyOpts Value>"
}
}
)

Para saber mais sobre o objeto dataKeyOpts para seu fornecedor de KMS, consulte Serviços de gerenciamento de chaves suportados.

Você pode excluir uma chave de encriptação de dados da Key Vault Collection usando operações de exclusão CRUD padrão. Se você excluir uma DEK, todos os campos criptografados com essa DEK ficarão permanentemente ilegíveis.

Dica

Funcionalidade específica do MongoDB Shell

O MongoDB Shell permite excluir uma DEK pela UUID usando o seguinte método keyVault.deleteKey():

keyVault = db.getKeyVault()
keyVault.deleteKey(UUID("<UUID String>"))

Para saber mais sobre as collections do Key Vault, consulte Chaves de encriptação e Key Vaults.

Para obter tutoriais detalhando como configurar um aplicativo habilitado para CSFLE com cada um dos fornecedores de KMS compatíveis, consulte as páginas a seguir:

Para ver mais exemplos de esquemas de criptografia, consulte Esquemas de criptografia CSFLE.

Voltar

Schemas