AWS KMS 階層式鍵控 - AWS Encryption SDK
運作方式必要條件所需的許可選擇快取建立階層式鍵控

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

AWS KMS 階層式鍵控

使用 AWS KMS 階層式金鑰控制，您可以使用對稱加密KMS金鑰來保護密碼編譯材料，而無需 AWS KMS 在每次加密或解密資料時呼叫 。對於需要將對 的呼叫降至最低的應用程式 AWS KMS，以及可以在不違反其安全要求的情況下重複使用某些密碼編譯材料的應用程式，這是很好的選擇。

階層式索引鍵是一種密碼編譯材料快取解決方案，透過使用保留在 Amazon DynamoDB 資料表中的 AWS KMS 受保護分支金鑰，以及加密和解密操作中使用的本機快取分支金鑰材料來減少 AWS KMS 呼叫次數。DynamoDB 資料表可做為管理及保護分支金鑰的金鑰存放區。它會儲存作用中分支金鑰和所有先前版本的分支金鑰。作用中分支金鑰是最新的分支金鑰版本。階層式金鑰控制使用唯一的資料金鑰來加密每個訊息，並為每個加密請求加密每個資料加密金鑰，並使用衍生自作用中分支金鑰的唯一包裝金鑰來加密每個資料加密金鑰。階層式鍵控取決於作用中分支索引鍵與其衍生包裝索引鍵之間建立的階層。

階層式鍵控通常使用每個分支鍵版本來滿足多個請求。但是，您可以控制重複使用作用中分支金鑰的程度，並決定作用中分支金鑰的輪換頻率。分支金鑰的作用中版本會保持作用中，直到您將其輪換為止。舊版的作用中分支金鑰不會用來執行加密操作，但仍可以查詢並用於解密操作。

當您實例化階層式鍵控時，它會建立本機快取。您可以指定快取限制，定義分支金鑰材料在本機快取內儲存的時間上限，以免過期並從快取中移出。當 第一次在 操作中branch-key-id指定 時，階層式鍵控會 AWS KMS 呼叫 來解密分支金鑰並組合分支金鑰材料。然後，分支金鑰材料會儲存在本機快取中，並重複使用於所有指定快取限制過期branch-key-id前的加密和解密操作。在本機快取中存放分支金鑰材料可減少 AWS KMS 呼叫。例如，請考慮 15 分鐘的快取限制。如果您在該快取限制內執行 10，000 個加密操作，傳統 AWS KMS 金鑰環將需要進行 10，000 次 AWS KMS 呼叫，以滿足 10，000 個加密操作。如果您有一個作用中的 branch-key-id，則階層式鍵控只需要呼叫一次 AWS KMS ，以滿足 10，000 個加密操作。

本機快取會將加密材料與解密材料分開。加密材料是從作用中分支金鑰組合而成，並重複使用於所有加密操作，直到快取限制過期為止。解密材料是從加密欄位中繼資料中識別的分支金鑰 ID 和版本組合而成，而且它們會重複使用於與分支金鑰 ID 和版本相關的所有解密操作，直到快取限制到期為止。本機快取一次可以存放相同分支金鑰的多個版本。當本機快取設定為使用 時branch key ID supplier，它也可以一次儲存來自多個作用中分支金鑰的分支金鑰材料。

注意

中所有提到的階層式鍵控 AWS Encryption SDK 都參考 AWS KMS 階層式鍵控。

程式設計語言相容性

下列程式設計語言和版本支援階層式鍵控：

  • 3.x 版 適用於 JAVA 的 AWS Encryption SDK

  • AWS Encryption SDK 適用於 的 4.x 版。NET

  • 與選用MPL相依性搭配使用時 適用於 Python 的 AWS Encryption SDK， 的 4.x 版。

運作方式

下列逐步解說說明階層式金鑰環如何組合加密和解密材料，以及金鑰環針對加密和解密操作所做的不同呼叫。如需包裝金鑰衍生和純文字資料金鑰加密程序的技術詳細資訊，請參閱AWS KMS 階層式金鑰觸發技術詳細資訊 。

加密和簽署

下列逐步解說說明階層式金鑰環如何組合加密材料並衍生唯一的包裝金鑰。

  1. 加密方法會要求加密材料的階層式金鑰。鍵控會產生純文字資料金鑰，然後檢查本機快取中是否有有效的分支資料來產生包裝金鑰。如果有有效的分支金鑰材料，則金鑰環會繼續進行步驟 4。

  2. 如果沒有有效的分支金鑰材料，則階層式鍵控會查詢作用中分支金鑰的金鑰存放區。

    1. 金鑰存放區會呼叫 AWS KMS 來解密作用中分支金鑰，並傳回純文字作用中分支金鑰。識別作用中分支金鑰的資料會序列化，以在解密呼叫中提供額外的已驗證資料 （AAD） 給 AWS KMS。

    2. 金鑰存放區會傳回純文字分支金鑰和可識別該金鑰的資料，例如分支金鑰版本。

  3. 階層式鍵環會組合分支金鑰材料 （純文字分支金鑰和分支金鑰版本），並將它們的副本儲存在本機快取中。

  4. 階層式鍵控從純文字分支索引鍵和 16 位元組隨機鹽中衍生出唯一的包裝索引鍵。它使用衍生的包裝金鑰來加密純文字資料金鑰的副本。

加密方法使用加密材料來加密資料。如需詳細資訊，請參閱 如何 AWS Encryption SDK 加密資料 。

顯示較多顯示較少
解密和驗證

下列逐步解說說明階層式金鑰環如何組合解密材料並解密加密的資料金鑰。

  1. 解密方法會從加密訊息中識別加密的資料金鑰，並將其傳遞至階層式金鑰。

  2. 階層式金鑰環會還原序列化識別加密資料金鑰的資料，包括分支金鑰版本、16 位元組 salt，以及描述資料金鑰如何加密的其他資訊。

    如需詳細資訊，請參閱AWS KMS 階層式鍵控技術詳細資訊。

  3. 階層式鍵控會檢查本機快取中是否有與步驟 2 中識別的分支金鑰版本相符的有效分支金鑰材料。如果有有效的分支金鑰材料，則金鑰環會繼續進行步驟 6。

  4. 如果沒有有效的分支金鑰材料，階層式鍵控會查詢符合步驟 2 中識別分支金鑰版本的分支金鑰儲存庫。

    1. 金鑰存放區會呼叫 AWS KMS 來解密分支金鑰，並傳回純文字作用中分支金鑰。識別作用中分支金鑰的資料會序列化，以在解密呼叫中提供額外的已驗證資料 （AAD） 給 AWS KMS。

    2. 金鑰存放區會傳回純文字分支金鑰和可識別該金鑰的資料，例如分支金鑰版本。

  5. 階層式鍵環會組合分支金鑰材料 （純文字分支金鑰和分支金鑰版本），並將它們的副本儲存在本機快取中。

  6. 階層式鍵控使用步驟 2 中識別的已組裝分支金鑰材料和 16 位元組鹽，來重現加密資料金鑰的唯一包裝金鑰。

  7. 階層式鍵控使用重製的包裝金鑰來解密資料金鑰並傳回純文字資料金鑰。

解密方法使用解密材料和純文字資料金鑰來解密加密的訊息。如需詳細資訊，請參閱 如何 AWS Encryption SDK 解密加密訊息 。

顯示較多顯示較少

必要條件

在建立和使用階層式金鑰環之前，請確定符合下列先決條件。

所需的許可

AWS Encryption SDK 不需要 AWS 帳戶 ，也不依賴任何 AWS 服務。不過，若要使用階層式金鑰環，您需要 AWS 帳戶 和下列對金鑰存放區中對稱加密 AWS KMS key（s） 的最低許可。

如需控制對分支金鑰和金鑰存放區之存取的詳細資訊，請參閱 實作最低權限的許可。

選擇快取

階層式鍵控 AWS KMS 可透過本機快取用於加密和解密操作的分支金鑰材料來減少對 的呼叫次數。在建立階層式金鑰環 之前，您需要決定要使用的快取類型。您可以使用預設快取或自訂快取，以符合您的需求。

階層式鍵控支援下列快取類型：

重要

所有支援的快取類型都旨在支援多執行緒環境。

不過，當 與 搭配使用時 適用於 Python 的 AWS Encryption SDK，階層式金鑰環不支援多執行緒環境。如需詳細資訊，請參閱 上的 aws-cryptographic-material-providers- 程式庫儲存庫中的 Python README.rst 檔案 GitHub。

預設快取

對於大多數使用者，預設快取滿足其執行緒需求。預設快取旨在支援大量多執行緒環境。當分支金鑰材料項目過期時，預設快取 AWS KMS 會提前 10 秒通知一個執行緒分支金鑰材料項目即將過期，以防止多個執行緒呼叫。這可確保只有一個執行緒傳送請求至 AWS KMS 以重新整理快取。

預設 和 StormTracking 快取支援相同的執行緒模型，但您只需指定使用預設快取的輸入容量即可。如需更精細的快取自訂，請使用 StormTracking 快取。

除非您想要自訂可在本機快取中儲存的分支金鑰材料項目數目，否則建立階層式鍵控時不需要指定快取類型。如果您未指定快取類型，階層式鍵控會使用預設快取類型，並將輸入容量設定為 1000。

若要自訂預設快取，請指定下列值：

  • 輸入容量：限制可在本機快取中儲存的分支金鑰材料項目數量。

Java
.cache(CacheType.builder()
        .Default(DefaultCache.builder()
        .entryCapacity(100)
        .build())
C# / .NET
CacheType defaultCache = new CacheType
{
    Default = new DefaultCache{EntryCapacity = 100}
};
Python
default_cache = CacheTypeDefault(
    value=DefaultCache(
        entry_capacity=100
    )
)

MultiThreaded 快取

MultiThreaded 快取可在多執行緒環境中安全使用，但它不提供任何功能來最小化 AWS KMS 或 Amazon DynamoDB 呼叫。因此，當分支金鑰材料項目過期時，所有執行緒都會同時收到通知。這可能會導致多個 AWS KMS 呼叫重新整理快取。

若要使用 MultiThreaded 快取，請指定下列值：

  • 輸入容量：限制可在本機快取中儲存的分支金鑰材料項目數量。

  • 項目剪除尾部大小：定義達到輸入容量時要剪除的項目數量。

Java
.cache(CacheType.builder()
        .MultiThreaded(MultiThreadedCache.builder()
        .entryCapacity(100)
        .entryPruningTailSize(1)                                        
        .build())
C# / .NET
CacheType multithreadedCache = new CacheType
{
    MultiThreaded = new MultiThreadedCache
    {
        EntryCapacity = 100,
        EntryPruningTailSize = 1
    }
};
Python
multithreaded_cache = CacheTypeMultiThreaded(
    value=MultiThreadedCache(
        entry_capacity=100,
        entry_pruning_tail_size=1
    )
)

StormTracking 快取

StormTracking 快取旨在支援大量多執行緒環境。當分支金鑰材料項目過期時，快取會 StormTracking提前 AWS KMS 通知一個執行緒分支金鑰材料項目即將過期，以防止多個執行緒呼叫。這可確保只有一個執行緒將請求傳送至 AWS KMS 以重新整理快取。

若要使用 StormTracking 快取，請指定下列值：

  • 輸入容量：限制可在本機快取中儲存的分支金鑰材料項目數量。

    預設值：1000 個項目

  • 項目剪除尾部大小：定義一次剪除的分支金鑰材料項目數目。

    預設值：1 個項目

  • 寬限期 ：定義嘗試重新整理分支金鑰材料的過期前秒數。

    預設值：10 秒

  • Grace 間隔 ：定義嘗試重新整理分支金鑰材料之間的秒數。

    預設值：1 秒

  • Fan out ：定義可同時嘗試重新整理分支金鑰材料的次數。

    預設值：20 次嘗試

  • 飛行中存留時間 （TTL）： 會定義直到嘗試重新整理分支金鑰材料逾時的秒數。每當快取傳回NoSuchEntry回應 時GetCacheEntry，該分支金鑰會被視為正在執行中，直到使用PutCache項目寫入相同的金鑰為止。

    預設值：20 秒

  • 休眠：定義如果fanOut超過 ，執行緒應休眠的秒數。

    預設值：20 毫秒

Java
.cache(CacheType.builder()
        .StormTracking(StormTrackingCache.builder()
        .entryCapacity(100)
        .entryPruningTailSize(1)
        .gracePeriod(10)
        .graceInterval(1)
        .fanOut(20) 
        .inFlightTTL(20)
        .sleepMilli(20)                                        
        .build())
C# / .NET
CacheType stormTrackingCache = new CacheType
{
    StormTracking = new StormTrackingCache
    {
        EntryCapacity = 100,
        EntryPruningTailSize = 1,
        FanOut = 20,
        GraceInterval = 1,
        GracePeriod = 10,
        InFlightTTL = 20,
        SleepMilli = 20
    }
};
Python
storm_tracking_cache = CacheTypeStormTracking(
    value=StormTrackingCache(
        entry_capacity=100,
        entry_pruning_tail_size=1,
        fan_out=20,
        grace_interval=1,
        grace_period=10,
        in_flight_ttl=20,
        sleep_milli=20
    )
)

共用快取

依預設，階層式金鑰集會在您每次實例化金鑰集時建立新的本機快取。不過，共用快取可讓您跨多個階層式金鑰環共用快取，有助於節省記憶體。共用快取不會為每個您實例化的階層式索引鍵建立新的密碼編譯材料快取，而是在記憶體中僅儲存一個快取，而所有參考該快取的階層式索引鍵都可以使用。共用快取可避免密碼編譯材料在金鑰環之間重複，有助於最佳化記憶體用量。相反地，階層式金鑰環可以存取相同的基礎快取，減少整體記憶體佔用空間。

建立共用快取時，您仍然會定義快取類型。您可以指定 預設快取、 MultiThreaded 快取或 StormTracking 快取作為快取類型，或取代任何相容的自訂快取。

資料分割

多個階層式金鑰集可以使用單一共用快取。當您使用共用快取建立階層式金鑰環時，您可以定義選用的分割區 ID 。分割區 ID 會區分要寫入快取的階層式金鑰。如果兩個階層式金鑰環參考相同的分割區 ID、 logical key store name和分支金鑰 ID，則兩個金鑰環將在快取中共用相同的快取項目。如果您建立兩個具有相同共用快取的階層式金鑰環，但分割區 不同IDs，則每個金鑰環只會存取共用快取內自有指定分割區的快取項目。分割區在共用快取中充當邏輯分割，允許每個階層鍵控在其指定的分割區上獨立運作，而不會干擾存放在另一個分割區中的資料。

如果您想要重複使用或共用分割區中的快取項目，您必須定義自己的分割區 ID。當您將分割區 ID 傳遞至階層式金鑰環時，金鑰環可以重複使用共用快取中已存在的快取項目，而不必再次擷取並重新授權分支金鑰材料。如果您未指定分割區 ID，則每次您實例化階層式鍵控時，系統都會自動將唯一的分割區 ID 指派給鍵控。

下列程序示範如何使用預設快取類型建立共用快取，並將其傳遞至階層式金鑰集。

  1. 使用材料提供者程式庫 CryptographicMaterialsCache（CMC） 建立 （MPL）。 https://github.com/aws/aws-cryptographic-material-providers-library

    Java
    // Instantiate the MPL
final MaterialProviders matProv =
    MaterialProviders.builder()
        .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
        .build();

// Create a CacheType object for the Default cache
final CacheType cache =
    CacheType.builder() 
        .Default(DefaultCache.builder().entryCapacity(100).build())
        .build();

// Create a CMC using the default cache
final CreateCryptographicMaterialsCacheInput cryptographicMaterialsCacheInput =
    CreateCryptographicMaterialsCacheInput.builder()
        .cache(cache)
        .build();

final ICryptographicMaterialsCache sharedCryptographicMaterialsCache =
    matProv.CreateCryptographicMaterialsCache(cryptographicMaterialsCacheInput);
    C# / .NET
    // Instantiate the MPL
var materialProviders = new MaterialProviders(new MaterialProvidersConfig());

// Create a CacheType object for the Default cache
var cache = new CacheType { Default = new DefaultCache{EntryCapacity = 100} };

// Create a CMC using the default cache
var cryptographicMaterialsCacheInput = new CreateCryptographicMaterialsCacheInput {Cache = cache};

var sharedCryptographicMaterialsCache = materialProviders.CreateCryptographicMaterialsCache(cryptographicMaterialsCacheInput);
    Python
    # Instantiate the MPL
mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
    config=MaterialProvidersConfig()
)

# Create a CacheType object for the default cache
cache: CacheType = CacheTypeDefault(
    value=DefaultCache(
        entry_capacity=100,
    )
)

# Create a CMC using the default cache
cryptographic_materials_cache_input = CreateCryptographicMaterialsCacheInput(
    cache=cache,
)

shared_cryptographic_materials_cache = mat_prov.create_cryptographic_materials_cache(
    cryptographic_materials_cache_input
)

  2. 為共用快取建立CacheType物件。

    將sharedCryptographicMaterialsCache您在步驟 1 中建立的 傳遞至新CacheType物件。

    Java
    // Create a CacheType object for the sharedCryptographicMaterialsCache
final CacheType sharedCache =
    CacheType.builder()
        .Shared(sharedCryptographicMaterialsCache)
        .build();
    C# / .NET
    // Create a CacheType object for the sharedCryptographicMaterialsCache
var sharedCache = new CacheType { Shared = sharedCryptographicMaterialsCache };
    Python
    # Create a CacheType object for the shared_cryptographic_materials_cache
shared_cache: CacheType = CacheTypeShared(
    value=shared_cryptographic_materials_cache
)

  3. 將sharedCache物件從步驟 2 傳遞至您的階層式鍵控。

    當您使用共用快取建立階層式金鑰環時，您可以選擇定義 ，partitionID以在多個階層式金鑰環之間共用快取項目。如果您未指定分割區 ID，階層式鍵控會自動指派唯一的分割區 ID 給鍵控。

    注意

    如果您建立兩個或多個參考相同分割區 ID、 和分支金鑰 ID 的金鑰環logical key store name，您的階層式金鑰環將在共用快取中共用相同的快取項目。如果您不希望多個鍵環共用相同的快取項目，則必須為每個階層式鍵環使用唯一的分割區 ID。

    下列範例會使用 建立階層式金鑰環branch key ID supplier，快取限制為 600 秒。如需下列階層鍵控組態中定義值的詳細資訊，請參閱 建立階層式鍵控。

    Java
    // Create the Hierarchical keyring
final CreateAwsKmsHierarchicalKeyringInput keyringInput =
    CreateAwsKmsHierarchicalKeyringInput.builder()
        .keyStore(keystore)
        .branchKeyIdSupplier(branchKeyIdSupplier)
        .ttlSeconds(600)
        .cache(sharedCache)
        .partitionID(partitionID)
        .build();
final IKeyring hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
    C# / .NET
    // Create the Hierarchical keyring        
var createKeyringInput = new CreateAwsKmsHierarchicalKeyringInput
{
   KeyStore = keystore,
   BranchKeyIdSupplier = branchKeyIdSupplier,
   Cache = sharedCache,
   TtlSeconds = 600,
   PartitionId = partitionID
};
var keyring = materialProviders.CreateAwsKmsHierarchicalKeyring(createKeyringInput);
    Python
    # Create the Hierarchical keyring
keyring_input: CreateAwsKmsHierarchicalKeyringInput = CreateAwsKmsHierarchicalKeyringInput(
    key_store=keystore,
    branch_key_id_supplier=branch_key_id_supplier,
    ttl_seconds=600,
    cache=shared_cache,
    partition_id=partition_id
)

hierarchical_keyring: IKeyring = mat_prov.create_aws_kms_hierarchical_keyring(
    input=keyring_input
)
顯示較多顯示較少

建立階層式鍵控

若要建立階層式鍵控，您必須提供下列值：

  • 金鑰存放區名稱

    您或金鑰存放區管理員建立的 DynamoDB 資料表名稱，以做為您的金鑰存放區。

  • 快取限制存留時間 （TTL）

    在本機快取內分支金鑰材料項目過期之前，可以使用的秒數。快取限制TTL會決定用戶端呼叫 AWS KMS 以授權使用分支金鑰的頻率。該值必須大於零。快取限制TTL過期後，永遠不會提供項目，並且會從本機快取中移出。

  • 分支金鑰識別符

    您可以靜態設定 branch-key-id，以識別金鑰存放區中的單一作用中分支金鑰，或提供分支金鑰 ID 供應商。

    分支金鑰 ID 供應商會使用存放在加密內容中的欄位，來判斷解密記錄所需的分支金鑰。

    我們強烈建議在多租戶資料庫中使用分支金鑰 ID 供應商，其中每個租戶都有自己的分支金鑰。您可以使用分支金鑰 ID 供應商為分支金鑰建立易記的名稱IDs，以便輕鬆識別特定租戶的正確分支金鑰 ID。例如，易記名稱可讓您將分支金鑰稱為 tenant1，而不是 b3f61619-4d35-48ad-a275-050f87e15122。

    對於解密操作，您可以靜態設定單一階層式鍵控以限制對單一租用戶的解密，也可以使用分支金鑰 ID 供應商來識別負責解密記錄的租用戶。

  • （選用） 快取

    如果您想要自訂快取類型或可儲存在本機快取中的分支金鑰材料項目數量，請在初始化金鑰環時指定快取類型和項目容量。

    階層式鍵控支援下列快取類型：預設 MultiThreaded StormTracking、 和共用。如需示範如何定義每個快取類型的詳細資訊和範例，請參閱 選擇快取。

    如果您未指定快取，階層式鍵控會自動使用預設快取類型，並將輸入容量設定為 1000。

  • （選用） 分割區 ID

    如果您指定 共用快取，您可以選擇定義分割區 ID。分割區 ID 會區分要寫入快取的階層式金鑰。如果您想要重複使用或共用分割區中的快取項目，您必須定義自己的分割區 ID。您可以為分割區 ID 指定任何字串。如果您未指定分割區 ID，則建立時會自動將唯一的分割區 ID 指派給鍵環。

    如需詳細資訊，請參閱Partitions。

    注意

    如果您建立兩個或多個參考相同分割區 ID、 和分支金鑰 ID 的金鑰環logical key store name，您的階層式金鑰環將在共用快取中共用相同的快取項目。如果您不希望多個鍵環共用相同的快取項目，則必須為每個階層式鍵環使用唯一的分割區 ID。

  • （選用） 授予權杖的清單

    如果您使用 授予來控制對階層式鍵控中KMS金鑰的存取，則必須在初始化鍵控時提供所有必要的授予權杖。

下列範例示範如何使用靜態分支金鑰 ID、 預設快取和 快取限制 TTL 600 秒來建立階層式金鑰環。

Java
final MaterialProviders matProv = MaterialProviders.builder()
        .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
        .build();
final CreateAwsKmsHierarchicalKeyringInput keyringInput = CreateAwsKmsHierarchicalKeyringInput.builder()
        .keyStore(branchKeyStoreName)
        .branchKeyId(branch-key-id)
        .ttlSeconds(600)
        .build();
final Keyring hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
C# / .NET
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var keyringInput = new CreateAwsKmsHierarchicalKeyringInput
{
   KeyStore = keystore,
   BranchKeyId = branch-key-id,
   TtlSeconds = 600
};
var hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
Python
mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
    config=MaterialProvidersConfig()
)

keyring_input: CreateAwsKmsHierarchicalKeyringInput = CreateAwsKmsHierarchicalKeyringInput(
    key_store=keystore,
    branch_key_id=branch_key_id,
    ttl_seconds=600
)

hierarchical_keyring: IKeyring = mat_prov.create_aws_kms_hierarchical_keyring(
    input=keyring_input
)

下列程序示範如何使用分支金鑰 ID 供應商建立階層式金鑰環。

  1. 建立分支金鑰 ID 供應商

    下列範例會建立兩個分支金鑰的易記名稱，以及建立分支金鑰 ID 供應商CreateDynamoDbEncryptionBranchKeyIdSupplier的呼叫。

    Java
    // Create friendly names for each branch-key-id 
class ExampleBranchKeyIdSupplier implements IDynamoDbKeyBranchKeyIdSupplier {
    private static String branchKeyIdForTenant1;
    private static String branchKeyIdForTenant2;

    public ExampleBranchKeyIdSupplier(String tenant1Id, String tenant2Id) {
        this.branchKeyIdForTenant1 = tenant1Id;
        this.branchKeyIdForTenant2 = tenant2Id;
    }
// Create the branch key ID supplier    
final DynamoDbEncryption ddbEnc = DynamoDbEncryption.builder()
        .DynamoDbEncryptionConfig(DynamoDbEncryptionConfig.builder().build())
        .build();
final BranchKeyIdSupplier branchKeyIdSupplier = ddbEnc.CreateDynamoDbEncryptionBranchKeyIdSupplier(
    CreateDynamoDbEncryptionBranchKeyIdSupplierInput.builder()
            .ddbKeyBranchKeyIdSupplier(new ExampleBranchKeyIdSupplier(branch-key-ID-tenant1, branch-key-ID-tenant2))
            .build()).branchKeyIdSupplier();
    C# / .NET
    // Create friendly names for each branch-key-id
 class ExampleBranchKeyIdSupplier : DynamoDbKeyBranchKeyIdSupplierBase {
    private String _branchKeyIdForTenant1;
    private String _branchKeyIdForTenant2;

    public ExampleBranchKeyIdSupplier(String tenant1Id, String tenant2Id) {
        this._branchKeyIdForTenant1 = tenant1Id;
        this._branchKeyIdForTenant2 = tenant2Id;
    }    
// Create the branch key ID supplier
var ddbEnc = new DynamoDbEncryption(new DynamoDbEncryptionConfig());
var branchKeyIdSupplier = ddbEnc.CreateDynamoDbEncryptionBranchKeyIdSupplier(
    new CreateDynamoDbEncryptionBranchKeyIdSupplierInput
    {
        DdbKeyBranchKeyIdSupplier = new ExampleBranchKeyIdSupplier(branch-key-ID-tenant1, branch-key-ID-tenant2)
    }).BranchKeyIdSupplier;
    Python
    # Create branch key ID supplier that maps the branch key ID to a friendly name
branch_key_id_supplier: IBranchKeyIdSupplier = ExampleBranchKeyIdSupplier(
        tenant_1_id=branch_key_id_a,
        tenant_2_id=branch_key_id_b,
)

  2. 建立階層式鍵控

    下列範例會使用在步驟 1 中建立的分支金鑰 ID 供應商初始化階層式金鑰環，快取限制TLL為 600 秒，快取大小上限為 1000。

    Java
    final MaterialProviders matProv = MaterialProviders.builder()
        .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
        .build();
final CreateAwsKmsHierarchicalKeyringInput keyringInput = CreateAwsKmsHierarchicalKeyringInput.builder()
        .keyStore(keystore)
        .branchKeyIdSupplier(branchKeyIdSupplier)
        .ttlSeconds(600)
        .cache(CacheType.builder() //OPTIONAL
                .Default(DefaultCache.builder()
                .entryCapacity(100)
                .build())
        .build();
final Keyring hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
    C# / .NET
    var matProv = new MaterialProviders(new MaterialProvidersConfig());
var keyringInput = new CreateAwsKmsHierarchicalKeyringInput
{
   KeyStore = keystore,
   BranchKeyIdSupplier = branchKeyIdSupplier,
   TtlSeconds = 600, 
   Cache = new CacheType
   {
        Default = new DefaultCache { EntryCapacity = 100 }
   }
};
var hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
    Python
    mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
    config=MaterialProvidersConfig()
)

keyring_input: CreateAwsKmsHierarchicalKeyringInput = CreateAwsKmsHierarchicalKeyringInput(
    key_store=keystore,
    branch_key_id_supplier=branch_key_id_supplier,
    ttl_seconds=600,
    cache=CacheTypeDefault(
        value=DefaultCache(
            entry_capacity=100
        )
    ),
)

hierarchical_keyring: IKeyring = mat_prov.create_aws_kms_hierarchical_keyring(
    input=keyring_input
)