AWS Encryption SDK for C の例 - AWS Encryption SDK
文字列の暗号化と復号

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

AWS Encryption SDK for C の例

以下の例では、AWS Encryption SDK for C を使用してデータの暗号化と復号を行う方法を示します。

このセクションの例では、AWS Encryption SDK for C のバージョン 2.0.x 以降の使用方法について説明します。　 前バージョンを使用する例については、GitHub の aws-encryption-sdk-c リポジトリのリリースリストで使用中のリリースを検索してください。

AWS Encryption SDK for C をインストールおよび構築する場合、これらの例やその他の例のソースコードは examples サブディレクトリに含まれており、build ディレクトリにコンパイルおよびビルドされます。GitHub の aws-encryption-sdk-c リポジトリの examples サブディレクトリで検索することもできます。

文字列の暗号化と復号

次の例は、AWS Encryption SDK for C を使用して文字列の暗号化と復号を行う方法を示しています。

この例では、AWS Key Management Service (AWS KMS) で AWS KMS key を使用してデータキーの生成と暗号化を行うタイプのキーリングである AWS KMS キーリング を特徴としています。この例には C++ で記述されたコードが含まれています。　 AWS Encryption SDK for C は、AWS KMS キーリングを使用する場合、AWS SDK for C++ が AWS KMS を呼び出すよう要求します。未加工の AES キーリング、未加工の RSA キーリング、または AWS KMS キーリングを含まないマルチキーリングなど、AWS KMS と相互作用しないキーリングを使用している場合は、AWS SDK for C++ は必要ありません。

AWS KMS key の作成については、「AWS Key Management Service デベロッパーガイド」の「キーの作成」を参照してください。AWS KMS キーリングでの AWS KMS keys の識別方法については、「AWS KMS キーリングの AWS KMS keys の指定」を参照してください。

完全なコードサンプルの参照: string.cpp

文字列の暗号化

この例の最初の部分では、AWS KMS キーリングと 1 つの AWS KMS keyを使用してプレーンテキストの文字列を暗号化します。

ステップ 1。エラー文字列をロード

C コードまたは C++ コードで aws_cryptosdk_load_error_strings() メソッドを呼び出します。デバッグに非常に役立つエラー情報をロードします。

main メソッド内でなど、1 回だけ呼び出す必要があります。

/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();
ステップ 2: キーリングを作成します。

暗号化に使用する AWS KMS キーリングを作成します。この例のキーリングは 1 つの AWS KMS key で設定されていますが、AWS KMS キーリングは異なる AWS リージョン や異なるアカウントの AWS KMS keys などの複数の AWS KMS keys で設定することができます。

「AWS Encryption SDK for C」内の暗号化キーリングで AWS KMS key を識別するには、キー ARN または エイリアス ARN を指定します。復号キーリングでは、キー ARN を使用する必要があります。詳細については、「AWS KMS キーリングの AWS KMS keys の指定」を参照してください。

AWS KMS キーリングの AWS KMS keys の指定

複数の AWS KMS keys を使用してキーリングを作成する場合は、プレーンテキストのデータキーの生成と暗号化に使用する AWS KMS key と、同じプレーンテキストのデータキーを暗号化する追加の AWS KMS keys の任意の配列を指定します。この例では、ジェネレーター AWS KMS key のみを指定します。

このコードを実行する前に、キー ARN を有効なキー ARN に置き換えます。

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: セッションを作成します。

アロケーター、モードの列挙子、キーリングを使用してセッションを作成します。

各セッションは、AWS_CRYPTOSDK_ENCRYPT モード (暗号化) または AWS_CRYPTOSDK_DECRYPT モード (復号) にする必要があります。既存のセッションのモードを変更するには、aws_cryptosdk_session_reset メソッドを使用します。

キーリングを使用してセッションを作成したら、SDK が提供する機能を使用してキーリングへの参照を解放できます。セッションは、その有効期間中、キーリングオブジェクトへの参照を保持します。セッションを破棄すると、キーリングオブジェクトやセッションオブジェクトへの参照が解放されます。この参照カウント方式は、メモリリークを防ぎ、オブジェクトが使用中に解放されないようにするために役立ちます。

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);
ステップ 4: 暗号化コンテキストを設定します。

暗号化コンテキストは、任意の、シークレットではない追加認証データです。暗号化時に暗号化コンテキストを指定した場合は、暗号化コンテキストは、AWS Encryption SDK によって、データの復号時に同じ暗号コンテキストが使用されるように、暗号を使用して暗号化テキストにバインドされます。暗号化コンテキストの使用はオプションですが、ベストプラクティスとして推奨します。

まず、暗号化コンテキスト文字列を含むハッシュテーブルを作成します。

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

セッション内の暗号化コンテキストへの変更可能なポインタを取得します。次に、aws_cryptosdk_enc_ctx_clone 関数を使用して、暗号化コンテキストをセッションにコピーします。コピーを my_enc_ctx に保持しているため、データの復号後に値を検証することができます。

暗号化コンテキストはセッションの一部であり、セッション処理関数に渡されるパラメータではありません。これにより、メッセージ全体を暗号化するためにセッション処理関数が複数回呼び出された場合でも、必ずメッセージのすべてのセグメントに同じ暗号化コンテキストが使用されるようになります。

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)
ステップ 5: 文字列を暗号化します。

プレーンテキストの文字列を暗号化するには、暗号化モードのセッションで aws_cryptosdk_session_process_full メソッドを使用します。AWS Encryption SDK バージョン 1.9.x および 2.2.x で導入されたこのメソッドは、非ストリーミングの暗号化および復号化のために設計されています。ストリーミングデータを処理するには、ループで aws_cryptosdk_session_process を呼び出します。

暗号化する場合、プレーンテキストフィールドは入力フィールド、暗号化テキストフィールドは出力フィールドです。処理が完了すると、ciphertext_output フィールドには、暗号化されたメッセージ (例: 実際の暗号化テキスト、暗号化されたデータキー、暗号化コンテキスト) が含まれます。この暗号化されたメッセージの復号は、サポートされている任意のプログラミング言語の AWS Encryption SDK を使用して行うことができます。

/* 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;
}
ステップ 6: セッションをクリーンアップします。

最終ステップでは、CMM とキーリングへの参照を含むセッションを破棄します。

必要に応じて、セッションを破棄せずに、同じキーリングと CMM でセッションを再利用し、文字列の復号や、他のメッセージの暗号化または復号を行うことができます。復号のセッションを使用するには、aws_cryptosdk_session_reset メソッドを使用して、モードを AWS_CRYPTOSDK_DECRYPT に変更します。

文字列の復号

この例の 2 番目の部分では、元の文字列の暗号化テキストを含む暗号化されたメッセージを復号します。

ステップ 1: エラー文字列をロード

C コードまたは C++ コードで aws_cryptosdk_load_error_strings() メソッドを呼び出します。デバッグに非常に役立つエラー情報をロードします。

main メソッド内でなど、1 回だけ呼び出す必要があります。

/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();
ステップ 2: キーリングを作成します。

AWS KMS のデータを復号する場合は、返る API を暗号化する暗号化されたメッセージで渡します。復号 API では、AWS KMS key を入力として使用することはありません。代わりに、AWS KMS は暗号化に使用したものと同じ AWS KMS key を使用して暗号化テキストを復号します。ただし、AWS Encryption SDK では、暗号化時および復号時に AWS KMS keys を使用する AWS KMS キーリングを指定することができます。

復号では、暗号化されたメッセージの復号に使用する AWS KMS keys でのみキーリングを設定することができます。例えば、組織の特定のロールで使用する AWS KMS key のみを使用してキーリングを作成することができます。AWS Encryption SDK では、復号キーリングにない AWS KMS key を使用することはありません。SDK で指定したキーリングの AWS KMS keys を使用して暗号化されたデータキーを復号できない場合は、そのデータキーの暗号化にそのキーリングの AWS KMS keys が使用されていないか、呼び出し元にそのキーリングの AWS KMS keys を使用して復号するためのアクセス許可がないために復号の呼び出しが失敗します。

復号キーリングに AWS KMS key を指定する場合は、そのキー ARN を使用する必要があります。エイリアス ARN は、暗号化キーリングでのみ許可されます。AWS KMS キーリングでの AWS KMS keys の識別方法については、「AWS KMS キーリングの AWS KMS keys の指定」を参照してください。

この例では、文字列の暗号化に使用したものと同じ AWS KMS key が設定されているキーリングを指定します。このコードを実行する前に、キー ARN を有効なキー ARN に置き換えます。

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: セッションを作成します。

アロケーターとキーリングを使用してセッションを作成します。セッションを復号用に設定するには、セッションを AWS_CRYPTOSDK_DECRYPT モードに設定します。

キーリングを使用してセッションを作成したら、SDK が提供する機能を使用してキーリングへの参照を解放できます。セッションは、その有効期間中、キーリングオブジェクトへの参照を保持します。セッションを破棄すると、セッションとキーリングの両方が解放されます。この参照カウント方式は、メモリリークを防ぎ、オブジェクトが使用中に解放されないようにするために役立ちます。

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);
ステップ 4: 文字列を復号します。

文字列を復号するには、復号用に設定されているセッションで aws_cryptosdk_session_process_full メソッドを使用します。AWS Encryption SDK バージョン 1.9.x および 2.2.x で導入されたこのメソッドは、非ストリーミングの暗号化および復号化のために設計されています。ストリーミングデータを処理するには、ループで aws_cryptosdk_session_process を呼び出します。

復号する際、暗号化テキストフィールドは入力フィールド、プレーンテキストフィールドは出力フィールドです。ciphertext_input フィールドには、返るメソッドを暗号化する暗号化されたメッセージが含まれます。処理が完了すると、plaintext_output フィールドには、プレーンテキスト (復号された) 文字列が含まれます。

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;
}
ステップ 5: 暗号化コンテキストを確認します。

実際の暗号化コンテキスト (メッセージの復号に使用されたもの) に、メッセージの暗号化時に指定した暗号化コンテキストが含まれていることを確認します。暗号化マテリアルマネージャー (CMM) によって、メッセージの暗号化前に指定した暗号化コンテキストにペアが追加される場合があるため、実際の暗号化コンテキストには、追加のペアが含まれる場合があります。

AWS Encryption SDK for C では、暗号化コンテキストは SDK から返される暗号化されたメッセージに含まれているため、復号時に暗号化コンテキストを指定する必要はありません。ただし、プレーンテキストのメッセージが返る前に、復号関数を使用して、返った暗号化コンテキスト内のすべてのペアが、メッセージの復号に使用された暗号化コンテキスト内にあることを確認する必要があります。

まず、セッション内のハッシュテーブルへの読み取り専用ポインタを取得します。このハッシュテーブルには、メッセージの復号に使用された暗号化コンテキストが含まれています。

const struct aws_hash_table *session_enc_ctx = aws_cryptosdk_session_get_enc_ctx_ptr(session);

次に、暗号化時にコピーした my_enc_ctx ハッシュテーブル内の暗号化コンテキストをループします。暗号化に使用された my_enc_ctx ハッシュテーブルの各ペアが、復号に使用された session_enc_ctx ハッシュテーブルに表示されていることを確認します。キーが見つからない場合や、キーが別の値の場合は、処理を停止し、エラーメッセージを書き込みます。

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();
    }
}
ステップ 6: セッションをクリーンアップします。

暗号化コンテキストを確認したら、セッションは破棄、または再利用できます。セッションを再設定する必要がある場合は、aws_cryptosdk_session_reset メソッドを使用します。

aws_cryptosdk_session_destroy(session);