Memilih bahasa pemrograman Memilih tombol pembungkus Menggunakan Multi-region AWS KMS keys Memilih rangkaian algoritma Membatasi kunci data terenkripsi Membuat filter penemuan Menetapkan kebijakan komitmen Bekerja dengan data streaming Kunci data cache

Mengkonfigurasi AWS Encryption SDK

AWS Encryption SDK Ini dirancang agar mudah digunakan. Meskipun AWS Encryption SDK memiliki beberapa opsi konfigurasi, nilai default dipilih dengan cermat agar praktis dan aman untuk sebagian besar aplikasi. Namun, Anda mungkin perlu menyesuaikan konfigurasi untuk meningkatkan kinerja atau menyertakan fitur khusus dalam desain Anda.

Saat mengonfigurasi implementasi Anda, tinjau praktik AWS Encryption SDK terbaik dan terapkan sebanyak yang Anda bisa.

Memilih bahasa pemrograman

AWS Encryption SDK Ini tersedia dalam berbagai bahasa pemrograman. Implementasi bahasa dirancang untuk sepenuhnya dapat dioperasikan dan menawarkan fitur yang sama, meskipun mereka mungkin diimplementasikan dengan cara yang berbeda. Biasanya, Anda menggunakan perpustakaan yang kompatibel dengan aplikasi Anda. Namun, Anda dapat memilih bahasa pemrograman untuk implementasi tertentu. Misalnya, jika Anda lebih suka bekerja dengan gantungan kunci, Anda dapat memilih AWS Encryption SDK for C atau. AWS Encryption SDK for JavaScript

Memilih tombol pembungkus

Ini AWS Encryption SDK menghasilkan kunci data simetris yang unik untuk mengenkripsi setiap pesan. Kecuali Anda menggunakan caching kunci data, Anda tidak perlu mengkonfigurasi, mengelola, atau menggunakan kunci data. Yang AWS Encryption SDK melakukannya untuk Anda.

Namun, Anda harus memilih satu atau lebih kunci pembungkus untuk mengenkripsi setiap kunci data. AWS Encryption SDK Mendukung tombol AES simetris dan tombol RSA asimetris dalam berbagai ukuran. Ini juga mendukung enkripsi AWS KMS keys simetris AWS Key Management Service(AWS KMS). Anda bertanggung jawab atas keamanan dan daya tahan kunci pembungkus Anda, jadi kami sarankan Anda menggunakan kunci enkripsi dalam modul keamanan perangkat keras atau layanan infrastruktur utama, seperti AWS KMS.

Untuk menentukan kunci pembungkus Anda untuk enkripsi dan dekripsi, Anda menggunakan keyring (C dan JavaScript) atau penyedia kunci master (Java, Python, Enkripsi). AWS CLI Anda dapat menentukan satu kunci pembungkus atau beberapa kunci pembungkus dari jenis yang sama atau berbeda. Jika Anda menggunakan beberapa kunci pembungkus untuk membungkus kunci data, setiap kunci pembungkus akan mengenkripsi salinan kunci data yang sama. Kunci data terenkripsi (satu per kunci pembungkus) disimpan dengan data terenkripsi dalam pesan terenkripsi yang dikembalikan. AWS Encryption SDK Untuk mendekripsi data, pertama-tama AWS Encryption SDK harus menggunakan salah satu kunci pembungkus Anda untuk mendekripsi kunci data terenkripsi.

Untuk menentukan AWS KMS key dalam keyring atau penyedia kunci utama, gunakan pengenal AWS KMS kunci yang didukung. Untuk detail tentang pengidentifikasi kunci untuk AWS KMS kunci, lihat Pengidentifikasi Kunci di Panduan AWS Key Management Service Pengembang.

Saat mengenkripsi dengan AWS Encryption SDK for Java,, AWS Encryption SDK for JavaScript, atau AWS Enkripsi AWS Encryption SDK for Python CLI, Anda dapat menggunakan pengidentifikasi kunci yang valid (ID kunci, kunci, nama aliasARN, atau aliasARN) untuk kunci. KMS Saat mengenkripsi dengan AWS Encryption SDK for C, Anda hanya dapat menggunakan ID kunci atau kunci. ARN

Jika Anda menentukan nama alias atau alias ARN untuk KMS kunci saat mengenkripsi, kunci yang ARN saat ini terkait dengan alias itu; itu tidak AWS Encryption SDK menyimpan alias. Perubahan pada alias tidak memengaruhi kunci yang digunakan untuk mendekripsi KMS kunci data Anda.
Saat mendekripsi dalam mode ketat (di mana Anda menentukan kunci pembungkus tertentu), Anda harus menggunakan kunci ARN untuk mengidentifikasi. AWS KMS keys Persyaratan ini berlaku untuk semua implementasi bahasa dari. AWS Encryption SDK

Ketika Anda mengenkripsi dengan AWS KMS keyring, AWS Encryption SDK menyimpan kunci ARN AWS KMS key dalam metadata kunci data terenkripsi. Saat mendekripsi dalam mode ketat, AWS Encryption SDK memverifikasi bahwa kunci yang sama ARN muncul di keyring (atau penyedia kunci utama) sebelum mencoba menggunakan kunci pembungkus untuk mendekripsi kunci data terenkripsi. Jika Anda menggunakan pengenal kunci yang berbeda, tidak AWS Encryption SDK akan mengenali atau menggunakan AWS KMS key, bahkan jika pengidentifikasi merujuk ke kunci yang sama.

Untuk menentukan AESkunci mentah atau raw RSA key pair sebagai kunci pembungkus dalam keyring, Anda harus menentukan namespace dan nama. Dalam penyedia kunci master, Provider ID adalah setara dengan namespace dan setara dengan nama. Key ID Saat mendekripsi, Anda harus menggunakan namespace dan nama yang sama persis untuk setiap kunci pembungkus mentah seperti yang Anda gunakan saat mengenkripsi. Jika Anda menggunakan namespace atau nama yang berbeda, tidak AWS Encryption SDK akan mengenali atau menggunakan kunci pembungkus, meskipun materi kuncinya sama.

Menggunakan Multi-region AWS KMS keys

Anda dapat menggunakan AWS Key Management Service (AWS KMS) Tombol multi-region sebagai kunci pembungkus di. AWS Encryption SDK Jika Anda mengenkripsi dengan kunci Multi-wilayah dalam satu Wilayah AWS, Anda dapat mendekripsi menggunakan kunci Multi-wilayah terkait di yang berbeda. Wilayah AWS Support untuk kunci Multi-region diperkenalkan di versi 2.3. x dari AWS Encryption SDK dan versi 3.0. x dari AWS EnkripsiCLI.

AWS KMS Kunci multi-wilayah adalah satu set berbeda AWS KMS keys Wilayah AWS yang memiliki bahan kunci dan ID kunci yang sama. Anda dapat menggunakan kunci terkait ini seolah-olah mereka adalah kunci yang sama di Wilayah yang berbeda. Kunci Multi-Region mendukung pemulihan bencana umum dan skenario pencadangan yang memerlukan enkripsi di satu Wilayah dan mendekripsi di Wilayah yang berbeda tanpa melakukan panggilan lintas wilayah. AWS KMS Untuk informasi tentang kunci Multi-region, lihat Menggunakan kunci Multi-region di Panduan AWS Key Management Service Pengembang.

Untuk mendukung kunci Multi-wilayah, AWS Encryption SDK termasuk gantungan kunci AWS KMS sadar Multi-wilayah dan penyedia kunci utama. Simbol Multi-Region-aware baru di setiap bahasa pemrograman mendukung kunci Single-region dan Multi-region.

Untuk kunci Single-region, simbol Multi-region-aware berperilaku seperti keyring wilayah tunggal AWS KMS dan penyedia kunci master. Ini mencoba untuk mendekripsi ciphertext hanya dengan kunci Single-region yang mengenkripsi data.
Untuk kunci Multi-region, simbol Multi-Region-aware mencoba mendekripsi ciphertext dengan kunci Multi-region yang sama yang mengenkripsi data atau dengan kunci replika Multi-region terkait di Wilayah yang Anda tentukan.

Di gantungan kunci Multi-Region-aware dan penyedia kunci master yang mengambil lebih dari satu kunci, Anda dapat menentukan beberapa KMS kunci Single-region dan Multi-region. Namun, Anda hanya dapat menentukan satu kunci dari setiap set kunci replika Multi-wilayah terkait. Jika Anda menentukan lebih dari satu pengenal kunci dengan ID kunci yang sama, panggilan konstruktor gagal.

Anda juga dapat menggunakan kunci Multi-region dengan AWS KMS keyring standar, Single-region dan penyedia kunci master. Namun, Anda harus menggunakan kunci Multi-region yang sama di Wilayah yang sama untuk mengenkripsi dan mendekripsi. Keyring wilayah tunggal dan penyedia kunci utama mencoba mendekripsi ciphertext hanya dengan kunci yang mengenkripsi data.

Contoh berikut menunjukkan cara mengenkripsi dan mendekripsi data menggunakan kunci Multi-region dan keyring Multi-Region-aware baru dan penyedia kunci master. Contoh-contoh ini mengenkripsi data di us-east-1 Wilayah dan mendekripsi data di us-west-2 Wilayah menggunakan kunci replika Multi-wilayah terkait di setiap Wilayah. Sebelum menjalankan contoh ini, ganti contoh Multi-region key ARN dengan nilai yang valid dari Anda Akun AWS.

C

Untuk mengenkripsi dengan kunci Multi-region, gunakan Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder() metode ini untuk membuat instance keyring. Tentukan kunci Multi-wilayah.

Contoh sederhana ini tidak termasuk konteks enkripsi. Untuk contoh yang menggunakan konteks enkripsi di C, lihatMengenkripsi dan mendekripsi string.

Untuk contoh lengkap, lihat kms_multi_region_keys.cpp di AWS Encryption SDK for C repositori pada. GitHub


/* Encrypt with a multi-Region KMS key in us-east-1 */

/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();

/* Initialize a multi-Region keyring */
const char *mrk_us_east_1 = "arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab";   

struct aws_cryptosdk_keyring *mrk_keyring = 
    Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder().Build(mrk_us_east_1);

/* Create a session; release the keyring */
struct aws_cryptosdk_session *session =
    aws_cryptosdk_session_new_from_keyring_2(aws_default_allocator(), AWS_CRYPTOSDK_ENCRYPT, mrk_keyring);

aws_cryptosdk_keyring_release(mrk_keyring);

/* Encrypt the data
 *   aws_cryptosdk_session_process_full is designed for non-streaming data
 */
aws_cryptosdk_session_process_full(
    session, ciphertext, ciphertext_buf_sz, &ciphertext_len, plaintext, plaintext_len));

/* Clean up the session */
aws_cryptosdk_session_destroy(session);

C# / .NET

Untuk mengenkripsi dengan kunci Multi-region di Wilayah AS Timur (Virginia N.) (us-east-1), buat instance CreateAwsKmsMrkKeyringInput objek dengan pengenal kunci untuk kunci Multi-region dan klien untuk Wilayah yang ditentukan. AWS KMS Kemudian gunakan CreateAwsKmsMrkKeyring() metode untuk membuat keyring.

CreateAwsKmsMrkKeyring()Metode ini membuat keyring dengan tepat satu kunci Multi-region. Untuk mengenkripsi dengan beberapa kunci pembungkus, termasuk kunci Multi-wilayah, gunakan metode ini. CreateAwsKmsMrkMultiKeyring()

Untuk contoh lengkapnya, lihat AwsKmsMrkKeyringExample.cs di AWS Encryption SDK for. NETrepositori aktif. GitHub


//Encrypt with a multi-Region KMS key in us-east-1 Region

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


// Multi-Region keys have a distinctive key ID that begins with 'mrk'
// Specify a multi-Region key in us-east-1
string mrkUSEast1 = "arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab";

// Create the keyring
// You can specify the Region or get the Region from the key ARN
var createMrkEncryptKeyringInput = new CreateAwsKmsMrkKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(RegionEndpoint.USEast1),
    KmsKeyId = mrkUSEast1
};
var mrkEncryptKeyring = materialProviders.CreateAwsKmsMrkKeyring(createMrkEncryptKeyringInput);

// Define the encryption context
var encryptionContext = new Dictionary<string, string>()
{
    {"purpose", "test"}
};

// Encrypt your plaintext data.
var encryptInput = new EncryptInput
{
    Plaintext = plaintext,
    Keyring = mrkEncryptKeyring,
    EncryptionContext = encryptionContext
};
var encryptOutput = encryptionSdk.Encrypt(encryptInput);

AWS Encryption CLI

Contoh ini mengenkripsi hello.txt file di bawah kunci Multi-region di Wilayah us-east-1. Karena contoh menentukan kunci ARN dengan elemen Region, contoh ini tidak menggunakan atribut region dari --wrapping-keys parameter.

Jika ID kunci dari kunci pembungkus tidak menentukan Wilayah, Anda dapat menggunakan atribut region --wrapping-keys untuk menentukan wilayah, seperti--wrapping-keys key=$keyID region=us-east-1.


# Encrypt with a multi-Region KMS key in us-east-1 Region

# To run this example, replace the fictitious key ARN with a valid value.
$ mrkUSEast1=arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab

$ aws-encryption-cli --encrypt \
                     --input hello.txt \
                     --wrapping-keys key=$mrkUSEast1 \
                     --metadata-output ~/metadata \
                     --encryption-context purpose=test \
                     --output .

Java

Untuk mengenkripsi dengan kunci Multi-region, buat instance AwsKmsMrkAwareMasterKeyProvider dan tentukan kunci Multi-region.

Untuk contoh lengkap, lihat BasicMultiRegionKeyEncryptionExample.javadi AWS Encryption SDK for Java repositori pada. GitHub


//Encrypt with a multi-Region KMS key in us-east-1 Region

// Instantiate the client
final AwsCrypto crypto = AwsCrypto.builder()
    .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
    .build();

// Multi-Region keys have a distinctive key ID that begins with 'mrk'
// Specify a multi-Region key in us-east-1
final String mrkUSEast1 = "arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab";

// Instantiate an AWS KMS master key provider in strict mode for multi-Region keys
// Configure it to encrypt with the multi-Region key in us-east-1
final AwsKmsMrkAwareMasterKeyProvider kmsMrkProvider = AwsKmsMrkAwareMasterKeyProvider
    .builder()
    .buildStrict(mrkUSEast1);

// Create an encryption context
final Map<String, String> encryptionContext = Collections.singletonMap("Purpose", "Test");

// Encrypt your plaintext data
final CryptoResult<byte[], AwsKmsMrkAwareMasterKey> encryptResult = crypto.encryptData(
    kmsMrkProvider,
    encryptionContext,
    sourcePlaintext);
byte[] ciphertext = encryptResult.getResult();

JavaScript Browser

Untuk mengenkripsi dengan kunci Multi-region, gunakan buildAwsKmsMrkAwareStrictMultiKeyringBrowser() metode untuk membuat keyring dan tentukan kunci Multi-region.

Untuk contoh lengkap, lihat kms_multi_region_simple.ts di repositori pada. AWS Encryption SDK for JavaScript GitHub


/* Encrypt with a multi-Region KMS key in us-east-1 Region */

import {
  buildAwsKmsMrkAwareStrictMultiKeyringBrowser,
  buildClient,
  CommitmentPolicy,
  KMS,
} from '@aws-crypto/client-browser'


/* Instantiate an AWS Encryption SDK client */
const { encrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)

declare const credentials: {
  accessKeyId: string
  secretAccessKey: string
  sessionToken: string
}

/* Instantiate an AWS KMS client 
 * The AWS Encryption SDK for JavaScript gets the Region from the key ARN
 */
const clientProvider = (region: string) => new KMS({ region, credentials })


/* Specify a multi-Region key in us-east-1 */
const multiRegionUsEastKey =
    'arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'

/* Instantiate the keyring */
const encryptKeyring = buildAwsKmsMrkAwareStrictMultiKeyringBrowser({
    generatorKeyId: multiRegionUsEastKey,
    clientProvider,
  })


/* Set the encryption context */
const context = {
    purpose: 'test',
  }

/* Test data to encrypt */
const cleartext = new Uint8Array([1, 2, 3, 4, 5])

/* Encrypt the data */
const { result } = await encrypt(encryptKeyring, cleartext, {
    encryptionContext: context,
  })

JavaScript Node.js

Untuk mengenkripsi dengan kunci Multi-region, gunakan buildAwsKmsMrkAwareStrictMultiKeyringNode() metode untuk membuat keyring dan tentukan kunci Multi-region.

Untuk contoh lengkap, lihat kms_multi_region_simple.ts di repositori pada. AWS Encryption SDK for JavaScript GitHub


//Encrypt with a multi-Region KMS key in us-east-1 Region

import { buildClient } from '@aws-crypto/client-node'

/* Instantiate the AWS Encryption SDK client
const { encrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)

/* Test string to encrypt */
const cleartext = 'asdf'

/* Multi-Region keys have a distinctive key ID that begins with 'mrk'
 * Specify a multi-Region key in us-east-1
 */
const multiRegionUsEastKey =
    'arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'

/* Create an AWS KMS keyring */
const mrkEncryptKeyring = buildAwsKmsMrkAwareStrictMultiKeyringNode({
    generatorKeyId: multiRegionUsEastKey,
  })

/* Specify an encryption context */
const context = {
    purpose: 'test',
  }

/* Create an encryption keyring */
const { result } = await encrypt(mrkEncryptKeyring, cleartext, {
    encryptionContext: context,
  })

Python

Untuk mengenkripsi dengan kunci AWS KMS Multi-region, gunakan MRKAwareStrictAwsKmsMasterKeyProvider() metode dan tentukan kunci Multi-region.

Untuk contoh lengkap, lihat mrk_aware_kms_provider.py di AWS Encryption SDK for Python repositori pada. GitHub


* Encrypt with a multi-Region KMS key in us-east-1 Region

# Instantiate the client
client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT)

# Specify a multi-Region key in us-east-1
mrk_us_east_1 = "arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab"

# Use the multi-Region method to create the master key provider
# in strict mode
strict_mrk_key_provider = MRKAwareStrictAwsKmsMasterKeyProvider(
        key_ids=[mrk_us_east_1]
)

# Set the encryption context
encryption_context = {
        "purpose": "test"
    }

# Encrypt your plaintext data
ciphertext, encrypt_header = client.encrypt(
        source=source_plaintext,
        encryption_context=encryption_context,
        key_provider=strict_mrk_key_provider
)

Selanjutnya, pindahkan ciphertext Anda ke Region. us-west-2 Anda tidak perlu mengenkripsi ulang ciphertext.

Untuk mendekripsi ciphertext dalam mode ketat di us-west-2 Region, buat instance simbol Multi-Region-aware dengan kunci kunci ARN Multi-region terkait di Region. us-west-2 Jika Anda menentukan kunci kunci ARN Multi-wilayah terkait di Wilayah yang berbeda (termasukus-east-1, di mana kunci tersebut dienkripsi), simbol Multi-Region-aware akan membuat panggilan Lintas wilayah untuk itu. AWS KMS key

Saat mendekripsi dalam mode ketat, simbol Multi-Region-aware memerlukan kunci. ARN Ini hanya menerima satu kunci ARN dari setiap set kunci Multi-wilayah terkait.

Sebelum menjalankan contoh ini, ganti contoh Multi-region key ARN dengan nilai yang valid dari Anda Akun AWS.

C

Untuk mendekripsi dalam mode ketat dengan kunci Multi-region, gunakan Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder() metode ini untuk membuat instance keyring. Tentukan kunci Multi-wilayah terkait di Wilayah lokal (us-west-2).

Untuk contoh lengkap, lihat kms_multi_region_keys.cpp di AWS Encryption SDK for C repositori pada. GitHub


/* Decrypt with a related multi-Region KMS key in us-west-2 Region */

/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();

/* Initialize a multi-Region keyring */
const char *mrk_us_west_2 = "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab";    

struct aws_cryptosdk_keyring *mrk_keyring = 
    Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder().Build(mrk_us_west_2);

/* Create a session; release the keyring */
struct aws_cryptosdk_session *session =
    aws_cryptosdk_session_new_from_keyring_2(aws_default_allocator(), AWS_CRYPTOSDK_ENCRYPT, mrk_keyring);

aws_cryptosdk_session_set_commitment_policy(session,
    COMMITMENT_POLICY_REQUIRE_ENCRYPT_REQUIRE_DECRYPT);

aws_cryptosdk_keyring_release(mrk_keyring);

/* Decrypt the ciphertext 
 *   aws_cryptosdk_session_process_full is designed for non-streaming data
 */
aws_cryptosdk_session_process_full(
    session, plaintext, plaintext_buf_sz, &plaintext_len, ciphertext, ciphertext_len));

/* Clean up the session */
aws_cryptosdk_session_destroy(session);

C# / .NET

Untuk mendekripsi dalam mode ketat dengan satu kunci Multi-wilayah, gunakan konstruktor dan metode yang sama yang Anda gunakan untuk merakit input dan membuat keyring untuk mengenkripsi. Buat instance CreateAwsKmsMrkKeyringInput objek dengan kunci kunci ARN Multi-wilayah terkait dan AWS KMS klien untuk Wilayah AS Barat (Oregon) (us-west-2). Kemudian gunakan CreateAwsKmsMrkKeyring() metode ini untuk membuat keyring Multi-region dengan satu kunci KMS Multi-region.

Untuk contoh lengkapnya, lihat AwsKmsMrkKeyringExample.cs di AWS Encryption SDK for. NETrepositori aktif. GitHub


// Decrypt with a related multi-Region KMS key in us-west-2 Region

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

// Specify the key ARN of the multi-Region key in us-west-2
string mrkUSWest2 = "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab";

// Instantiate the keyring input
// You can specify the Region or get the Region from the key ARN
var createMrkDecryptKeyringInput = new CreateAwsKmsMrkKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(RegionEndpoint.USWest2),
    KmsKeyId = mrkUSWest2
};

// Create the multi-Region keyring        
var mrkDecryptKeyring = materialProviders.CreateAwsKmsMrkKeyring(createMrkDecryptKeyringInput);

// Decrypt the ciphertext
var decryptInput = new DecryptInput
{
    Ciphertext = ciphertext,
    Keyring = mrkDecryptKeyring
};
var decryptOutput = encryptionSdk.Decrypt(decryptInput);

AWS Encryption CLI

Untuk mendekripsi dengan kunci Multi-region terkait di Wilayah us-west-2, gunakan atribut kunci parameter untuk menentukan kuncinya. --wrapping-keys ARN


# Decrypt with a related multi-Region KMS key in us-west-2 Region

# To run this example, replace the fictitious key ARN with a valid value.
$ mrkUSWest2=arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab

$ aws-encryption-cli --decrypt \
                     --input hello.txt.encrypted \
                     --wrapping-keys key=$mrkUSWest2 \
                     --commitment-policy require-encrypt-require-decrypt \
                     --encryption-context purpose=test \
                     --metadata-output ~/metadata \
                     --max-encrypted-data-keys 1 \
                     --buffer \
                     --output .

Java

Untuk mendekripsi dalam mode ketat, buat instance AwsKmsMrkAwareMasterKeyProvider dan tentukan kunci Multi-wilayah terkait di Wilayah lokal (us-west-2).

Untuk contoh lengkap, lihat BasicMultiRegionKeyEncryptionExample.java di AWS Encryption SDK for Java repositori pada. GitHub


// Decrypt with a related multi-Region KMS key in us-west-2 Region

// Instantiate the client
final AwsCrypto crypto = AwsCrypto.builder()
    .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
    .build();

// Related multi-Region keys have the same key ID. Their key ARNs differs only in the Region field.
String mrkUSWest2 = "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab";

// Use the multi-Region method to create the master key provider
// in strict mode
AwsKmsMrkAwareMasterKeyProvider kmsMrkProvider = AwsKmsMrkAwareMasterKeyProvider.builder()
    .buildStrict(mrkUSWest2);

// Decrypt your ciphertext
CryptoResult<byte[], AwsKmsMrkAwareMasterKey> decryptResult = crypto.decryptData(
        kmsMrkProvider,
        ciphertext);
byte[] decrypted = decryptResult.getResult();

JavaScript Browser

Untuk mendekripsi dalam mode ketat, gunakan buildAwsKmsMrkAwareStrictMultiKeyringBrowser() metode untuk membuat keyring dan tentukan kunci Multi-region terkait di Wilayah lokal (us-west-2).

Untuk contoh lengkap, lihat kms_multi_region_simple.ts di repositori pada. AWS Encryption SDK for JavaScript GitHub


/* Decrypt with a related multi-Region KMS key in us-west-2 Region */

import {
  buildAwsKmsMrkAwareStrictMultiKeyringBrowser,
  buildClient,
  CommitmentPolicy,
  KMS,
} from '@aws-crypto/client-browser'


/* Instantiate an AWS Encryption SDK client */
const { decrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)

declare const credentials: {
  accessKeyId: string
  secretAccessKey: string
  sessionToken: string
}

/* Instantiate an AWS KMS client 
 * The AWS Encryption SDK for JavaScript gets the Region from the key ARN
 */
const clientProvider = (region: string) => new KMS({ region, credentials })


/* Specify a multi-Region key in us-west-2 */
const multiRegionUsWestKey =
    'arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'

/* Instantiate the keyring */
const mrkDecryptKeyring = buildAwsKmsMrkAwareStrictMultiKeyringBrowser({
    generatorKeyId: multiRegionUsWestKey,
    clientProvider,
  })


/* Decrypt the data */
const { plaintext, messageHeader } = await decrypt(mrkDecryptKeyring, result)

JavaScript Node.js

Untuk mendekripsi dalam mode ketat, gunakan buildAwsKmsMrkAwareStrictMultiKeyringNode() metode untuk membuat keyring dan tentukan kunci Multi-region terkait di Wilayah lokal (us-west-2).

Untuk contoh lengkap, lihat kms_multi_region_simple.ts di repositori pada. AWS Encryption SDK for JavaScript GitHub


/* Decrypt with a related multi-Region KMS key in us-west-2 Region */

import { buildClient } from '@aws-crypto/client-node'

/* Instantiate the client
const { decrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)

/* Multi-Region keys have a distinctive key ID that begins with 'mrk'
 * Specify a multi-Region key in us-west-2
 */
const multiRegionUsWestKey =
    'arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'

/* Create an AWS KMS keyring */
const mrkDecryptKeyring = buildAwsKmsMrkAwareStrictMultiKeyringNode({
    generatorKeyId: multiRegionUsWestKey,
  })

/* Decrypt your ciphertext */
const { plaintext, messageHeader } = await decrypt(decryptKeyring, result)

Python

Untuk mendekripsi dalam mode ketat, gunakan MRKAwareStrictAwsKmsMasterKeyProvider() metode untuk membuat penyedia kunci master. Tentukan kunci Multi-wilayah terkait di Wilayah lokal (us-west-2).

Untuk contoh lengkap, lihat mrk_aware_kms_provider.py di AWS Encryption SDK for Python repositori pada. GitHub


# Decrypt with a related multi-Region KMS key in us-west-2 Region

# Instantiate the client
client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT)

# Related multi-Region keys have the same key ID. Their key ARNs differs only in the Region field
mrk_us_west_2 = "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab"

# Use the multi-Region method to create the master key provider
# in strict mode
strict_mrk_key_provider = MRKAwareStrictAwsKmsMasterKeyProvider(
        key_ids=[mrk_us_west_2]
)

# Decrypt your ciphertext
plaintext, _ = client.decrypt(
        source=ciphertext, 
        key_provider=strict_mrk_key_provider
)

Anda juga dapat mendekripsi dalam mode penemuan dengan tombol AWS KMS Multi-wilayah. Saat mendekripsi dalam mode penemuan, Anda tidak menentukan apa pun. AWS KMS keys(Untuk informasi tentang gantungan kunci AWS KMS penemuan wilayah tunggal, lihatMenggunakan AWS KMS keyring penemuan.)

Jika Anda dienkripsi dengan kunci Multi-region, simbol Multi-Region-aware dalam mode penemuan akan mencoba mendekripsi dengan menggunakan kunci Multi-region terkait di Region lokal. Jika tidak ada; panggilan gagal. Dalam mode penemuan, tidak AWS Encryption SDK akan mencoba panggilan lintas wilayah untuk kunci Multi-wilayah yang digunakan untuk enkripsi.

catatan

Jika Anda menggunakan simbol Multi-Region-aware dalam mode penemuan untuk mengenkripsi data, operasi enkripsi gagal.

Contoh berikut menunjukkan cara mendekripsi dengan simbol Multi-region-aware dalam mode penemuan. Karena Anda tidak menentukan AWS KMS key, AWS Encryption SDK harus mendapatkan Wilayah dari sumber yang berbeda. Jika memungkinkan, tentukan Wilayah lokal secara eksplisit. Jika tidak, AWS Encryption SDK mendapatkan Wilayah lokal dari Wilayah yang dikonfigurasi dalam AWS SDK untuk bahasa pemrograman Anda.

Sebelum menjalankan contoh ini, ganti contoh ID akun dan kunci Multi-wilayah ARN dengan nilai yang valid dari Anda Akun AWS.

C

Untuk mendekripsi dalam mode penemuan dengan kunci Multi-region, gunakan Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder() metode untuk membangun keyring, dan Aws::Cryptosdk::KmsKeyring::DiscoveryFilter::Builder() metode untuk membangun filter penemuan. Untuk menentukan Wilayah lokal, tentukan ClientConfiguration dan tentukan di AWS KMS klien.

Untuk contoh lengkap, lihat kms_multi_region_keys.cpp di AWS Encryption SDK for C repositori pada. GitHub


/* Decrypt in discovery mode with a multi-Region KMS key */

/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();

/* Construct a discovery filter for the account and partition. The
 *  filter is optional, but it's a best practice that we recommend.
 */
const char *account_id = "111122223333";
const char *partition = "aws";
const std::shared_ptr<Aws::Cryptosdk::KmsKeyring::DiscoveryFilter> discovery_filter =
    Aws::Cryptosdk::KmsKeyring::DiscoveryFilter::Builder(partition).AddAccount(account_id).Build();

/* Create an AWS KMS client in the desired region. */
const char *region = "us-west-2";

Aws::Client::ClientConfiguration client_config;
client_config.region = region;
const std::shared_ptr<Aws::KMS::KMSClient> kms_client =
    Aws::MakeShared<Aws::KMS::KMSClient>("AWS_SAMPLE_CODE", client_config);

struct aws_cryptosdk_keyring *mrk_keyring = 
    Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder()
        .WithKmsClient(kms_client)
        .BuildDiscovery(region, discovery_filter);

/* Create a session; release the keyring */
struct aws_cryptosdk_session *session =
    aws_cryptosdk_session_new_from_keyring_2(aws_default_allocator(), AWS_CRYPTOSDK_DECRYPT, mrk_keyring);

aws_cryptosdk_keyring_release(mrk_keyring);
commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
/* Decrypt the ciphertext 
 *   aws_cryptosdk_session_process_full is designed for non-streaming data
 */
aws_cryptosdk_session_process_full(
    session, plaintext, plaintext_buf_sz, &plaintext_len, ciphertext, ciphertext_len));

/* Clean up the session */
aws_cryptosdk_session_destroy(session);

C# / .NET

Untuk membuat keyring penemuan sadar Multi-wilayah di for. AWS Encryption SDK NET, membuat instance CreateAwsKmsMrkDiscoveryKeyringInput objek yang mengambil AWS KMS klien untuk tertentu Wilayah AWS, dan filter penemuan opsional yang membatasi KMS kunci ke AWS partisi dan akun tertentu. Kemudian panggil CreateAwsKmsMrkDiscoveryKeyring() metode dengan objek input. Untuk contoh lengkapnya, lihat AwsKmsMrkDiscoveryKeyringExample.cs di AWS Encryption SDK for. NETrepositori aktif. GitHub

Untuk membuat keyring penemuan Multi-Region-aware untuk lebih dari satu Wilayah AWS, gunakan CreateAwsKmsMrkDiscoveryMultiKeyring() metode ini untuk membuat multi-keyring, atau gunakan untuk membuat beberapa keyring penemuan Multi-Region-aware dan kemudian gunakan metode CreateAwsKmsMrkDiscoveryKeyring() untuk menggabungkannya dalam multi-keyring. CreateMultiKeyring()

Sebagai contoh, lihat AwsKmsMrkDiscoveryMultiKeyringExample.cs.


// Decrypt in discovery mode with a multi-Region KMS key

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

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

// Instantiate the discovery filter
DiscoveryFilter mrkDiscoveryFilter = new DiscoveryFilter()
{
    AccountIds = account,
    Partition = "aws"
}

// Create the keyring
var createMrkDiscoveryKeyringInput = new CreateAwsKmsMrkDiscoveryKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(RegionEndpoint.USWest2),
    DiscoveryFilter = mrkDiscoveryFilter
};
var mrkDiscoveryKeyring = materialProviders.CreateAwsKmsMrkDiscoveryKeyring(createMrkDiscoveryKeyringInput);


// Decrypt the ciphertext
var decryptInput = new DecryptInput
{
    Ciphertext = ciphertext,
    Keyring = mrkDiscoveryKeyring
};
var decryptOutput = encryptionSdk.Decrypt(decryptInput);

AWS Encryption CLI

Untuk mendekripsi dalam mode penemuan, gunakan atribut penemuan parameter. --wrapping-keys Atribut discovery-account dan discovery-partition membuat filter penemuan yang opsional, tetapi direkomendasikan.

Untuk menentukan Region, perintah ini mencakup atribut region dari --wrapping-keys parameter.


# Decrypt in discovery mode with a multi-Region KMS key

$ aws-encryption-cli --decrypt \
                     --input hello.txt.encrypted \
                     --wrapping-keys discovery=true \ 
                                     discovery-account=111122223333 \
                                     discovery-partition=aws \
                                     region=us-west-2 \
                     --encryption-context purpose=test \
                     --metadata-output ~/metadata \
                     --max-encrypted-data-keys 1 \
                     --buffer \
                     --output .

Java

Untuk menentukan Wilayah lokal, gunakan builder().withDiscoveryMrkRegion parameter. Jika tidak, AWS Encryption SDK mendapatkan Wilayah lokal dari Wilayah yang dikonfigurasi di AWS SDK for Java.

Untuk contoh lengkap, lihat DiscoveryMultiRegionDecryptionExample.java di AWS Encryption SDK for Java repositori pada. GitHub


// Decrypt in discovery mode with a multi-Region KMS key

// Instantiate the client
final AwsCrypto crypto = AwsCrypto.builder()
    .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
    .build();
                
DiscoveryFilter discoveryFilter = new DiscoveryFilter("aws", 111122223333);

AwsKmsMrkAwareMasterKeyProvider mrkDiscoveryProvider = AwsKmsMrkAwareMasterKeyProvider
    .builder()
    .withDiscoveryMrkRegion(Region.US_WEST_2)
    .buildDiscovery(discoveryFilter);

// Decrypt your ciphertext
final CryptoResult<byte[], AwsKmsMrkAwareMasterKey> decryptResult = crypto
    .decryptData(mrkDiscoveryProvider, ciphertext);

JavaScript Browser

Untuk mendekripsi dalam mode penemuan dengan kunci Multi-region simetris, gunakan metode ini. AwsKmsMrkAwareSymmetricDiscoveryKeyringBrowser()

Untuk contoh lengkap, lihat kms_multi_region_discovery.ts di repositori pada. AWS Encryption SDK for JavaScript GitHub


/* Decrypt in discovery mode with a multi-Region KMS key */

import {
  AwsKmsMrkAwareSymmetricDiscoveryKeyringBrowser,
  buildClient,
  CommitmentPolicy,
  KMS,
} from '@aws-crypto/client-browser'


/* Instantiate an AWS Encryption SDK client */
const { decrypt } = buildClient()

declare const credentials: {
  accessKeyId: string
  secretAccessKey: string
  sessionToken: string
}

/* Instantiate the KMS client with an explicit Region */
const client = new KMS({ region: 'us-west-2', credentials })


/* Create a discovery filter */
const discoveryFilter = { partition: 'aws', accountIDs: ['111122223333'] }


/* Create an AWS KMS discovery keyring */
const mrkDiscoveryKeyring = new AwsKmsMrkAwareSymmetricDiscoveryKeyringBrowser({
    client,
    discoveryFilter,
  })


/* Decrypt the data */
const { plaintext, messageHeader } = await decrypt(mrkDiscoveryKeyring, ciphertext)

JavaScript Node.js

Untuk mendekripsi dalam mode penemuan dengan kunci Multi-region simetris, gunakan metode ini. AwsKmsMrkAwareSymmetricDiscoveryKeyringNode()

Untuk contoh lengkap, lihat kms_multi_region_discovery.ts di repositori pada. AWS Encryption SDK for JavaScript GitHub


/* Decrypt in discovery mode with a multi-Region KMS key */

import {
  AwsKmsMrkAwareSymmetricDiscoveryKeyringNode,
  buildClient,
  CommitmentPolicy,
  KMS,
} from '@aws-crypto/client-node'

/* Instantiate the Encryption SDK client
const { decrypt } = buildClient()

/* Instantiate the KMS client with an explicit Region */
const client = new KMS({ region: 'us-west-2' })

/* Create a discovery filter */
const discoveryFilter = { partition: 'aws', accountIDs: ['111122223333'] }

/* Create an AWS KMS discovery keyring */
const mrkDiscoveryKeyring = new AwsKmsMrkAwareSymmetricDiscoveryKeyringNode({
    client,
    discoveryFilter,
  })

/* Decrypt your ciphertext */
const { plaintext, messageHeader } = await decrypt(mrkDiscoveryKeyring, result)

Python

Untuk mendekripsi dalam mode penemuan dengan kunci Multi-wilayah, gunakan metode ini. MRKAwareDiscoveryAwsKmsMasterKeyProvider()

Untuk contoh lengkap, lihat mrk_aware_kms_provider.py di AWS Encryption SDK for Python repositori pada. GitHub


# Decrypt in discovery mode with a multi-Region KMS key

# Instantiate the client
client = aws_encryption_sdk.EncryptionSDKClient()

# Create the discovery filter and specify the region
decrypt_kwargs = dict(
        discovery_filter=DiscoveryFilter(account_ids="111122223333", partition="aws"),
        discovery_region="us-west-2",
    )

# Use the multi-Region method to create the master key provider
# in discovery mode
mrk_discovery_key_provider = MRKAwareDiscoveryAwsKmsMasterKeyProvider(**decrypt_kwargs)

# Decrypt your ciphertext
plaintext, _ = client.decrypt(
        source=ciphertext, 
        key_provider=mrk_discovery_key_provider
)

Memilih rangkaian algoritma

AWS Encryption SDK Mendukung beberapa algoritma enkripsi simetris dan asimetris untuk mengenkripsi kunci data Anda di bawah kunci pembungkus yang Anda tentukan. Namun, ketika menggunakan kunci data tersebut untuk mengenkripsi data Anda, AWS Encryption SDK default ke rangkaian algoritme yang direkomendasikan yang menggunakan algoritme AES - GCM dengan derivasi kunci, tanda tangan digital, dan komitmen kunci. Meskipun rangkaian algoritme default kemungkinan cocok untuk sebagian besar aplikasi, Anda dapat memilih rangkaian algoritme alternatif. Misalnya, beberapa model kepercayaan akan dipenuhi oleh rangkaian algoritma tanpa tanda tangan digital. Untuk informasi tentang rangkaian algoritme yang AWS Encryption SDK didukung, lihatAlgoritma suite yang didukung diAWS Encryption SDK.

Contoh berikut menunjukkan cara memilih rangkaian algoritma alternatif saat mengenkripsi. Contoh-contoh ini memilih rangkaian GCM algoritme yang direkomendasikan AES dengan derivasi kunci dan komitmen kunci, tetapi tanpa tanda tangan digital. Saat Anda mengenkripsi dengan rangkaian algoritme yang tidak menyertakan tanda tangan digital, gunakan mode dekripsi khusus tanpa tanda tangan saat mendekripsi. Mode ini, yang gagal jika menemukan ciphertext yang ditandatangani, paling berguna saat streaming dekripsi.

C

Untuk menentukan rangkaian algoritma alternatif di AWS Encryption SDK for C, Anda harus membuat CMM secara eksplisit. Kemudian gunakan aws_cryptosdk_default_cmm_set_alg_id dengan CMM dan suite algoritma yang dipilih.


/* Specify an algorithm suite without signing */

/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();

/* Construct an AWS KMS keyring */
struct aws_cryptosdk_keyring *kms_keyring = Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn);

/* To set an alternate algorithm suite, create an cryptographic 
   materials manager (CMM) explicitly
 */
struct aws_cryptosdk_cmm *cmm = aws_cryptosdk_default_cmm_new(aws_default_allocator(), kms_keyring);
aws_cryptosdk_keyring_release(kms_keyring); 

/* Specify the algorithm suite for the CMM */
aws_cryptosdk_default_cmm_set_alg_id(cmm, ALG_AES256_GCM_HKDF_SHA512_COMMIT_KEY);
    
/* Construct the session with the CMM, 
   then release the CMM reference 
 */
struct aws_cryptosdk_session *session = aws_cryptosdk_session_new_from_cmm_2(alloc, AWS_CRYPTOSDK_ENCRYPT, cmm);
aws_cryptosdk_cmm_release(cmm);

/* Encrypt the data 
   Use aws_cryptosdk_session_process_full with non-streaming data
 */
if (AWS_OP_SUCCESS != aws_cryptosdk_session_process_full(
                          session, 
                          ciphertext, 
                          ciphertext_buf_sz, 
                          &ciphertext_len, 
                          plaintext, 
                          plaintext_len)) {
    aws_cryptosdk_session_destroy(session);
    return AWS_OP_ERR;
}

Saat mendekripsi data yang dienkripsi tanpa tanda tangan digital, gunakan. AWS_CRYPTOSDK_DECRYPT_UNSIGNED Hal ini menyebabkan dekripsi gagal jika menemukan ciphertext yang ditandatangani.


/* Decrypt unsigned streaming data */

/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();

/* Construct an AWS KMS keyring */
struct aws_cryptosdk_keyring *kms_keyring = Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn);
    
/* Create a session for decrypting with the AWS KMS keyring
   Then release the keyring reference
 */
struct aws_cryptosdk_session *session =
        aws_cryptosdk_session_new_from_keyring_2(alloc, AWS_CRYPTOSDK_DECRYPT_UNSIGNED, kms_keyring);
aws_cryptosdk_keyring_release(kms_keyring); 
   
if (!session) {
    return AWS_OP_ERR;
}
    
/* Limit encrypted data keys */
aws_cryptosdk_session_set_max_encrypted_data_keys(session, 1);
  
/* Decrypt 
   Use aws_cryptosdk_session_process_full with non-streaming data
 */
    if (AWS_OP_SUCCESS != aws_cryptosdk_session_process_full(
                          session,                          
                          plaintext,
                          plaintext_buf_sz,
                          &plaintext_len,
                          ciphertext,
                          ciphertext_len)) {
    aws_cryptosdk_session_destroy(session);
    return AWS_OP_ERR;
}

C# / .NET

Untuk menentukan rangkaian algoritma alternatif di AWS Encryption SDK for. NET, tentukan AlgorithmSuiteId properti suatu EncryptInputobjek. AWS Encryption SDK Untuk. NETtermasuk konstanta yang dapat Anda gunakan untuk mengidentifikasi rangkaian algoritme pilihan Anda.

AWS Encryption SDK Untuk. NETtidak memiliki metode untuk mendeteksi ciphertext yang ditandatangani saat streaming dekripsi karena pustaka ini tidak mendukung data streaming.


// Specify an algorithm suite without signing

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

// Create the keyring
var keyringInput = new CreateAwsKmsKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = keyArn
};
var keyring = materialProviders.CreateAwsKmsKeyring(keyringInput);

// Encrypt your plaintext data
var encryptInput = new EncryptInput
{
    Plaintext = plaintext,
    Keyring = keyring,
    AlgorithmSuiteId = AlgorithmSuiteId.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY
};
var encryptOutput = encryptionSdk.Encrypt(encryptInput);

AWS Encryption CLI

Saat mengenkripsi hello.txt file, contoh ini menggunakan --algorithm parameter untuk menentukan rangkaian algoritma tanpa tanda tangan digital.


# Specify an algorithm suite without signing

# To run this example, replace the fictitious key ARN with a valid value.
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

$ aws-encryption-cli --encrypt \
                     --input hello.txt \
                     --wrapping-keys key=$keyArn \
                     --algorithm AES_256_GCM_HKDF_SHA512_COMMIT_KEY \
                     --metadata-output ~/metadata \
                     --encryption-context purpose=test \
                     --commitment-policy require-encrypt-require-decrypt \
                     --output hello.txt.encrypted \
                     --decode

Saat mendekripsi, contoh ini menggunakan parameter. --decrypt-unsigned Parameter ini disarankan untuk memastikan bahwa Anda mendekripsi ciphertext yang tidak ditandatangani, terutama denganCLI, yang selalu streaming input dan output.


# Decrypt unsigned streaming data

# To run this example, replace the fictitious key ARN with a valid value.
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

$ aws-encryption-cli --decrypt-unsigned \
                     --input hello.txt.encrypted \
                     --wrapping-keys key=$keyArn \
                     --max-encrypted-data-keys 1 \
                     --commitment-policy require-encrypt-require-decrypt \
                     --encryption-context purpose=test \
                     --metadata-output ~/metadata \
                     --output .

Java

Untuk menentukan rangkaian algoritma alternatif, gunakan AwsCrypto.builder().withEncryptionAlgorithm() metode ini. Contoh ini menentukan rangkaian algoritma alternatif tanpa tanda tangan digital.


// Specify an algorithm suite without signing

// Instantiate the client
AwsCrypto crypto = AwsCrypto.builder()
    .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
    .withEncryptionAlgorithm(CryptoAlgorithm.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY)
    .build();

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

// Create a master key provider in strict mode
KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder()
    .buildStrict(awsKmsKey);
    
// Create an encryption context to identify this ciphertext
        Map<String, String> encryptionContext = Collections.singletonMap("Example", "FileStreaming");

// Encrypt your plaintext data
CryptoResult<byte[], KmsMasterKey> encryptResult = crypto.encryptData(
    masterKeyProvider,
    sourcePlaintext,
    encryptionContext);
byte[] ciphertext = encryptResult.getResult();

Saat streaming data untuk dekripsi, gunakan createUnsignedMessageDecryptingStream() metode ini untuk memastikan bahwa semua ciphertext yang Anda dekripsi tidak ditandatangani.


// Decrypt unsigned streaming data

// Instantiate the client
AwsCrypto crypto = AwsCrypto.builder()
  .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
  .withMaxEncryptedDataKeys(1)
  .build();

// Create a master key provider in strict mode
String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder()
  .buildStrict(awsKmsKey);

// Decrypt the encrypted message
FileInputStream in = new FileInputStream(srcFile + ".encrypted");  
CryptoInputStream<KmsMasterKey> decryptingStream = crypto.createUnsignedMessageDecryptingStream(masterKeyProvider, in);
  
// Return the plaintext data
// Write the plaintext data to disk
FileOutputStream out = new FileOutputStream(srcFile + ".decrypted");
IOUtils.copy(decryptingStream, out);
decryptingStream.close();

JavaScript Browser

Untuk menentukan rangkaian algoritma alternatif, gunakan suiteId parameter dengan nilai AlgorithmSuiteIdentifier enum.


// Specify an algorithm suite without signing

// Instantiate the client 
const { encrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT )

// Specify a KMS key 
const generatorKeyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";

// Create a keyring with the KMS key
const keyring = new KmsKeyringBrowser({ generatorKeyId })

// Encrypt your plaintext data 
const { result } = await encrypt(keyring, cleartext, { suiteId: AlgorithmSuiteIdentifier.ALG_AES256_GCM_IV12_TAG16_HKDF_SHA512_COMMIT_KEY, encryptionContext: context, })

Saat mendekripsi, gunakan metode standardecrypt. AWS Encryption SDK for JavaScript di browser tidak memiliki decrypt-unsigned mode karena browser tidak mendukung streaming.


// Decrypt unsigned streaming data

// Instantiate the client 
const { decrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT )

// Create a keyring with the same KMS key used to encrypt
const generatorKeyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; 
const keyring = new KmsKeyringBrowser({ generatorKeyId })

// Decrypt the encrypted message 
const { plaintext, messageHeader } = await decrypt(keyring, ciphertextMessage)

JavaScript Node.js

Untuk menentukan rangkaian algoritma alternatif, gunakan suiteId parameter dengan nilai AlgorithmSuiteIdentifier enum.


// Specify an algorithm suite without signing

// Instantiate the client 
const { encrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT )

// Specify a KMS key
const generatorKeyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";

// Create a keyring with the KMS key
const keyring = new KmsKeyringNode({ generatorKeyId })

// Encrypt your plaintext data 
const { result } = await encrypt(keyring, cleartext, { suiteId: AlgorithmSuiteIdentifier.ALG_AES256_GCM_IV12_TAG16_HKDF_SHA512_COMMIT_KEY, encryptionContext: context, })

Saat mendekripsi data yang dienkripsi tanpa tanda tangan digital, gunakan Stream. decryptUnsignedMessage Metode ini gagal jika menemukan ciphertext yang ditandatangani.


// Decrypt unsigned streaming data

// Instantiate the client 
const { decryptUnsignedMessageStream } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT )

// Create a keyring with the same KMS key used to encrypt
const generatorKeyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; 
const keyring = new KmsKeyringNode({ generatorKeyId })

// Decrypt the encrypted message 
const outputStream = createReadStream(filename) .pipe(decryptUnsignedMessageStream(keyring))

Python

Untuk menentukan algoritma enkripsi alternatif, gunakan algorithm parameter dengan nilai Algorithm enum.


# Specify an algorithm suite without signing

# Instantiate a client
client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT, 
                                                max_encrypted_data_keys=1)

# Create a master key provider in strict mode
aws_kms_key = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
aws_kms_strict_master_key_provider = StrictAwsKmsMasterKeyProvider(
        key_ids=[aws_kms_key]
)

# Encrypt the plaintext using an alternate algorithm suite
ciphertext, encrypted_message_header = client.encrypt(
    algorithm=Algorithm.AES_256_GCM_HKDF_SHA512_COMMIT_KEY, source=source_plaintext, key_provider=kms_key_provider
)

Saat mendekripsi pesan yang dienkripsi tanpa tanda tangan digital, gunakan mode decrypt-unsigned streaming, terutama saat mendekripsi saat streaming.


# Decrypt unsigned streaming data

# Instantiate the client
client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT, 
                                                max_encrypted_data_keys=1)

# Create a master key provider in strict mode
aws_kms_key = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
aws_kms_strict_master_key_provider = StrictAwsKmsMasterKeyProvider(
        key_ids=[aws_kms_key]
)

# Decrypt with decrypt-unsigned
with open(ciphertext_filename, "rb") as ciphertext, open(cycled_plaintext_filename, "wb") as plaintext:
    with client.stream(mode="decrypt-unsigned", 
                       source=ciphertext, 
                       key_provider=master_key_provider) as decryptor:
        for chunk in decryptor:
            plaintext.write(chunk)

# Verify that the encryption context
assert all(
   pair in decryptor.header.encryption_context.items() for pair in encryptor.header.encryption_context.items()
)
return ciphertext_filename, cycled_plaintext_filename

Membatasi kunci data terenkripsi

Anda dapat membatasi jumlah kunci data terenkripsi dalam pesan terenkripsi. Fitur praktik terbaik ini dapat membantu Anda mendeteksi keyring yang salah konfigurasi saat mengenkripsi atau ciphertext berbahaya saat mendekripsi. Ini juga mencegah panggilan yang tidak perlu, mahal, dan berpotensi lengkap ke infrastruktur utama Anda. Membatasi kunci data terenkripsi paling berharga saat Anda mendekripsi pesan dari sumber yang tidak tepercaya.

Meskipun sebagian besar pesan terenkripsi memiliki satu kunci data terenkripsi untuk setiap kunci pembungkus yang digunakan dalam enkripsi, pesan terenkripsi dapat berisi hingga 65.535 kunci data terenkripsi. Aktor jahat mungkin membuat pesan terenkripsi dengan ribuan kunci data terenkripsi, tidak ada yang dapat didekripsi. Akibatnya, AWS Encryption SDK akan mencoba untuk mendekripsi setiap kunci data terenkripsi sampai habis kunci data terenkripsi dalam pesan.

Untuk membatasi kunci data terenkripsi, gunakan parameter. MaxEncryptedDataKeys Parameter ini tersedia untuk semua bahasa pemrograman yang didukung mulai versi 1.9. x dan 2.2. x dari AWS Encryption SDK. Ini opsional dan valid saat mengenkripsi dan mendekripsi. Contoh berikut mendekripsi data yang dienkripsi di bawah tiga kunci pembungkus yang berbeda. MaxEncryptedDataKeysNilai diatur ke 3.

C


/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();

/* Construct an AWS KMS keyring */
struct aws_cryptosdk_keyring *kms_keyring = 
      Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn1, { key_arn2, key_arn3 });

/* Create a session */
struct aws_cryptosdk_session *session = 
    aws_cryptosdk_session_new_from_keyring_2(alloc, AWS_CRYPTOSDK_DECRYPT, kms_keyring);
aws_cryptosdk_keyring_release(kms_keyring);

/* Limit encrypted data keys */
aws_cryptosdk_session_set_max_encrypted_data_keys(session, 3);
  
/* Decrypt */
size_t ciphertext_consumed_output;
aws_cryptosdk_session_process(session,
    plaintext_output,
    plaintext_buf_sz_output,
    &plaintext_len_output,
    ciphertext_input,
    ciphertext_len_input,
    &ciphertext_consumed_output);
assert(aws_cryptosdk_session_is_done(session));
assert(ciphertext_consumed == ciphertext_len);

C# / .NET

Untuk membatasi kunci data terenkripsi di for. AWS Encryption SDK NET, membuat instance klien untuk for. AWS Encryption SDK NETdan atur MaxEncryptedDataKeys parameter opsionalnya ke nilai yang diinginkan. Kemudian, panggil Decrypt() metode pada AWS Encryption SDK instance yang dikonfigurasi.


// Decrypt with limited data keys

// Instantiate the material providers
var materialProviders =
    AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();

// Configure the commitment policy on the AWS Encryption SDK instance
var config = new AwsEncryptionSdkConfig
{
    MaxEncryptedDataKeys = 3
};
var encryptionSdk = AwsEncryptionSdkFactory.CreateAwsEncryptionSdk(config);

// Create the keyring
string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
var createKeyringInput = new CreateAwsKmsKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = keyArn
};
var decryptKeyring = materialProviders.CreateAwsKmsKeyring(createKeyringInput);

// Decrypt the ciphertext
var decryptInput = new DecryptInput
{
    Ciphertext = ciphertext,
    Keyring = decryptKeyring
};
var decryptOutput = encryptionSdk.Decrypt(decryptInput);

AWS Encryption CLI


# Decrypt with limited encrypted data keys

$ aws-encryption-cli --decrypt \
    --input hello.txt.encrypted \
    --wrapping-keys key=$key_arn1 key=$key_arn2 key=$key_arn3 \
    --buffer \
    --max-encrypted-data-keys 3 \
    --encryption-context purpose=test \
    --metadata-output ~/metadata \
    --output .

Java


// Construct a client with limited encrypted data keys
final AwsCrypto crypto = AwsCrypto.builder()
  .withMaxEncryptedDataKeys(3)
  .build();

// Create an AWS KMS master key provider
final KmsMasterKeyProvider keyProvider = KmsMasterKeyProvider.builder()
      .buildStrict(keyArn1, keyArn2, keyArn3);
   
// Decrypt
final CryptoResult<byte[], KmsMasterKey> decryptResult = crypto.decryptData(keyProvider, ciphertext)

JavaScript Browser


// Construct a client with limited encrypted data keys
const { encrypt, decrypt } = buildClient({ maxEncryptedDataKeys: 3 })

declare const credentials: {
  accessKeyId: string
  secretAccessKey: string
  sessionToken: string
}
const clientProvider = getClient(KMS, {
  credentials: { accessKeyId, secretAccessKey, sessionToken }
})

// Create an AWS KMS keyring
const keyring = new KmsKeyringBrowser({
  clientProvider,
  keyIds: [keyArn1, keyArn2, keyArn3],
})

// Decrypt
const { plaintext, messageHeader } = await decrypt(keyring, ciphertext)

JavaScript Node.js


// Construct a client with limited encrypted data keys
const { encrypt, decrypt } = buildClient({ maxEncryptedDataKeys: 3 })

// Create an AWS KMS keyring
const keyring = new KmsKeyringBrowser({
  keyIds: [keyArn1, keyArn2, keyArn3],
})
  
// Decrypt
const { plaintext, messageHeader } = await decrypt(keyring, ciphertext)

Python


# Instantiate a client with limited encrypted data keys
client = aws_encryption_sdk.EncryptionSDKClient(max_encrypted_data_keys=3)

# Create an AWS KMS master key provider
master_key_provider = aws_encryption_sdk.StrictAwsKmsMasterKeyProvider(
    key_ids=[key_arn1, key_arn2, key_arn3])

# Decrypt
plaintext, header = client.decrypt(source=ciphertext, key_provider=master_key_provider)

Membuat filter penemuan

Saat mendekripsi data yang dienkripsi dengan KMS kunci, ini adalah praktik terbaik untuk mendekripsi dalam mode ketat, yaitu membatasi kunci pembungkus yang digunakan hanya untuk yang Anda tentukan. Namun, jika perlu, Anda juga dapat mendekripsi dalam mode penemuan, di mana Anda tidak menentukan kunci pembungkus apa pun. Dalam mode ini, AWS KMS dapat mendekripsi kunci data terenkripsi menggunakan kunci yang mengenkripsi itu, terlepas dari siapa yang memiliki atau memiliki akses ke KMS kunci itu. KMS

Jika Anda harus mendekripsi dalam mode penemuan, kami sarankan Anda selalu menggunakan filter penemuan, yang membatasi KMS kunci yang dapat digunakan untuk yang ada di partisi Akun AWS dan yang ditentukan. Filter penemuan adalah opsional, tetapi ini adalah praktik terbaik.

Gunakan tabel berikut untuk menentukan nilai partisi untuk filter penemuan Anda.

Wilayah	Partition
Wilayah AWS	`aws`
Wilayah China	`aws-cn`
AWS GovCloud (US) Regions	`aws-us-gov`

Contoh di bagian ini menunjukkan cara membuat filter penemuan. Sebelum menggunakan kode, ganti nilai contoh dengan nilai yang valid untuk partisi Akun AWS dan.

C

Untuk contoh lengkap, lihat kms_discovery.cpp di file AWS Encryption SDK for C.


/* Create a discovery filter for an AWS account and partition */
    
const char *account_id = "111122223333";
const char *partition = "aws";
const std::shared_ptr<Aws::Cryptosdk::KmsKeyring::DiscoveryFilter> discovery_filter =
    Aws::Cryptosdk::KmsKeyring::DiscoveryFilter::Builder(partition).AddAccount(account_id).Build();

C# / .NET

Untuk contoh lengkapnya, lihat DiscoveryFilterExample.cs di AWS Encryption SDK for. NET.


// Create a discovery filter for an AWS account and partition

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

DiscoveryFilter exampleDiscoveryFilter = new DiscoveryFilter()
{
    AccountIds = account,
    Partition = "aws"
}

AWS Encryption CLI


# Decrypt in discovery mode with a discovery filter

$ aws-encryption-cli --decrypt \
                     --input hello.txt.encrypted \
                     --wrapping-keys discovery=true \ 
                                     discovery-account=111122223333 \
                                     discovery-partition=aws \
                     --encryption-context purpose=test \
                     --metadata-output ~/metadata \
                     --max-encrypted-data-keys 1 \
                     --buffer \
                     --output .

Java

Untuk contoh lengkap, lihat DiscoveryDecryptionExample.java di file. AWS Encryption SDK for Java


// Create a discovery filter for an AWS account and partition

DiscoveryFilter discoveryFilter = new DiscoveryFilter("aws", 111122223333);

JavaScript (Node and Browser)

Untuk contoh lengkap, lihat kms_filtered_discovery.ts (Node.js) dan kms_multi_region_discovery.ts (Browser) di file. AWS Encryption SDK for JavaScript


/* Create a discovery filter for an AWS account and partition */
const discoveryFilter = { 
  accountIDs: ['111122223333'], 
  partition: 'aws',
}

Python

Untuk contoh lengkap, lihat discovery_kms_provider.py di file AWS Encryption SDK for Python.


# Create the discovery filter and specify the region
decrypt_kwargs = dict(
        discovery_filter=DiscoveryFilter(account_ids="111122223333", partition="aws"),
        discovery_region="us-west-2",
    )

Menetapkan kebijakan komitmen

Kebijakan komitmen adalah pengaturan konfigurasi yang menentukan apakah aplikasi Anda mengenkripsi dan mendekripsi dengan komitmen utama. Mengenkripsi dan mendekripsi dengan komitmen utama adalah praktik terbaik.AWS Encryption SDK

Menyetel dan menyesuaikan kebijakan komitmen Anda adalah langkah penting dalam melakukan migrasi dari versi 1.7. x dan sebelumnya AWS Encryption SDK ke versi 2.0. x dan kemudian. Perkembangan ini dijelaskan secara rinci dalam topik migrasi.

Nilai kebijakan komitmen default di versi terbaru AWS Encryption SDK (dimulai pada versi 2.0. x),RequireEncryptRequireDecrypt, sangat ideal untuk sebagian besar situasi. Namun, jika Anda perlu mendekripsi ciphertext yang dienkripsi tanpa komitmen utama, Anda mungkin perlu mengubah kebijakan komitmen Anda. RequireEncryptAllowDecrypt Untuk contoh cara menetapkan kebijakan komitmen dalam setiap bahasa pemrograman, lihatMenetapkan kebijakan komitmen Anda.

Bekerja dengan data streaming

Saat Anda mengalirkan data untuk dekripsi, ketahuilah bahwa teks biasa yang didekripsi AWS Encryption SDK kembali setelah pemeriksaan integritas selesai, tetapi sebelum tanda tangan digital diverifikasi. Untuk memastikan bahwa Anda tidak mengembalikan atau menggunakan plaintext sampai tanda tangan diverifikasi, kami sarankan Anda menyangga plaintext yang dialirkan hingga seluruh proses dekripsi selesai.

Masalah ini muncul hanya ketika Anda melakukan streaming ciphertext untuk dekripsi, dan hanya ketika Anda menggunakan rangkaian algoritme, seperti rangkaian algoritme default, yang menyertakan tanda tangan digital.

Untuk mempermudah buffering, beberapa implementasi AWS Encryption SDK bahasa, seperti AWS Encryption SDK for JavaScript di Node.js, menyertakan fitur buffering sebagai bagian dari metode dekripsi. AWS EnkripsiCLI, yang selalu mengalirkan input dan output memperkenalkan --buffer parameter dalam versi 1.9. x dan 2.2. x. Dalam implementasi bahasa lain, Anda dapat menggunakan fitur buffering yang ada. ( AWS Encryption SDK Untuk. NETtidak mendukung streaming.)

Jika Anda menggunakan rangkaian algoritme tanpa tanda tangan digital, pastikan untuk menggunakan decrypt-unsigned fitur ini di setiap implementasi bahasa. Fitur ini mendekripsi ciphertext tetapi gagal jika menemukan ciphertext yang ditandatangani. Untuk detailnya, lihat Memilih rangkaian algoritma.

Kunci data cache

Secara umum, menggunakan kembali kunci data tidak disarankan, tetapi AWS Encryption SDK menawarkan opsi caching kunci data yang menyediakan penggunaan kembali kunci data secara terbatas. Caching kunci data dapat meningkatkan kinerja beberapa aplikasi dan mengurangi panggilan ke infrastruktur utama Anda. Sebelum menggunakan caching kunci data dalam produksi, sesuaikan ambang keamanan, dan uji untuk memastikan bahwa manfaatnya lebih besar daripada kerugian menggunakan kembali kunci data.

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Praktik terbaik

Menggunakan keyrings