本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 客户端字段级加密
<a name="field-level-encryption"></a>

Amazon DocumentDB 客户端字段级加密 (FLE) 允许您在客户端应用程序中的敏感数据传输到 Amazon DocumentDB 集群之前对其进行加密。敏感数据在集群中存储和处理时保持加密状态，检索时在客户端应用程序中解密。

**Topics**
+ [入门](#fle-getting-started)
+ [在客户端文件中查询](#fle-querying)
+ [限制](#fle-limitationa)

## 入门
<a name="fle-getting-started"></a>

Amazon DocumentDB 中客户端 FLE 的初始配置分为四个步骤，包括创建加密密钥、将角色与应用程序关联、配置应用程序以及使用加密选项定义 CRUD 操作。

**Topics**
+ [步骤 1：创建加密密钥](#fle-step-create-key)
+ [步骤 2：将角色与应用程序关联](#fle-step-associate-role)
+ [步骤 3：配置应用程序](#fle-step-config-app)
+ [步骤 4：定义 CRUD 操作](#fle-step-crud-ops)
+ [示例：客户端字段级加密配置文件](#fle-config-example)

### 步骤 1：创建加密密钥
<a name="fle-step-create-key"></a>

使用 AWS Key Management Service，创建用于加密和解密敏感数据字段的对称密钥，并为其提供必要的 IAM 使用权限。AWS KMS 存储用于加密数据密钥 (DK) 的客户密钥 (CK)。我们建议将客户密钥存储在 KMS 中，以加强安全防护。数据密钥是存储在 Amazon DocumentDB 集合中的辅助密钥，在将文档存储到 Amazon DocumentDB 之前，需要使用数据密钥对敏感字段进行加密。客户密钥对数据密钥进行加密，而数据密钥反过来会加密和解密您的数据。如果使用的是全局集群，则可以创建一个多区域密钥，供不同区域的不同服务角色使用。

有关 AWS Key Management Service（包括如何创建密钥）的更多信息，请参阅 [AWS 密钥管理服务开发人员指南](https://docs.aws.amazon.com/kms/latest/developerguide/overview.html)。

### 步骤 2：将角色与应用程序关联
<a name="fle-step-associate-role"></a>

使用适当的 AWS KMS 权限创建 IAM policy。此策略允许附加到其上的 IAM 身份获取加密和解密资源字段中指定的 KMS 密钥。您的应用程序假定使用此 IAM 角色与 AWS KMS 进行身份验证。

策略应如下所示：

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

### 步骤 3：配置应用程序
<a name="fle-step-config-app"></a>

现在，您在 AWS KMS 中定义了客户密钥并创建了一个 IAM 角色，并为其提供了访问客户密钥的正确 IAM 权限。导入必需的程序包。

```
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. 指定“aws”作为 KMS 提供商类型，然后输入在上一步中检索到的账户证书。

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

1. 指定用于加密数据密钥的客户密钥：

   ```
   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. 配置 MongoClient 对象：

   ```
   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. 生成您的数据密钥：

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

1. 检索现有的数据密钥：

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

### 步骤 4：定义 CRUD 操作
<a name="fle-step-crud-ops"></a>

使用加密选项定义 CRUD 操作。

1. 定义集合以写入/读取/删除单个文档：

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

1. 显式加密 - 加密字段并插入：
**注意**  
必须只提供“key\$1id”或“key\$1alt\$1name”中的一个。

   ```
   encrypted_first_name = client_encryption.encrypt(
       "Jane",
       Algorithm.AEAD_AES_256_CBC_HMAC_SHA_512_Deterministic,
       key_alt_name=data_key_id
   )
   encrypted_last_name = client_encryption.encrypt(
       "Doe",
       Algorithm.AEAD_AES_256_CBC_HMAC_SHA_512_Deterministic,
       key_alt_name=data_key_id
   )
   encrypted_dob = client_encryption.encrypt(
       "1990-01-01",
       Algorithm.AEAD_AES_256_CBC_HMAC_SHA_512_Random,
       key_alt_name=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"]
   })
   ```

### 示例：客户端字段级加密配置文件
<a name="fle-config-example"></a>

在以下示例中，将每个*用户输入占位符*替换为您自己的信息。

```
# 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 strore 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["encryptedField"] = client_encryption.decrypt(doc["encryptedField"])
    print('Decrypted document: %s' % (doc,))
    
    # cleanup resources:
    client_encryption.close()
    client.close()
    
    if __name__ == "__main__":
        main()
```

## 在客户端文件中查询
<a name="fle-querying"></a>

Amazon DocumentDB 支持使用客户端 FLE 进行点相等查询。不相等和比较查询可能会返回不准确的结果。与对解密后的值发出相同的操作相比，读取和写入操作可能会出现意外或不正确的行为。

例如，要查询玩家分数大于 500 的文档筛选条件，请执行以下操作：

```
db.users.find( {
    "gamerscore" : { $gt : 500 }
})
```

客户端使用显式加密方法对查询值进行加密：

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

db.users.find( {
    "gamerscore" : { $gt : encrypted_gamerscore_filter }
} )
```

在查找操作中，Amazon DocumentDB 使用大于不相等校验将加密值 500 与存储在每个文档中的加密字段值进行比较。使用解密后的数据和值执行查找操作中的不相等校验可能会返回不同的结果，即使该操作成功生成了结果。

## 限制
<a name="fle-limitationa"></a>

以下限制适用于 Amazon DocumentDB 客户端字段级加密：
+ Amazon DocumentDB 仅支持点相等查询。不相等和比较查询可能会返回不准确的结果。与对解密后的值发出相同的操作相比，读取和写入操作可能会出现意外或不正确的行为。查询玩家分数大于 500 的文档过滤器。

  ```
  db.users.find( {
      "gamerscore" : { $gt : 500 }
      })
  ```

  客户端使用显式加密方法对查询值进行加密。

  ```
  encrypted_gamerscore_filter = client_encryption.encrypt(
      500,
      Algorithm.AEAD_AES_256_CBC_HMAC_SHA_512_Deterministic,
      key_alt_name=data_key_id
  )
  
  db.users.find({
      "gamerscore" : { $gt : encrypted_gamerscore_filter }
  })
  ```

  在查找操作中，Amazon DocumentDB 使用大于不相等校验将加密值 500 与存储在每个文档中的加密字段值进行比较。使用解密后的数据和值执行查找操作中的不相等校验可能会返回不同的结果，即使该操作成功生成了结果。
+ Amazon DocumentDB 不支持来自 Mongo Shell 的显式客户端 FLE。但是，该功能适用于我们支持的任何驱动程序。