AWS Encryption SDK for JavaScript の例

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

AWS Encryption SDK for JavaScript の使用例については、GitHub の aws-encryption-sdk-javascript リポジトリで example-node および example-browser モジュールを参照してください。これらのサンプルモジュールは、client-browser モジュールや client-node モジュールのインストール時にはインストールされません。

詳しいサンプルコードについては、ノードの場合は kms_simple.ts、ブラウザの場合は kms_simple.ts を参照してください。

AWS KMS キーリングを使用したデータの暗号化

以下の例では、AWS Encryption SDK for JavaScript を使用して短い文字列やバイト配列を暗号化および復号する方法を示します。

この例では、AWS KMS key を使用してデータキーの生成と暗号化を行うタイプのキーリングである AWS KMS キーリングについて詳しく説明します。AWS KMS key の作成については、「AWS Key Management Service デベロッパーガイド」の「キーの作成」を参照してください。AWS KMS キーリングでの AWS KMS keys の識別方法については、「キーリング AWS KMS keys での AWS KMS の識別」を参照してください。

ステップ 1: キーリングを作成します。

暗号化に使用する AWS KMS キーリングを作成します。

AWS KMS キーリングを使用して暗号化する場合は、ジェネレーターキーを指定する必要があります。これは、プレーンテキストのデータキーを生成してそれを暗号化する AWS KMS key です。また、同じプレーンテキストのデータキーを暗号化する追加のキーを必要な数だけ指定することもできます。キーリングは、キーリングの AWS KMS key (ジェネレーターキーを含む) ごとに、プレーンテキストのデータキーとそのデータキーの 1 つの暗号化されたコピーを返します。データを復号するには、この暗号化されたデータキーのいずれかを復号する必要があります。

AWS Encryption SDK for JavaScript の暗号化キーリングの AWS KMS keys を指定するには、サポートされている任意の AWS KMS キー識別子を使用できます。この例では、エイリアス ARN で指定するジェネレーターキーとキー ARN で指定する 1 つの追加のキーを使用します。

注記

復号に AWS KMS キーリングを再利用する場合は、キー ARN を使用してキーリングの AWS KMS keys を指定する必要があります。

このコードを実行する前には、例の AWS KMS key の識別子を有効な識別子に置き換えてください。キーリングの AWS KMS keys を使用するために必要なアクセス許可を持っている必要があります。

JavaScript Browser

まず、ブラウザの認証情報を指定します。この AWS Encryption SDK for JavaScript の例では、認証情報の定数を実際の認証情報に置き換える webpack.DefinePlugin を使用しています。ただし、認証情報の指定には任意の方法を使用することができます。次に、その認証情報を使用して AWS KMS クライアントを作成します。

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

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

次に、ジェネレーターキーと追加のキーの AWS KMS keys を指定します。次に、その AWS KMS クライアントと AWS KMS keys を使用して AWS KMS キーリングを作成します。

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

ステップ 2: 暗号化コンテキストを設定します。

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

暗号化コンテキストのペアを含むシンプルなオブジェクトを作成します。各ペアのキーと値は、文字列である必要があります。

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'
}

ステップ 3: データを暗号化します。

プレーンテキストのデータを暗号化するには、encrypt 関数を呼び出します。AWS KMS キーリング、プレーンテキストのデータ、暗号化コンテキストを渡します。

encrypt 関数は、暗号化されたデータ、暗号化されたデータキー、重要なメタデータ (暗号化コンテキストや署名など) を含む暗号化されたメッセージ (result) を返します。

この暗号化されたメッセージの復号は、サポートされている任意のプログラミング言語の AWS Encryption SDK を使用して行うことができます。

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

AWS KMS キーリングを使用したデータの復号化

AWS Encryption SDK for JavaScript を使用して、暗号化されたメッセージを復号して元のデータに戻すことができます。

この例では、「AWS KMS キーリングを使用したデータの暗号化」の例で暗号化したデータを復号します。

ステップ 1: キーリングを作成します。

データを復号するには、encrypt 関数が返す暗号化されたメッセージ (result) を渡します。暗号化されたメッセージには、暗号化されたデータ、暗号化されたデータキー、重要なメタデータ (暗号化コンテキストや署名など) が含まれています。

AWS KMS キーリングは、復号時にも指定する必要があります。データの暗号化に使用したものと同じキーリングを使用することも、別のキーリングを使用することもできます。復号が成功するには、復号キーリングの少なくとも 1 つの AWS KMS key が暗号化されたメッセージの暗号化されたデータキーのいずれかを復号できる必要があります。データキーは生成されないため、復号キーリングでジェネレーターキーを指定する必要はありません。指定しても、ジェネレーターキーと追加のキーは同じように扱われます。

AWS Encryption SDK for JavaScript の復号キーリングの AWS KMS key を指定するには、キー ARN を使用する必要があります。使用しない場合、AWS KMS key は認識されません。AWS KMS キーリングでの AWS KMS keys の識別方法については、「キーリング AWS KMS keys での AWS KMS の識別」を参照してください。

注記

暗号化と復号に同じキーリングを使用する場合は、キー ARN を使用してキーリングの AWS KMS keys を指定します。

この例では、暗号化キーリングの 1 つの AWS KMS keys のみを含むキーリングを作成します。このコードを実行する前に、キー ARN を有効なキー ARN に置き換えます。AWS KMS key に対する kms:Decrypt アクセス許可が必要です。

JavaScript Browser

まず、ブラウザの認証情報を指定します。この AWS Encryption SDK for JavaScript の例では、認証情報の定数を実際の認証情報に置き換える webpack.DefinePlugin を使用しています。ただし、認証情報の指定には任意の方法を使用することができます。次に、その認証情報を使用して AWS KMS クライアントを作成します。

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

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

次に、その AWS KMS クライアントを使用して AWS KMS キーリングを作成します。この例では、暗号化キーリングの 1 つの AWS KMS keys のみを使用します。

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

ステップ 2: データを復号します。

次に、decrypt 関数を呼び出します。先ほど作成した復号化キーリング (keyring) および encrypt 関数が返す暗号化されたメッセージ (result) を渡します。AWS Encryption SDK は、このキーリングを使用して、暗号化されたデータキーの 1 つを復号します。次に、そのプレーンテキストのデータキーを使用してデータを復号します。

呼び出しが成功すると、plaintext フィールドにはプレーンテキストの (復号された) データが含まれます。messageHeader フィールドには、データの復号に使用した暗号化コンテキストなどの復号プロセスに関するメタデータが含まれます。

JavaScript Browser

const { plaintext, messageHeader } = await decrypt(keyring, result)

JavaScript Node.js

const { plaintext, messageHeader } = await decrypt(keyring, result)

ステップ 3: 暗号化コンテキストを確認します。

データの復号に使用した暗号化コンテキストは、decrypt 関数から返されるメッセージヘッダー (messageHeader) に含まれます。アプリケーションでプレーンテキストのデータを返す前に、暗号化時に指定した暗号化コンテキストが復号時に使用した暗号化コンテキストに含まれていることを確認します。一致しない場合は、データが改ざんされたか、復号する暗号化テキストを間違ったことを示している可能性があります。

暗号化コンテキストを確認する際は、完全に一致している必要ありません。署名付きの暗号化アルゴリズムを使用する場合、暗号化マテリアルマネージャー (CMM) は、メッセージを暗号化する前にパブリック署名キーを暗号化コンテキストに追加します。ただし、送信したすべての暗号化コンテキストのペアが返された暗号化コンテキストに含まれている必要があります。

まず、メッセージヘッダーから暗号化コンテキストを取得します。次に、元の暗号化コンテキスト (context) のキーと値の各ペアが、返された暗号化コンテキスト (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')
})

暗号化コンテキストを確認して問題がなければ、プレーンテキストのデータを返すことができます。