Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# AWS Encryption SDK untuk .NET
The AWS Encryption SDK for .NET adalah pustaka enkripsi sisi klien untuk pengembang yang menulis aplikasi dalam C \$1 dan bahasa pemrograman.NET lainnya. Hal ini didukung di Windows, macOS, dan Linux.
**catatan**
Versi 4.0.0 AWS Encryption SDK untuk .NET menyimpang dari Spesifikasi Pesan. AWS Encryption SDK Akibatnya, pesan yang dienkripsi oleh versi 4.0.0 hanya dapat didekripsi oleh versi 4.0.0 atau yang lebih baru untuk .NET. AWS Encryption SDK Mereka tidak dapat didekripsi oleh implementasi bahasa pemrograman lainnya.
Versi 4.0.1 AWS Encryption SDK untuk .NET menulis pesan sesuai dengan Spesifikasi AWS Encryption SDK Pesan, dan interoperable dengan implementasi bahasa pemrograman lainnya. Secara default, versi 4.0.1 dapat membaca pesan yang dienkripsi oleh versi 4.0.0. Namun, jika Anda tidak ingin mendekripsi pesan yang dienkripsi oleh versi 4.0.0, Anda dapat menentukan [https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples/NetV4_0_0Example.cs](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples/NetV4_0_0Example.cs)properti untuk mencegah klien membaca pesan-pesan ini. Untuk informasi lebih lanjut, lihat [catatan rilis v4.0.1](https://github.com/aws/aws-encryption-sdk/releases/tag/v4.0.1) di aws-encryption-sdk repositori di. GitHub
AWS Encryption SDK Untuk .NET berbeda dari beberapa implementasi bahasa pemrograman lainnya dengan AWS Encryption SDK cara berikut:
+ Tidak ada dukungan untuk [caching kunci data](data-key-caching.md)
**catatan**
Versi 4. *x* dari AWS Encryption SDK untuk .NET mendukung [keyring AWS KMS Hierarchical, solusi](use-hierarchical-keyring.md) caching bahan kriptografi alternatif.
+ Tidak ada dukungan untuk streaming data
+ [Tidak ada pencatatan atau jejak tumpukan](#dot-net-debugging) dari AWS Encryption SDK untuk .NET
+ [Membutuhkan AWS SDK untuk .NET](#dot-net-install)
The AWS Encryption SDK for .NET mencakup semua fitur keamanan yang diperkenalkan dalam versi 2.0. *x* dan yang lebih baru dari implementasi bahasa lain dari. AWS Encryption SDK Namun, jika Anda menggunakan AWS Encryption SDK untuk.NET untuk mendekripsi data yang dienkripsi oleh pra-2.0. *x* versi implementasi bahasa lain dari AWS Encryption SDK, Anda mungkin perlu menyesuaikan [kebijakan komitmen](concepts.md#commitment-policy) Anda. Lihat perinciannya di [Cara menetapkan kebijakan komitmen Anda](migrate-commitment-policy.md#migrate-commitment-step1).
The AWS Encryption SDK for .NET adalah produk dari AWS Encryption SDK in [Dafny](https://github.com/dafny-lang/dafny/blob/master/README.md), bahasa verifikasi formal di mana Anda menulis spesifikasi, kode untuk mengimplementasikannya, dan bukti untuk mengujinya. Hasilnya adalah perpustakaan yang mengimplementasikan fitur-fitur AWS Encryption SDK dalam kerangka kerja yang menjamin kebenaran fungsional.
**Pelajari Lebih Lanjut**
+ 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](configure.md)
+ Untuk detail tentang pemrograman dengan AWS Encryption SDK for .NET, lihat [https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/)direktori aws-encryption-sdk repositori di. GitHub
**Topics**
+ [Instal dan bangun](#dot-net-install)
+ [Debugging](#dot-net-debugging)
+ [Contoh](dot-net-examples.md)
## Instalasi AWS Encryption SDK untuk .NET
AWS Encryption SDK Untuk .NET tersedia sebagai [https://www.nuget.org/packages/AWS.Cryptography.EncryptionSDK](https://www.nuget.org/packages/AWS.Cryptography.EncryptionSDK)paket di NuGet. Untuk detail tentang menginstal dan membangun AWS Encryption SDK untuk .NET, lihat file [README.md](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/#readme) di repositori. `aws-encryption-sdk-net`
**Versi 3.x**
Versi 3. *x* dari AWS Encryption SDK untuk .NET mendukung .NET Framework 4.5.2 - 4.8 hanya pada Windows. Ini mendukung .NET Core 3.0\$1 dan .NET 5.0 dan kemudian pada semua sistem operasi yang didukung.
**Versi 4.x**
Versi 4. *x* dari AWS Encryption SDK untuk .NET mendukung .NET 6.0 dan .NET Framework net48 dan yang lebih baru. Versi 4. *x* membutuhkan AWS SDK untuk.NET v3.
**Versi 5.x**
Versi 5. *x* dari AWS Encryption SDK untuk .NET mendukung .NET 6.0 dan .NET Framework net48 dan yang lebih baru. Versi 5. *x* membutuhkan versi 2. *x* dari Material Providers Library (MPL) dan AWS SDK for .NET v4.
AWS Encryption SDK Untuk .NET membutuhkan SDK untuk .NET bahkan jika Anda tidak menggunakan kunci AWS Key Management Service (AWS KMS). Itu diinstal dengan NuGet paket. Namun, kecuali Anda menggunakan AWS KMS kunci, AWS Encryption SDK untuk .NET tidak memerlukan Akun AWS, AWS kredensi, atau interaksi dengan layanan apa pun AWS . Untuk bantuan menyiapkan AWS akun jika Anda membutuhkannya, lihat[Menggunakan AWS Encryption SDK dengan AWS KMS](getting-started.md).
## Debugging AWS Encryption SDK untuk .NET
The AWS Encryption SDK for .NET tidak menghasilkan log apa pun. Pengecualian di AWS Encryption SDK for .NET menghasilkan pesan pengecualian, tetapi tidak ada jejak tumpukan.
Untuk membantu Anda men-debug, pastikan untuk mengaktifkan login. SDK untuk .NET Log dan pesan kesalahan dari SDK untuk .NET dapat membantu Anda membedakan kesalahan yang timbul SDK untuk .NET dari yang ada di AWS Encryption SDK untuk .NET. Untuk bantuan terkait SDK untuk .NET logging, lihat [AWSLogging](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/net-dg-config-other.html#config-setting-awslogging)di *Panduan AWS SDK untuk .NET Pengembang*. (Untuk melihat topiknya, perluas bagian **konten Open to view .NET Framework**.)
# 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 SDK untuk .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](configure.md)
Untuk lebih banyak contoh pemrograman dengan AWS Encryption SDK untuk .NET, lihat [contoh](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples) 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.
```
// Instantiate the AWS Encryption SDK and material providers
var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk();
var materialProviders =
AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();
```
```
// 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](use-kms-keyring.md#kms-keyring-encrypt) 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. SDK untuk .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](use-kms-keyring.md#kms-keyring-id) 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](concepts.md#encryption-context) adalah elemen opsional, tetapi sangat direkomendasikan dari operasi kriptografi dalam. AWS Encryption SDK Anda dapat menentukan satu atau lebih pasangan nilai kunci non-rahasia.
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](configure.md#config-required-encryption-context-cmm).
```
// Define the encryption context
var encryptionContext = new Dictionary()
{
{"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.
`Ciphertext`Anggota `EncryptOutput` objek adalah [pesan terenkripsi](concepts.md#message), 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, itu membuat instance `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`
`Ciphertext`Parameter `DecryptInput()` konstruktor mengambil `Ciphertext` anggota `EncryptOutput` objek yang dikembalikan `Encrypt()` metode. `Ciphertext`Properti mewakili [pesan terenkripsi](concepts.md#message), 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, itu membuat instance `CreateAwsKmsDiscoveryKeyringInput` kelas untuk input.
```
List accounts = new List { "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 pada`Decrypt()`. 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");
}
```