AWS KMS Gantungan kunci hierarkis - AWS SDK Enkripsi Basis Data
Cara kerjanyaPrasyaratBuat keyring HierarkisPutar kunci cabang aktif AndaMenggunakan keyring Hierarkis dengan database multitenantMenggunakan keyring Hierarkis untuk enkripsi yang dapat dicari

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

Pustaka enkripsi sisi klien kami diubah namanya menjadi SDK Enkripsi AWS Database. Panduan pengembang ini masih memberikan informasi tentang Klien Enkripsi DynamoDB.
catatan

Mulai 24 Juli 2023, kunci cabang yang dibuat selama pratinjau pengembang tidak didukung. Buat kunci cabang baru untuk terus menggunakan toko kunci cabang yang Anda buat selama pratinjau pengembang.

Dengan keyring AWS KMS Hierarkis, Anda dapat melindungi materi kriptografi Anda di bawah kunci KMS enkripsi simetris tanpa menelepon AWS KMS setiap kali Anda mengenkripsi atau mendekripsi catatan. 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 bidang 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 database multitenant, partisi enkripsi juga dapat menyimpan beberapa versi materi kunci cabang sekaligus. Untuk informasi selengkapnya, lihat Menggunakan keyring Hierarkis dengan database multitenant.

catatan

Semua penyebutan keyring Hierarkis dalam SDK Enkripsi AWS Database 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 5.

  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 otentikasi tambahan (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 dan menandatangani catatan. Untuk informasi selengkapnya tentang cara catatan dienkripsi dan ditandatangani di SDK Enkripsi AWS Database, lihat Mengenkripsi dan menandatangani.

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 bidang deskripsi material dari catatan 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 KMSRincian 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 otentikasi tambahan (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 dan memverifikasi catatan. Untuk informasi selengkapnya tentang cara rekaman didekripsi dan diverifikasi di SDK Enkripsi AWS Database, lihat Mendekripsi dan memverifikasi.

Tampilkan lebih banyakTampilkan lebih sedikit

Prasyarat

SDK Enkripsi AWS Database tidak memerlukan Akun AWS dan tidak bergantung pada apa pun Layanan AWS. 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 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 toko kunci cabang, dan ARN kunci KMS yang mengidentifikasi kunci KMS 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. Kami sangat menyarankan untuk menentukan nama tabel DynamoDB Anda sebagai nama tabel logis saat Anda 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.

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();
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);
Langkah 2: Panggil CreateKeyStore untuk membuat toko kunci cabang

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

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

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 KMS yang 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.

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();
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
});

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"
}
catatan

CreateKeyOperasi membuat kunci cabang aktif dan kunci suar, bahkan jika Anda belum mengonfigurasi database Anda untuk enkripsi yang dapat dicari. Kedua kunci disimpan di toko kunci cabang Anda. Untuk informasi selengkapnya, lihat Menggunakan keyring hierarkis untuk enkripsi yang dapat dicari.

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. Batas cache TTL menentukan seberapa sering klien memanggil AWS KMS untuk mengotorisasi penggunaan kunci cabang. 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 dengan database multitenant.

  • (Opsional) Daftar Token Hibah

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

Contoh berikut menunjukkan cara menginisialisasi keyring Hierarkis dengan SDK Enkripsi AWS Database untuk klien DynamoDB. Contoh berikut menentukan batas cache TTL 600 detik.

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,
   BranchKeyIdSupplier = branchKeyIdSupplier,
   TtlSeconds = 600
};
var 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.

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

Menggunakan keyring Hierarkis dengan database multitenant

Anda dapat menggunakan hierarki kunci yang dibuat antara kunci cabang aktif dan kunci pembungkus turunannya untuk mendukung database multitenant dengan membuat kunci cabang untuk setiap penyewa di database Anda. Keyring Hierarkis kemudian mengenkripsi dan menandatangani semua data untuk penyewa tertentu dengan kunci cabang yang berbeda. Ini memungkinkan Anda untuk menyimpan data multitenant dalam satu database dan 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.

Pemasok ID kunci cabang

Sebelum Anda dapat menginisialisasi keyring Hierarkis untuk penggunaan multitenant, Anda harus membuat kunci cabang untuk setiap penyewa dan membuat pemasok ID kunci cabang. Pemasok ID kunci cabang menggunakan bidang yang disimpan dalam konteks enkripsi untuk menentukan kunci cabang penyewa mana yang diperlukan untuk mendekripsi catatan. Secara default, hanya partisi dan kunci pengurutan yang disertakan dalam konteks enkripsi. Namun, Anda dapat menggunakan tindakan SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT kriptografi untuk memasukkan bidang tambahan dalam konteks enkripsi.

catatan

Untuk menggunakan tindakan SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT kriptografi, Anda harus menggunakan SDK Enkripsi AWS Database versi 3.3 atau yang lebih baru. Terapkan versi baru ke semua pembaca sebelum memperbarui model data Anda untuk disertakanSIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT.

Anda dapat menggunakan pemasok ID kunci cabang untuk membuat nama yang ramah bagi Anda branch-key-ids agar mudah mengenali yang benar branch-key-id untuk penyewa. Misalnya, nama ramah memungkinkan Anda 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 catatan.

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 database Anda

Hubungi CreateKey setiap penyewa di database Anda.

Operasi berikut membuat dua kunci cabang menggunakan kunci KMS yang 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. Kunci KMS yang sama harus melindungi semua kunci cabang.

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

Contoh berikut membuat nama ramah dari dua kunci cabang yang dibuat pada Langkah 1, dan panggilan CreateDynamoDbEncryptionBranchKeyIdSupplier untuk membuat pemasok ID kunci cabang dengan AWS Database Encryption SDK untuk klien DynamoDB.

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;
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. Keyring Hierarkis menyediakan tiga jenis cache yang mendukung database 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 utas memanggil AWS KMS 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.

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

    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.

    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
    }
};
    StormTracking

    StormTracking Cache dirancang untuk mendukung lingkungan yang sangat multithreaded. Ketika entri materi kunci cabang kedaluwarsa, StormTracking cache mencegah beberapa utas memanggil AWS KMS 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

    • In flight time to live (TTL): mendefinisikan 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

    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
    }
};

  • (Opsional) Daftar Token Hibah

    Jika Anda mengontrol akses ke kunci KMS di 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 cache TLL 600 detik, dan ukuran cache maksimum 1000. Contoh ini menginisialisasi keyring Hierarkis dengan AWS Database Encryption SDK untuk klien DynamoDB.

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);
Tampilkan lebih banyakTampilkan lebih sedikit

Menggunakan keyring Hierarkis untuk enkripsi yang dapat dicari

Enkripsi yang dapat dicari memungkinkan Anda untuk mencari catatan terenkripsi tanpa mendekripsi seluruh database. Ini dicapai dengan mengindeks nilai plaintext dari bidang terenkripsi dengan suar. Untuk menerapkan enkripsi yang dapat dicari, Anda harus menggunakan keyring Hierarkis.

CreateKeyOperasi penyimpanan kunci menghasilkan kunci cabang dan kunci suar. Kunci cabang digunakan dalam enkripsi catatan dan operasi dekripsi. Kunci suar digunakan untuk menghasilkan suar.

Kunci cabang dan kunci suar dilindungi oleh yang sama dengan AWS KMS key yang Anda tentukan saat membuat layanan toko kunci Anda. Setelah panggilan CreateKey operasi AWS KMS untuk menghasilkan kunci cabang, ia memanggil kms: GenerateDataKeyWithoutPlaintext kedua kalinya untuk menghasilkan kunci suar 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
   },
   "KeyId": "the KMS key ARN",
   "NumberOfBytes": "32"
}

Setelah menghasilkan kedua kunci, CreateKey operasi memanggil ddb: TransactWriteItems untuk menulis dua item baru yang akan mempertahankan kunci cabang dan kunci suar di toko kunci cabang Anda.

Saat Anda mengonfigurasi suar standar, SDK Enkripsi AWS Database menanyakan penyimpanan kunci cabang untuk kunci suar. Kemudian, ia menggunakan fungsi derivasi extract-and-expand kunci berbasis HMAC (HKDF) untuk menggabungkan kunci suar dengan nama suar standar untuk membuat kunci HMAC untuk suar yang diberikan.

Tidak seperti kunci cabang, hanya ada satu versi kunci suar per branch-key-id di toko kunci cabang. Kunci suar tidak pernah diputar.

Mendefinisikan sumber kunci suar Anda

Saat Anda menentukan versi beacon untuk beacon standar dan gabungan Anda, Anda harus mengidentifikasi kunci suar dan menentukan batas waktu cache untuk hidup (TTL) untuk materi kunci suar. Materi kunci suar disimpan dalam cache lokal terpisah dari kunci cabang. Cuplikan berikut menunjukkan bagaimana mendefinisikan untuk database penyewa keySource tunggal. Identifikasi kunci suar Anda dengan yang branch-key-id terkait dengannya.

Java
keySource(BeaconKeySource.builder()
        .single(SingleKeyStore.builder()
                .keyId(branch-key-id)
                .cacheTTL(6000)
                .build())
        .build())
C# / .NET
KeySource = new BeaconKeySource
{
    Single = new SingleKeyStore
    {
       KeyId = branch-key-id,
       CacheTTL = 6000
    }
}
Mendefinisikan sumber suar dalam database multitenant

Jika Anda memiliki database multitenant, Anda harus menentukan nilai-nilai berikut saat mengkonfigurasi. keySource

  • keyFieldName

    Mendefinisikan nama bidang yang menyimpan yang branch-key-id terkait dengan kunci suar yang digunakan untuk menghasilkan suar untuk penyewa tertentu. keyFieldNameBisa berupa string apa saja, tetapi harus unik untuk semua bidang lain di database Anda. Saat Anda menulis catatan baru ke database Anda, branch-key-id yang mengidentifikasi kunci suar yang digunakan untuk menghasilkan suar apa pun untuk catatan itu disimpan di bidang ini. Anda harus menyertakan bidang ini dalam kueri suar Anda dan mengidentifikasi bahan kunci suar yang sesuai yang diperlukan untuk menghitung ulang suar. Untuk informasi selengkapnya, lihat Menanyakan beacon dalam database multitenant.

  • CacheTTL

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

  • (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. Keyring Hierarkis menyediakan tiga jenis cache yang mendukung database 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 utas memanggil AWS KMS 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.

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

    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.

    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
    }
};
    StormTracking

    StormTracking Cache dirancang untuk mendukung lingkungan yang sangat multithreaded. Ketika entri materi kunci cabang kedaluwarsa, StormTracking cache mencegah beberapa utas memanggil AWS KMS 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

    • In flight time to live (TTL): mendefinisikan 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

    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
    }
};

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

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(1000)
                        .build())
                .build();
final IKeyring 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 = 1000 }
   }
};
var hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);