AWS Encryption SDKuntuk .NET - AWS Encryption SDK
Instal dan bangunDebuggingAWS KMSgantungan kunciKonteks enkripsi yang diperlukan CMM

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

AWS Encryption SDKuntuk .NET

The AWS Encryption SDK for .NET adalah pustaka enkripsi sisi klien untuk pengembang yang menulis aplikasi dalam C # dan bahasa pemrograman.NET lainnya. Hal ini didukung di Windows, macOS, dan Linux.

Semua implementasi bahasa pemrograman sepenuhnya AWS Encryption SDK dapat dioperasikan. Namun, jika Anda mengenkripsi data menggunakan konteks enkripsi yang diperlukan CMM di versi 4. x dari AWS Encryption SDK untuk .NET, Anda hanya dapat mendekripsi dengan versi 4. x dari AWS Encryption SDK untuk .NET atau versi 3. x dariAWS Encryption SDK for Java.

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 NetV4_0_0_RetryPolicyproperti untuk mencegah klien membaca pesan-pesan ini. Untuk informasi lebih lanjut, lihat catatan rilis v4.0.1 di aws-encryption-sdk-dafny repositori di. GitHub

AWS Encryption SDKUntuk .NET berbeda dari beberapa implementasi bahasa pemrograman lainnya dengan AWS Encryption SDK cara berikut:

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 dariAWS Encryption SDK, Anda mungkin perlu menyesuaikan kebijakan komitmen Anda. Untuk detailnya, lihat Cara menetapkan kebijakan komitmen Anda.

The AWS Encryption SDK for .NET adalah produk dari AWS Encryption SDK in Dafny, 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 diAWS Encryption SDK, seperti menentukan rangkaian algoritme alternatif, membatasi kunci data terenkripsi, dan menggunakan kunci AWS KMS Multi-region, lihat. Mengkonfigurasi AWS Encryption SDK

  • Untuk detail tentang pemrograman dengan AWS Encryption SDK for .NET, lihat aws-encryption-sdk-netdirektori aws-encryption-sdk-dafny repositori di. GitHub

Topik

Instalasi AWS Encryption SDK untuk .NET

The AWS Encryption SDK for .NET tersedia sebagai AWS.Cryptography.EncryptionSDKpaket di NuGet. Untuk detail tentang menginstal dan membangun AWS Encryption SDK untuk .NET, lihat file README.md 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+ 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.

AWS Encryption SDKUntuk .NET membutuhkan AWS SDK for .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 memerlukanAkun AWS, AWS kredensi, atau interaksi dengan layanan apa punAWS. Untuk bantuan menyiapkan AWS akun jika Anda membutuhkannya, lihatMenggunakan AWS Encryption SDK dengan AWS KMS.

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. AWS SDK for .NET Log dan pesan kesalahan dari AWS SDK for .NET dapat membantu Anda membedakan kesalahan yang timbul AWS SDK for .NET dari yang ada di AWS Encryption SDK untuk .NET. Untuk bantuan terkait AWS SDK for .NET logging, lihat AWSLoggingdi Panduan AWS SDK for .NET Pengembang. (Untuk melihat topiknya, perluas bagian konten Open to view .NET Framework.)

AWS KMSgantungan kunci di AWS Encryption SDK untuk .NET

AWS KMSGantungan kunci dasar AWS Encryption SDK untuk .NET hanya mengambil satu kunci KMS. Mereka juga membutuhkan AWS KMS klien, yang memberi Anda kesempatan untuk mengkonfigurasi klien untuk kunci KMS. Wilayah AWS

Untuk membuat AWS KMS keyring dengan satu atau lebih tombol pembungkus, gunakan multi-keyring. AWS Encryption SDKUntuk .NET memiliki multi-keyring khusus yang mengambil satu atau lebih AWS KMS tombol, dan multi-keyring standar yang mengambil satu atau lebih keyring dari jenis apa pun yang didukung. Beberapa programmer lebih suka menggunakan metode multi-keyring untuk membuat semua keyrings mereka, dan AWS Encryption SDK untuk .NET mendukung strategi itu.

The AWS Encryption SDK for .NET menyediakan keyrings single-key dasar dan multi-keyrings untuk semua kasus penggunaan umum, termasuk kunci Multi-region. AWS KMS

Misalnya, untuk membuat AWS KMS keyring dengan satu AWS KMS tombol, Anda dapat menggunakan CreateAwsKmsKeyring() metode ini.

Version 3.x

Contoh berikut menggunakan versi 3. x dari AWS Encryption SDK untuk.NET untuk membuat AWS KMS klien default untuk Wilayah yang berisi kunci yang ditentukan.

// Instantiate the AWS Encryption SDK and material providers
var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk();
var materialProviders =
    AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();

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

// Create the keyring
var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);
Version 4.x

Contoh berikut menggunakan versi 4. x dari AWS Encryption SDK untuk.NET untuk membuat AWS KMS klien untuk Wilayah yang berisi kunci yang ditentukan.

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

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

// Instantiate the keyring input object
var createKeyringInput = new CreateAwsKmsKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = kmsArn
};

// Create the keyring
var kmsKeyring = mpl.CreateAwsKmsKeyring(createKeyringInput);

Untuk membuat keyring dengan satu atau lebih AWS KMS tombol, gunakan CreateAwsKmsMultiKeyring() metode ini. Contoh ini menggunakan dua AWS KMS kunci. Untuk menentukan satu kunci KMS, gunakan hanya Generator parameter. KmsKeyIdsParameter yang menentukan kunci KMS tambahan adalah opsional.

Input untuk keyring ini tidak membutuhkan AWS KMS klien. Sebaliknya, AWS Encryption SDK menggunakan AWS KMS klien default untuk setiap Wilayah diwakili oleh kunci KMS di keyring. Misalnya, jika kunci KMS yang diidentifikasi oleh nilai Generator parameter berada di Wilayah AS Barat (Oregon) (us-west-2), akan AWS Encryption SDK membuat AWS KMS klien default untuk Wilayah tersebutus-west-2. Jika Anda perlu menyesuaikan AWS KMS klien, gunakan CreateAwsKmsKeyring() metode ini.

Contoh berikut menggunakan versi 4. x AWS Encryption SDK untuk .NET dan CreateAwsKmsKeyring() metode untuk menyesuaikan AWS KMS klien.

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

string generatorKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
List<string> additionalKeys = new List<string> { "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321" };

// Instantiate the keyring input object
var createEncryptKeyringInput = new CreateAwsKmsMultiKeyringInput
{
    Generator = generatorKey,
    KmsKeyIds = additionalKeys
};

var kmsEncryptKeyring = materialProviders.CreateAwsKmsMultiKeyring(createEncryptKeyringInput);

Versi 4. x dari AWS Encryption SDK untuk .NET mendukung AWS KMS keyrings yang menggunakan enkripsi simetris (SYMMETRIC_DEFAULT) atau kunci KMS RSA asimetris. AWS KMSkeyrings yang dibuat dengan kunci KMS RSA asimetris hanya dapat berisi satu key pair.

Untuk mengenkripsi dengan AWS KMS keyring RSA asimetris, Anda tidak perlu kms: GenerateDataKey atau KMS:Encrypt karena Anda harus menentukan materi kunci publik yang ingin Anda gunakan untuk enkripsi saat Anda membuat keyring. Tidak ada AWS KMS panggilan yang dilakukan saat mengenkripsi dengan keyring ini. Untuk mendekripsi dengan AWS KMS keyring RSA asimetris, Anda memerlukan izin KMS: Dekripsi.

Untuk membuat AWS KMS keyring RSA asimetris, Anda harus memberikan kunci publik dan kunci pribadi ARN dari kunci KMS RSA asimetris Anda. Kunci publik harus dikodekan PEM. Contoh berikut membuat AWS KMS keyring dengan asimetris RSA key pair.

// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
        
var publicKey = new MemoryStream(Encoding.UTF8.GetBytes(AWS KMS RSA public key));

// Instantiate the keyring input object
var createKeyringInput = new CreateAwsKmsRsaKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = AWS KMS RSA private key ARN,
    PublicKey = publicKey,
    EncryptionAlgorithm = EncryptionAlgorithmSpec.RSAES_OAEP_SHA_256
};

// Create the keyring
var kmsRsaKeyring = mpl.CreateAwsKmsRsaKeyring(createKeyringInput);

Konteks enkripsi yang diperlukan dalam versi 4.x

Dengan versi 4. x dari AWS Encryption SDK untuk .NET, Anda dapat menggunakan konteks enkripsi CMM yang diperlukan untuk memerlukan konteks enkripsi dalam operasi kriptografi Anda. Konteks enkripsi adalah sekumpulan pasangan kunci-nilai non-rahasia. Konteks enkripsi terikat secara kriptografis ke data terenkripsi sehingga konteks enkripsi yang sama diperlukan untuk mendekripsi bidang. Bila Anda menggunakan konteks enkripsi CMM yang diperlukan, Anda dapat menentukan satu atau beberapa kunci konteks enkripsi yang diperlukan (kunci wajib) yang harus disertakan dalam semua panggilan enkripsi dan dekripsi.

catatan

Konteks enkripsi yang diperlukan CMM hanya dapat dioperasikan dengan versi 3. x dariAWS Encryption SDK for Java. Ini tidak dapat dioperasikan dengan implementasi bahasa pemrograman lainnya. Jika Anda mengenkripsi data menggunakan konteks enkripsi CMM yang diperlukan, Anda hanya dapat mendekripsi dengan versi 3. x dari AWS Encryption SDK for Java atau versi 4. x dari AWS Encryption SDK untuk .NET.

Pada enkripsi, AWS Encryption SDK memverifikasi bahwa semua kunci konteks enkripsi yang diperlukan disertakan dalam konteks enkripsi yang Anda tentukan. AWS Encryption SDKTanda konteks enkripsi yang Anda tentukan. Hanya pasangan kunci-nilai yang bukan kunci wajib yang diserialisasi dan disimpan dalam teks biasa di header pesan terenkripsi yang dikembalikan oleh operasi enkripsi.

Saat mendekripsi, Anda harus menyediakan konteks enkripsi yang berisi semua pasangan kunci-nilai yang mewakili kunci yang diperlukan. AWS Encryption SDKMenggunakan konteks enkripsi ini dan pasangan kunci-nilai yang disimpan dalam header pesan terenkripsi untuk merekonstruksi konteks enkripsi asli yang Anda tentukan dalam operasi enkripsi. Jika AWS Encryption SDK tidak dapat merekonstruksi konteks enkripsi asli, maka operasi dekripsi gagal. Jika Anda memberikan pasangan kunci-nilai yang berisi kunci yang diperlukan dengan nilai yang salah, pesan terenkripsi tidak dapat didekripsi. Anda harus memberikan pasangan nilai kunci yang sama yang ditentukan pada enkripsi.

penting

Pertimbangkan dengan cermat nilai mana yang Anda pilih untuk kunci yang diperlukan dalam konteks enkripsi Anda. Anda harus dapat memberikan kunci yang sama dan nilai yang sesuai lagi pada dekripsi. Jika Anda tidak dapat mereproduksi kunci yang diperlukan, pesan terenkripsi tidak dapat didekripsi.

Contoh berikut menginisialisasi AWS KMS keyring dengan konteks enkripsi CMM yang diperlukan.

var encryptionContext = new Dictionary<string, string>()
{
    {"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 and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
        
// Instantiate the keyring input object
var createKeyringInput = new CreateAwsKmsKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = kmsKey
};
 
// Create the keyring 
var kmsKeyring = mpl.CreateAwsKmsKeyring(createKeyringInput);
        
var createCMMInput = new CreateRequiredEncryptionContextCMMInput
{
    UnderlyingCMM = mpl.CreateDefaultCryptographicMaterialsManager(new CreateDefaultCryptographicMaterialsManagerInput{Keyring = kmsKeyring}),
    // If you pass in a keyring but no underlying cmm, it will result in a failure because only cmm is supported.
    RequiredEncryptionContextKeys = new List<string>(encryptionContext.Keys)
};
 
// Create the required encryption context CMM
var requiredEcCMM = mpl.CreateRequiredEncryptionContextCMM(createCMMInput);

Jika Anda menggunakan AWS KMS keyring, AWS Encryption SDK for .NET juga menggunakan konteks enkripsi untuk menyediakan data otentikasi tambahan (AAD) dalam panggilan yang dilakukan oleh keyring. AWS KMS