Menggunakan AWS Encryption SDK for C

Topik ini menjelaskan beberapa fitur dariAWS Encryption SDK for Cyang tidak didukung dalam implementasi bahasa pemrograman lainnya.

Contoh dalam bagian ini menunjukkan cara menggunakanversi 2.0.xdan setelahnyaAWS Encryption SDK for C. Untuk contoh yang menggunakan versi sebelumnya, temukan rilis Anda diRilisdaftarrepositori aws-encryption-sdk-crepositori di GitHub.

Untuk rincian tentang pemrograman denganAWS Encryption SDK for C, lihatC contoh, yangcontohdirepositori aws-encryption-sdk-cdi GitHub, danAWS Encryption SDK for CDokumentasi API.

Lihat juga:Menggunakan keyrings

Pola untuk mengenkripsi dan mendekripsi data

Bila Anda menggunakanAWS Encryption SDK for C, Anda mengikuti pola yang mirip dengan ini: membuatkeyring, membuatCMMyang menggunakan keyring, membuat sesi yang menggunakan CMM (dan keyring), dan kemudian memproses sesi.

1. Memuat string kesalahan.

Panggilaws_cryptosdk_load_error_strings()Metode dalam kode C atau C++ Anda. 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();

2. Buat keyring.

Mengonfigurasikeyringdengan kunci pembungkus yang ingin Anda gunakan untuk mengenkripsi kunci data Anda. Contoh ini menggunakanAWS KMSkeyringdengan satuAWS KMS key, tetapi Anda dapat menggunakan semua jenis keyring di tempatnya.

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.

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

3. Buat sesi.

DiAWS Encryption SDK for C, Anda menggunakansesiuntuk mengenkripsi pesan teks biasa tunggal atau mendekripsi pesan ciphertext tunggal, terlepas dari ukurannya. Sesi mempertahankan keadaan pesan di seluruh pemrosesannya.

Konfigurasikan sesi Anda dengan pengalokasi, keyring, dan mode:AWS_CRYPTOSDK_ENCRYPTatauAWS_CRYPTOSDK_DECRYPT. Jika Anda perlu mengubah mode sesi, gunakanaws_cryptosdk_session_resetmetode.

Ketika Anda membuat sesi dengan keyring,AWS Encryption SDK for Cotomatis membuat default cryptographic materials manager (CMM) untuk Anda. Anda tidak perlu membuat, memelihara, atau menghancurkan objek ini.

Misalnya, sesi berikut menggunakan allocator dan keyring yang didefinisikan pada langkah 1. Saat Anda mengenkripsi data, modenyaAWS_CRYPTOSDK_ENCRYPT.

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

4. Mengenkripsi atau mendekripsi data.

Untuk memproses data dalam sesi, gunakanaws_cryptosdk_session_processmetode. Jika buffer input cukup besar untuk menahan seluruh plaintext, dan buffer output cukup besar untuk menahan seluruh ciphertext, Anda dapat memanggilaws_cryptosdk_session_process_full. Namun, jika Anda perlu menangani data streaming, Anda dapat menghubungiaws_cryptosdk_session_processdalam satu lingkaran. Sebagai contoh, lihatfile_streaming.cppcontoh. Parameteraws_cryptosdk_session_process_fulldiperkenalkan diAWS Encryption SDKversi 1.9.xdan 2.2.x.

Ketika sesi dikonfigurasi untuk mengenkripsi data, bidang plaintext menggambarkan input dan bidang ciphertext menggambarkan output. Parameterplaintextbidang memegang pesan yang ingin Anda enkripsi danciphertextbidang mendapatpesan terenkripsibahwa metode enkripsi kembali.

/* Encrypting data */
aws_cryptosdk_session_process_full(session,
                                   ciphertext,
                                   ciphertext_buffer_size,
                                   &ciphertext_length,
                                   plaintext,
                                   plaintext_length)
                              

Ketika sesi dikonfigurasi untuk mendekripsi data, bidang ciphertext menggambarkan input dan bidang plaintext menggambarkan output. Parameterciphertextbidang memegangpesan terenkripsibahwa metode enkripsi kembali, danplaintextbidang mendapat pesan plaintext bahwa metode mendekripsi kembali.

Untuk mendekripsi data, panggilaws_cryptosdk_session_process_fullmetode.

/* Decrypting data */
aws_cryptosdk_session_process_full(session,
                                   plaintext,
                                   plaintext_buffer_size,
                                   &plaintext_length,
                                   ciphertext,
                                   ciphertext_length)
                                   

Penghitungan referensi

Untuk mencegah kebocoran memori, pastikan untuk melepaskan referensi Anda ke semua objek yang Anda buat ketika Anda selesai dengan mereka. Jika tidak, Anda berakhir dengan kebocoran memori. SDK menyediakan metode untuk membuat tugas ini lebih mudah.

Setiap kali Anda membuat objek induk dengan salah satu objek anak berikut, objek induk mendapat dan mempertahankan referensi ke objek anak, sebagai berikut:

• SEBUAHkeyring, seperti membuat sesi dengan keyring

• BawaanManajer bahan kriptografi(CMM), seperti membuat sesi atau kustom CMM dengan CMM default

• SEBUAHCache kunci data, seperti membuat caching CMM dengan keyring dan cache

Kecuali Anda memerlukan referensi independen ke objek anak, Anda dapat melepaskan referensi Anda ke objek anak segera setelah Anda membuat objek induk. Referensi yang tersisa untuk objek anak dilepaskan ketika objek induk hancur. Pola ini memastikan bahwa Anda mempertahankan referensi ke setiap objek hanya selama Anda membutuhkannya, dan Anda tidak membocorkan memori karena referensi yang belum dirilis.

Anda hanya bertanggung jawab untuk melepaskan referensi ke objek anak yang Anda buat secara eksplisit. Anda tidak bertanggung jawab untuk mengelola referensi ke objek apa pun yang dibuat SDK untuk Anda. Jika SDK membuat objek, seperti CMM default yangaws_cryptosdk_caching_cmm_new_from_keyringMetode menambah sesi, SDK mengelola penciptaan dan penghancuran objek dan referensinya.

Pada contoh berikut, saat Anda membuat sesi dengankeyring, sesi mendapat referensi ke keyring, dan mempertahankan referensi itu sampai sesi hancur. Jika Anda tidak perlu mempertahankan referensi tambahan ke keyring, Anda dapat menggunakanaws_cryptosdk_keyring_releasemetode untuk melepaskan objek keyring segera setelah sesi dibuat. Metode ini mengurangi jumlah referensi untuk keyring. Referensi sesi ke keyring dilepaskan saat Anda meneleponaws_cryptosdk_session_destroyuntuk menghancurkan sesi.

// The session gets a reference to the keyring.
struct aws_cryptosdk_session *session =	
	aws_cryptosdk_session_new_from_keyring_2(alloc, AWS_CRYPTOSDK_ENCRYPT, keyring);

// After you create a session with a keyring, release the reference to the keyring object.
aws_cryptosdk_keyring_release(keyring);

Untuk tugas yang lebih kompleks, seperti menggunakan kembali keyring untuk beberapa sesi atau menentukan rangkaian algoritma dalam CMM, Anda mungkin perlu mempertahankan referensi independen ke objek. Jika demikian, jangan segera memanggil metode rilis. Sebagai gantinya, lepaskan referensi Anda saat Anda tidak lagi menggunakan objek, selain menghancurkan sesi.

Teknik penghitungan referensi ini juga bekerja ketika Anda menggunakan CMM alternatif, seperti caching CMM untukcaching kunci data. Ketika Anda membuat caching CMM dari cache dan keyring, caching CMM mendapatkan referensi ke kedua objek. Kecuali Anda membutuhkannya untuk tugas lain, Anda dapat melepaskan referensi independen Anda ke cache dan keyring segera setelah caching CMM dibuat. Kemudian, ketika Anda membuat sesi dengan caching CMM, Anda dapat melepaskan referensi Anda ke caching CMM.

Perhatikan bahwa Anda hanya bertanggung jawab untuk merilis referensi ke objek yang Anda buat secara eksplisit. Objek yang membuat metode untuk Anda, seperti CMM default yang mendasari caching CMM, dikelola oleh metode.

/ Create the caching CMM from a cache and a keyring.
struct aws_cryptosdk_cmm *caching_cmm = aws_cryptosdk_caching_cmm_new_from_keyring(allocator, cache, kms_keyring, NULL, 60, AWS_TIMESTAMP_SECS);

// Release your references to the cache and the keyring.
aws_cryptosdk_materials_cache_release(cache);
aws_cryptosdk_keyring_release(kms_keyring);

// Create a session with the caching CMM.
struct aws_cryptosdk_session *session = aws_cryptosdk_session_new_from_cmm_2(allocator, AWS_CRYPTOSDK_ENCRYPT, caching_cmm);

// Release your references to the caching CMM.
aws_cryptosdk_cmm_release(caching_cmm);

// ...

aws_cryptosdk_session_destroy(session);