AWS Encryption SDK untuk contoh.NET - 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 contoh.NET

Contoh berikut menunjukkan pola pengkodean dasar yang Anda gunakan saat pemrograman 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 untuk .NET, lihat contoh di aws-encryption-sdk-net direktori aws-encryption-sdk repositori pada. GitHub

Mengenkripsi data di untuk .NET AWS Encryption SDK

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, kunci KMS 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 kunci KMS. 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 AWS Encryption SDK for .NET, Anda dapat mengidentifikasi kunci KMS dengan menggunakan ID kunci, kunci ARN, nama alias, atau alias ARN. Dalam AWS KMS keyring yang digunakan untuk mendekripsi, Anda harus menggunakan ARN kunci untuk mengidentifikasi setiap kunci KMS. Jika Anda berencana untuk menggunakan kembali keyring enkripsi Anda untuk mendekripsi, gunakan pengenal ARN 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 kunci KMS.

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 enkripsi CMM 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 dalam AWS Encryption SDK for .NET mengambil 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 untuk.NET AWS Encryption SDK

Praktik terbaik menyarankan Anda menentukan kunci yang Anda gunakan untuk mendekripsi data, opsi yang dikenal sebagai mode ketat. Hanya AWS Encryption SDK menggunakan kunci KMS yang Anda tentukan dalam 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 AWS Encryption SDK untuk .NET.

Langkah 1: Buat instantiate perpustakaan penyedia AWS Encryption SDK dan 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 Anda.

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

Dalam keyring dekripsi, Anda harus menggunakan ARN kunci 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 .NET tidak 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 .NET AWS Encryption SDK

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

The AWS Encryption SDK for .NET menyediakan 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 kunci KMS 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 .NET memiliki objek input yang sesuai. Karena contoh ini menggunakan CreateAwsKmsDiscoveryKeyring() metode untuk membuat keyring, contoh 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 .NET tidak 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");
}