使用 DynamoDB 增強型用戶端使用低階 DynamoDB API 使用較低層級的 DynamoDbItemEncryptor

Java 範例

我們的用戶端加密程式庫已重新命名為 AWS 資料庫加密 SDK。此開發人員指南仍提供有關 DynamoDB 加密用戶端的資訊。

下列範例示範如何使用適用於 DynamoDB 的 Java 用戶端加密程式庫來保護應用程式中的資料表項目。您可以在 GitHub 的 aws-database-encryption-sdk-dynamodb 儲存庫的 Java 範例中找到更多範例（並自行提供）。

下列範例示範如何在未填入的新 Amazon DynamoDB 資料表中設定 DynamoDB 的 Java 用戶端加密程式庫。如果您想要設定現有的 Amazon DynamoDB 資料表進行用戶端加密，請參閱將 4.x 版新增至現有資料表。

使用 DynamoDB 增強型用戶端

下列範例示範如何使用 DynamoDB 增強型用戶端和 DynamoDbEncryptionInterceptor搭配 AWS KMS keyring 來加密 DynamoDB 資料表項目，做為 DynamoDB API 呼叫的一部分。

您可以搭配 DynamoDB 增強型用戶端使用任何支援的 keyring，但我們建議您盡可能使用其中一個 AWS KMS keyring。

注意

DynamoDB 增強型用戶端不支援可搜尋加密。使用 DynamoDbEncryptionInterceptor搭配低階 DynamoDB API，以使用可搜尋的加密。

請參閱完整的程式碼範例：EnhancedPutGetExample.java

步驟 1：建立 AWS KMS keyring

下列範例使用 CreateAwsKmsMrkMultiKeyring建立具有對稱加密 KMS 金鑰的 AWS KMS keyring。CreateAwsKmsMrkMultiKeyring 方法可確保 keyring 可正確處理單一區域和多區域金鑰。


final MaterialProviders matProv = MaterialProviders.builder()
        .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
        .build();
final CreateAwsKmsMrkMultiKeyringInput keyringInput = CreateAwsKmsMrkMultiKeyringInput.builder()
        .generator(kmsKeyId)
        .build();
final IKeyring kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput);

步驟 2：從註釋的資料類別建立資料表結構描述

下列範例使用註釋的資料類別來建立 TableSchema。

此範例假設已使用 SimpleClass.java 定義註釋的資料類別和屬性動作。如需註釋屬性動作的更多指引，請參閱使用標註的資料類別。

注意

AWS Database Encryption SDK 不支援巢狀屬性上的註釋。


final TableSchema<SimpleClass> schemaOnEncrypt = TableSchema.fromBean(SimpleClass.class);

步驟 3：定義從簽章中排除哪些屬性

下列範例假設所有DO_NOTHING屬性共用不同的字首「:」，並使用字首定義允許的未簽章屬性。用戶端假設任何具有「:」字首的屬性名稱都會從簽章中排除。如需詳細資訊，請參閱Allowed unsigned attributes。


final String unsignedAttrPrefix = ":";

步驟 4：建立加密組態

下列範例定義代表 DynamoDB 資料表加密組態的tableConfigs映射。

此範例指定 DynamoDB 資料表名稱做為邏輯資料表名稱。當您第一次定義加密組態時，強烈建議指定您的 DynamoDB 資料表名稱做為邏輯資料表名稱。如需詳細資訊，請參閱DynamoDB AWS 資料庫加密 SDK 中的加密組態。

注意

若要使用可搜尋加密或已簽章的信標，您還必須在加密組態SearchConfig中包含。


final Map<String, DynamoDbEnhancedTableEncryptionConfig> tableConfigs = new HashMap<>();
tableConfigs.put(ddbTableName,
    DynamoDbEnhancedTableEncryptionConfig.builder()
        .logicalTableName(ddbTableName)
        .keyring(kmsKeyring)
        .allowedUnsignedAttributePrefix(unsignedAttrPrefix)
        .schemaOnEncrypt(tableSchema)
        .build());

步驟 5：建立 DynamoDbEncryptionInterceptor

下列範例會使用步驟 4 DynamoDbEncryptionInterceptortableConfigs中的建立新的。


final DynamoDbEncryptionInterceptor interceptor =
    DynamoDbEnhancedClientEncryption.CreateDynamoDbEncryptionInterceptor(
        CreateDynamoDbEncryptionInterceptorInput.builder()
            .tableEncryptionConfigs(tableConfigs)
            .build()
    );

步驟 6：建立新的 AWS SDK DynamoDB 用戶端

下列範例使用步驟 5 interceptor中的建立新的 AWS SDK DynamoDB 用戶端。


final DynamoDbClient ddb = DynamoDbClient.builder()
        .overrideConfiguration(
                ClientOverrideConfiguration.builder()
                       .addExecutionInterceptor(interceptor)
                       .build())
        .build();

步驟 7：建立 DynamoDB 增強型用戶端並建立資料表

下列範例使用步驟 6 中建立的 AWS SDK DynamoDB 用戶端建立 DynamoDB 增強型用戶端，並使用註釋的資料類別建立資料表。


final DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder()
        .dynamoDbClient(ddb)
        .build();
final DynamoDbTable<SimpleClass> table = enhancedClient.table(ddbTableName, tableSchema);

步驟 8：加密和簽署資料表項目

下列範例會使用 DynamoDB 增強型用戶端將項目放入 DynamoDB 資料表。項目在傳送至 DynamoDB 之前，會先加密並簽署用戶端。


final SimpleClass item = new SimpleClass();
item.setPartitionKey("EnhancedPutGetExample");
item.setSortKey(0);
item.setAttribute1("encrypt and sign me!");
item.setAttribute2("sign me!");
item.setAttribute3("ignore me!");

table.putItem(item);

顯示較多

顯示較少

使用低階 DynamoDB API

下列範例示範如何使用低階 DynamoDB API 搭配 AWS KMS keyring，以自動加密和簽署具有 DynamoDB PutItem請求的用戶端項目。

您可以使用任何支援的 keyring，但我們建議您盡可能使用其中一個 AWS KMS keyring。

請參閱完整的程式碼範例：BasicPutGetExample.java

步驟 1：建立 AWS KMS keyring


final MaterialProviders matProv = MaterialProviders.builder()
         .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
         .build();
final CreateAwsKmsMrkMultiKeyringInput keyringInput = CreateAwsKmsMrkMultiKeyringInput.builder()
        .generator(kmsKeyId)
        .build();
final IKeyring kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput);

步驟 2：設定屬性動作

下列範例定義代表資料表項目範例屬性動作的attributeActionsOnEncrypt映射。

注意

下列範例不會將任何屬性定義為 SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT。如果您指定任何SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT屬性，則分割區和排序屬性也必須是 SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT。


final Map<String, CryptoAction> attributeActionsOnEncrypt = new HashMap<>();
// The partition attribute must be SIGN_ONLY
attributeActionsOnEncrypt.put("partition_key", CryptoAction.SIGN_ONLY); 
// The sort attribute must be SIGN_ONLY
attributeActionsOnEncrypt.put("sort_key", CryptoAction.SIGN_ONLY); 
attributeActionsOnEncrypt.put("attribute1", CryptoAction.ENCRYPT_AND_SIGN);
attributeActionsOnEncrypt.put("attribute2", CryptoAction.SIGN_ONLY);
attributeActionsOnEncrypt.put(":attribute3", CryptoAction.DO_NOTHING);

步驟 3：定義從簽章中排除哪些屬性


final String unsignedAttrPrefix = ":";

步驟 4：定義 DynamoDB 資料表加密組態

下列範例會定義代表此 DynamoDB 資料表加密組態的tableConfigs映射。

此範例會將 DynamoDB 資料表名稱指定為邏輯資料表名稱。當您第一次定義加密組態時，強烈建議指定您的 DynamoDB 資料表名稱做為邏輯資料表名稱。如需詳細資訊，請參閱DynamoDB AWS 資料庫加密 SDK 中的加密組態。

注意

若要使用可搜尋加密或已簽章的信標，您還必須在加密組態SearchConfig中包含。


final Map<String, DynamoDbTableEncryptionConfig> tableConfigs = new HashMap<>();
final DynamoDbTableEncryptionConfig config = DynamoDbTableEncryptionConfig.builder()
        .logicalTableName(ddbTableName)
        .partitionKeyName("partition_key")
        .sortKeyName("sort_key")
        .attributeActionsOnEncrypt(attributeActionsOnEncrypt)
        .keyring(kmsKeyring)
        .allowedUnsignedAttributePrefix(unsignedAttrPrefix)
        .build();
tableConfigs.put(ddbTableName, config);

步驟 5：建立 DynamoDbEncryptionInterceptor

下列範例DynamoDbEncryptionInterceptor使用步驟 4 tableConfigs中的建立。


DynamoDbEncryptionInterceptor interceptor = DynamoDbEncryptionInterceptor.builder()
        .config(DynamoDbTablesEncryptionConfig.builder()
                .tableEncryptionConfigs(tableConfigs)
                .build())
        .build();

步驟 6：建立新的 AWS SDK DynamoDB 用戶端

下列範例使用步驟 5 interceptor中的建立新的 AWS SDK DynamoDB 用戶端。


final DynamoDbClient ddb = DynamoDbClient.builder()
        .overrideConfiguration(
                ClientOverrideConfiguration.builder()
                       .addExecutionInterceptor(interceptor)
                       .build())
        .build();

步驟 7：加密並簽署 DynamoDB 資料表項目

下列範例定義代表範例資料表項目的item映射，並將該項目放在 DynamoDB 資料表中。項目會在傳送至 DynamoDB 之前加密並簽署用戶端。


final HashMap<String, AttributeValue> item = new HashMap<>();
item.put("partition_key", AttributeValue.builder().s("BasicPutGetExample").build());
item.put("sort_key", AttributeValue.builder().n("0").build());
item.put("attribute1", AttributeValue.builder().s("encrypt and sign me!").build());
item.put("attribute2", AttributeValue.builder().s("sign me!").build());
item.put(":attribute3", AttributeValue.builder().s("ignore me!").build());

final PutItemRequest putRequest = PutItemRequest.builder()
        .tableName(ddbTableName)
        .item(item)
        .build();

final PutItemResponse putResponse = ddb.putItem(putRequest);

顯示較多

顯示較少

使用較低層級的 DynamoDbItemEncryptor

下列範例示範如何使用較低層級DynamoDbItemEncryptor的 AWS KMS keyring 來直接加密和簽署資料表項目。DynamoDbItemEncryptor 不會將項目放在 DynamoDB 資料表中。

您可以搭配 DynamoDB 增強型用戶端使用任何支援的 keyring，但我們建議您盡可能使用其中一個 AWS KMS keyring。

注意

較低層級DynamoDbItemEncryptor不支援可搜尋的加密。使用 DynamoDbEncryptionInterceptor搭配低階 DynamoDB API，以使用可搜尋的加密。

請參閱完整的程式碼範例：I ItemEncryptDecryptExample.java

步驟 1：建立 AWS KMS keyring


final MaterialProviders matProv = MaterialProviders.builder()
         .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
         .build();
final CreateAwsKmsMrkMultiKeyringInput keyringInput = CreateAwsKmsMrkMultiKeyringInput.builder()
        .generator(kmsKeyId)
        .build();
final IKeyring kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput);

步驟 2：設定屬性動作

下列範例定義代表資料表項目範例屬性動作的attributeActionsOnEncrypt映射。

注意


final Map<String, CryptoAction> attributeActionsOnEncrypt = new HashMap<>();
// The partition attribute must be SIGN_ONLY
attributeActionsOnEncrypt.put("partition_key", CryptoAction.SIGN_ONLY); 
// The sort attribute must be SIGN_ONLY
attributeActionsOnEncrypt.put("sort_key", CryptoAction.SIGN_ONLY); 
attributeActionsOnEncrypt.put("attribute1", CryptoAction.ENCRYPT_AND_SIGN);
attributeActionsOnEncrypt.put("attribute2", CryptoAction.SIGN_ONLY);
attributeActionsOnEncrypt.put(":attribute3", CryptoAction.DO_NOTHING);

步驟 3：定義從簽章中排除哪些屬性


final String unsignedAttrPrefix = ":";

步驟 4：定義DynamoDbItemEncryptor組態

下列範例定義的組態DynamoDbItemEncryptor。


final DynamoDbItemEncryptorConfig config = DynamoDbItemEncryptorConfig.builder()
        .logicalTableName(ddbTableName)
        .partitionKeyName("partition_key")
        .sortKeyName("sort_key")
        .attributeActionsOnEncrypt(attributeActionsOnEncrypt)
        .keyring(kmsKeyring)
        .allowedUnsignedAttributePrefix(unsignedAttrPrefix)
        .build();

步驟 5：建立 DynamoDbItemEncryptor

下列範例DynamoDbItemEncryptor使用步驟 4 config中的建立新的。


final DynamoDbItemEncryptor itemEncryptor = DynamoDbItemEncryptor.builder()
        .DynamoDbItemEncryptorConfig(config)
        .build();

步驟 6：直接加密和簽署資料表項目

下列範例使用直接加密和簽署項目DynamoDbItemEncryptor。DynamoDbItemEncryptor 不會將項目放在 DynamoDB 資料表中。


final Map<String, AttributeValue> originalItem = new HashMap<>();
originalItem.put("partition_key", AttributeValue.builder().s("ItemEncryptDecryptExample").build());
originalItem.put("sort_key", AttributeValue.builder().n("0").build());
originalItem.put("attribute1", AttributeValue.builder().s("encrypt and sign me!").build());
originalItem.put("attribute2", AttributeValue.builder().s("sign me!").build());
originalItem.put(":attribute3", AttributeValue.builder().s("ignore me!").build());

final Map<String, AttributeValue> encryptedItem = itemEncryptor.EncryptItem(
        EncryptItemInput.builder()
                .plaintextItem(originalItem)
                .build()
).encryptedItem();

顯示較多

顯示較少

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

使用 Java 用戶端

將 4.x 版新增至現有資料表