As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

# Client-side criptografia em nível de campo
<a name="field-level-encryption"></a>

A Field Level Encryption (FLE – Criptografia em nível de campo) do lado do cliente do Amazon DocumentDB permite que você criptografe dados confidenciais em aplicações clientes antes de serem transferidos para um cluster do Amazon DocumentDB. Os dados confidenciais permanecem criptografados quando armazenados e processados em um cluster e são descriptografados na aplicação cliente quando recuperados.

**Topics**
+ [Introdução](#fle-getting-started)
+ [Consulta no FLE do lado do cliente](#fle-querying)

## Introdução
<a name="fle-getting-started"></a>

A configuração inicial da FLE do lado do cliente no Amazon DocumentDB é um processo de quatro etapas que inclui a criação de uma chave de criptografia, a associação de um perfil à aplicação, a configuração da aplicação e a definição da operação CRUD com opções de criptografia.

**Topics**
+ [Etapa 1: criar as chaves de criptografia](#fle-step-create-key)
+ [Etapa 2: associar um perfil à aplicação](#fle-step-associate-role)
+ [Etapa 3: configurar a aplicação](#fle-step-config-app)
+ [Etapa 4: definir uma operação CRUD](#fle-step-crud-ops)
+ [Exemplo: arquivo de configuração de criptografia em nível de campo do lado do cliente](#fle-config-example)

### Etapa 1: criar as chaves de criptografia
<a name="fle-step-create-key"></a>

Usando AWS Key Management Service, crie uma chave simétrica que seja usada para criptografar e descriptografar o campo de dados confidenciais e forneça a ela as permissões de uso do IAM necessárias. AWS KMS armazena a chave do cliente (CK) que é usada para criptografar chaves de dados (DKs). Armazene a chave do cliente no KMS para fortalecer sua postura de segurança. A chave de dados é a chave secundária que é armazenada em uma coleção do Amazon DocumentDB e é necessária para criptografar campos confidenciais antes de armazenar o documento no Amazon DocumentDB. A chave do cliente criptografa a chave de dados que, por sua vez, criptografa e descriptografa seus dados. Se estiver usando um cluster global, você poderá criar uma chave multirregional que pode ser usada por diferentes perfis de serviço em diferentes regiões.

Para obter mais informações sobre AWS Key Management Service, inclusive como criar uma chave, consulte o [Guia do desenvolvedor do AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/overview.html).

### Etapa 2: associar um perfil à aplicação
<a name="fle-step-associate-role"></a>

Crie uma política do IAM com AWS KMS as permissões apropriadas. Essa política permite que as identidades do IAM às quais está associada obtenham e descriptografem a chave do KMS especificada no campo do recurso. Seu aplicativo assume essa função do IAM para se autenticar. AWS KMS

A política deve ter a seguinte aparência:

```
{ "Effect": "Allow",
"Action": ["kms:Decrypt", "kms:Encrypt"],
"Resource": "Customer Key ARN"
}
```

### Etapa 3: configurar a aplicação
<a name="fle-step-config-app"></a>

Até agora, você definiu uma chave do cliente, criou uma função do IAM e forneceu a ela as permissões corretas do IAM para acessar a chave do cliente. AWS KMS Importe os pacotes necessários.

```
import boto3
import json
import base64
from pymongo import MongoClient
from pymongo.encryption import (Algorithm,
                                ClientEncryption)
```

```
# create a session object: 
my_session = boto3.session.Session()

# get access_key and secret_key programmatically using get_frozen_credentials() method:
current_credentials = my_session.get_credentials().get_frozen_credentials()
```

1. Especifique 'aws' como tipo de provedor KMS e insira as credenciais da sua conta que foram recuperadas na etapa anterior.

   ```
   provider = "aws"
   kms_providers = {
       provider: {
           "accessKeyId": current_credentials.access_key,
           "secretAccessKey": current_credentials.secret_key
       }
   }
   ```

1. Especifique a chave do cliente que é usada para criptografar a chave de dados:

   ```
   customer_key = {
   “region”: “AWS region of the customer_key”,
       “key”: “customer_key ARN”
   }
   
   key_vault_namespace = "encryption.dataKeys"
   
   key_alt_name = 'TEST_DATA_KEY'
   ```

1. Configure o MongoClient objeto:

   ```
   client = MongoClient(connection_string)
   
   coll = client.test.coll
   coll.drop()
   
   client_encryption = ClientEncryption(
       kms_providers, # pass in the kms_providers variable from the previous step
       key_vault_namespace = key_vault_namespace,
       client,
       coll.codec_options
   )
   ```

1. Gere sua chave de dados:

   ```
   data_key_id = client_encryption.create_data_key(provider,
       customer_key,
       key_alt_name = [key_alt_name])
   ```

1. Recupere sua chave de dados existente:

   ```
   data_key = DataKey("aws",
       master_key = customer_key)
   key_id = data_key["_id"]
   data_key_id = client[key_vault_namespace].find_one({"_id": key_id})
   ```

### Etapa 4: definir uma operação CRUD
<a name="fle-step-crud-ops"></a>

Defina a operação CRUD com opções de criptografia.

1. Defina a coleção para write/read /excluir um único documento:

   ```
   coll = client.gameinfo.users
   ```

1. Criptografia explícita - criptografe campos e insira:
**nota**  
É necessário fornecer exatamente um “key\_id” ou “key\_alt\_name”.

   ```
   encrypted_first_name = client_encryption.encrypt(
       "Jane",
       Algorithm.AEAD_AES_256_CBC_HMAC_SHA_512_Deterministic,
       key_id=data_key_id
   )
   encrypted_last_name = client_encryption.encrypt(
       "Doe",
       Algorithm.AEAD_AES_256_CBC_HMAC_SHA_512_Deterministic,
       key_id=data_key_id
   )
   encrypted_dob = client_encryption.encrypt(
       "1990-01-01",
       Algorithm.AEAD_AES_256_CBC_HMAC_SHA_512_Random,
       key_id=data_key_id
   )
   
   coll.insert_one(
       {"gamerTag": "jane_doe90",
       "firstName": encrypted_first_name,
       "lastName": encrypted_last_name,
       "dateOfBirth":encrypted_dob,
       "Favorite_games":["Halo","Age of Empires 2","Medal of Honor"]
   })
   ```

### Exemplo: arquivo de configuração de criptografia em nível de campo do lado do cliente
<a name="fle-config-example"></a>

No exemplo a seguir, substitua cada {{placeholder}} por suas próprias informações.

```
# import python packages:
import boto3
import json
import base64
from pymongo import MongoClient
from pymongo.encryption import (Algorithm,
                                ClientEncryption)

def main():
    
    # create a session object:
    my_session = boto3.session.Session()
    
    # get aws_region from session object:
    aws_region = my_session.region_name
    
    # get access_key and secret_key programmatically using get_frozen_credentials() method:
    current_credentials = my_session.get_credentials().get_frozen_credentials()
    provider = "aws"
    
    # define the kms_providers which is later used to create the Data Key:
    kms_providers = {
        provider: {
            "accessKeyId": current_credentials.access_key,
            "secretAccessKey": current_credentials.secret_key
        }
    }
    
    # enter the kms key ARN. Replace the example ARN value.
    kms_arn = "{{arn:aws:kms:us-east-1:123456789:key/abcd-efgh-ijkl-mnop}}"
    customer_key = {
        "region": aws_region,
        "key":kms_arn
    }

    # secrets manager is used to store and retrieve user credentials for connecting to an Amazon DocumentDB cluster. 
    # retrieve the secret using the secret name. Replace the example secret key.
    secret_name = "{{/dev/secretKey}}"
    docdb_credentials = json.loads(my_session.client(service_name = 'secretsmanager', region_name = "us-east-1").get_secret_value(SecretId = secret_name)['SecretString'])

    connection_params = '/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false'
    conn_str = 'mongodb://' + docdb_credentials["username"] + ':' + docdb_credentials["password"] + '@' + docdb_credentials["host"] + ':' + str(docdb_credentials["port"]) + connection_params
    client = MongoClient(conn_str) 

    coll = client.test.coll
    coll.drop()
    
    # store the encryption data keys in a key vault collection (having naming convention as db.collection):
    key_vault_namespace = "encryption.dataKeys"
    key_vault_db_name, key_vault_coll_name = key_vault_namespace.split(".", 1)

    # set up the key vault (key_vault_namespace) for this example:
    key_vault = client[key_vault_db_name][key_vault_coll_name]
    key_vault.drop()
    key_vault.create_index("keyAltNames", unique=True)

    client_encryption = ClientEncryption(
        kms_providers,
        key_vault_namespace,
        client,
        coll.codec_options)
    
    # create a new data key for the encrypted field:
    data_key_id = client_encryption.create_data_key(provider, master_key=customer_key, key_alt_names=["some_key_alt_name"], key_material = None)
    
    # explicitly encrypt a field:
    encrypted_first_name = client_encryption.encrypt(
    "Jane",
    Algorithm.AEAD_AES_256_CBC_HMAC_SHA_512_Deterministic,
    key_id=data_key_id
    )
    coll.insert_one(
    {"gamerTag": "jane_doe90",
    "firstName": encrypted_first_name
    })
    doc = coll.find_one()
    print('Encrypted document: %s' % (doc,))
    
    # explicitly decrypt the field:
    doc["firstName"] = client_encryption.decrypt(doc["firstName"])
    print('Decrypted document: %s' % (doc,))
    
    # cleanup resources:
    client_encryption.close()
    client.close()
    
if __name__ == "__main__":
    main()
```

## Consulta no FLE do lado do cliente
<a name="fle-querying"></a>

O Amazon DocumentDB só oferece suporte a consultas de igualdade com valores criptografados de FLE do lado do cliente.

Por exemplo, para consultar documentos em que a pontuação do jogador criptografada é igual a 500, o cliente usa um método de criptografia explícito para criptografar o valor da consulta:

```
encrypted_gamerscore_filter = client_encryption.encrypt(
    500,
    Algorithm.AEAD_AES_256_CBC_HMAC_SHA_512_Deterministic,
    key_id=data_key_id
)

coll.find( {
    "gamerscore" : { "$eq" : encrypted_gamerscore_filter }
} )
```