AWS Encryption SDK for JavaScript 例 - AWS Encryption SDK
AWS KMS キーリングによるデータの暗号化AWS KMS キーリングを使用したデータの復号化

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

AWS Encryption SDK for JavaScript 例

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

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

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

AWS KMS キーリングによるデータの暗号化

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

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

ステップ 1: コミットメントポリシーを設定します。

のバージョン 1.7.x 以降では AWS Encryption SDK for JavaScript、 AWS Encryption SDK クライアントをインスタンス化する新しいbuildClient関数を呼び出すときに、コミットメントポリシーを設定できます。buildClient 関数は、コミットメントポリシーを表す列挙値を取ります。更新された encrypt 関数と decrypt 関数が返されて、暗号化および復号化時にコミットメントポリシーが適用されます。

次の例では、 buildClient関数を使用してデフォルトのコミットメントポリシー 、 を指定しますREQUIRE_ENCRYPT_REQUIRE_DECRYPT。を使用してbuildClient、暗号化されたメッセージ内の暗号化されたデータキーの数を制限することもできます。詳細については、「暗号化されたデータキーの制限」を参照してください。

JavaScript Browser
import {
  KmsKeyringBrowser,
  KMS,
  getClient,
  buildClient,
  CommitmentPolicy,
} from '@aws-crypto/client-browser'

const { encrypt, decrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
JavaScript Node.js
import {
  KmsKeyringNode,
  buildClient,
  CommitmentPolicy,
} from '@aws-crypto/client-node'
                                
const { encrypt, decrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
ステップ 2: キーリングを作成します。

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

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

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

注記

キー AWS KMS リングを復号化に再利用する場合は、キーリング AWS KMS keys で を識別ARNsするためにキーを使用する必要があります。

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

JavaScript Browser

まず、ブラウザの認証情報を指定します。この例では、ウェブパック AWS Encryption SDK for JavaScript を使用します。これは、認証情報定数を実際の認証情報に置き換えます。 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 キーリングを作成します AWS KMS keys。

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

暗号化コンテキストは、任意の、シークレットではない追加認証データです。暗号化時に暗号化コンテキストを指定すると、 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'
}
ステップ 4: データを暗号化します。

プレーンテキストのデータを暗号化するには、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: コミットメントポリシーを設定します。

のバージョン 1.7.x 以降では AWS Encryption SDK for JavaScript、 AWS Encryption SDK クライアントをインスタンス化する新しいbuildClient関数を呼び出すときに、コミットメントポリシーを設定できます。buildClient 関数は、コミットメントポリシーを表す列挙値を取ります。更新された encrypt 関数と decrypt 関数が返されて、暗号化および復号化時にコミットメントポリシーが適用されます。

次の例では、 buildClient関数を使用してデフォルトのコミットメントポリシー 、 を指定しますREQUIRE_ENCRYPT_REQUIRE_DECRYPT。を使用してbuildClient、暗号化されたメッセージ内の暗号化されたデータキーの数を制限することもできます。詳細については、「暗号化されたデータキーの制限」を参照してください。

JavaScript Browser
import {
  KmsKeyringBrowser,
  KMS,
  getClient,
  buildClient,
  CommitmentPolicy,
} from '@aws-crypto/client-browser'

const { encrypt, decrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
JavaScript Node.js
import {
  KmsKeyringNode,
  buildClient,
  CommitmentPolicy,
} from '@aws-crypto/client-node'
                                
const { encrypt, decrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
ステップ 2: キーリングを作成します。

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

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

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

注記

暗号化と復号に同じキーリングを使用する場合は、キーリング AWS KMS keys で を識別ARNsするためにキーを使用します。

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

JavaScript Browser

まず、ブラウザの認証情報を指定します。この例では、ウェブパック AWS Encryption SDK for JavaScript を使用します。これは、認証情報定数を実際の認証情報に置き換えます。 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 })
ステップ 3: データを復号します。

次に、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)
ステップ 4: 暗号化コンテキストを確認します。

データの復号に使用した暗号化コンテキストは、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')
})

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