在 DynamoDB 中可搜尋的加密 - AWS 資料庫加密 SDK
使用信標設定次要索引測試信標輸出

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

在 DynamoDB 中可搜尋的加密

若要將 Amazon DynamoDB 表格設定為可搜尋的加密，您必須使用AWS KMS 階層式金鑰圈來產生、加密和解密用於保護項目的資料金鑰。您還必須SearchConfig在表格加密配置中包含。

注意

如果您使用 DynamoDB 的 Java 用戶端加密程式庫，則必須使用適用於 DynamoDB API 的低階 AWS 資料庫加密開發套件來加密、簽署、驗證和解密資料表項目。DynamoDB 增強型用戶端和較低層級DynamoDBItemEncryptor不支援可搜尋的加密。

使用信標設定次要索引

設定信標之後，您必須先設定反映每個信標的次要索引，才能搜尋加密的屬性。

當您設定標準或複合信標時，Datab AWS ase Encryption SDK 會將前置aws_dbe_b_詞新增至信標名稱，以便伺服器可以輕鬆識別信標。例如，如果您命名複合信標compoundBeacon，則實際上是完整的信標名稱aws_dbe_b_compoundBeacon。如果要設定包含標準或複合信標的次要索引，識別信標名aws_dbe_b_稱時必須包含前置詞。

分割和排序索引鍵

您無法加密主索引鍵值。您的分區和排序鍵必須簽名。您的主鍵值不能是標準或複合信標。

您的主鍵值必須是SIGN_ONLY，除非您指定任何SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT屬性，否則分區和排序屬性也必須是SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT。

您的主鍵值可以是簽名的信標。如果您為每個主索引鍵值設定不同的簽署信標，則必須指定可將主索引鍵值識別為已簽署信標名稱的屬性名稱。不過， AWS 資料庫加密 SDK 不會將aws_dbe_b_前置詞新增至已簽署的信標。即使您為主索引鍵值設定了不同的已簽署信標，在設定次要索引時，只需指定主索引鍵值的屬性名稱。

本機次要索引

本機次要索引的排序索引鍵可以是信標。

如果您指定排序索引鍵的信標，類型必須是「字串」。如果您為排序索引鍵指定標準或複合信標，則必須在指定信標名aws_dbe_b_稱時加入前置碼。如果您指定已簽署的信標，請指定不含任何前置碼的信標名稱。

全域次要索引

全域次要索引的分割區和排序索引鍵都可以是信標。

如果您指定分割區或排序索引鍵的信標，類型必須是「字串」。如果您為排序索引鍵指定標準或複合信標，則必須在指定信標名aws_dbe_b_稱時加入前置碼。如果您指定已簽署的信標，請指定不含任何前置碼的信標名稱。

屬性投影

投影是指從資料表複製到次要索引的屬性集合。資料表的分割區索引鍵和排序索引鍵一律會投影到索引中；您可以投影其他屬性來支援應用程式的查詢需求。DynamoDB 針對屬性投影提供了三種不同的選項：KEYS_ONLY、INCLUDE和。ALL

如果您使用 INCLUDE 屬性投影來搜尋信標，則必須指定建構信標之所有屬性的名稱，以及含有aws_dbe_b_前置碼的信標名稱。例如，如果您設定了複合信標compoundBeacon，則來自field1field2field3、和，則必須在投影field3中指定aws_dbe_b_compoundBeaconfield1field2、和。

全域次要索引只能使用在投影中明確指定的屬性，但本機次要索引可以使用任何屬性。

測試信標輸出

如果您設定了複合信標或使用虛擬欄位建構信標，建議您在填入 DynamoDB 表之前先確認這些信標是否產生預期的輸出。

資 AWS 料庫加密 SDK 提供的DynamoDbEncryptionTransforms服務可協助您疑難排解虛擬欄位和複合信標輸出。

下列程式碼片段會建立測試項目、使用 DynamoDB 表格加密組態定義DynamoDbEncryptionTransforms服務，並示範如何使用ResolveAttributes來驗證虛擬欄位是否產生預期的輸出。

Java

請參閱完整的代碼示例：VirtualBeaconSearchableEncryptionExample.java 

// Create test items
final PutItemRequest itemWithHasTestResultPutRequest = PutItemRequest.builder()
    .tableName(ddbTableName)
    .item(itemWithHasTestResult)
    .build();

final PutItemResponse itemWithHasTestResultPutResponse = ddb.putItem(itemWithHasTestResultPutRequest);

final PutItemRequest itemWithNoHasTestResultPutRequest = PutItemRequest.builder()
    .tableName(ddbTableName)
    .item(itemWithNoHasTestResult)
    .build();
    
final PutItemResponse itemWithNoHasTestResultPutResponse = ddb.putItem(itemWithNoHasTestResultPutRequest);    

// Define the DynamoDbEncryptionTransforms service
final DynamoDbEncryptionTransforms trans = DynamoDbEncryptionTransforms.builder()
    .DynamoDbTablesEncryptionConfig(encryptionConfig).build();

// Verify configuration
final ResolveAttributesInput resolveInput = ResolveAttributesInput.builder()
    .TableName(ddbTableName)
    .Item(itemWithHasTestResult)
    .Version(1)
    .build();
final ResolveAttributesOutput resolveOutput = trans.ResolveAttributes(resolveInput);

// Verify that VirtualFields has the expected value
Map<String, String> vf = new HashMap<>();
vf.put("stateAndHasTestResult", "CAt");
assert resolveOutput.VirtualFields().equals(vf);
C# / .NET

請參閱完整的程式碼範例：VirtualBeaconSearchableEncryptionExample.cs

 // Create item with hasTestResult=true
var itemWithHasTestResult = new Dictionary<String, AttributeValue>
{
    ["customer_id"] = new AttributeValue("ABC-123"),
    ["create_time"] = new AttributeValue { N = "1681495205" },
    ["state"] = new AttributeValue("CA"),
    ["hasTestResult"] = new AttributeValue { BOOL = true }
};

// Create item with hasTestResult=false
var itemWithNoHasTestResult = new Dictionary<String, AttributeValue>
{
    ["customer_id"] = new AttributeValue("DEF-456"),
    ["create_time"] = new AttributeValue { N = "1681495205" },
    ["state"] = new AttributeValue("CA"),
    ["hasTestResult"] = new AttributeValue { BOOL = false }
};

// Define the DynamoDbEncryptionTransforms service
var trans = new DynamoDbEncryptionTransforms(encryptionConfig);

// Verify configuration
var resolveInput = new ResolveAttributesInput
{
    TableName = ddbTableName,
    Item = itemWithHasTestResult,
    Version = 1
};
var resolveOutput = trans.ResolveAttributes(resolveInput);

// Verify that VirtualFields has the expected value
Debug.Assert(resolveOutput.VirtualFields.Count == 1);
Debug.Assert(resolveOutput.VirtualFields["stateAndHasTestResult"] == "CAt");

下列程式碼片段會建立測試項目、使用 DynamoDB 表格加密組態定義DynamoDbEncryptionTransforms服務，並示範如何使用ResolveAttributes來驗證複合信標是否產生預期的輸出。

Java

請參閱完整的代碼示例：CompoundBeaconSearchableEncryptionExample.java 

// Create an item with both attributes used in the compound beacon.
final HashMap<String, AttributeValue> item = new HashMap<>();
item.put("work_id", AttributeValue.builder().s("9ce39272-8068-4efd-a211-cd162ad65d4c").build());
item.put("inspection_date", AttributeValue.builder().s("2023-06-13").build());
item.put("inspector_id_last4", AttributeValue.builder().s("5678").build());
item.put("unit", AttributeValue.builder().s("011899988199").build());
                            
// Define the DynamoDbEncryptionTransforms service
final DynamoDbEncryptionTransforms trans = DynamoDbEncryptionTransforms.builder()
    .DynamoDbTablesEncryptionConfig(encryptionConfig).build();

// Verify configuration 
final ResolveAttributesInput resolveInput = ResolveAttributesInput.builder()
    .TableName(ddbTableName)
    .Item(item)
    .Version(1)
    .build();

final ResolveAttributesOutput resolveOutput = trans.ResolveAttributes(resolveInput);
                            
// Verify that CompoundBeacons has the expected value   
Map<String, String> cbs = new HashMap<>();
cbs.put("last4UnitCompound", "L-5678.U-011899988199");
assert resolveOutput.CompoundBeacons().equals(cbs);
// Note : the compound beacon actually stored in the table is not "L-5678.U-011899988199"
// but rather something like "L-abc.U-123", as both parts are EncryptedParts
// and therefore the text is replaced by the associated beacon
C# / .NET

請參閱完整的程式碼範例：CompoundBeaconSearchableEncryptionExample.cs

// Create an item with both attributes used in the compound beacon
var item = new Dictionary<String, AttributeValue>
{
    ["work_id"] = new AttributeValue("9ce39272-8068-4efd-a211-cd162ad65d4c"),
    ["inspection_date"] = new AttributeValue("2023-06-13"),
    ["inspector_id_last4"] = new AttributeValue("5678"),
    ["unit"] = new AttributeValue("011899988199")
};                           
                            
// Define the DynamoDbEncryptionTransforms service
var trans = new DynamoDbEncryptionTransforms(encryptionConfig);

// Verify configuration
var resolveInput = new ResolveAttributesInput
{
    TableName = ddbTableName,
    Item = item,
    Version = 1
};
var resolveOutput = trans.ResolveAttributes(resolveInput);                            
                            
// Verify that CompoundBeacons has the expected value 
Debug.Assert(resolveOutput.CompoundBeacons.Count == 1);
Debug.Assert(resolveOutput.CompoundBeacons["last4UnitCompound"] == "L-5678.U-011899988199");
// Note : the compound beacon actually stored in the table is not "L-5678.U-011899988199"
// but rather something like "L-abc.U-123", as both parts are EncryptedParts
// and therefore the text is replaced by the associated beacon