AWS KMS Gantungan kunci hierarkis - AWS Encryption SDK
Cara kerjanyaPrasyaratBuat keyring HierarkisPutar kunci cabang aktif AndaMenggunakan keyring Hierarkis di lingkungan multitenant

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

AWS KMS Gantungan kunci hierarkis

penting

Keyring AWS KMS Hierarkis hanya didukung oleh versi 4. x dari AWS Encryption SDK untuk. NETdan versi 3. x dari AWS Encryption SDK for Java.

Dengan keyring AWS KMS Hierarkis, Anda dapat melindungi materi kriptografi Anda di bawah KMS kunci enkripsi simetris tanpa menelepon AWS KMS setiap kali Anda mengenkripsi atau mendekripsi data. Ini adalah pilihan yang baik untuk aplikasi yang perlu meminimalkan panggilan ke AWS KMS, dan aplikasi yang dapat menggunakan kembali beberapa materi kriptografi tanpa melanggar persyaratan keamanan mereka.

Hierarchical keyring adalah solusi caching materi kriptografi yang mengurangi jumlah AWS KMS panggilan dengan menggunakan kunci cabang yang AWS KMS dilindungi yang disimpan dalam tabel Amazon DynamoDB, dan kemudian secara lokal menyimpan materi kunci cabang yang digunakan dalam operasi enkripsi dan dekripsi. Tabel DynamoDB berfungsi sebagai penyimpanan kunci cabang yang mengelola dan melindungi kunci cabang. Ini menyimpan kunci cabang aktif dan semua versi sebelumnya dari kunci cabang. Kunci cabang aktif adalah versi kunci cabang terbaru. Keyring Hierarkis menggunakan kunci data unik untuk mengenkripsi setiap pesan dan mengenkripsi setiap kunci data dengan kunci pembungkus unik yang berasal dari kunci cabang aktif. Keyring Hierarkis tergantung pada hierarki yang ditetapkan antara kunci cabang aktif dan kunci pembungkus turunannya.

Keyring Hierarkis biasanya menggunakan setiap versi kunci cabang untuk memenuhi beberapa permintaan. Tetapi Anda mengontrol sejauh mana kunci cabang aktif digunakan kembali dan menentukan seberapa sering kunci cabang aktif diputar. Versi aktif dari kunci cabang tetap aktif sampai Anda memutarnya. Versi sebelumnya dari kunci cabang aktif tidak akan digunakan untuk melakukan operasi enkripsi, tetapi masih dapat ditanyakan dan digunakan dalam operasi dekripsi.

Ketika Anda membuat instance keyring Hierarchical, itu membuat cache lokal. Anda menentukan batas cache yang menentukan jumlah waktu maksimum materi kunci cabang disimpan dalam cache lokal sebelum kedaluwarsa dan dikeluarkan dari cache. Hierarchical keyring membuat satu AWS KMS panggilan untuk mendekripsi kunci cabang dan merakit materi kunci cabang saat pertama kali a branch-key-id ditentukan dalam suatu operasi. Kemudian, materi kunci cabang disimpan dalam cache lokal dan digunakan kembali untuk semua operasi enkripsi dan dekripsi yang menentukan itu branch-key-id sampai batas cache berakhir. Menyimpan materi kunci cabang di cache lokal mengurangi AWS KMS panggilan. Misalnya, pertimbangkan batas cache 15 menit. Jika Anda melakukan 10.000 operasi enkripsi dalam batas cache tersebut, AWS KMS keyring tradisional perlu melakukan 10.000 AWS KMS panggilan untuk memenuhi 10.000 operasi enkripsi. Jika Anda memiliki satu aktifbranch-key-id, keyring Hierarkis hanya perlu membuat satu AWS KMS panggilan untuk memenuhi 10.000 operasi enkripsi.

Cache lokal terdiri dari dua partisi, satu untuk operasi enkripsi dan yang kedua untuk operasi dekripsi. Partisi enkripsi menyimpan materi kunci cabang yang dirakit dari kunci cabang aktif dan menggunakannya kembali untuk semua operasi enkripsi hingga batas cache berakhir. Partisi dekripsi menyimpan bahan kunci cabang yang dirakit untuk versi kunci cabang lainnya yang diidentifikasi dalam operasi dekripsi. Partisi dekripsi dapat menyimpan beberapa versi bahan kunci cabang aktif sekaligus. Ketika dikonfigurasi untuk menggunakan pemasok ID kunci cabang untuk lingkungan multitenant, partisi enkripsi juga dapat menyimpan beberapa versi materi kunci cabang sekaligus. Untuk informasi selengkapnya, lihat Menggunakan keyring Hierarkis di lingkungan multitenant.

catatan

Semua penyebutan keyring Hierarkis AWS Encryption SDK mengacu pada keyring Hierarkis. AWS KMS

Cara kerjanya

Panduan berikut menjelaskan bagaimana keyring Hierarkis merakit bahan enkripsi dan dekripsi, dan panggilan berbeda yang dibuat oleh keyring untuk mengenkripsi dan mendekripsi operasi. Untuk detail teknis tentang derivasi kunci pembungkus dan proses enkripsi kunci data plaintext, lihat Detail teknis keyring AWS KMS hierarkis.

Enkripsi dan tandatangani

Panduan berikut menjelaskan bagaimana keyring Hierarkis merakit bahan enkripsi dan memperoleh kunci pembungkus yang unik.

  1. Metode enkripsi meminta keyring Hierarkis untuk materi enkripsi. Keyring menghasilkan kunci data plaintext, lalu memeriksa untuk melihat apakah ada materi cabang yang valid di cache lokal untuk menghasilkan kunci pembungkus. Jika ada materi kunci cabang yang valid, keyring dilanjutkan ke Langkah 4.

  2. Jika tidak ada materi kunci cabang yang valid, keyring Hierarkis menanyakan penyimpanan kunci cabang untuk kunci cabang aktif.

    1. Kunci cabang menyimpan panggilan AWS KMS untuk mendekripsi kunci cabang aktif dan mengembalikan kunci cabang aktif teks biasa. Data yang mengidentifikasi kunci cabang aktif diserialisasi untuk memberikan data tambahan yang diautentikasi (AAD) dalam panggilan dekripsi ke. AWS KMS

    2. Toko kunci cabang mengembalikan kunci cabang plaintext dan data yang mengidentifikasinya, seperti versi kunci cabang.

  3. Hierarchical keyring merakit materi kunci cabang (kunci cabang plaintext dan versi kunci cabang) dan menyimpan salinannya di cache lokal.

  4. Keyring Hierarchical memperoleh kunci pembungkus unik dari kunci cabang plaintext dan garam acak 16-byte. Ini menggunakan kunci pembungkus turunan untuk mengenkripsi salinan kunci data teks biasa.

Metode enkripsi menggunakan bahan enkripsi untuk mengenkripsi data. Untuk informasi selengkapnya, lihat Cara AWS Encryption SDK mengenkripsi data.

Tampilkan lebih banyakTampilkan lebih sedikit
Dekripsi dan verifikasi

Panduan berikut menjelaskan bagaimana keyring Hierarkis merakit bahan dekripsi dan mendekripsi kunci data terenkripsi.

  1. Metode dekripsi mengidentifikasi kunci data terenkripsi dari pesan terenkripsi, dan meneruskannya ke keyring Hierarkis.

  2. Hierarchical keyring deserialisasi data yang mengidentifikasi kunci data terenkripsi, termasuk versi kunci cabang, garam 16-byte, dan informasi lain yang menjelaskan bagaimana kunci data dienkripsi.

    Untuk informasi selengkapnya, lihat AWS KMS Rincian teknis keyring hierarkis.

  3. Keyring hierarkis memeriksa untuk melihat apakah ada materi kunci cabang yang valid di cache lokal yang cocok dengan versi kunci cabang yang diidentifikasi pada Langkah 2. Jika ada materi kunci cabang yang valid, keyring dilanjutkan ke Langkah 6.

  4. Jika tidak ada materi kunci cabang yang valid, keyring Hierarkis menanyakan penyimpanan kunci cabang untuk kunci cabang yang cocok dengan versi kunci cabang yang diidentifikasi pada Langkah 2.

    1. Kunci cabang menyimpan panggilan AWS KMS untuk mendekripsi kunci cabang dan mengembalikan kunci cabang aktif teks biasa. Data yang mengidentifikasi kunci cabang aktif diserialisasi untuk memberikan data tambahan yang diautentikasi (AAD) dalam panggilan dekripsi ke. AWS KMS

    2. Toko kunci cabang mengembalikan kunci cabang plaintext dan data yang mengidentifikasinya, seperti versi kunci cabang.

  5. Hierarchical keyring merakit materi kunci cabang (kunci cabang plaintext dan versi kunci cabang) dan menyimpan salinannya di cache lokal.

  6. Keyring Hierarchical menggunakan bahan kunci cabang yang dirakit dan garam 16-byte yang diidentifikasi pada Langkah 2 untuk mereproduksi kunci pembungkus unik yang mengenkripsi kunci data.

  7. Keyring Hierarkis menggunakan kunci pembungkus yang direproduksi untuk mendekripsi kunci data dan mengembalikan kunci data plaintext.

Metode dekripsi menggunakan bahan dekripsi dan kunci data teks biasa untuk mendekripsi pesan terenkripsi. Untuk informasi selengkapnya, lihat Cara AWS Encryption SDK mendekripsi pesan terenkripsi.

Tampilkan lebih banyakTampilkan lebih sedikit

Prasyarat

AWS Encryption SDK Itu tidak memerlukan Akun AWS dan itu tidak tergantung pada apa pun AWS layanan. Namun, keyring Hierarkis bergantung pada AWS KMS dan Amazon DynamoDB.

Untuk menggunakan keyring Hierarchical, Anda memerlukan enkripsi simetris AWS KMS key dengan izin KMS: Decrypt. Anda juga dapat menggunakan kunci multi-region enkripsi simetris. Untuk informasi selengkapnya tentang izin AWS KMS keys, lihat Otentikasi dan kontrol akses di Panduan AWS Key Management Service Pengembang.

Sebelum Anda dapat membuat dan menggunakan keyring Hierarkis, Anda harus membuat toko kunci cabang Anda dan mengisinya dengan kunci cabang aktif pertama Anda.

Langkah 1: Konfigurasikan layanan toko kunci baru

Layanan toko kunci menyediakan beberapa API operasi, seperti CreateKeyStore danCreateKey, untuk membantu Anda merakit prasyarat keyring Hierarkis dan mengelola toko kunci cabang Anda.

Contoh berikut menciptakan layanan toko kunci. Anda harus menentukan nama tabel DynamoDB untuk berfungsi sebagai nama toko kunci cabang Anda, nama logis untuk penyimpanan kunci cabang, dan KMS kunci yang mengidentifikasi ARN KMS kunci yang akan melindungi kunci cabang Anda.

Nama penyimpanan kunci logis terikat secara kriptografis ke semua data yang disimpan dalam tabel untuk menyederhanakan operasi pemulihan DynamoDB. Nama toko kunci logis bisa sama dengan nama tabel DynamoDB Anda, tetapi tidak harus demikian. Sebaiknya tentukan nama tabel DynamoDB Anda sebagai nama tabel logis saat pertama kali mengonfigurasi layanan penyimpanan kunci Anda. Anda harus selalu menentukan nama tabel logis yang sama. Jika nama toko kunci cabang Anda berubah setelah memulihkan tabel DynamoDB Anda dari cadangan, nama penyimpanan kunci logis memetakan ke nama tabel DynamoDB yang Anda tentukan untuk memastikan bahwa keyring Hierarkis masih dapat mengakses toko kunci cabang Anda.

catatan

Nama penyimpanan kunci logis disertakan dalam konteks enkripsi semua API operasi layanan penyimpanan kunci yang memanggil AWS KMS. Konteks enkripsi bukan rahasia, nilai-nilainya — termasuk nama penyimpanan kunci logis — muncul dalam teks biasa di log. AWS CloudTrail

C# / .NET
var kmsConfig = new KMSConfiguration { KmsKeyArn = kmsKeyArn };
var keystoreConfig = new KeyStoreConfig
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsConfiguration = kmsConfig,
    DdbTableName = keyStoreName,
    DdbClient = new AmazonDynamoDBClient(),
    LogicalKeyStoreName = logicalKeyStoreName
};
var keystore = new KeyStore(keystoreConfig);
Java
final KeyStore keystore = KeyStore.builder().KeyStoreConfig(
                KeyStoreConfig.builder()
                        .ddbClient(DynamoDbClient.create())
                        .ddbTableName(keyStoreName)
                        .logicalKeyStoreName(logicalKeyStoreName)
                        .kmsClient(KmsClient.create())
                        .kmsConfiguration(KMSConfiguration.builder()
                                .kmsKeyArn(kmsKeyArn)
                                .build())
                        .build()).build();
Langkah 2: Panggil CreateKeyStore untuk membuat toko kunci cabang

Operasi berikut membuat toko kunci cabang yang akan bertahan dan melindungi kunci cabang Anda.

C# / .NET
var createKeyStoreOutput = keystore.CreateKeyStore(new CreateKeyStoreInput());
Java
keystore.CreateKeyStore(CreateKeyStoreInput.builder().build());

CreateKeyStoreOperasi membuat tabel DynamoDB dengan nama tabel yang Anda tentukan di Langkah 1 dan nilai-nilai berikut yang diperlukan.

Kunci partisi Sortir kunci
Tabel dasar branch-key-id type
catatan

Anda dapat secara manual membuat tabel DynamoDB yang berfungsi sebagai penyimpanan kunci cabang Anda alih-alih menggunakan operasi. CreateKeyStore Jika Anda memilih untuk secara manual membuat toko kunci cabang, Anda harus menentukan nilai string berikut untuk partisi dan mengurutkan kunci:

  • Kunci partisi: branch-key-id

  • Kunci urutan: type

Langkah 3: Panggil CreateKey untuk membuat kunci cabang aktif baru

Operasi berikut membuat kunci cabang aktif baru menggunakan kunci yang KMS Anda tentukan di Langkah 1, dan menambahkan kunci cabang aktif ke tabel DynamoDB yang Anda buat di Langkah 2.

Saat Anda meneleponCreateKey, Anda dapat memilih untuk menentukan nilai opsional berikut.

C# / .NET
var additionalEncryptionContext = new Dictionary<string, string>();
additionalEncryptionContext.Add("Additional Encryption Context for", "custom branch key id");
        
var branchKeyId = keystore.CreateKey(new CreateKeyInput
{
    BranchKeyIdentifier = "custom-branch-key-id", // OPTIONAL
    EncryptionContext = additionalEncryptionContext // OPTIONAL
});
Java
final Map<String, String> additionalEncryptionContext = Collections.singletonMap("Additional Encryption Context for",
        "custom branch key id");
            
final String BranchKey = keystore.CreateKey(
        CreateKeyInput.builder()
                .branchKeyIdentifier(custom-branch-key-id) //OPTIONAL
                .encryptionContext(additionalEncryptionContext) //OPTIONAL
                .build()).branchKeyIdentifier();

Pertama, CreateKey operasi menghasilkan nilai-nilai berikut.

Kemudian, CreateKey operasi memanggil kms: GenerateDataKeyWithoutPlaintext menggunakan permintaan berikut.

{
   "EncryptionContext": { 
      "branch-key-id" : "branch-key-id",
      "type" : "type",
      "create-time" : "timestamp",
      "logical-key-store-name" : "the logical table name for your branch key store",
      "kms-arn" : the KMS key ARN,
      "hierarchy-version" : "1",
      "aws-crypto-ec:contextKey": "contextValue"
   },
   "KeyId": "the KMS key ARN you specified in Step 1",
   "NumberOfBytes": "32"
}

Selanjutnya, CreateKey operasi memanggil kms: ReEncrypt untuk membuat catatan aktif untuk kunci cabang dengan memperbarui konteks enkripsi.

Terakhir, CreateKey operasi memanggil ddb: TransactWriteItems untuk menulis item baru yang akan mempertahankan kunci cabang dalam tabel yang Anda buat di Langkah 2. Item memiliki atribut berikut.

{
    "branch-key-id" : branch-key-id,
    "type" : "branch:ACTIVE",
    "enc" : the branch key returned by the GenerateDataKeyWithoutPlaintext call,
    "version": "branch:version:the branch key version UUID",
    "create-time" : "timestamp",
    "kms-arn" : "the KMS key ARN you specified in Step 1",
    "hierarchy-version" : "1",
    "aws-crypto-ec:contextKey": "contextValue"
}

Buat keyring Hierarkis

Untuk menginisialisasi keyring Hierarkis, Anda harus memberikan nilai-nilai berikut:

  • Nama toko kunci cabang

    Nama tabel DynamoDB yang Anda buat untuk berfungsi sebagai toko kunci cabang Anda.

  • Batas waktu cache untuk hidup (TTL)

    Jumlah waktu dalam hitungan detik entri materi kunci cabang dalam cache lokal dapat digunakan sebelum kedaluwarsa. Nilai ini harus lebih besar dari nol. Ketika batas cache TTL berakhir, entri diusir dari cache lokal.

  • Pengidentifikasi kunci cabang

    branch-key-idYang mengidentifikasi kunci cabang aktif di toko kunci cabang Anda.

    catatan

    Untuk menginisialisasi keyring Hierarkis untuk penggunaan multitenant, Anda harus menentukan pemasok ID kunci cabang, bukan. branch-key-id Untuk informasi selengkapnya, lihat Menggunakan keyring Hierarkis di lingkungan multitenant.

  • (Opsional) Sebuah cache

    Jika Anda ingin menyesuaikan jenis cache atau jumlah entri materi kunci cabang yang dapat disimpan di cache lokal, tentukan jenis cache dan kapasitas entri saat Anda menginisialisasi keyring.

    Jenis cache mendefinisikan model threading. Hierarchical keyring menyediakan tiga jenis cache yang mendukung lingkungan multitenant: Default,,. MultiThreaded StormTracking

    Jika Anda tidak menentukan cache, keyring Hierarkis secara otomatis menggunakan jenis cache Default dan menetapkan kapasitas entri ke 1000.

    Default (Recommended)

    Untuk sebagian besar pengguna, cache Default memenuhi persyaratan threading mereka. Cache Default dirancang untuk mendukung lingkungan yang sangat multithreaded. Ketika entri materi kunci cabang kedaluwarsa, cache Default mencegah beberapa thread memanggil AWS KMS dan Amazon DynamoDB dengan memberi tahu satu utas bahwa entri materi kunci cabang akan kedaluwarsa 10 detik sebelumnya. Ini memastikan bahwa hanya satu utas yang mengirimkan permintaan AWS KMS untuk menyegarkan cache.

    Untuk menginisialisasi keyring Hierarkis Anda dengan cache Default, tentukan nilai berikut:

    • Kapasitas entri: membatasi jumlah entri materi kunci cabang yang dapat disimpan di cache lokal.

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

    Default dan StormTracking cache mendukung model threading yang sama, tetapi Anda hanya perlu menentukan kapasitas entri untuk menginisialisasi keyring Hierarkis dengan cache Default. Untuk kustomisasi cache yang lebih terperinci, gunakan cache. StormTracking

    MultiThreaded

    MultiThreaded Cache aman digunakan di lingkungan multithreaded, tetapi tidak menyediakan fungsionalitas apa pun untuk meminimalkan atau panggilan Amazon AWS KMS DynamoDB. Akibatnya, ketika entri materi kunci cabang kedaluwarsa, semua utas akan diberitahukan pada saat yang sama. Ini dapat menghasilkan beberapa AWS KMS panggilan untuk menyegarkan cache.

    Untuk menginisialisasi keyring Hierarkis Anda dengan MultiThreaded cache, tentukan nilai berikut:

    • Kapasitas entri: membatasi jumlah entri materi kunci cabang yang dapat disimpan di cache lokal.

    • Ukuran ekor pemangkasan entri: menentukan jumlah entri yang akan dipangkas jika kapasitas masuk tercapai.

    C #/. NET
    CacheType multithreadedCache = new CacheType
{
    MultiThreaded = new MultiThreadedCache
    {
        EntryCapacity = 100,
        EntryPruningTailSize = 1
    }
};
    Java
    .cache(CacheType.builder()
        .MultiThreaded(MultiThreadedCache.builder()
        .entryCapacity(100)
        .entryPruningTailSize(1)                                        
        .build())
    StormTracking

    StormTracking Cache dirancang untuk mendukung lingkungan yang sangat multithreaded. Saat entri materi kunci cabang kedaluwarsa, StormTracking cache mencegah beberapa utas memanggil AWS KMS dan Amazon DynamoDB dengan memberi tahu satu utas bahwa entri materi kunci cabang akan kedaluwarsa sebelumnya. Ini memastikan bahwa hanya satu utas yang mengirimkan permintaan AWS KMS untuk menyegarkan cache.

    Untuk menginisialisasi keyring Hierarkis Anda dengan StormTracking cache, tentukan nilai berikut:

    • Kapasitas entri: membatasi jumlah entri materi kunci cabang yang dapat disimpan di cache lokal.

    • Ukuran ekor pemangkasan entri: menentukan jumlah entri bahan kunci cabang untuk dipangkas sekaligus.

      Nilai default: 1 entri

    • Masa tenggang: mendefinisikan jumlah detik sebelum kedaluwarsa bahwa upaya untuk menyegarkan materi kunci cabang dilakukan.

      Nilai default: 10 detik

    • Interval rahmat: mendefinisikan jumlah detik antara upaya untuk menyegarkan materi kunci cabang.

      Nilai default: 1 detik

    • Fan out: mendefinisikan jumlah upaya simultan yang dapat dilakukan untuk menyegarkan materi kunci cabang.

      Nilai default: 20 upaya

    • Dalam waktu penerbangan untuk hidup (TTL): menentukan jumlah detik hingga upaya untuk menyegarkan materi kunci cabang habis waktu. Setiap kali cache kembali NoSuchEntry sebagai respons terhadap aGetCacheEntry, kunci cabang tersebut dianggap dalam penerbangan sampai kunci yang sama ditulis dengan PutCache entri.

      Nilai default: 20 detik

    • Tidur: mendefinisikan jumlah detik bahwa sebuah utas harus tidur jika fanOut terlampaui.

      Nilai default: 20 milidetik

    C #/. NET
    CacheType stormTrackingCache = new CacheType
{
    StormTracking = new StormTrackingCache
    {
        EntryCapacity = 100,
        EntryPruningTailSize = 1,
        FanOut = 20,
        GraceInterval = 1,
        GracePeriod = 10,
        InFlightTTL = 20,
        SleepMilli = 20
    }
};
    Java
    .cache(CacheType.builder()
        .MultiThreaded(MultiThreadedCache.builder()
        .entryCapacity(100)
        .entryPruningTailSize(1)
        .gracePeriod(10)
        .graceInterval(1)
        .fanOut(20) 
        .inFlightTTL(20)
        .sleepMilli(20)                                        
        .build())

  • (Opsional) Daftar Token Hibah

    Jika Anda mengontrol akses ke KMS kunci dalam keyring Hierarkis Anda dengan hibah, Anda harus menyediakan semua token hibah yang diperlukan saat Anda menginisialisasi keyring.

Contoh berikut menginisialisasi keyring Hierarkis dengan batas TLL cache 600 detik, dan kapasitas entri 1000.

C# / .NET
// Instantiate the AWS Encryption SDK and material providers 
var mpl = new MaterialProviders(new MaterialProvidersConfig());
var esdk =  new ESDK(new AwsEncryptionSdkConfig());

// Instantiate the keyring
var createKeyringInput = new CreateAwsKmsHierarchicalKeyringInput
{
    KeyStore = branchKeyStoreName,
    BranchKeyId = branch-key-id,
    Cache = new CacheType { Default = new DefaultCache{EntryCapacity = 1000} },
    TtlSeconds = 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)
        .cache(CacheType.builder() //OPTIONAL
                .Default(DefaultCache.builder()
                .entryCapacity(1000)
                .build())
        .build();
final Keyring hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);

Putar kunci cabang aktif Anda

Hanya ada satu versi aktif untuk setiap kunci cabang pada satu waktu. Keyring Hierarkis biasanya menggunakan setiap versi kunci cabang aktif untuk memenuhi beberapa permintaan. Tetapi Anda mengontrol sejauh mana kunci cabang aktif digunakan kembali dan menentukan seberapa sering kunci cabang aktif diputar.

Kunci cabang tidak digunakan untuk mengenkripsi kunci data teks biasa. Mereka digunakan untuk mendapatkan kunci pembungkus unik yang mengenkripsi kunci data teks biasa. Proses derivasi kunci pembungkus menghasilkan kunci pembungkus 32 byte yang unik dengan 28 byte keacakan. Ini berarti bahwa kunci cabang dapat memperoleh lebih dari 79 oktillion, atau 2 96, kunci pembungkus unik sebelum keausan kriptografi terjadi. Meskipun risiko kelelahan yang sangat rendah ini, Anda mungkin diminta untuk memutar kunci cabang aktif Anda karena aturan bisnis atau kontrak atau peraturan pemerintah.

Versi aktif dari kunci cabang tetap aktif sampai Anda memutarnya. Versi sebelumnya dari kunci cabang aktif tidak akan digunakan untuk melakukan operasi enkripsi dan tidak dapat digunakan untuk mendapatkan kunci pembungkus baru. Tetapi mereka masih dapat ditanyakan dan menyediakan kunci pembungkus untuk mendekripsi kunci data yang mereka enkripsi saat aktif.

Gunakan VersionKey operasi layanan toko kunci untuk memutar kunci cabang aktif Anda. Saat Anda memutar kunci cabang aktif, kunci cabang baru dibuat untuk menggantikan versi sebelumnya. branch-key-idTidak berubah saat Anda memutar kunci cabang aktif. Anda harus menentukan branch-key-id yang mengidentifikasi kunci cabang aktif saat ini ketika Anda meneleponVersionKey.

C# / .NET
 keystore.VersionKey(new VersionKeyInput{BranchKeyIdentifier = branchKeyId});
Java
keystore.VersionKey(
    VersionKeyInput.builder()
        .branchKeyIdentifier("branch-key-id")
        .build()
);

Menggunakan keyring Hierarkis di lingkungan multitenant

Anda dapat menggunakan hierarki kunci yang dibuat antara kunci cabang aktif dan kunci pembungkus turunannya untuk mendukung lingkungan multitenant dengan membuat kunci cabang untuk setiap penyewa di lingkungan Anda. Keyring Hierarkis kemudian mengenkripsi semua data untuk penyewa tertentu dengan kunci cabang yang berbeda. Ini memungkinkan Anda untuk mengisolasi data penyewa dengan kunci cabang.

Setiap penyewa memiliki kunci cabang mereka sendiri yang ditentukan oleh unikbranch-key-id. Hanya ada satu versi aktif masing-masing branch-key-id pada satu waktu.

Sebelum Anda dapat menginisialisasi keyring Hierarkis untuk penggunaan multitenant, Anda harus membuat kunci cabang untuk setiap penyewa dan membuat pemasok ID kunci cabang. Gunakan pemasok ID kunci cabang untuk membuat nama yang ramah bagi Anda branch-key-ids agar lebih mudah mengenali yang benar branch-key-id untuk penyewa. Misalnya, nama ramah memungkinkan Anda untuk merujuk ke kunci cabang sebagai tenant1 gantinyab3f61619-4d35-48ad-a275-050f87e15122.

Untuk operasi dekripsi, Anda dapat mengonfigurasi secara statis satu keyring Hierarkis untuk membatasi dekripsi ke penyewa tunggal, atau Anda dapat menggunakan pemasok ID kunci cabang untuk mengidentifikasi penyewa mana yang bertanggung jawab untuk mendekripsi pesan.

Pertama, ikuti Langkah 1 dan Langkah 2 dari prosedur Prasyarat. Kemudian, gunakan prosedur berikut untuk membuat kunci cabang untuk setiap penyewa, membuat pemasok ID kunci cabang, dan menginisialisasi keyring Hierarkis Anda untuk penggunaan multitenant.

Langkah 1: Buat kunci cabang untuk setiap penyewa di lingkungan Anda

Panggilan CreateKey untuk setiap penyewa.

Operasi berikut membuat dua kunci cabang menggunakan kunci yang KMS Anda tentukan saat membuat layanan penyimpanan kunci Anda, dan menambahkan kunci cabang ke tabel DynamoDB yang Anda buat untuk berfungsi sebagai toko kunci cabang Anda. KMSKunci yang sama harus melindungi semua kunci cabang.

C# / .NET
var branchKeyId1 = keystore.CreateKey(new CreateKeyInput());
var branchKeyId2 = keystore.CreateKey(new CreateKeyInput());
Java
CreateKeyOutput branchKeyId1 = keystore.CreateKey(CreateKeyInput.builder().build());
CreateKeyOutput branchKeyId2 = keystore.CreateKey(CreateKeyInput.builder().build());
Langkah 2: Buat pemasok ID kunci cabang

Contoh berikut membuat pemasok ID kunci cabang.

C# / .NET
var branchKeySupplier =
    new ExampleBranchKeySupplier(branchKeyId1.BranchKeyIdentifier, branchKeyId2.BranchKeyIdentifier);
Java
IBranchKeyIdSupplier branchKeyIdSupplier = new ExampleBranchKeyIdSupplier(
        branchKeyId1.branchKeyIdentifier(), branchKeyId2.branchKeyIdentifier());
Langkah 3: Inisialisasi keyring Hierarkis Anda dengan pemasok ID kunci cabang

Untuk menginisialisasi keyring Hierarkis Anda harus memberikan nilai-nilai berikut:

  • Nama toko kunci cabang

  • Batas waktu cache untuk hidup (TTL)

  • Pemasok ID kunci cabang

  • (Opsional) Sebuah cache

    Jika Anda ingin menyesuaikan jenis cache atau jumlah entri materi kunci cabang yang dapat disimpan di cache lokal, tentukan jenis cache dan kapasitas entri saat Anda menginisialisasi keyring.

    Jenis cache mendefinisikan model threading. Hierarchical keyring menyediakan tiga jenis cache yang mendukung lingkungan multitenant: Default,,. MultiThreaded StormTracking

    Jika Anda tidak menentukan cache, keyring Hierarkis secara otomatis menggunakan jenis cache Default dan menetapkan kapasitas entri ke 1000.

    Default (Recommended)

    Untuk sebagian besar pengguna, cache Default memenuhi persyaratan threading mereka. Cache Default dirancang untuk mendukung lingkungan yang sangat multithreaded. Ketika entri materi kunci cabang kedaluwarsa, cache Default mencegah beberapa thread memanggil AWS KMS dan Amazon DynamoDB dengan memberi tahu satu utas bahwa entri materi kunci cabang akan kedaluwarsa 10 detik sebelumnya. Ini memastikan bahwa hanya satu utas yang mengirimkan permintaan AWS KMS untuk menyegarkan cache.

    Untuk menginisialisasi keyring Hierarkis Anda dengan cache Default, tentukan nilai berikut:

    • Kapasitas entri: membatasi jumlah entri materi kunci cabang yang dapat disimpan di cache lokal.

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

    Default dan StormTracking cache mendukung model threading yang sama, tetapi Anda hanya perlu menentukan kapasitas entri untuk menginisialisasi keyring Hierarkis dengan cache Default. Untuk kustomisasi cache yang lebih terperinci, gunakan cache. StormTracking

    MultiThreaded

    MultiThreaded Cache aman digunakan di lingkungan multithreaded, tetapi tidak menyediakan fungsionalitas apa pun untuk meminimalkan atau panggilan Amazon AWS KMS DynamoDB. Akibatnya, ketika entri materi kunci cabang kedaluwarsa, semua utas akan diberitahukan pada saat yang sama. Ini dapat menghasilkan beberapa AWS KMS panggilan untuk menyegarkan cache.

    Untuk menginisialisasi keyring Hierarkis Anda dengan MultiThreaded cache, tentukan nilai berikut:

    • Kapasitas entri: membatasi jumlah entri materi kunci cabang yang dapat disimpan di cache lokal.

    • Ukuran ekor pemangkasan entri: menentukan jumlah entri yang akan dipangkas jika kapasitas masuk tercapai.

    C #/. NET
    CacheType multithreadedCache = new CacheType
{
    MultiThreaded = new MultiThreadedCache
    {
        EntryCapacity = 100,
        EntryPruningTailSize = 1
    }
};
    Java
    .cache(CacheType.builder()
        .MultiThreaded(MultiThreadedCache.builder()
        .entryCapacity(100)
        .entryPruningTailSize(1)                                        
        .build())
    StormTracking

    StormTracking Cache dirancang untuk mendukung lingkungan yang sangat multithreaded. Saat entri materi kunci cabang kedaluwarsa, StormTracking cache mencegah beberapa utas memanggil AWS KMS dan Amazon DynamoDB dengan memberi tahu satu utas bahwa entri materi kunci cabang akan kedaluwarsa sebelumnya. Ini memastikan bahwa hanya satu utas yang mengirimkan permintaan AWS KMS untuk menyegarkan cache.

    Untuk menginisialisasi keyring Hierarkis Anda dengan StormTracking cache, tentukan nilai berikut:

    • Kapasitas entri: membatasi jumlah entri materi kunci cabang yang dapat disimpan di cache lokal.

    • Ukuran ekor pemangkasan entri: menentukan jumlah entri bahan kunci cabang untuk dipangkas sekaligus.

      Nilai default: 1 entri

    • Masa tenggang: mendefinisikan jumlah detik sebelum kedaluwarsa bahwa upaya untuk menyegarkan materi kunci cabang dilakukan.

      Nilai default: 10 detik

    • Interval rahmat: mendefinisikan jumlah detik antara upaya untuk menyegarkan materi kunci cabang.

      Nilai default: 1 detik

    • Fan out: mendefinisikan jumlah upaya simultan yang dapat dilakukan untuk menyegarkan materi kunci cabang.

      Nilai default: 20 upaya

    • Dalam waktu penerbangan untuk hidup (TTL): menentukan jumlah detik hingga upaya untuk menyegarkan materi kunci cabang habis waktu. Setiap kali cache kembali NoSuchEntry sebagai respons terhadap aGetCacheEntry, kunci cabang tersebut dianggap dalam penerbangan sampai kunci yang sama ditulis dengan PutCache entri.

      Nilai default: 20 detik

    • Tidur: mendefinisikan jumlah detik bahwa sebuah utas harus tidur jika fanOut terlampaui.

      Nilai default: 20 milidetik

    C #/. NET
    CacheType stormTrackingCache = new CacheType
{
    StormTracking = new StormTrackingCache
    {
        EntryCapacity = 100,
        EntryPruningTailSize = 1,
        FanOut = 20,
        GraceInterval = 1,
        GracePeriod = 10,
        InFlightTTL = 20,
        SleepMilli = 20
    }
};
    Java
    .cache(CacheType.builder()
        .MultiThreaded(MultiThreadedCache.builder()
        .entryCapacity(100)
        .entryPruningTailSize(1)
        .gracePeriod(10)
        .graceInterval(1)
        .fanOut(20) 
        .inFlightTTL(20)
        .sleepMilli(20)                                        
        .build())

  • (Opsional) Daftar Token Hibah

    Jika Anda mengontrol akses ke KMS kunci dalam keyring Hierarkis Anda dengan hibah, Anda harus menyediakan semua token hibah yang diperlukan saat Anda menginisialisasi keyring.

Contoh berikut menginisialisasi keyring Hierarkis dengan pemasok ID kunci cabang yang dibuat pada Langkah 2, batas TLL cache 600 detik, dan kapasitas entri 1000.

C# / .NET
var createKeyringInput = new CreateAwsKmsHierarchicalKeyringInput
{
    KeyStore = keystore,
    BranchKeyIdSupplier = branchKeySupplier,
    Cache = new CacheType { Default = new DefaultCache{EntryCapacity = 1000} }, 
    TtlSeconds = 600
};
var keyring = mpl.CreateAwsKmsHierarchicalKeyring(createKeyringInput);
Java
final MaterialProviders matProv = MaterialProviders.builder()
        .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
        .build();
final CreateAwsKmsHierarchicalKeyringInput keyringInput = CreateAwsKmsHierarchicalKeyringInput.builder()
        .keyStore(branchKeyStoreName)
        .branchKeyIdSupplier(branchKeyIdSupplier)
        .ttlSeconds(600)
        .cache(CacheType.builder() //OPTIONAL
                .Default(DefaultCache.builder()
                        .entryCapacity(100)
                        .build())
                .build();
final IKeyring hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
Langkah 4: Buat nama ramah untuk setiap kunci cabang

Contoh berikut menciptakan nama ramah untuk dua kunci cabang yang dibuat pada Langkah 1. AWS Encryption SDK Menggunakan konteks enkripsi untuk memetakan nama ramah yang Anda tentukan ke yang terkait. branch-key-id

C# / .NET
// Create encryption contexts for the two branch keys created in Step 1
var encryptionContextA = new Dictionary<string, string>()
{
    // We will encrypt with branchKeyTenantA
    {"tenant", "TenantA"},
    {"encryption", "context"},
    {"is not", "secret"},
    {"but adds", "useful metadata"},
    {"that can help you", "be confident that"},
    {"the data you are handling", "is what you think it is"}
};
var encryptionContextB = new Dictionary<string, string>()
{
    // We will encrypt with branchKeyTenantB
    {"tenant", "TenantB"},
    {"encryption", "context"},
    {"is not", "secret"},
    {"but adds", "useful metadata"},
    {"that can help you", "be confident that"},
    {"the data you are handling", "is what you think it is"}
};
        
// Instantiate the AWS Encryption SDK var esdk =  new ESDK(new AwsEncryptionSdkConfig());


var encryptInputA = new EncryptInput
{
    Plaintext = plaintext,
    Keyring = keyring,
    // Encrypt with branchKeyId1
    EncryptionContext = encryptionContextA
};

var encryptInputB = new EncryptInput
{
    Plaintext = plaintext,
    Keyring = keyring,
    // Encrypt with branchKeyId2
    EncryptionContext = encryptionContextB
};
        
var encryptOutput = esdk.Encrypt(encryptInputA);
encryptOutput = esdk.Encrypt(encryptInputB);
 
// Use the encryption contexts to define friendly names for each branch key   
public class ExampleBranchKeySupplier : IBranchKeyIdSupplier
{
    private string branchKeyTenantA;
    private string branchKeyTenantB;

    public ExampleBranchKeySupplier(string branchKeyTenantA, string branchKeyTenantB)
    {
        this.branchKeyTenantA = branchKeyTenantA;
        this.branchKeyTenantB = branchKeyTenantB;
    }
        
    public GetBranchKeyIdOutput GetBranchKeyId(GetBranchKeyIdInput input)
    {
        Dictionary<string, string> encryptionContext = input.EncryptionContext;
            
        if (!encryptionContext.ContainsKey("tenant"))
        {
            throw new Exception("EncryptionContext invalid, does not contain expected tenant key value pair.");
        }

        string tenant = encryptionContext["tenant"];
        string branchkeyId;

        if (tenant.Equals("TenantA"))
        {
            GetBranchKeyIdOutput output = new GetBranchKeyIdOutput();
            output.BranchKeyId = branchKeyTenantA;
            return output;
        } else if (tenant.Equals("TenantB"))
        {
            GetBranchKeyIdOutput output = new GetBranchKeyIdOutput();
            output.BranchKeyId = branchKeyTenantB;
            return output;
        }
        else
        {
            throw new Exception("Item does not have a valid tenantID.");
        }
    }
}
Java
// Create encryption context for branchKeyTenantA
Map<String, String> encryptionContextA = new HashMap<>();
encryptionContextA.put("tenant", "TenantA");
encryptionContextA.put("encryption", "context");
encryptionContextA.put("is not", "secret");
encryptionContextA.put("but adds", "useful metadata");
encryptionContextA.put("that can help you", "be confident that");
encryptionContextA.put("the data you are handling", "is what you think it is");
                                            
// Create encryption context for branchKeyTenantB
Map<String, String> encryptionContextB = new HashMap<>();
encryptionContextB.put("tenant", "TenantB");
encryptionContextB.put("encryption", "context");
encryptionContextB.put("is not", "secret");
encryptionContextB.put("but adds", "useful metadata");
encryptionContextB.put("that can help you", "be confident that");
encryptionContextB.put("the data you are handling", "is what you think it is");                                            
                                            
// Instantiate the AWS Encryption SDK 
final AwsCrypto crypto = AwsCrypto.builder().build();

final CryptoResult<byte[], ?> encryptResultA = crypto.encryptData(keyring, plaintext, encryptionContextA);

final CryptoResult<byte[], ?> encryptResultB = crypto.encryptData(keyring, plaintext, encryptionContextB);
                                            
// Use the encryption contexts to define friendly names for each branch key
public class ExampleBranchKeyIdSupplier implements IBranchKeyIdSupplier {
    private static String branchKeyIdForTenantA;
    private static String branchKeyIdForTenantB;

    public ExampleBranchKeyIdSupplier(String tenant1Id, String tenant2Id) {
        this.branchKeyIdForTenantA = tenant1Id;
        this.branchKeyIdForTenantB = tenant2Id;
    }

    @Override
    public GetBranchKeyIdOutput GetBranchKeyId(GetBranchKeyIdInput input) {

        Map<String, String> encryptionContext = input.encryptionContext();

        if (!encryptionContext.containsKey("tenant"))
        {
            throw new IllegalArgumentException("EncryptionContext invalid, does not contain expected tenant key value pair.");
        }

        String tenantKeyId = encryptionContext.get("tenant");
        String branchKeyId;

        if (tenantKeyId.equals("TenantA")) {
            branchKeyId = branchKeyIdForTenantA;
        } else if (tenantKeyId.equals("TenantB")) {
            branchKeyId = branchKeyIdForTenantB;
        } else {
            throw new IllegalArgumentException("Item does not contain valid tenant ID");
        }
        
        return GetBranchKeyIdOutput.builder().branchKeyId(branchKeyId).build();
    }
}
Tampilkan lebih banyakTampilkan lebih sedikit