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

KMIP による自動 Queryable Encryption の使用

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

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

  • KMIP準拠のキー プロバイダーによって管理されるカスタマー マスター キー

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

Tip

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

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

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

Tip

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

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

1

MongoDB ドライバー クライアントをKMIP準拠のキー プロバイダーに接続するには、クライアントの TLS 証明書を受け入れるようにKMIP準拠のキー プロバイダーを構成する必要があります。

クライアント証明書を受け入れる方法については、 KMIP準拠のキー プロバイダーのドキュメントを参照してください。

2

クライアントは TLS 経由で KMIP 準拠のキー プロバイダーに接続し、 KMIP準拠のキー プロバイダーが受け入れるクライアント証明書を提示する必要があります。

const tlsOptions = { kmip: { tlsCAFile: process.env["KMIP_TLS_CA_FILE"], // Path to your TLS CA file tlsCertificateKeyFile: process.env["KMIP_TLS_CERT_FILE"], // Path to your TLS certificate key file },};
1

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

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

  • 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

次の構造を持つ KMIP 準拠のキー プロバイダーのエンドポイントを含む変数を作成します。

kmsProviderCredentials = { kmip: { endpoint: process.env["KMIP_KMS_ENDPOINT"], // Your KMIP KMS endpoint },};

次のコード例に示すように、空のオブジェクトを作成します。 これにより、 KMIP準拠のキー プロバイダーに新しい CMK の生成が求められます。

customerMasterKeyCredentials = {};

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

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

  • KMIPエンドポイントを含むkmsProviderCredentialsオブジェクト

  • 証明書の指定ステップで作成したtlsOptionsオブジェクト

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

注意

自動暗号化オプション

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

自動暗号化共有ライブラリの詳細については、「 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 プロバイダーのページで確認してください。