Contoh AWS Encryption SDK for C - AWS Encryption SDK
Mengenkripsi dan mendekripsi string

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

Contoh AWS Encryption SDK for C

Contoh berikut menunjukkan kepada Anda cara menggunakanAWS Encryption SDK for Cmengenkripsi dan mendekripsi data.

Contoh dalam bagian ini menunjukkan cara menggunakan versi 2.0.xdan setelahnyaAWS Encryption SDK for C. Untuk contoh yang menggunakan versi sebelumnya, temukan rilis Anda diRilisdaftaraws-encryption-sdkrepositori -crepositori padaGitHub.

Ketika Anda menginstal dan membangunAWS Encryption SDK for C, kode sumber untuk ini dan contoh lainnya termasuk dalamexamplessubdirektori, dan mereka dikompilasi dan dibangun ke dalambuilddirektori. Anda juga dapat menemukannya dicontohsubdirektori dariaws-encryption-sdk-crepositori padaGitHub.

Mengenkripsi dan mendekripsi string

Contoh berikut menunjukkan kepada Anda cara menggunakanAWS Encryption SDK for Cmengenkripsi dan mendekripsi string.

Contoh ini memiliki fiturAWS KMSkeyring, jenis keyring yang menggunakanAWS KMS keydiAWS Key Management Service(AWS KMS)untuk menghasilkan dan mengenkripsi kunci data. Contoh termasuk kode yang ditulis dalam C ++. ParameterAWS Encryption SDK for CmembutuhkanAWS SDK for C++meneleponAWS KMSsaat menggunakanAWS KMSkeyrings. Jika Anda menggunakan keyring yang tidak berinteraksiAWS KMS, seperti keyring AES mentah, keyring RSA mentah, atau multi-keyring yang tidak termasukAWS KMSkeyring,AWS SDK for C++tidak diperlukan.

Untuk bantuan membuatAWS KMS key, lihatMembuat kuncidiAWS Key Management ServicePanduan Pengembang. Untuk bantuan mengidentifikasiAWS KMS keysdalamAWS KMSkeyring, lihatMengidentifikasi AWS KMS keys dalam AWS KMS keyring.

Lihat contoh kode lengkap:string.cpp

Mengenkripsi string

Bagian pertama dari contoh ini menggunakanAWS KMSkeyring dengan satuAWS KMS keyuntuk mengenkripsi string plaintext.

Langkah 1. Memuat string kesalahan.

Memanggilaws_cryptosdk_load_error_strings()Metode dalam kode C atau C++. Ini memuat informasi kesalahan yang sangat berguna untuk debugging.

Anda hanya perlu menyebutnya sekali, seperti dimainmetode.

/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();
Langkah 2: Membangun keyring.

BuatAWS KMSkeyring untuk enkripsi. Keyring dalam contoh ini dikonfigurasi dengan satuAWS KMS key, tetapi Anda dapat mengonfigurasiAWS KMSkeyring dengan beberapaAWS KMS keys, termasukAWS KMS keysberbedaWilayah AWSdan akun yang berbeda.

Untuk mengidentifikasiAWS KMS keydalam keyring enkripsi diAWS Encryption SDK for C, tentukanARN kunciatauARN alias. Dalam keyring dekripsi, Anda harus menggunakan ARN kunci. Untuk detailnya, lihat Mengidentifikasi AWS KMS keys dalam AWS KMS keyring.

Mengidentifikasi AWS KMS keys dalam AWS KMS keyring

Bila Anda membuat keyring dengan beberapaAWS KMS keys, Anda menentukanAWS KMS keydigunakan untuk menghasilkan dan mengenkripsi kunci data plaintext, dan array opsional tambahanAWS KMS keysmengenkripsi kunci data plaintext yang sama. Dalam hal ini, Anda hanya menentukan generatorAWS KMS key.

Sebelum menjalankan kode ini, ganti contoh kunci ARN dengan yang valid.

const char * key_arn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";    

struct aws_cryptosdk_keyring *kms_keyring = 
       Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn);
Langkah 3: Buat sesi.

Buat sesi menggunakan allocator, enumerator mode, dan keyring.

Setiap sesi membutuhkan mode: baikAWS_CRYPTOSDK_ENCRYPTuntuk mengenkripsi atauAWS_CRYPTOSDK_DECRYPTmendekripsi. Untuk mengubah mode sesi yang ada, gunakanaws_cryptosdk_session_resetmetode.

Setelah Anda membuat sesi dengan keyring, Anda dapat melepaskan referensi Anda ke keyring menggunakan metode yang SDK menyediakan. Sesi mempertahankan referensi ke objek keyring selama masa hidupnya. Referensi ke keyring dan sesi objek dilepaskan ketika Anda menghancurkan sesi. Inimenghitung referensimembantu untuk mencegah kebocoran memori dan untuk mencegah objek dari yang dilepaskan saat mereka sedang digunakan.

struct aws_cryptosdk_session *session = 
       aws_cryptosdk_session_new_from_keyring_2(alloc, AWS_CRYPTOSDK_ENCRYPT, kms_keyring);

/* When you add the keyring to the session, release the keyring object */
aws_cryptosdk_keyring_release(kms_keyring);
Langkah 4: Mengatur konteks enkripsi.

Sesikonteks enkripsiadalah data terotentikasi tambahan yang sewenang-wenang dan non-rahasia. Ketika Anda memberikan konteks enkripsi pada enkripsi,AWS Encryption SDKkriptografi 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.

Pertama, buat tabel hash yang mencakup string konteks enkripsi.

/* Allocate a hash table for the encryption context */
int set_up_enc_ctx(struct aws_allocator *alloc, struct aws_hash_table *my_enc_ctx) 

// Create encryption context strings
AWS_STATIC_STRING_FROM_LITERAL(enc_ctx_key1, "Example");
AWS_STATIC_STRING_FROM_LITERAL(enc_ctx_value1, "String");
AWS_STATIC_STRING_FROM_LITERAL(enc_ctx_key2, "Company");
AWS_STATIC_STRING_FROM_LITERAL(enc_ctx_value2, "MyCryptoCorp");

// Put the key-value pairs in the hash table
aws_hash_table_put(my_enc_ctx, enc_ctx_key1, (void *)enc_ctx_value1, &was_created)
aws_hash_table_put(my_enc_ctx, enc_ctx_key2, (void *)enc_ctx_value2, &was_created)

Dapatkan pointer yang bisa berubah ke konteks enkripsi dalam sesi. Kemudian, gunakanaws_cryptosdk_enc_ctx_cloneberfungsi untuk menyalin konteks enkripsi ke sesi. Simpan salinannyamy_enc_ctxsehingga Anda dapat memvalidasi nilai setelah mendekripsi data.

Konteks enkripsi adalah bagian dari sesi, bukan parameter yang diteruskan ke fungsi proses sesi. Ini menjamin bahwa konteks enkripsi yang sama digunakan untuk setiap segmen pesan, bahkan jika fungsi proses sesi dipanggil beberapa kali untuk mengenkripsi seluruh pesan.

struct aws_hash_table *session_enc_ctx = aws_cryptosdk_session_get_enc_ctx_ptr_mut(session);

aws_cryptosdk_enc_ctx_clone(alloc, session_enc_ctx, my_enc_ctx)
Langkah 5: Enkripsi string.

Untuk mengenkripsi string plaintext, gunakanaws_cryptosdk_session_process_fullmetode dengan sesi dalam mode enkripsi. Metode ini, diperkenalkan diAWS Encryption SDKversi 1.9.xdan 2.2.x, dirancang untuk enkripsi non-streaming dan dekripsi. Untuk menangani data streaming, hubungiaws_cryptosdk_session_processdalam lingkaran.

Saat mengenkripsi, bidang plaintext adalah field input; bidang ciphertext adalah bidang output. Saat pemrosesan selesai,ciphertext_outputbidang berisipesan terenkripsi, termasuk ciphertext aktual, kunci data terenkripsi, dan konteks enkripsi. Anda dapat mendekripsi pesan terenkripsi ini dengan menggunakanAWS Encryption SDKuntuk bahasa pemrograman yang didukung.

/* Gets the length of the plaintext that the session processed */
size_t ciphertext_len_output;
if (AWS_OP_SUCCESS != aws_cryptosdk_session_process_full(session,
                                  ciphertext_output,
                                  ciphertext_buf_sz_output,
                                  &ciphertext_len_output,
                                  plaintext_input,
                                  plaintext_len_input)) {
    aws_cryptosdk_session_destroy(session);
    return 8;
}
Langkah 6: Membersihkan sesi.

Langkah terakhir menghancurkan sesi termasuk referensi ke CMM dan keyring.

Jika Anda lebih suka, alih-alih menghancurkan sesi, Anda dapat menggunakan kembali sesi dengan keyring dan CMM yang sama untuk mendekripsi string, atau untuk mengenkripsi atau mendekripsi pesan lain. Untuk menggunakan sesi untuk mendekripsi, gunakanaws_cryptosdk_session_resetmetode untuk mengubah mode keAWS_CRYPTOSDK_DECRYPT.

Dekripsi string

Bagian kedua dari contoh ini mendekripsi pesan terenkripsi yang berisi ciphertext dari string asli.

Langkah 1: Memuat string kesalahan.

Memanggilaws_cryptosdk_load_error_strings()Metode dalam kode C atau C++. Ini memuat informasi kesalahan yang sangat berguna untuk debugging.

Anda hanya perlu menyebutnya sekali, seperti dimainmetode.

/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();
Langkah 2: Membangun keyring.

Ketika Anda mendekripsi data diAWS KMS, Anda lulus dalampesan terenkripsibahwa API enkripsi kembali. ParameterDekripsi APItidak mengambilAWS KMS keysebagai input. Sebagai gantinya,AWS KMSmenggunakan yang samaAWS KMS keyuntuk mendekripsi ciphertext yang digunakan untuk mengenkripsi itu. Namun,AWS Encryption SDKmemungkinkan Anda menentukanAWS KMSkeyring denganAWS KMS keyspada mengenkripsi dan mendekripsi.

Pada dekripsi, Anda dapat mengkonfigurasi keyring hanya denganAWS KMS keysyang ingin Anda gunakan untuk mendekripsi pesan terenkripsi. Misalnya, Anda mungkin ingin membuat keyring denganAWS KMS keyyang digunakan oleh peran tertentu dalam organisasi Anda. ParameterAWS Encryption SDKtidak akan pernah menggunakanAWS KMS keykecuali muncul di keyring dekripsi. Jika SDK tidak dapat mendekripsi kunci data terenkripsi dengan menggunakanAWS KMS keysdi keyring yang Anda berikan, baik karena tidak adaAWS KMS keysdalam keyring digunakan untuk mengenkripsi salah satu kunci data, atau karena pemanggil tidak memiliki izin untuk menggunakanAWS KMS keysdalam keyring untuk mendekripsi, panggilan dekripsi gagal.

Bila Anda menentukanAWS KMS keyuntuk keyring dekripsi, Anda harus menggunakanARN kunci. ARN aliashanya diizinkan dalam keyrings enkripsi. Untuk bantuan mengidentifikasiAWS KMS keysdalamAWS KMSkeyring, lihatMengidentifikasi AWS KMS keys dalam AWS KMS keyring.

Dalam contoh ini, kami tentukan keyring yang dikonfigurasi dengan yang samaAWS KMS keydigunakan untuk mengenkripsi string. Sebelum menjalankan kode ini, ganti contoh kunci ARN dengan yang valid.

const char * key_arn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"    

struct aws_cryptosdk_keyring *kms_keyring =
        Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn);
Langkah 3: Buat sesi.

Buat sesi menggunakan allocator dan keyring. Untuk mengkonfigurasi sesi dekripsi, konfigurasikan sesi denganAWS_CRYPTOSDK_DECRYPTmode.

Setelah Anda membuat sesi dengan keyring, Anda dapat melepaskan referensi Anda ke keyring menggunakan metode yang SDK menyediakan. Sesi mempertahankan referensi ke objek keyring selama masa hidupnya, dan kedua sesi dan keyring dilepaskan ketika Anda menghancurkan sesi. Teknik penghitungan referensi ini membantu mencegah kebocoran memori dan mencegah objek dilepaskan saat sedang digunakan.

struct aws_cryptosdk_session *session =	
	aws_cryptosdk_session_new_from_keyring_2(alloc, AWS_CRYPTOSDK_DECRYPT, kms_keyring);

/* When you add the keyring to the session, release the keyring object */
aws_cryptosdk_keyring_release(kms_keyring);
Langkah 4: Dekripsi string.

Untuk mendekripsi string, gunakanaws_cryptosdk_session_process_fullmetode dengan sesi yang dikonfigurasi untuk dekripsi. Metode ini, diperkenalkan diAWS Encryption SDKversi 1.9.xdan 2.2.x, dirancang untuk enkripsi non-streaming dan dekripsi. Untuk menangani data streaming, hubungiaws_cryptosdk_session_processdalam lingkaran.

Ketika mendekripsi, bidang ciphertext adalah bidang input dan bidang plaintext adalah bidang output. Parameterciphertext_inputmemegangpesan terenkripsibahwa metode enkripsi kembali. Saat pemrosesan selesai,plaintext_outputbidang berisi plaintext (didekripsi) string.

size_t plaintext_len_output;

if (AWS_OP_SUCCESS != aws_cryptosdk_session_process_full(session,
                                  plaintext_output,
                                  plaintext_buf_sz_output,
                                  &plaintext_len_output,
                                  ciphertext_input,
                                  ciphertext_len_input)) {
    aws_cryptosdk_session_destroy(session);
    return 13;
}
Langkah 5: Memverifikasi konteks enkripsi.

Pastikan bahwa konteks enkripsi sebenarnya — yang digunakan untuk mendekripsi pesan — berisi konteks enkripsi yang Anda berikan saat mengenkripsi pesan. Konteks enkripsi yang sebenarnya mungkin termasuk pasangan tambahan, karenaManajer bahan kriptografi(CMM) dapat menambahkan pasangan ke konteks enkripsi yang disediakan sebelum mengenkripsi pesan.

DiAWS Encryption SDK for C, Anda tidak diharuskan untuk memberikan konteks enkripsi saat mendekripsi karena konteks enkripsi disertakan dalam pesan terenkripsi yang dikembalikan SDK. Tapi, sebelum mengembalikan pesan plaintext, fungsi dekripsi Anda harus memverifikasi bahwa semua pasangan dalam konteks enkripsi yang disediakan muncul dalam konteks enkripsi yang digunakan untuk mendekripsi pesan.

Pertama, dapatkan pointer read-only ke tabel hash di sesi. Tabel hash ini berisi konteks enkripsi yang digunakan untuk mendekripsi pesan. 

const struct aws_hash_table *session_enc_ctx = aws_cryptosdk_session_get_enc_ctx_ptr(session);

Kemudian, loop melalui konteks enkripsi dimy_enc_ctxtabel hash yang Anda salin saat mengenkripsi. Verifikasi bahwa setiap pasangan dimy_enc_ctxtabel hash yang digunakan untuk mengenkripsi muncul disession_enc_ctxtabel hash yang digunakan untuk mendekripsi. Jika ada kunci yang hilang, atau kunci itu memiliki nilai yang berbeda, hentikan pemrosesan dan tulis pesan kesalahan.

for (struct aws_hash_iter iter = aws_hash_iter_begin(my_enc_ctx); !aws_hash_iter_done(&iter);
      aws_hash_iter_next(&iter)) {
     struct aws_hash_element *session_enc_ctx_kv_pair;
     aws_hash_table_find(session_enc_ctx, iter.element.key, &session_enc_ctx_kv_pair)

    if (!session_enc_ctx_kv_pair ||
        !aws_string_eq(
            (struct aws_string *)iter.element.value, (struct aws_string *)session_enc_ctx_kv_pair->value)) {
        fprintf(stderr, "Wrong encryption context!\n");
        abort();
    }
}
Langkah 6: Membersihkan sesi.

Setelah Anda memverifikasi konteks enkripsi, Anda dapat menghancurkan sesi, atau menggunakannya kembali. Jika Anda perlu mengkonfigurasi ulang sesi, gunakanaws_cryptosdk_session_resetmetode.

aws_cryptosdk_session_destroy(session);