使用 適用於 C 的 AWS Encryption SDK

本主題說明在其他程式設計語言實作中不支援的一些 適用於 C 的 AWS Encryption SDK 功能。

本節中的範例展示如何使用2.0 版。x和後來的適用於 C 的 AWS Encryption SDK。有關使用早期版本的示例，請在版本的清單AWS 加密 sdk-c 存儲庫資 GitHub。

如需相關詳細資訊適用於 C 的 AWS Encryption SDK，請參C 範例，例子中的AWS 加密 sdk-c 存儲庫在 GitHub 上，並且適用於 C 的 AWS Encryption SDKAPI 文件。

另請參閱：使用 keyring

加密和解密資料的模式

當您使用 適用於 C 的 AWS Encryption SDK 時，請依照類似這裡的模式：建立 keyring、建立使用 keyring 的 CMM、建立使用 CMM (和 keyring) 的工作階段，然後處理工作階段。

1. 載入錯誤字符串。

呼叫aws_cryptosdk_load_error_strings()方法，請參考 C 或 C ++ 代碼。它加載對調試非常有用的錯誤信息。

您只需調用一次，例如在main方法。

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

2. 建立 keyring。

使用您想用來加密資料金鑰的包裝金鑰來設定 keyring。此範例使用AWS KMSKeyring，具備一個AWS KMS key，但您可以改用任何類型的 keyring。

要標識AWS KMS key在加密密鑰環中適用於 C 的 AWS Encryption SDK中，指定金鑰 ARN或者別名 ARN。在解密 Keyring 中，您必須使用金鑰 ARN。如需詳細資訊，請參閱 在 AWS KMS 鑰匙圈 AWS KMS keys 中識別。

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. 建立工作階段。

在 適用於 C 的 AWS Encryption SDK 中，您可以使用工作階段來加密單一純文字訊息，或解密單一加密文字訊息，而無論其大小。此工作階段在整個處理過程中會維護訊息的狀態。

使用分配器、keyring 和模式來設定您的工作階段：AWS_CRYPTOSDK_ENCRYPT 或 AWS_CRYPTOSDK_DECRYPT。如果您需要變更工作階段的模式，請使用 aws_cryptosdk_session_reset 方法。

當您使用 keyring 建立工作階段時，適用於 C 的 AWS Encryption SDK自動為您建立預設的密碼編譯資料管理員 (CMM)。您不需要建立、維護或銷毀此物件。

例如，以下工作階段使用在步驟 1 中定義的分配器和 keyring。當您加密資料時，模式為 AWS_CRYPTOSDK_ENCRYPT。

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

4. 加密或解密資料。

若要在工作階段中處理資料，請使用 aws_cryptosdk_session_process 方法。如果輸入緩衝區夠大，足以容納整個純文字，並且輸出緩衝區夠大，足以容納整個密文字，則可以呼叫aws_cryptosdk_session_process_full。但是，如果您需要處理串流資料，您可以呼叫aws_cryptosdk_session_process在一個循環中。如需範例，請參閱 file_streaming.cpp 範例。所以此aws_cryptosdk_session_process_full引進於AWS Encryption SDK1.9 版。x和 2.2.x。

當工作階段設定為加密資料時，純文字欄位描述輸入，加密文字欄位描述輸出。plaintext 欄位保留您想要加密的訊息，ciphertext 欄位取得加密方法所傳回的加密訊息。

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

當工作階段設定為解密資料時，加密文字欄位描述輸入，純文字欄位描述輸出。ciphertext 欄位保留加密方法所傳回的已加密訊息，plaintext 欄位取得解密方法傳回的純文字訊息。

若要解密資料，請呼叫 aws_cryptosdk_session_process_full 方法。

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

參考計數

為了防止記憶體流失，當您使用完您建立的所有物件參考時，請務必將其釋出。否則會造成記憶體失流。此開發套件提供方法讓您輕鬆這樣做。

每當您使用下列其中一個子物件建立父物件時，父物件會取得並維護對子物件的參考，如下所示：

• keyring，例如，使用 keyring 建立工作階段

• 預設的密碼編譯資料管理員(CMM)，例如，使用預設 CMM 建立工作階段或自訂 CMM

• 資料金鑰快取，例如，使用 keyring 和快取建立快取 CMM

除非您需要對子物件的獨立參考，否則您可以在建立父物件後立即釋出對子物件的參考。在銷毀父物件時，對子物件的其餘參考即會釋出。此模式可確保只在您需要的一段時間內維護每個物件的參考，您不會因為參考未釋放而流失記憶體。

您只需負責釋出您明確建立的子物件參考。您不需負責管理 SDK 為您建立的任何物件的參考。如果 SDK 創建了一個對象（例如默認 CMM）aws_cryptosdk_caching_cmm_new_from_keyring方法，則 SDK 會管理物件及其參考的建立和銷毀。

在下列範例中，當您使用 keyring 建立工作階段，該工作階段會取得 keyring 的參考，並保留該參考，直到工作階段銷毀為止。如果您不需要保有 keyring 的其他參考，您可以使用 aws_cryptosdk_keyring_release 方法在建立工作階段後立即釋出 keyring 物件。此方法可遞減 keyring 的參考計數。當您呼叫 aws_cryptosdk_session_destroy 來銷毀工作階段時，將會釋出工作階段對 keyring 的參考。

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

對於更複雜的工作，例如對多個工作階段重複使用 keyring 或在 CMM 中指定演算法套件，您可能需要維護物件的獨立參考。如果是這樣，請勿立即呼叫釋出方法。而是除了銷毀工作階段之外，當您不再使用這些物件時，請釋出您的參考。

當您使用備用 CMM 時，此引用計數技術也可以使用，例如資料金鑰快取。當您從快取和 keyring 建立快取 CMM 時，快取 CMM 會取得對這兩個物件的參考。除非您需要它們進行另一項任務，否則您可以在建立快取後立即釋出對快取和 keyring 的獨立參考。然後，當您使用快取 CMM 建立工作階段時，您可以釋出您對快取 CMM 的參考。

請注意，您只需負責釋出您明確建立的物件參考。方法為您建立的物件，例如快取底層的預設 CMM，是由方法管理。

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