AWS Encryption SDK for JavaScript contoh - AWS Encryption SDK
Mengenkripsi data dengan keyring AWS KMSMendekripsi data dengan keyring AWS KMS

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

AWS Encryption SDK for JavaScript contoh

Contoh berikut menunjukkan cara menggunakan untuk mengenkripsi dan AWS Encryption SDK for JavaScript mendekripsi data.

Anda dapat menemukan lebih banyak contoh penggunaan modul AWS Encryption SDK for JavaScript dalam example-node dan example-browser di repositori pada. aws-encryption-sdk-javascript GitHub Modul contoh ini tidak diinstal ketika Anda menginstal client-browser atau client-node modul.

Lihat contoh kode lengkap: Node: kms_simple.ts, Browser: kms_simple.ts

Mengenkripsi data dengan keyring AWS KMS

Contoh berikut menunjukkan kepada Anda bagaimana menggunakan AWS Encryption SDK for JavaScript untuk mengenkripsi dan mendekripsi string pendek atau array byte.

Contoh ini menampilkan AWS KMS keyring, jenis keyring yang menggunakan AWS KMS key untuk menghasilkan dan mengenkripsi kunci data. Untuk bantuan membuat AWS KMS key, lihat Membuat Kunci di Panduan AWS Key Management Service Pengembang. Untuk bantuan mengidentifikasi AWS KMS keys dalam AWS KMS gantungan kunci, lihat Mengidentifikasi AWS KMS keys dalam AWS KMS keyring

Langkah 1: Tetapkan kebijakan komitmen.

Dimulai pada versi 1.7. x dari AWS Encryption SDK for JavaScript, Anda dapat mengatur kebijakan komitmen ketika Anda memanggil buildClient fungsi baru yang membuat instance AWS Encryption SDK klien. buildClientFungsi ini mengambil nilai yang disebutkan yang mewakili kebijakan komitmen Anda. Ini mengembalikan decrypt fungsi yang diperbarui encrypt dan yang menegakkan kebijakan komitmen Anda saat Anda mengenkripsi dan mendekripsi.

Contoh berikut menggunakan buildClient fungsi untuk menentukan kebijakan komitmen default,REQUIRE_ENCRYPT_REQUIRE_DECRYPT. Anda juga dapat menggunakan buildClient untuk membatasi jumlah kunci data terenkripsi dalam pesan terenkripsi. Untuk informasi selengkapnya, lihat Membatasi kunci data terenkripsi.

JavaScript Browser
import {
  KmsKeyringBrowser,
  KMS,
  getClient,
  buildClient,
  CommitmentPolicy,
} from '@aws-crypto/client-browser'

const { encrypt, decrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
JavaScript Node.js
import {
  KmsKeyringNode,
  buildClient,
  CommitmentPolicy,
} from '@aws-crypto/client-node'
                                
const { encrypt, decrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
Langkah 2: Bangun keyring.

Buat AWS KMS keyring untuk enkripsi.

Saat mengenkripsi dengan AWS KMS keyring, Anda harus menentukan kunci generator, yaitu kunci yang digunakan untuk menghasilkan kunci data plaintext dan mengenkripsinya. AWS KMS key Anda juga dapat menentukan nol atau lebih kunci tambahan yang mengenkripsi kunci data teks biasa yang sama. Keyring mengembalikan kunci data plaintext dan satu salinan terenkripsi dari kunci data tersebut untuk masing-masing AWS KMS key di keyring, termasuk kunci generator. Untuk mendekripsi data, Anda perlu mendekripsi salah satu kunci data terenkripsi.

Untuk menentukan keyring enkripsi di dalam AWS Encryption SDK for JavaScript, Anda dapat menggunakan pengenal AWS KMS kunci yang didukung. AWS KMS keys Contoh ini menggunakan kunci generator, yang diidentifikasi oleh aliasnyaARN, dan satu kunci tambahan, yang diidentifikasi oleh kunci ARN.

catatan

Jika Anda berencana untuk menggunakan kembali AWS KMS keyring Anda untuk mendekripsi, Anda harus menggunakan kunci ARNs untuk mengidentifikasi di AWS KMS keys keyring.

Sebelum menjalankan kode ini, ganti AWS KMS key pengidentifikasi contoh dengan pengidentifikasi yang valid. Anda harus memiliki izin yang diperlukan untuk menggunakan AWS KMS keys di keyring.

JavaScript Browser

Mulailah dengan memberikan kredensil Anda ke browser. AWS Encryption SDK for JavaScript Contohnya menggunakan webpack. DefinePlugin, yang menggantikan konstanta kredenal dengan kredensil Anda yang sebenarnya. Tetapi Anda dapat menggunakan metode apa pun untuk memberikan kredensil Anda. Kemudian, gunakan kredensialnya untuk membuat klien. AWS KMS 

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

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

Selanjutnya, tentukan AWS KMS keys untuk kunci generator dan kunci tambahan. Kemudian, buat AWS KMS keyring menggunakan AWS KMS klien dan. AWS KMS keys

const generatorKeyId = 'arn:aws:kms:us-west-2:111122223333:alias/EncryptDecrypt'
const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab']

const keyring = new KmsKeyringBrowser({ clientProvider, generatorKeyId, keyIds })
JavaScript Node.js
const generatorKeyId = 'arn:aws:kms:us-west-2:111122223333:alias/EncryptDecrypt'
const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab']

const keyring = new KmsKeyringNode({ generatorKeyId, keyIds })
Langkah 3: Atur konteks enkripsi.

Konteks enkripsi adalah data otentikasi tambahan yang sewenang-wenang dan tidak rahasia. Ketika Anda menyediakan konteks enkripsi pada enkripsi, AWS Encryption SDK kriptografis mengikat konteks enkripsi ke ciphertext sehingga konteks enkripsi yang sama diperlukan untuk mendekripsi data. Menggunakan konteks enkripsi adalah opsional, tetapi kami merekomendasikannya sebagai praktik terbaik.

Buat objek sederhana yang mencakup pasangan konteks enkripsi. Kunci dan nilai dalam setiap pasangan harus berupa string.

JavaScript Browser
const context = {
  stage: 'demo',
  purpose: 'simple demonstration app',
  origin: 'us-west-2'
}
JavaScript Node.js
const context = {
  stage: 'demo',
  purpose: 'simple demonstration app',
  origin: 'us-west-2'
}
Langkah 4: Enkripsi data.

Untuk mengenkripsi data plaintext, panggil fungsi. encrypt Masukkan AWS KMS keyring, data plaintext, dan konteks enkripsi.

encryptFungsi mengembalikan pesan terenkripsi (result) yang berisi data terenkripsi, kunci data terenkripsi, dan metadata penting, termasuk konteks enkripsi dan tanda tangan.

Anda dapat mendekripsi pesan terenkripsi ini dengan menggunakan AWS Encryption SDK untuk setiap bahasa pemrograman yang didukung.

JavaScript Browser
const plaintext = new Uint8Array([1, 2, 3, 4, 5])

const { result } = await encrypt(keyring, plaintext, { encryptionContext: context })
JavaScript Node.js
const plaintext = 'asdf'

const { result } = await encrypt(keyring, plaintext, { encryptionContext: context })

Mendekripsi data dengan keyring AWS KMS

Anda dapat menggunakan AWS Encryption SDK for JavaScript untuk mendekripsi pesan terenkripsi dan memulihkan data asli.

Dalam contoh ini, kami mendekripsi data yang kami enkripsi dalam contoh. Mengenkripsi data dengan keyring AWS KMS

Langkah 1: Tetapkan kebijakan komitmen.

Dimulai pada versi 1.7. x dari AWS Encryption SDK for JavaScript, Anda dapat mengatur kebijakan komitmen ketika Anda memanggil buildClient fungsi baru yang membuat instance AWS Encryption SDK klien. buildClientFungsi ini mengambil nilai yang disebutkan yang mewakili kebijakan komitmen Anda. Ini mengembalikan decrypt fungsi yang diperbarui encrypt dan yang menegakkan kebijakan komitmen Anda saat Anda mengenkripsi dan mendekripsi.

Contoh berikut menggunakan buildClient fungsi untuk menentukan kebijakan komitmen default,REQUIRE_ENCRYPT_REQUIRE_DECRYPT. Anda juga dapat menggunakan buildClient untuk membatasi jumlah kunci data terenkripsi dalam pesan terenkripsi. Untuk informasi selengkapnya, lihat Membatasi kunci data terenkripsi.

JavaScript Browser
import {
  KmsKeyringBrowser,
  KMS,
  getClient,
  buildClient,
  CommitmentPolicy,
} from '@aws-crypto/client-browser'

const { encrypt, decrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
JavaScript Node.js
import {
  KmsKeyringNode,
  buildClient,
  CommitmentPolicy,
} from '@aws-crypto/client-node'
                                
const { encrypt, decrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
Langkah 2: Bangun keyring.

Untuk mendekripsi data, teruskan pesan terenkripsi (result) yang dikembalikan fungsi. encrypt Pesan terenkripsi mencakup data terenkripsi, kunci data terenkripsi, dan metadata penting, termasuk konteks enkripsi dan tanda tangan.

Anda juga harus menentukan AWS KMS keyring saat mendekripsi. Anda dapat menggunakan keyring yang sama yang digunakan untuk mengenkripsi data atau keyring yang berbeda. Agar berhasil, setidaknya satu AWS KMS key di keyring dekripsi harus dapat mendekripsi salah satu kunci data terenkripsi dalam pesan terenkripsi. Karena tidak ada kunci data yang dihasilkan, Anda tidak perlu menentukan kunci generator dalam keyring dekripsi. Jika Anda melakukannya, kunci generator dan kunci tambahan diperlakukan dengan cara yang sama.

Untuk menentukan AWS KMS key untuk keyring dekripsi di AWS Encryption SDK for JavaScript, Anda harus menggunakan kunci. ARN Kalau tidak, AWS KMS key tidak dikenali. Untuk bantuan mengidentifikasi AWS KMS keys dalam AWS KMS gantungan kunci, lihat Mengidentifikasi AWS KMS keys dalam AWS KMS keyring

catatan

Jika Anda menggunakan keyring yang sama untuk mengenkripsi dan mendekripsi, gunakan kunci ARNs untuk mengidentifikasi di keyring. AWS KMS keys

Dalam contoh ini, kami membuat keyring yang hanya menyertakan salah satu dari keyring enkripsi. AWS KMS keys Sebelum menjalankan kode ini, ganti kunci contoh ARN dengan yang valid. Anda harus memiliki kms:Decrypt izin pada AWS KMS key.

JavaScript Browser

Mulailah dengan memberikan kredensil Anda ke browser. AWS Encryption SDK for JavaScript Contohnya menggunakan webpack. DefinePlugin, yang menggantikan konstanta kredenal dengan kredensil Anda yang sebenarnya. Tetapi Anda dapat menggunakan metode apa pun untuk memberikan kredensil Anda. Kemudian, gunakan kredensialnya untuk membuat klien. AWS KMS 

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

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

Selanjutnya, buat AWS KMS keyring menggunakan AWS KMS klien. Contoh ini hanya menggunakan salah satu AWS KMS keys dari keyring enkripsi.

const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab']

const keyring = new KmsKeyringBrowser({ clientProvider, keyIds })
JavaScript Node.js
const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab']

const keyring = new KmsKeyringNode({ keyIds })
Langkah 3: Dekripsi data.

Selanjutnya, panggil decrypt fungsinya. Masukkan keyring dekripsi yang baru saja Anda buat (keyring) dan pesan terenkripsi yang dikembalikan oleh fungsi (). encrypt result AWS Encryption SDK Menggunakan keyring untuk mendekripsi salah satu kunci data terenkripsi. Kemudian menggunakan kunci data plaintext untuk mendekripsi data.

Jika panggilan berhasil, plaintext bidang berisi data plaintext (didekripsi). messageHeaderBidang berisi metadata tentang proses dekripsi, termasuk konteks enkripsi yang digunakan untuk mendekripsi data.

JavaScript Browser
const { plaintext, messageHeader } = await decrypt(keyring, result)
JavaScript Node.js
const { plaintext, messageHeader } = await decrypt(keyring, result)
Langkah 4: Verifikasi konteks enkripsi.

Konteks enkripsi yang digunakan untuk mendekripsi data disertakan dalam header pesan (messageHeader) yang dikembalikan decrypt fungsi. Sebelum aplikasi Anda mengembalikan data plaintext, verifikasi bahwa konteks enkripsi yang Anda berikan saat mengenkripsi disertakan dalam konteks enkripsi yang digunakan saat mendekripsi. Ketidakcocokan mungkin menunjukkan bahwa data telah dirusak, atau bahwa Anda tidak mendekripsi ciphertext yang tepat.

Saat memverifikasi konteks enkripsi, tidak memerlukan kecocokan persis. Saat Anda menggunakan algoritme enkripsi dengan penandatanganan, pengelola materi kriptografi (CMM) menambahkan kunci penandatanganan publik ke konteks enkripsi sebelum mengenkripsi pesan. Tetapi semua pasangan konteks enkripsi yang Anda kirimkan harus disertakan dalam konteks enkripsi yang dikembalikan.

Pertama, dapatkan konteks enkripsi dari header pesan. Kemudian, verifikasi bahwa setiap pasangan kunci-nilai dalam konteks enkripsi asli (context) cocok dengan pasangan kunci-nilai dalam konteks enkripsi yang dikembalikan (). encryptionContext

JavaScript Browser
const { encryptionContext } = messageHeader

Object
  .entries(context)
  .forEach(([key, value]) => {
    if (encryptionContext[key] !== value) throw new Error('Encryption Context does not match expected values')
})
JavaScript Node.js
const { encryptionContext } = messageHeader

Object
  .entries(context)
  .forEach(([key, value]) => {
    if (encryptionContext[key] !== value) throw new Error('Encryption Context does not match expected values')
})

Jika pemeriksaan konteks enkripsi berhasil, Anda dapat mengembalikan data teks biasa.