AWS Encryption SDK untuk. NETcontoh - AWS Encryption SDK
Mengenkripsi dataMendekripsi dalam mode ketatMendekripsi dengan keyring penemuan AWS KMS

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

AWS Encryption SDK untuk. NETcontoh

Contoh berikut menunjukkan pola pengkodean dasar yang Anda gunakan saat memprogram dengan AWS Encryption SDK for. NET. Secara khusus, Anda membuat instance perpustakaan AWS Encryption SDK dan penyedia materi. Kemudian, sebelum memanggil setiap metode, Anda membuat instance objek yang mendefinisikan input untuk metode tersebut. Ini sangat mirip dengan pola pengkodean yang Anda gunakan di AWS SDK for .NET.

Untuk contoh yang menunjukkan cara mengonfigurasi opsi di AWS Encryption SDK, seperti menentukan rangkaian algoritme alternatif, membatasi kunci data terenkripsi, dan menggunakan kunci AWS KMS Multi-region, lihat. Mengkonfigurasi AWS Encryption SDK

Untuk lebih banyak contoh pemrograman dengan AWS Encryption SDK for. NET, lihat contoh di aws-encryption-sdk-net direktori aws-encryption-sdk-dafny repositori pada. GitHub

Mengenkripsi data di for. AWS Encryption SDK NET

Contoh ini menunjukkan pola dasar untuk mengenkripsi data. Ini mengenkripsi file kecil dengan kunci data yang dilindungi oleh satu kunci AWS KMS pembungkus.

Langkah 1: Buat instance AWS Encryption SDK dan perpustakaan penyedia materi.

Mulailah dengan membuat instance perpustakaan penyedia AWS Encryption SDK dan materi. Anda akan menggunakan metode dalam AWS Encryption SDK untuk mengenkripsi dan mendekripsi data. Anda akan menggunakan metode di pustaka penyedia materi untuk membuat keyrings yang menentukan kunci mana yang melindungi data Anda.

Cara Anda membuat instance AWS Encryption SDK dan pustaka penyedia materi berbeda antara versi 3. x dan 4. x dari AWS Encryption SDK untuk. NET. Semua langkah berikut adalah sama untuk kedua versi 3. x dan 4. x dari AWS Encryption SDK untuk. NET.

Version 3.x
// Instantiate the AWS Encryption SDK and material providers
var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk();
var materialProviders =
    AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();
Version 4.x
// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
Langkah 2: Buat objek input untuk keyring.

Setiap metode yang membuat keyring memiliki kelas objek input yang sesuai. Misalnya, untuk membuat objek masukan untuk CreateAwsKmsKeyring() metode, buat instance CreateAwsKmsKeyringInput kelas.

Meskipun input untuk keyring ini tidak menentukan kunci generator, KMS kunci tunggal yang ditentukan oleh KmsKeyId parameter adalah kunci generator. Ini menghasilkan dan mengenkripsi kunci data yang mengenkripsi data.

Objek masukan ini membutuhkan AWS KMS klien untuk KMS kunci. Wilayah AWS Untuk membuat AWS KMS klien, buat instance AmazonKeyManagementServiceClient kelas di. AWS SDK for .NET Memanggil AmazonKeyManagementServiceClient() konstruktor tanpa parameter membuat klien dengan nilai default.

Dalam AWS KMS keyring yang digunakan untuk mengenkripsi dengan for. AWS Encryption SDK NET, Anda dapat mengidentifikasi KMS kunci dengan menggunakan ID kunci, kunciARN, nama alias, atau aliasARN. Dalam AWS KMS keyring yang digunakan untuk mendekripsi, Anda harus menggunakan kunci ARN untuk mengidentifikasi setiap kunci. KMS Jika Anda berencana untuk menggunakan kembali keyring enkripsi Anda untuk mendekripsi, gunakan ARN pengenal kunci untuk semua kunci. KMS

string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";

// Instantiate the keyring input object
var kmsKeyringInput = new CreateAwsKmsKeyringInput
{    
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = keyArn
};
Langkah 3: Buat keyring.

Untuk membuat keyring, panggil metode keyring dengan objek input keyring. Contoh ini menggunakan CreateAwsKmsKeyring() metode, yang hanya membutuhkan satu KMS kunci.

var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);
Langkah 4: Tentukan konteks enkripsi.

Konteks enkripsi adalah elemen opsional, tetapi sangat direkomendasikan dari operasi kriptografi dalam. AWS Encryption SDK Anda dapat menentukan satu atau lebih pasangan nilai kunci non-rahasia.

catatan

Dengan versi 4. x dari AWS Encryption SDK untuk. NET, Anda dapat memerlukan konteks enkripsi di semua permintaan enkripsi dengan konteks CMM enkripsi yang diperlukan.

// Define the encryption context
var encryptionContext = new Dictionary<string, string>()
{
    {"purpose", "test"}
};
Langkah 5: Buat objek input untuk mengenkripsi.

Sebelum memanggil Encrypt() metode, buat instance dari EncryptInput kelas.

string plaintext = File.ReadAllText("C:\\Documents\\CryptoTest\\TestFile.txt");
            
// Define the encrypt input
var encryptInput = new EncryptInput
{
    Plaintext = plaintext,
    Keyring = keyring,
    EncryptionContext = encryptionContext
};
Langkah 6: Enkripsi plaintext.

Gunakan Encrypt() metode AWS Encryption SDK untuk mengenkripsi plaintext menggunakan keyring yang Anda tentukan.

Encrypt() Metode EncryptOutput yang dikembalikan memiliki metode untuk mendapatkan pesan terenkripsi (Ciphertext), konteks enkripsi, dan rangkaian algoritma. 

var encryptOutput = encryptionSdk.Encrypt(encryptInput);
Langkah 7: Dapatkan pesan terenkripsi.

Decrypt()Metode di AWS Encryption SDK for. NETmengambil Ciphertext anggota EncryptOutput instance.

CiphertextAnggota EncryptOutput objek adalah pesan terenkripsi, objek portabel yang mencakup data terenkripsi, kunci data terenkripsi, dan metadata, termasuk konteks enkripsi. Anda dapat menyimpan pesan terenkripsi dengan aman untuk waktu yang lama atau mengirimkannya ke Decrypt() metode untuk memulihkan teks biasa. 

var encryptedMessage = encryptOutput.Ciphertext;

Mendekripsi dalam mode ketat di for. AWS Encryption SDK NET

Praktik terbaik menyarankan Anda menentukan kunci yang Anda gunakan untuk mendekripsi data, opsi yang dikenal sebagai mode ketat. Hanya AWS Encryption SDK menggunakan KMS kunci yang Anda tentukan di keyring Anda untuk mendekripsi ciphertext. Kunci dalam keyring dekripsi Anda harus menyertakan setidaknya salah satu kunci yang mengenkripsi data.

Contoh ini menunjukkan pola dasar dekripsi dalam mode ketat dengan for. AWS Encryption SDK NET.

Langkah 1: Buat instance perpustakaan penyedia materi AWS Encryption SDK dan.
// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
Langkah 2: Buat objek input untuk keyring Anda.

Untuk menentukan parameter untuk metode keyring, buat objek input. Setiap metode keyring di AWS Encryption SDK for. NETmemiliki objek input yang sesuai. Karena contoh ini menggunakan CreateAwsKmsKeyring() metode untuk membuat keyring, itu membuat instance CreateAwsKmsKeyringInput kelas untuk input.

Dalam keyring dekripsi, Anda harus menggunakan kunci ARN untuk mengidentifikasi kunci. KMS

string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";

// Instantiate the keyring input object
var kmsKeyringInput = new CreateAwsKmsKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = keyArn
};
Langkah 3: Buat keyring.

Untuk membuat keyring dekripsi, contoh ini menggunakan CreateAwsKmsKeyring() metode dan objek input keyring.

var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);
Langkah 4: Buat objek input untuk mendekripsi.

Untuk membuat objek masukan untuk Decrypt() metode, buat instance kelas. DecryptInput

CiphertextParameter DecryptInput() konstruktor mengambil Ciphertext anggota EncryptOutput objek yang dikembalikan Encrypt() metode. CiphertextProperti mewakili pesan terenkripsi, yang mencakup data terenkripsi, kunci data terenkripsi, dan metadata yang diperlukan untuk mendekripsi pesan. AWS Encryption SDK

Dengan versi 4. x dari AWS Encryption SDK untuk. NET, Anda dapat menggunakan EncryptionContext parameter opsional untuk menentukan konteks enkripsi Anda dalam Decrypt() metode.

Gunakan EncryptionContext parameter untuk memverifikasi bahwa konteks enkripsi yang digunakan pada enkripsi disertakan dalam konteks enkripsi yang digunakan untuk mendekripsi ciphertext. AWS Encryption SDK Menambahkan pasangan ke konteks enkripsi, termasuk tanda tangan digital jika Anda menggunakan rangkaian algoritme dengan penandatanganan, seperti rangkaian algoritme default.

var encryptedMessage = encryptOutput.Ciphertext;

var decryptInput = new DecryptInput
{
    Ciphertext = encryptedMessage,
    Keyring = keyring,
    EncryptionContext = encryptionContext // OPTIONAL
};
Langkah 5: Dekripsi ciphertext.
var decryptOutput = encryptionSdk.Decrypt(decryptInput);
Langkah 6: Verifikasi konteks enkripsi - Versi 3. x

Decrypt()Metode versi 3. x dari AWS Encryption SDK untuk. NETtidak mengambil konteks enkripsi. Ini mendapatkan nilai konteks enkripsi dari metadata dalam pesan terenkripsi. Namun, sebelum mengembalikan atau menggunakan plaintext, ini adalah praktik terbaik untuk memverifikasi bahwa konteks enkripsi yang digunakan untuk mendekripsi ciphertext mencakup konteks enkripsi yang Anda berikan saat mengenkripsi.

Verifikasi bahwa konteks enkripsi yang digunakan pada enkripsi disertakan dalam konteks enkripsi yang digunakan untuk mendekripsi ciphertext. AWS Encryption SDK Menambahkan pasangan ke konteks enkripsi, termasuk tanda tangan digital jika Anda menggunakan rangkaian algoritme dengan penandatanganan, seperti rangkaian algoritme default.

// Verify the encryption context
string contextKey = "purpose";
string contextValue = "test";

if (!decryptOutput.EncryptionContext.TryGetValue(contextKey, out var decryptContextValue)
    || !decryptContextValue.Equals(contextValue))
{
    throw new Exception("Encryption context does not match expected values");
}

Mendekripsi dengan keyring penemuan di for. AWS Encryption SDK NET

Daripada menentukan KMS kunci untuk dekripsi, Anda dapat memberikan keyring AWS KMS penemuan, yang merupakan keyring yang tidak menentukan kunci apa pun. KMS Keyring penemuan memungkinkan AWS Encryption SDK dekripsi data dengan menggunakan kunci mana pun yang dienkripsi, asalkan pemanggil memiliki izin dekripsi pada KMS kunci tersebut. Untuk praktik terbaik, tambahkan filter penemuan yang membatasi KMS kunci yang dapat digunakan untuk kunci tertentu pada Akun AWS partisi tertentu.

AWS Encryption SDK Untuk. NETmenyediakan keyring penemuan dasar yang membutuhkan AWS KMS klien dan penemuan multi-keyring yang mengharuskan Anda menentukan satu atau lebih. Wilayah AWS Klien dan Wilayah membatasi KMS kunci yang dapat digunakan untuk mendekripsi pesan terenkripsi. Objek input untuk kedua keyring mengambil filter penemuan yang direkomendasikan.

Contoh berikut menunjukkan pola untuk mendekripsi data dengan keyring AWS KMS penemuan dan filter penemuan.

Langkah 1: Buat instance AWS Encryption SDK dan perpustakaan penyedia materi.
// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
Langkah 2: Buat objek input untuk keyring.

Untuk menentukan parameter untuk metode keyring, buat objek input. Setiap metode keyring di AWS Encryption SDK for. NETmemiliki objek input yang sesuai. Karena contoh ini menggunakan CreateAwsKmsDiscoveryKeyring() metode untuk membuat keyring, itu membuat instance CreateAwsKmsDiscoveryKeyringInput kelas untuk input.

List<string> accounts = new List<string> { "111122223333" };

var discoveryKeyringInput = new CreateAwsKmsDiscoveryKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    DiscoveryFilter = new DiscoveryFilter()
    {
        AccountIds = accounts,
        Partition = "aws"
    }
};
Langkah 3: Buat keyring.

Untuk membuat keyring dekripsi, contoh ini menggunakan CreateAwsKmsDiscoveryKeyring() metode dan objek input keyring.

var discoveryKeyring = materialProviders.CreateAwsKmsDiscoveryKeyring(discoveryKeyringInput);
Langkah 4: Buat objek input untuk mendekripsi.

Untuk membuat objek masukan untuk Decrypt() metode, buat instance kelas. DecryptInput Nilai Ciphertext parameter adalah Ciphertext anggota EncryptOutput objek yang dikembalikan Encrypt() metode.

Dengan versi 4. x dari AWS Encryption SDK untuk. NET, Anda dapat menggunakan EncryptionContext parameter opsional untuk menentukan konteks enkripsi Anda dalam Decrypt() metode.

Gunakan EncryptionContext parameter untuk memverifikasi bahwa konteks enkripsi yang digunakan pada enkripsi disertakan dalam konteks enkripsi yang digunakan untuk mendekripsi ciphertext. AWS Encryption SDK Menambahkan pasangan ke konteks enkripsi, termasuk tanda tangan digital jika Anda menggunakan rangkaian algoritme dengan penandatanganan, seperti rangkaian algoritme default.

var ciphertext = encryptOutput.Ciphertext;

var decryptInput = new DecryptInput
{
    Ciphertext = ciphertext,
    Keyring = discoveryKeyring,
    EncryptionContext = encryptionContext // OPTIONAL
    
};
var decryptOutput = encryptionSdk.Decrypt(decryptInput);
Langkah 5: Verifikasi konteks enkripsi - Versi 3. x

Decrypt()Metode versi 3. x dari AWS Encryption SDK untuk. NETtidak mengambil konteks enkripsi padaDecrypt(). Ini mendapatkan nilai konteks enkripsi dari metadata dalam pesan terenkripsi. Namun, sebelum mengembalikan atau menggunakan plaintext, ini adalah praktik terbaik untuk memverifikasi bahwa konteks enkripsi yang digunakan untuk mendekripsi ciphertext mencakup konteks enkripsi yang Anda berikan saat mengenkripsi.

Verifikasi bahwa konteks enkripsi yang digunakan pada enkripsi disertakan dalam konteks enkripsi yang digunakan untuk mendekripsi ciphertext. AWS Encryption SDK Menambahkan pasangan ke konteks enkripsi, termasuk tanda tangan digital jika Anda menggunakan rangkaian algoritme dengan penandatanganan, seperti rangkaian algoritme default. 

// Verify the encryption context
string contextKey = "purpose";
string contextValue = "test";

if (!decryptOutput.EncryptionContext.TryGetValue(contextKey, out var decryptContextValue)
    || !decryptContextValue.Equals(contextValue))
{
    throw new Exception("Encryption context does not match expected values");
}