翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# Python 用 DynamoDB 暗号化クライアントのサンプルコード
**注記**
クライアント側の暗号化ライブラリの名前が [AWS Database Encryption SDK](DDBEC-rename.md) に変更されました。次のトピックには、DynamoDB Encryption Client for Java のバージョン 1.x～2.x および DynamoDB Encryption Client for Python のバージョン 1.x～3.x に関する情報が記載されています。詳細については、「[AWS Database Encryption SDK for DynamoDB バージョンのサポート](legacy-dynamodb-encryption-client.md#legacy-support)」を参照してください。
以下の例では、Python 用 DynamoDB 暗号化クライアントを使用して、アプリケーションの DynamoDB データを保護する方法について説明します。GitHub の [aws-dynamodb-encryption-python](https://github.com/aws/aws-dynamodb-encryption-python/) リポジトリの [examples](https://github.com/aws/aws-dynamodb-encryption-python/tree/master/examples) ディレクトリに、その他の例 (および独自の使用に役立つ例) があります。
**Topics**
+ [EncryptedTable クライアントヘルパークラスを使用する](#python-example-table)
+ [項目エンクリプタを使用する](#python-example-item-encryptor)
## EncryptedTable クライアントヘルパークラスを使用する
以下の例は、`EncryptedTable` [クライアントヘルパークラス](python-using.md#python-helpers)で [Direct KMS プロバイダー](direct-kms-provider.md)を使用する方法を示しています。この例では、次の [項目エンクリプタを使用する](#python-example-item-encryptor) の例と同じ[暗号化マテリアルプロバイダー](DDBEC-legacy-concepts.md#concept-material-provider)を使用しています。ただし、低レベルの[項目エンクリプタ](DDBEC-legacy-concepts.md#item-encryptor)と直接やり取りするのではなく、`EncryptedTable` クラスを使用します。
これらの例を比較することで、クライアントのヘルパークラスが行う作業を確認できます。この処理では、[DynamoDB 暗号化コンテキスト](concepts.md#encryption-context)を作成します。また、プライマリキー属性が常に署名されているが暗号化されていないことを確認します。暗号化コンテキストを作成し、プライマリキーを検出するには、クライアントのヘルパークラスで DynamoDB [DescribeTable](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DescribeTable.html) オペレーションを呼び出します。このコードを実行するには、このオペレーションを呼び出すアクセス許可が必要です。
**完全なコードサンプルの参照**: [aws\$1kms\$1encrypted\$1table.py](https://github.com/aws/aws-dynamodb-encryption-python/blob/master/examples/src/dynamodb_encryption_sdk_examples/aws_kms_encrypted_table.py)
ステップ 1: テーブルを作成する
開始するには、テーブル名を指定して、標準の DynamoDB テーブルのインスタンスを作成します。
```
table_name='test-table'
table = boto3.resource('dynamodb').Table(table_name)
```
ステップ 2: 暗号化マテリアルプロバイダーを作成する
選択した[暗号化マテリアルプロバイダー](crypto-materials-providers.md) (CMP) のインスタンスを作成します。
この例では、[Direct KMS プロバイダー](direct-kms-provider.md)を使用していますが、互換性のある CMP を使用することもできます。Direct KMS プロバイダーを作成するには、[AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys) を指定します。この例では、 の Amazon リソースネーム (ARN) を使用しますが AWS KMS key、任意の有効なキー識別子を使用できます。
```
kms_key_id='arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
kms_cmp = AwsKmsCryptographicMaterialsProvider(key_id=kms_key_id)
```
ステップ 3: 属性アクションオブジェクトを作成する
[属性アクション](DDBEC-legacy-concepts.md#legacy-attribute-actions)は、項目の各属性に対して実行するアクションを項目エンクリプタに指示します。この例の `AttributeActions` オブジェクトは、無視される `test` 属性を除くすべての項目を暗号化し、署名します。
クライアントのヘルパークラスを使用する場合は、プライマリキー属性の属性アクションを指定しないでください。`EncryptedTable` クラスでは、プライマリキー属性に署名しますが、暗号化しません。
```
actions = AttributeActions(
default_action=CryptoAction.ENCRYPT_AND_SIGN,
attribute_actions={'test': CryptoAction.DO_NOTHING}
)
```
ステップ 4: 暗号化されたテーブルを作成する
標準テーブル、Direct KMS プロバイダー、属性アクションを使用して、暗号化されたテーブルを作成します。このステップで設定を完了します。
```
encrypted_table = EncryptedTable(
table=table,
materials_provider=kms_cmp,
attribute_actions=actions
)
```
ステップ 5: テーブルにプレーンテキスト項目を入力する
`encrypted_table` で `put_item` メソッドを呼び出すと、テーブル項目は透過的に暗号化されて署名された後、DynamoDB テーブルに追加されます。
まず、テーブル項目を定義します。
```
plaintext_item = {
'partition_attribute': 'value1',
'sort_attribute': 55
'example': 'data',
'numbers': 99,
'binary': Binary(b'\x00\x01\x02'),
'test': 'test-value'
}
```
次に、テーブルにデータを入力します。
```
encrypted_table.put_item(Item=plaintext_item)
```
DynamoDB テーブルから暗号化形式で項目を取得するには、`table` オブジェクトに対して `get_item` メソッドを呼び出します。復号された項目を取得するには、`get_item` オブジェクトの `encrypted_table` メソッドを呼び出します。
## 項目エンクリプタを使用する
この例は、テーブル項目を暗号化するときに、項目エンクリプタと自動的にやり取りする[クライアントヘルパークラス](DDBEC-legacy-concepts.md#item-encryptor)を使用する代わりに、DynamoDB 暗号化クライアントで[項目エンクリプタ](python-using.md#python-helpers)と直接やり取りする方法を示しています。
この方法を使用するときは、DynamoDB 暗号化コンテキストと設定オブジェクト (`CryptoConfig`) を手動で作成します。また、1 つの呼び出しで項目を暗号化し、別の呼び出しで DynamoDB テーブルにその項目を入力します。これにより、`put_item` 呼び出しのカスタマイズや、DynamoDB 暗号化クライアントを使用した構造化データの暗号化および署名を行うことができます。このデータが DynamoDB に送信されることはありません。
この例では、[Direct KMS プロバイダー](direct-kms-provider.md)を使用していますが、互換性のある CMP を使用することもできます。
**完全なコードサンプルの参照**: [aws\$1kms\$1encrypted\$1item.py](https://github.com/aws/aws-dynamodb-encryption-python/blob/master/examples/src/dynamodb_encryption_sdk_examples/aws_kms_encrypted_item.py)
ステップ 1: テーブルを作成する
開始するには、テーブル名を指定して、標準の DynamoDB テーブルリソースのインスタンスを作成します。
```
table_name='test-table'
table = boto3.resource('dynamodb').Table(table_name)
```
ステップ 2: 暗号化マテリアルプロバイダーを作成する
選択した[暗号化マテリアルプロバイダー](crypto-materials-providers.md) (CMP) のインスタンスを作成します。
この例では、[Direct KMS プロバイダー](direct-kms-provider.md)を使用していますが、互換性のある CMP を使用することもできます。Direct KMS プロバイダーを作成するには、[AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys) を指定します。この例では、 の Amazon リソースネーム (ARN) を使用しますが AWS KMS key、任意の有効なキー識別子を使用できます。
```
kms_key_id='arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
kms_cmp = AwsKmsCryptographicMaterialsProvider(key_id=kms_key_id)
```
ステップ 3: TableInfo ヘルパークラスを使用する
DynamoDB からテーブルに関する情報を取得するには、[TableInfo](python-using.md#python-helpers) ヘルパークラスのインスタンスを作成します。項目エンクリプタで直接操作する場合は、`TableInfo` インスタンスを作成してそのメソッドを呼び出す必要があります。[クライアントのヘルパークラス](python-using.md#python-helpers)を使用してこの操作を行うことができます。
`TableInfo` の `refresh_indexed_attributes` メソッドでは、[DescribeTable](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DescribeTable.html) DynamoDB オペレーションを使用して、テーブルに関するリアルタイムで正確な情報を取得します。この情報には、プライマリキーと、ローカルおよびグローバルセカンダリインデックスが含まれます。`DescribeTable` を呼び出すアクセス許可が発信者に必要です。
```
table_info = TableInfo(name=table_name)
table_info.refresh_indexed_attributes(table.meta.client)
```
ステップ 4: DynamoDB 暗号化コンテキストを作成する
[DynamoDB 暗号化コンテキスト](concepts.md#encryption-context)には、テーブル構造に関する情報と、暗号化および署名の方法が含まれます。この例では、項目エンクリプタとやり取りするため、DynamoDB 暗号化コンテキストを明示的に作成します。[クライアントのヘルパークラス](python-using.md#python-helpers)では、DynamoDB 暗号化コンテキストが作成されます。
パーティションキーおよびソートキーを取得するには、[TableInfo](python-using.md#python-helpers) ヘルパークラスのプロパティを使用できます。
```
index_key = {
'partition_attribute': 'value1',
'sort_attribute': 55
}
encryption_context = EncryptionContext(
table_name=table_name,
partition_key_name=table_info.primary_index.partition,
sort_key_name=table_info.primary_index.sort,
attributes=dict_to_ddb(index_key)
)
```
ステップ 5: 属性アクションオブジェクトを作成する
[属性アクション](DDBEC-legacy-concepts.md#legacy-attribute-actions)は、項目の各属性に対して実行するアクションを項目エンクリプタに指示します。この例の `AttributeActions` オブジェクトは、署名されているが暗号されていないプライマリキー属性と、無視される `test` 属性を除き、すべての項目を暗号化し、署名します。
項目エンクリプタを使用して直接やり取りし、デフォルトアクションが `ENCRYPT_AND_SIGN` の場合、プライマリキーの代替アクションを指定する必要があります。`set_index_keys` メソッドを使用できます。このメソッドでは、プライマリキーに `SIGN_ONLY`、デフォルトアクションの場合には `DO_NOTHING` が使用されます。
プライマリキーを指定するために、この例では、[TableInfo](python-using.md#python-helpers) オブジェクトのインデックスキーを使用します。これは、DynamoDB への呼び出しによって指定されます。この技術は、ハードコーディングのプライマリキー名より安全です。
```
actions = AttributeActions(
default_action=CryptoAction.ENCRYPT_AND_SIGN,
attribute_actions={'test': CryptoAction.DO_NOTHING}
)
actions.set_index_keys(*table_info.protected_index_keys())
```
ステップ 6: 項目の設定を作成する
DynamoDB 暗号化クライアントを設定するには、テーブル項目の [CryptoConfig](https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/lib/encrypted/config.html) 設定で先ほど作成したオブジェクトを使用します。クライアントのヘルパークラスでは、CryptoConfig が作成されます。
```
crypto_config = CryptoConfig(
materials_provider=kms_cmp,
encryption_context=encryption_context,
attribute_actions=actions
)
```
ステップ 7: 項目を暗号化する
このステップでは、項目を暗号化および署名しますが、DynamoDB テーブルには入力されません。
クライアントのヘルパークラスを使用するときに、項目は透過的に暗号化されて署名され、その後、ヘルパークラスの `put_item` メソッドを呼び出すときに、DynamoDB テーブルに追加されます。項目エンクリプタを直接使用する場合、暗号化および入力アクションは独立しています。
まず、プレーンテキスト項目を作成します。
```
plaintext_item = {
'partition_attribute': 'value1',
'sort_key': 55,
'example': 'data',
'numbers': 99,
'binary': Binary(b'\x00\x01\x02'),
'test': 'test-value'
}
```
次に、その項目を暗号化して署名します。`encrypt_python_item` メソッドでは、`CryptoConfig` 設定オブジェクトが必要です。
```
encrypted_item = encrypt_python_item(plaintext_item, crypto_config)
```
ステップ 8: テーブルに項目を入力する
このステップでは、暗号化された署名済みの項目を DynamoDB テーブルに入力します。
```
table.put_item(Item=encrypted_item)
```
暗号化された項目を表示するには、元の `get_item` オブジェクトの `table` メソッドを呼び出します。`encrypted_table` オブジェクトではありません。これにより、検証および復号せずに、DynamoDB テーブルより項目を取得することができます。
```
encrypted_item = table.get_item(Key=partition_key)['Item']
```
次の画像は、暗号化された署名済みのテーブル項目の例の一部を示します。
暗号化された属性値は、バイナリデータです。プライマリキー属性の名前および値 (`partition_attribute` および `sort_attribute`) と、`test` 属性は、プレーンテキスト形式のままです。また、この出力は、署名を含む属性 (`*amzn-ddb-map-sig*`) と[マテリアル説明属性](DDBEC-legacy-concepts.md#legacy-material-description) (`*amzn-ddb-map-desc*`) を示します。
![\[暗号化されて署名された項目の抜粋\]](http://docs.aws.amazon.com/ja_jp/database-encryption-sdk/latest/devguide/images/encrypted-item-closeup.png)