AI エージェント向け: ドキュメントインデックスは https://www.mongodb.com/ja-jp/docs/llms.txt で利用できます。すべてのページの markdown バージョンは、いずれかの URL パスに .md を追加することで利用できます。

での自動 の使用Queryable EncryptionAmazon Web Services

このガイドでは、 MongoDB Queryable Encryption機能を実装し、ドキュメントフィールドを自動的に暗号化および復号化し、 Amazon Web Services ( Amazon Web Services )のKMSをキー管理に使用するアプリケーションを構築する方法について説明します。

このガイドの手順を完了すると、次のものが作成されます。

  • Amazon Web Services KMSによって管理される カスタマー マスター キー

  • のカスタマー マスター キーにアクセスする権限を持つ IAM ユーザーAmazon Web ServicesAmazon Web ServicesKMS

  • カスタマー マスター キーを使用して暗号化されたフィールドを持つドキュメントを挿入する動作するクライアント アプリケーション

Tip

CMK(カスタマー マスター キー)

CMK の詳細については、暗号化のキーと Key Vaults のドキュメントをお読みください。

このガイドのコードを完了して実行するには、Queryable Encryption互換ドライバーと依存関係のインストールページに示されているように開発環境を設定する必要があります。

Tip

詳細: フルアプリケーション

このサンプル アプリケーションの完全なコードを確認するには、プログラミング言語に対応するタブを選択し、表示されたリンクに従ってください。 各サンプル アプリケーション リポジトリにはREADME.mdファイルが含まれており、環境を設定しアプリケーションを実行する方法を学習できます。

1

対称 キーの作成 に関する の公式ドキュメントに従って、新しい対称キーを作成しますAmazon Web Services KMS。作成したキーが CMK です。 それを識別するのに役立つ名前と説明を選択します。これらのフィールドは、 CMKの機能や構成に影響を与えません。

キー生成プロセスのUsage Permissionsステップで、カスタマー マスター キーへのアクセスを許可するために、ID とアクセス管理( IAM )ポリシーを有効にする次のデフォルトのキーポリシーを適用します。

{ "Version": "2012-10-17", "Statement": [ { "Sid": "Enable IAM User Permissions", "Effect": "Allow", "Principal": { "AWS": "<ARN of your AWS account principal>" }, "Action": "kms:*", "Resource": "*" } ]}

重要

カスタマー マスター キーの Amazon リソース名( ARN )とリージョンを記録します。 これらはこのガイドの後の手順で使用します。

Tip

キー ポリシー

キー ポリシーの詳細については、 Amazon Web Services の公式ドキュメントの Amazon Web Services KMS のキー ポリシー を参照してください。

2

Amazon Web Services マネジメント コンソールで、新しいプログラムによる IAM ユーザーを作成します。これには、ユーザーの追加 に関する Amazon Web Services の公式ドキュメントに従ってください。Queryable 暗号化 を使用するアプリケーションのサービス アカウントとして、この IAM ユーザーを使用します。アプリケーションは、IAM ユーザーを使用して AWS KMS との間で認証し、CMK を使用してデータ暗号化キー (DEK) を暗号化および復号化します。

重要

認証情報の記録

IAM ユーザーを作成する最後のステップで、次の IAM 認証情報を必ず記録してください。

  • アクセスキー ID

  • シークレット アクセス キー

これらの認証情報を記録する機会が 1 つあります。 このステップの実行中にこれらの認証情報を記録しない場合は、別のIAMユーザーを作成する必要があります。

あなたの IAM ユーザーに、あなたのリモートマスターキーに対するkms:Encrypt と kms:Decrypt の権限を付与します。

重要

新しいクライアントIAM ユーザーには、マスター キーの管理権限があってはなりません。データを安全に保つには、最小特権の原則に従います。

次のインライン ポリシーにより、 IAMユーザーは最小限の特権で CMK を使用して暗号化および復号化を実行できます。

注意

リモート マスター キー ARN

次のポリシーには、このガイドの「 マスター キーの作成 」ステップで生成したキーの ARN が必要です。

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": ["kms:Decrypt", "kms:Encrypt"], "Resource": "<the Amazon Resource Name (ARN) of your remote master key>" } ]}

IAM ユーザーに前述のポリシーを適用するには、 Amazon Web Servicesドキュメントの「 IAM ID 権限の追加 」ガイドに従ってください。

重要

本番環境での IAM ロールによる認証

Queryable Encryption が有効なアプリケーションを本番環境に配置するときは、 IAM ユーザー ではなく IAM ロール を使用してアプリケーションを認証します。

IAMロールの詳細については、 Amazon Web Servicesの公式ドキュメントの次のページを参照してください。

1

このチュートリアルのコード サンプルでは、次の変数を使用して Queryable Encryption ワークフローを実行します。

  • kmsProviderName - CMK の保存に使用している KMS。 このチュートリアルでは、この変数を"aws"に設定します。

  • uri - MongoDB 配置接続 URI。 MONGODB_URI環境変数で接続 URI を設定するか、値を直接置き換えます。

  • keyVaultDatabaseName - データ暗号化キー(DEK)が保存される MongoDB のデータベース。 この変数を"encryption"に設定します。

  • keyVaultCollectionName - DEK が保存される MongoDB のコレクション。 この変数を"__keyVault"に設定します。

  • keyVaultNamespace - DEK が保存される MongoDB の名前空間。 この変数に、ピリオドで区切られたkeyVaultDatabaseName変数とkeyVaultCollectionName変数の値を設定します。

  • encryptionDatabaseName -暗号化されたデータが保存される MongoDB のデータベース。 この変数を"medicalRecords"に設定します。

  • encryptedCollectionName - 暗号化されたデータが保存される MongoDB のコレクション。 この変数を"patients"に設定します。

次のコードを使用して、これらの変数を宣言できます。

// KMS provider name should be one of the following: "aws", "gcp", "azure", "kmip" or "local"const kmsProviderName = "<Your KMS Provider Name>";const uri = process.env.MONGODB_URI; // Your connection URIconst keyVaultDatabaseName = "encryption";const keyVaultCollectionName = "__keyVault";const keyVaultNamespace = `${keyVaultDatabaseName}.${keyVaultCollectionName}`;const encryptedDatabaseName = "medicalRecords";const encryptedCollectionName = "patients";

重要

キーヴォールトコレクションの名前空間権限

Key Vault コレクションはencryption.__keyVault名前空間にあります。 アプリケーションが MongoDB への接続に使用するデータベースユーザーが、この名前空間に対する 読み取り /書き込み権限を持っていることを確認します。

Tip

環境変数

このチュートリアルのサンプル コードは、設定する必要がある環境変数を参照します。 あるいは、コード内で値を直接置き換えることもできます。

これらの環境変数を設定する方法については、Github のサンプルアプリケーションに含まれる README.md ファイルを参照してください。

2

次の構造を持つAmazon Web Services KMS認証情報を含む変数を作成します。 このチュートリアルの「 IAM ユーザーの作成」ステップで作成したアクセス キー ID と シークレット アクセス キー を使用します。

kmsProviderCredentials = { aws: { accessKeyId: process.env["AWS_ACCESS_KEY_ID"], // Your AWS access key ID secretAccessKey: process.env["AWS_SECRET_ACCESS_KEY"], // Your AWS secret access key },};

重要

ヒント: 本番環境で IAM ロールを使用して認証する

IAM ユーザーではなく IAM ロールを使用してアプリケーションを認証するには、KMS プロバイダー オブジェクトで認証情報の空のオブジェクトを指定します。これは、環境から認証情報を自動的に検索するようにドライバーに指示します。

kmsProviders = { aws: { }};

次の構造を持つカスタマー マスター キー(CMK)認証情報を含む変数を作成します。このチュートリアルの「 CMK の作成 」ステップで記録した ARN とリージョンを使用します。

customerMasterKeyCredentials = { key: process.env["AWS_KEY_ARN"], // Your AWS Key ARN region: process.env["AWS_KEY_REGION"], // Your AWS Key Region};

次のオプションを含むautoEncryptionOptionsオブジェクトを作成します。

  • キーヴォールト コレクションの名前空間

  • Amazon Web Services KMS認証情報を含む kmsProviderCredentials オブジェクト

const autoEncryptionOptions = { keyVaultNamespace: keyVaultNamespace, kmsProviders: kmsProviderCredentials,};

注意

自動暗号化オプション

自動暗号化オプションは、暗号化共有ライブラリに構成情報を提供し、暗号化されたフィールドにアクセスするときにアプリケーションの動作を変更します。

自動暗号化共有ライブラリの詳細については、「 Queryable Encryption のための自動暗号化共有ライブラリ」ページを参照してください。

コレクション内のデータの暗号化と復号化に使用されるクライアントを作成するには、接続 URI と 自動暗号化オプションを使用して新しいMongoClientをインスタンス化します。

const encryptedClient = Mongo(uri, autoEncryptionOptions);

フィールドを暗号化するには、暗号化スキーマに追加します。 フィールドでクエリを有効にするには、「クエリ」プロパティを追加します。 暗号化スキーマは、次のように作成します。

const encryptedFieldsMap = { encryptedFields: { fields: [ { path: "patientRecord.ssn", bsonType: "string", queries: { queryType: "equality" }, }, { path: "patientRecord.billing", bsonType: "object", }, ], },};

注意

前のコード例では、「ssn」フィールドと「 Billing 」フィールドの両方が暗号化されていますが、クエリは「ssn」フィールドのみです。

暗号化ヘルパー メソッドの API にアクセスするには、 ClientEncryptionをインスタンス化します。

const clientEncryption = encryptedClient.getClientEncryption()

ClientEncryptionクラスからアクセスされる暗号化ヘルパー メソッドを使用して、暗号化されたコレクションを作成します。 このメソッドは、暗号化されたフィールドのデータ暗号化キーを自動的に生成し、暗号化されたコレクションを作成します。

await clientEncryption.createEncryptedCollection( encryptedDatabaseName, encryptedCollectionName, { provider: kmsProviderName, createCollectionOptions: encryptedFieldsMap, masterKey: customerMasterKeyCredentials, });
3

ユーザの個人情報を説明するサンプルドキュメントを作成します。 次の例に示すように、暗号化されたクライアントを使用して、 patientsコレクションに挿入します。

const patientDocument = { patientName: "Jon Doe", patientId: 12345678, patientRecord: { ssn: "987-65-4320", billing: { type: "Visa", number: "4111111111111111", }, },}; const encryptedCollection = encryptedClient.getDB(encryptedDatabaseName).getCollection(encryptedCollectionName); const insertResult = await encryptedCollection.insertOne(patientDocument);
4

次のコード サンプルでは、暗号化されたフィールドに対して検索クエリを実行し、復号化されたデータを出力します。

const findResult = await encryptedCollection.findOne({ "patientRecord.ssn": "987-65-4320",});console.log(findResult);

上記のコード サンプルの出力は、次のようになります。

{ "_id": { "$oid": "648b384a722cb9b8392df76a" }, "name": "Jon Doe", "record": { "ssn": "987-65-4320", "billing": { "type": "Visa", "number": "4111111111111111" } }, "__safeContent__": [ { "$binary": { "base64": "L1NsYItk0Sg+oL66DBj6IYHbX7tveANQyrU2cvMzD9Y=", "subType": "00" } } ]}

警告

MongoDB_ENUS_JAJP フィールドを変更しないでください

__safeContent__フィールドは Queryable Encryption に必須です。 このフィールドの内容は変更しないでください。

Queryable Encryptionの仕組みについては、 Queryable Encryption の基礎 を参照してください。

このガイドで言及されているトピックについて詳しくは、次のリンクを参照してください。

  • Queryable Encryption コンポーネントの詳細については、リファレンスページを参照してください。

  • カスタマー マスター キーとデータ暗号化キーの仕組みについては、「暗号化キーとキーヴォールト」ページを参照してください。

  • KMS プロバイダーが Queryable Encryption キーを管理する方法については、 KMS プロバイダーのページで確認してください。