Menu Docs

Provedores de KMS CSFLE

Saiba mais sobre os provedores de criptografia de nível de campo (CSFLE) do sistema de gerenciamento de chaves (KMS).

No CSFLE, seu sistema de gerenciamento de chaves executa as seguintes tarefas:

Para saber mais sobre chave mestra do cliente e chave de encriptação de dados, consulte Keys and Key Vaults.

Para criar uma Chave Mestre do Cliente, você deve configurar seu Sistema de Gerenciamento de Chaves para gerar sua Chave Mestre do Cliente da seguinte maneira:

Para ver um tutorial que demonstre como criar e armazenar seu CMK em seu KMS preferido, consulte Tutoriais.

Ao criar uma Chave de criptografia de dados, você deve executar as seguintes ações:

  • Instanciar uma instância ClientEncryption em seu aplicativo habilitado para CSFLE:

    • Forneça um objeto kmsProviders que especifique as credenciais que seu aplicativo compatível com CSFLE usa para se autenticar com seu provedor KMS.

  • Crie uma Chave de criptografia de dados com o método CreateDataKey do objeto ClientEncryption em seu aplicativo habilitado para CSFLE.

    • Forneça um objeto do dataKeyOpts que especifique com qual chave seu KMS deve criptografar sua nova Chave de encriptação de dados.

Para aprender a criar e criptografar uma Chave de encriptação de dados, assista ao tutorial disponível nos recursos a seguir:

Para visualizar a estrutura de objetos do kmsProviders e dataKeyOpts para todos os provedores KMS suportados, consulte Serviços de gerenciamento de chaves compatíveis.

As seções a seguir desta página apresentam as seguintes informações para todos os provedores do Key Management System:

  • Arquitetura de cliente habilitado para CSFLE

  • Estrutura de kmsProviders objetos

  • Estrutura de dataKeyOpts objetos

O CSFLE é compatível com os seguintes provedores do Key Management System:

Esta seção fornece informações relacionadas ao uso do AWS Key Management Service no seu aplicativo habilitado para CSFLE.

Para ver um tutorial que demonstra como usar o AWS KMS em seu aplicativo habilitado para CSFLE, consulte Usar criptografia automática no nível do campo do lado do cliente com a AWS.

O diagrama a seguir descreve a arquitetura de um aplicativo habilitado para CSFLE usando o AWS KMS.

Observação

O cliente não consegue acessar a chave mestra do cliente

Ao usar o Sistema de gerenciamento de chaves anterior, seu aplicativo habilitado para CSFLE não tem acesso à sua Chave mestre do cliente.

A tabela a seguir apresenta a estrutura de um objeto kmsProviders para o AWS KMS:

Campo
Obrigatório para o usuário do IAM
Obrigatório para a função do IAM
Descrição

ID da chave de acesso

Sim

Sim

Identifica o usuário da conta.

Chave de acesso secreta

Sim

Sim

Contém as credenciais de autenticação do usuário da conta.

Session Token

No

Sim

Contém um token obtido do AWS Security Token Service (STS).

A tabela a seguir apresenta a estrutura de um objeto dataKeyOpts para o AWS KMS:

Campo
Obrigatório
Descrição

chave

Sim

região

No

Região AWS de sua chave mestra, por exemplo. "us-west-2"; necessário somente se não for especificado em seu ARN.

endpoint

No

Nome de host personalizado para o endpoint AWS, se configurado para sua conta.

Esta seção fornece informações relacionadas ao uso do Azure Key Vault em seu aplicativo habilitado para CSFLE.

Para ver um tutorial demonstrando como usar o Azure Key Vault em seu aplicativo compatível com CSFLE, consulte Usar criptografia automática em nível de campo do lado do clientecom o Azure.

O diagrama a seguir descreve a arquitetura de um aplicativo habilitado para CSFLE usando o Azure Key Vault.

Observação

O cliente não consegue acessar a chave mestra do cliente

Ao usar o Sistema de gerenciamento de chaves anterior, seu aplicativo habilitado para CSFLE não tem acesso à sua Chave mestre do cliente.

A tabela a seguir mostra a estrutura de um objeto de Realm kmsProviders para o Azure Key Vault:

Campo
Obrigatório
Descrição

azure.tenantId

Sim

Identifica a organização da conta.

azure.clientId

Sim

Identifica o clientId para autenticar seu aplicativo registrado.

azure.clientSecret

Sim

Usado para autenticar seu aplicativo registrado.

azure.identityPlatformEndpoint

No

Especifica um nome de host e número de porta para o servidor de autenticação. O padrão é login.microsoftonline.com e é necessário apenas para instâncias não comerciais do Azure, como uma conta do governo ou da China.

A tabela a seguir mostra a estrutura de um objeto de Realm dataKeyOpts para o Azure Key Vault:

Campo
Obrigatório
Descrição

keyName

Sim

Nome da chave mestre

keyVersion

Não, mas é altamente recomendável

Versão da chave mestre

Ponto final do KeyVault

Sim

URL do cofre de chaves. Por exemplo, myVaultName.vault.azure.net

Aviso

Se você não incluir um campo keyVersion, o Azure Key Vault tentará descriptografar as chaves de encriptação de dados usando a chave mestra do cliente mais recente. Se você girar o CMK, mas não reembrulhar as chaves de criptografia de dados com a nova chave mestre, a tentativa de descriptografar uma DEK existente falhará, pois a DEK é criptografada com a versão anterior do CMK.

Esta seção fornece informações relacionadas ao uso do Google Cloud Key Management em seu aplicativo habilitado para CSFLE.

Para exibir um tutorial demonstrando como usar o GCP KMS em seu aplicativo habilitado para CSFLE, consulte Usar criptografia automática de nível de campo do lado do cliente com GCP.

O diagrama a seguir descreve a arquitetura de um aplicativo habilitado para CSFLE usando o GCP KMS.

Observação

O cliente não consegue acessar a chave mestra do cliente

Ao usar o Sistema de gerenciamento de chaves anterior, seu aplicativo habilitado para CSFLE não tem acesso à sua Chave mestre do cliente.

A tabela a seguir mostra a estrutura de um objeto de Realm kmsProviders para a Google Cloud Platform Key Management Service (GCP KMS):

Campo
Obrigatório
Descrição

Email

Sim

Identifica o endereço de e-mail da sua conta de serviço.

chave privada

Sim

Identifies your service account private key in either base64 string or Binary subtype 0 format without the prefix and suffix markers.

Suppose your service account private key value is as follows:
-----BEGIN PRIVATE KEY-----\nyour-private-key\n-----END PRIVATE KEY-----\n
The value you would specify for this field is:
your-private-key
If you have a user-key.json credential file, you can extract the string by executing the following command in a bash or similar shell. The following command requires that you install OpenSSL:
cat user-key.json | jq -r .private_key | openssl pkcs8 -topk8 -nocrypt -inform PEM -outform DER | base64 -w 0

endpoint

No

Especifica um nome de host e número de porta para o servidor de autenticação. O padrão é oauth2.googleapis.com.

A tabela a seguir mostra a estrutura de um objeto de Realm dataKeyOpts para a Google Cloud Platform Key Management Service (GCP KMS):

Campo
Obrigatório
Descrição

projectId

Sim

Identificador do seu projeto no qual você criou a chave.

localização

Sim

Região especificada para sua chave.

chaveiro

Sim

Identificador do grupo de chaves ao qual sua chave pertence.

keyName

Sim

Identificador para a chave mestre simétrica.

keyVersion

No

Especifica a versão da chave nomeada. Se não for especificada, a versão padrão da chave será usada.

endpoint

No

Especifica o host e a porta opcional do Cloud KMS. O padrão é cloudkms.googleapis.com.

Esta seção fornece informações relacionadas ao uso de um Sistema de Gerenciamento de Chaves compatível com KMIP em seu aplicativo compatível com CSFLE.

Para ver um tutorial que demonstra como usar um sistema de gerenciamento de chaves compatível com KMIP em seu aplicativo habilitado para CSFLE, consulte Usar criptografia automática em nível de campo do lado do cliente com KMIP.

O diagrama a seguir descreve a arquitetura de um aplicativo habilitado para CSFLE usando um provedor de chaves compatível com KMIP.

Importante

O cliente acessa a chave mestre do cliente

Quando o aplicativo habilitado para CSFLE usa um provedor de chaves compatível com KMIP, o aplicativo acessa diretamente a chave mestra do cliente.

A tabela a seguir apresenta a estrutura de um objeto kmsProviders para um provedor de chaves compatível com KMIP:

Observação

Autenticar por TLS/SSL

Seu aplicativo habilitado para CSFLE autentica por TLS/SSL ao usar KMIP.

Campo
Obrigatório
Descrição

endpoint

Sim

Especifica um nome de host e número de porta para o servidor de autenticação.

A tabela a seguir apresenta a estrutura de um objeto dataKeyOpts para um sistema de gerenciamento de chaves compatível com KMIP:

Campo
Obrigatório
Descrição

keyId

No

O keyId campo de um 96 objeto gerenciado de dados secretos de bytes armazenados em seu provedor de chaves compatível com KMIP .

Se você não especificar o campo keyId no documento masterKey que enviar ao provedor de chaves compatível com KMIP, o driver criará um novo objeto gerenciado de dados secretos de 96 bytes no provedor de chaves compatível com KMIPpara atuar como sua chave mestra.

endpoint

Sim

O URI do seu provedor de chaves compatível com KMIP .

Esta seção fornece informações relacionadas ao uso de um provedor de chaves locais (seu sistema de arquivos) em seu aplicativo habilitado para CSFLE.

Aviso

Não use o provedor de chave local na produção

O provedor de chaves locais é um método inseguro de armazenamento 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 na implementação do CSFLE, consulte o guia Tutoriais.

Para visualizar um tutorial que demonstra como usar um provedor de chave local para testar a criptografia em nível de campo do lado do cliente, consulte Início rápido.

Quando você usa um provedor de chaves locais em seu aplicativo habilitado para CSFLE, seu aplicativo recupera sua chave mestre de cliente do sistema de arquivos do computador no qual seu aplicativo está sendo executado.

O diagrama a seguir descreve a arquitetura de um aplicativo habilitado para CSFLE usando um provedor de chave local.

A tabela a seguir apresenta a estrutura de um objeto kmsProviders para um provedor de chaves local:

Campo
Obrigatório
Descrição

chave

Sim

A chave mestre usada para criptografar/descriptografar chaves de dados. A chave mestre é passada como uma string codificada base64.

Ao usar um provedor de chave local, você especifica a chave mestra do cliente por meio do objeto kmsProviders.