Migrasi ke mode ketat Migrasi ke mode penemuan

Memperbarui penyedia kunci AWS KMS utama

Untuk bermigrasi ke yang terbaru 1. x versi AWS Encryption SDK, dan kemudian ke versi 2.0. x atau yang lebih baru, Anda harus mengganti penyedia kunci AWS KMS master lama dengan penyedia kunci master yang dibuat secara eksplisit dalam mode ketat atau mode penemuan. Penyedia kunci master lama tidak digunakan lagi di versi 1.7. x dan dihapus dalam versi 2.0. x. Perubahan ini diperlukan untuk aplikasi dan skrip yang menggunakan AWS Encryption SDK for Java, AWS Encryption SDK for Python, dan AWS Enkripsi CLI. Contoh di bagian ini akan menunjukkan cara memperbarui kode Anda.

catatan

Dengan Python, aktifkan peringatan penghentian. Ini akan membantu Anda mengidentifikasi bagian-bagian kode Anda yang perlu Anda perbarui.

Jika Anda menggunakan kunci AWS KMS master (bukan penyedia kunci master), Anda dapat melewati langkah ini. AWS KMS kunci master tidak digunakan lagi atau dihapus. Mereka mengenkripsi dan mendekripsi hanya dengan kunci pembungkus yang Anda tentukan.

Contoh di bagian ini berfokus pada elemen kode Anda yang perlu Anda ubah. Untuk contoh lengkap kode yang diperbarui, lihat bagian Contoh GitHub repositori untuk bahasa pemrograman Anda. Juga, contoh-contoh ini biasanya menggunakan kunci ARNs untuk mewakili AWS KMS keys. Saat Anda membuat penyedia kunci utama untuk mengenkripsi, Anda dapat menggunakan pengidentifikasi AWS KMS kunci yang valid untuk mewakili. AWS KMS key Saat Anda membuat penyedia kunci master untuk mendekripsi, Anda harus menggunakan kunci. ARN

Pelajari lebih lanjut tentang migrasi

Untuk semua AWS Encryption SDK pengguna, pelajari tentang menetapkan kebijakan komitmen AndaMenetapkan kebijakan komitmen Anda.

Untuk AWS Encryption SDK for C dan AWS Encryption SDK for JavaScript pengguna, pelajari tentang pembaruan opsional untuk keyrings diMemperbaruiAWS KMSgantungan kunci.

Migrasi ke mode ketat

Setelah memperbarui ke yang terbaru 1. x versi AWS Encryption SDK, ganti penyedia kunci master lama Anda dengan penyedia kunci master dalam mode ketat. Dalam mode ketat, Anda harus menentukan kunci pembungkus yang akan digunakan saat mengenkripsi dan mendekripsi. Hanya AWS Encryption SDK menggunakan tombol pembungkus yang Anda tentukan. Penyedia kunci master yang tidak digunakan lagi dapat mendekripsi data menggunakan data apa pun AWS KMS key yang mengenkripsi kunci data, termasuk di berbagai dan Wilayah. AWS KMS keys Akun AWS

Penyedia kunci utama dalam mode ketat diperkenalkan dalam AWS Encryption SDK versi 1.7. x. Mereka menggantikan penyedia kunci master lama, yang tidak digunakan lagi di 1.7. x dan dihapus di 2.0. x. Menggunakan penyedia kunci master dalam mode ketat adalah praktik AWS Encryption SDK terbaik.

Kode berikut membuat penyedia kunci master dalam mode ketat yang dapat Anda gunakan untuk mengenkripsi dan mendekripsi.

Java

Contoh ini mewakili kode dalam aplikasi yang menggunakan versi 1.6.2 atau sebelumnya. AWS Encryption SDK for Java

Kode ini menggunakan KmsMasterKeyProvider.builder() metode untuk membuat instance penyedia kunci AWS KMS master yang menggunakannya AWS KMS key sebagai kunci pembungkus.


// Create a master key provider
// Replace the example key ARN with a valid one
String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";

KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder()
    .withKeysForEncryption(awsKmsKey)
    .build();

Contoh ini mewakili kode dalam aplikasi yang menggunakan versi 1.7. x atau yang lebih baru AWS Encryption SDK for Java . Untuk contoh lengkap, lihat BasicEncryptionExample.java.

Builder.withKeysForEncryption()Metode Builder.build() dan yang digunakan dalam contoh sebelumnya tidak digunakan lagi di versi 1.7. x dan dihapus dari versi 2.0. x.

Untuk memperbarui ke penyedia kunci master mode ketat, kode ini menggantikan panggilan ke metode usang dengan panggilan ke metode baru. Builder.buildStrict() Contoh ini menentukan satu AWS KMS key sebagai kunci pembungkus, tetapi Builder.buildStrict() metode ini dapat mengambil daftar beberapa. AWS KMS keys


// Create a master key provider in strict mode
// Replace the example key ARN with a valid one from your Akun AWS.
String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";

KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder()
    .buildStrict(awsKmsKey);

Python

Contoh ini mewakili kode dalam aplikasi yang menggunakan versi 1.4.1 dari file. AWS Encryption SDK for Python Kode ini menggunakanKMSMasterKeyProvider, yang tidak digunakan lagi di versi 1.7. x dan dihapus dari versi 2.0. x. Saat mendekripsi, ia menggunakan apa pun AWS KMS key yang mengenkripsi kunci data tanpa memperhatikan yang Anda tentukan. AWS KMS keys

Perhatikan bahwa KMSMasterKey tidak digunakan lagi atau dihapus. Saat mengenkripsi dan mendekripsi, hanya menggunakan yang Anda tentukan. AWS KMS key


# Create a master key provider
# Replace the example key ARN with a valid one
key_1 = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
key_2 = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"

aws_kms_master_key_provider = KMSMasterKeyProvider(
   key_ids=[key_1, key_2]
)

Contoh ini mewakili kode dalam aplikasi yang menggunakan versi 1.7. x dari AWS Encryption SDK for Python. Untuk contoh lengkap, lihat basic_encryption.py.

Untuk memperbarui ke penyedia kunci master mode ketat, kode ini menggantikan panggilan ke KMSMasterKeyProvider() dengan panggilan keStrictAwsKmsMasterKeyProvider().


# Create a master key provider in strict mode
# Replace the example key ARNs with valid values from your Akun AWS
key_1 = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
key_2 = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"

aws_kms_master_key_provider = StrictAwsKmsMasterKeyProvider(
    key_ids=[key_1, key_2]
)

AWS Encryption CLI

Contoh ini menunjukkan cara mengenkripsi dan mendekripsi menggunakan AWS Enkripsi CLI versi 1.1.7 atau sebelumnya.

Di versi 1.1.7 dan sebelumnya, saat mengenkripsi, Anda menentukan satu atau lebih kunci master (atau kunci pembungkus), seperti. AWS KMS key Saat mendekripsi, Anda tidak dapat menentukan kunci pembungkus apa pun kecuali Anda menggunakan penyedia kunci master khusus. AWS Enkripsi CLI dapat menggunakan kunci pembungkus apa pun yang mengenkripsi kunci data.


\\ Replace the example key ARN with a valid one
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

\\ Encrypt your plaintext data
$ aws-encryption-cli --encrypt \
                     --input hello.txt \
                     --master-keys key=$keyArn \
                     --metadata-output ~/metadata \
                     --encryption-context purpose=test \
                     --output .

\\ Decrypt your ciphertext               
$ aws-encryption-cli --decrypt \
                     --input hello.txt.encrypted \
                     --encryption-context purpose=test \
                     --metadata-output ~/metadata \
                     --output .

Contoh ini menunjukkan cara mengenkripsi dan mendekripsi menggunakan AWS Enkripsi CLI versi 1.7. x atau yang lebih baru. Untuk contoh lengkap, lihatContoh dariAWSEnkripsi CLI.

--master-keysParameter ini tidak digunakan lagi di versi 1.7. x dan dihapus dalam versi 2.0. x. Ini diganti dengan --wrapping-keys parameter, yang diperlukan dalam perintah enkripsi dan dekripsi. Parameter ini mendukung mode ketat dan mode penemuan. Mode ketat adalah praktik AWS Encryption SDK terbaik yang memastikan bahwa Anda menggunakan kunci pembungkus yang Anda inginkan.

Untuk meningkatkan ke mode ketat, gunakan atribut kunci --wrapping-keys parameter untuk menentukan kunci pembungkus saat mengenkripsi dan mendekripsi.


\\ Replace the example key ARN with a valid value
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

\\ Encrypt your plaintext data
$ aws-encryption-cli --encrypt \
                     --input hello.txt \
                     --wrapping-keys key=$keyArn \
                     --metadata-output ~/metadata \
                     --encryption-context purpose=test \
                     --output .

\\ Decrypt your ciphertext               
$ aws-encryption-cli --decrypt \
                     --input hello.txt.encrypted \
                     --wrapping-keys key=$keyArn \
                     --encryption-context purpose=test \
                     --metadata-output ~/metadata \
                     --output .

Migrasi ke mode penemuan

Dimulai pada versi 1.7. x, ini adalah praktik AWS Encryption SDK terbaik untuk menggunakan mode ketat untuk penyedia kunci AWS KMS master, yaitu menentukan kunci pembungkus saat mengenkripsi dan mendekripsi. Anda harus selalu menentukan kunci pembungkus saat mengenkripsi. Tetapi ada situasi di mana menentukan kunci ARNs AWS KMS keys untuk mendekripsi tidak praktis. Misalnya, jika Anda menggunakan alias untuk mengidentifikasi AWS KMS keys saat mengenkripsi, Anda kehilangan manfaat alias jika Anda harus mencantumkan kunci saat mendekripsi. ARNs Selain itu, karena penyedia kunci master dalam mode penemuan berperilaku seperti penyedia kunci master asli, Anda dapat menggunakannya sementara sebagai bagian dari strategi migrasi Anda, dan kemudian meningkatkan ke penyedia kunci master dalam mode ketat nanti.

Dalam kasus seperti ini, Anda dapat menggunakan penyedia kunci utama dalam mode penemuan. Penyedia kunci master ini tidak mengizinkan Anda menentukan kunci pembungkus, sehingga Anda tidak dapat menggunakannya untuk mengenkripsi. Saat mendekripsi, mereka dapat menggunakan kunci pembungkus apa pun yang mengenkripsi kunci data. Tetapi tidak seperti penyedia kunci master lama, yang berperilaku dengan cara yang sama, Anda membuatnya dalam mode penemuan secara eksplisit. Saat menggunakan penyedia kunci master dalam mode penemuan, Anda dapat membatasi kunci pembungkus yang dapat digunakan untuk yang khusus Akun AWS. Filter penemuan ini opsional, tetapi ini adalah praktik terbaik yang kami rekomendasikan. Untuk informasi tentang AWS partisi dan akun, lihat Nama Sumber Daya Amazon di bagian. Referensi Umum AWS

Contoh berikut membuat penyedia kunci AWS KMS master dalam mode ketat untuk mengenkripsi dan penyedia kunci AWS KMS master dalam mode penemuan untuk mendekripsi. Penyedia kunci master dalam mode penemuan menggunakan filter penemuan untuk membatasi kunci pembungkus yang digunakan untuk mendekripsi ke aws partisi dan contoh tertentu. Akun AWS Meskipun filter akun tidak diperlukan dalam contoh yang sangat sederhana ini, ini adalah praktik terbaik yang sangat bermanfaat ketika satu aplikasi mengenkripsi data dan aplikasi lain mendekripsi data.

Java

Contoh ini mewakili kode dalam aplikasi yang menggunakan versi 1.7. x atau yang lebih baru AWS Encryption SDK for Java. Untuk contoh lengkap, lihat DiscoveryDecryptionExample.java.

Untuk membuat instance penyedia kunci master dalam mode ketat untuk mengenkripsi, contoh ini menggunakan metode ini. Builder.buildStrict() Untuk membuat instance penyedia kunci master dalam mode penemuan untuk mendekripsi, ia menggunakan metode ini. Builder.buildDiscovery() Builder.buildDiscovery()Metode ini mengambil DiscoveryFilter yang membatasi AWS Encryption SDK ke AWS KMS keys dalam AWS partisi dan akun yang ditentukan.


// Create a master key provider in strict mode for encrypting
// Replace the example alias ARN with a valid one from your Akun AWS.
String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias";

KmsMasterKeyProvider encryptingKeyProvider = KmsMasterKeyProvider.builder()
    .buildStrict(awsKmsKey);

// Create a master key provider in discovery mode for decrypting
// Replace the example account IDs with valid values.
DiscoveryFilter accounts = new DiscoveryFilter("aws", Arrays.asList("111122223333", "444455556666"));

KmsMasterKeyProvider decryptingKeyProvider = KmsMasterKeyProvider.builder()
    .buildDiscovery(accounts);

Python

Contoh ini mewakili kode dalam aplikasi yang menggunakan versi 1.7. x atau yang lebih baru AWS Encryption SDK for Python . Untuk contoh lengkap, lihat discovery_kms_provider.py.

Untuk membuat penyedia kunci master dalam mode ketat untuk mengenkripsi, contoh ini menggunakan. StrictAwsKmsMasterKeyProvider Untuk membuat penyedia kunci master dalam mode penemuan untuk mendekripsi, ia menggunakan DiscoveryAwsKmsMasterKeyProvider dengan a DiscoveryFilter yang membatasi AWS Encryption SDK ke AWS KMS keys dalam AWS partisi dan akun yang ditentukan.


# Create a master key provider in strict mode
# Replace the example key ARN and alias ARNs with valid values from your Akun AWS.
key_1 = "arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias"
key_2 = "arn:aws:kms:us-west-2:444455556666:key/1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d"

aws_kms_master_key_provider = StrictAwsKmsMasterKeyProvider(
    key_ids=[key_1, key_2]
)

# Create a master key provider in discovery mode for decrypting
# Replace the example account IDs with valid values
accounts = DiscoveryFilter(
    partition="aws",
    account_ids=["111122223333", "444455556666"]
)
aws_kms_master_key_provider = DiscoveryAwsKmsMasterKeyProvider(
        discovery_filter=accounts
)

AWS Encryption CLI

Contoh ini menunjukkan cara mengenkripsi dan mendekripsi menggunakan AWS Enkripsi CLI versi 1.7. x atau yang lebih baru. Dimulai pada versi 1.7. x, --wrapping-keys parameter diperlukan saat mengenkripsi dan mendekripsi. --wrapping-keysParameter mendukung mode ketat dan mode penemuan. Untuk contoh lengkap, lihatContoh dariAWSEnkripsi CLI.

Saat mengenkripsi, contoh ini menentukan kunci pembungkus, yang diperlukan. Saat mendekripsi, secara eksplisit memilih mode penemuan dengan menggunakan discovery atribut --wrapping-keys parameter dengan nilai. true

Untuk membatasi kunci pembungkus yang AWS Encryption SDK dapat digunakan dalam mode penemuan pada khususnya Akun AWS, contoh ini menggunakan discovery-account atribut discovery-partition dan --wrapping-keys parameter. Atribut opsional ini hanya valid ketika discovery atribut disetel ketrue. Anda harus menggunakan discovery-account atribut discovery-partition dan bersama-sama; tidak ada yang valid sendirian.


\\ Replace the example key ARN with a valid value
$ keyAlias=arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias

\\ Encrypt your plaintext data
$ aws-encryption-cli --encrypt \
                     --input hello.txt \
                     --wrapping-keys key=$keyAlias \
                     --metadata-output ~/metadata \
                     --encryption-context purpose=test \
                     --output .

\\ Decrypt your ciphertext
\\ Replace the example account IDs with valid values           
$ aws-encryption-cli --decrypt \
                     --input hello.txt.encrypted \
                     --wrapping-keys discovery=true \
                                     discovery-partition=aws \
                                     discovery-account=111122223333 \
                                     discovery-account=444455556666 \
                     --encryption-context purpose=test \
                     --metadata-output ~/metadata \
                     --output .

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

Cara bermigrasi dan menyebarkan

MemperbaruiAWS KMSgantungan kunci