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

CSFLE クイック スタート

このガイドでは、自動クライアント側フィールド レベル暗号化(CSFLE)と MongoDB ドライバーを使用してドキュメントを暗号化する方法を説明します。

このガイドを完了するには、次の知識とソフトウェアを用意してください。

  • ドキュメント内のフィールドを暗号化するようにドライバーを構成する手順に関する知識。

  • 自動 クライアント側フィールドレベル暗号化 を使用する、動作しているが本番環境には対応していないクライアント アプリケーション。

重要

このアプリケーションは本番環境では使用しないでください

このサンプルアプリケーションはアプリケーションのファイルシステムに暗号化のキーを保存するため、データを復号化するためのキーへの不正アクセスやキーの損失のリスクがあります。

本番環境に対応した CSFLE 対応のアプリケーションを作成する方法については、CSFLE チュートリアル を参照してください。

このガイドのコードを完了して実行するには、インストール要件ページに示されているように開発環境を設定する必要があります。

ページの右側にあるSelect your languageドロップダウン メニューから、コード例を表示するプログラミング言語の選択します。

サンプルアプリケーションの完全なコードを表示するには、言語セレクターでプログラミング言語を選択します。

// You are viewing the .NET/C# driver code examples.// Use the dropdown menu to select a different driver.
1

CSFLE を実行するには、カスタマー マスター キー( CMK )を作成する必要があります。

96 バイトのカスタマー マスター キーを作成し、それを ファイルシステムであるローカル キー プロバイダーにファイルmaster-key.txtとして保存します。

const fs = require("fs");const crypto = require("crypto");try { fs.writeFileSync("master-key.txt", crypto.randomBytes(96));} catch (err) { console.error(err);}

警告

本番環境でローカルキーファイルを保護する

カスタマーマスターキーはリモートキー管理システム (KMS)に保存することをお勧めします。Queryable Encryption の実装でリモート KMS を使用する方法については、 Queryable Encryptionチュートリアルガイドを参照してください。

本番環境でローカルキー プロバイダーを使用する場合は、十分に注意し、ファイルシステムに保存しないようにしてください。 サイドカー プロセスを使用してクライアントアプリケーションにキーを挿入するか、キーを安全に保つ別のアプローチを使用することを検討してください。

Tip

コマンドラインから CMK を生成

次のコマンドを使用して、Unix shell または PowerShell からCMKを生成します。

  • Unix/macOS シェル:

    echo $(head -c 96 /dev/urandom | base64 | tr -d '\n')
  • PowerShell:

    $r=[byte[]]::new(64);$g=[System.Security.Cryptography.RandomNumberGenerator]::Create();$g.GetBytes($r);[Convert]::ToBase64String($r)

上記のコマンドの出力をcustomer-master-key.txtという名前のファイルに保存します。

Tip

参照: 完全なコード

カスタマー マスター キーを作成するための完全なコードについては、Githubリポジトリ を参照してください。

2

encryption.__keyVault名前空間のkeyAltNamesフィールドに部分的な一意のインデックスを作成します。 このインデックスには、 keyAltNamesが存在するドキュメントに対してpartialFilterExpressionが必要です。

クライアント側のフィールドレベル暗号化は、サーバーによって強制されるキーの別名の一意性に依存します。

使用する MongoDB ドライバーに対応するタブを選択します。

var connectionString = "<Your MongoDB URI>";var keyVaultNamespace = CollectionNamespace.FromFullName("encryption.__keyVault");var keyVaultClient = new MongoClient(connectionString);var indexOptions = new CreateIndexOptions<BsonDocument>();indexOptions.Unique = true;indexOptions.PartialFilterExpression = new BsonDocument { { "keyAltNames", new BsonDocument { { "$exists", new BsonBoolean(true) } } } };var builder = Builders<BsonDocument>.IndexKeys;var indexKeysDocument = builder.Ascending("keyAltNames");var indexModel = new CreateIndexModel<BsonDocument>(indexKeysDocument, indexOptions);var keyVaultDatabase = keyVaultClient.GetDatabase(keyVaultNamespace.DatabaseNamespace.ToString());// Drop the Key Vault Collection in case you created this collection// in a previous run of this application. keyVaultDatabase.DropCollection(keyVaultNamespace.CollectionName);// Drop the database storing your encrypted fields as all// the DEKs encrypting those fields were deleted in the preceding line.keyVaultClient.GetDatabase("medicalRecords").DropCollection("patients");var keyVaultCollection = keyVaultDatabase.GetCollection<BsonDocument>(keyVaultNamespace.CollectionName.ToString());keyVaultCollection.Indexes.CreateOne(indexModel);
3
  1. CMK の読み取りと KMS プロバイダー設定の指定

    このガイドの「 カスタマー マスター キーの作成」ステップで生成したカスタマー マスター キー ファイルの内容を取得します。

    KMSプロバイダー設定でCMK値を使用します。クライアントはこれらの設定を使用してCMKを検出します。Local Key プロバイダーを使用しているため、プロバイダー名をlocalに設定します。

    var kmsProviders = new Dictionary<string, IReadOnlyDictionary<string, object>>();var provider = "local";string localMasterKeyBase64Read = File.ReadAllText("master-key.txt");var localMasterKeyBytes = Convert.FromBase64String(localMasterKeyBase64Read);var localOptions = new Dictionary<string, object>{ { "key", localMasterKeyBytes }};kmsProviders.Add("local", localOptions);
  2. データ暗号化キーの作成

    MongoDB接続stringと Key Vault コレクションの名前空間を使用してクライアントを構築し、データ暗号化キーを作成します。

    注意

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

    このチュートリアルを完了するには、アプリケーションが MongoDB への接続に使用するデータベースユーザーが、次の名前空間に対するdbAdmin権限を持っている必要があります。

    • encryption.__keyVault

    • medicalRecords database

    var clientEncryptionOptions = new ClientEncryptionOptions( keyVaultClient: keyVaultClient, keyVaultNamespace: keyVaultNamespace, kmsProviders: kmsProviders ); var clientEncryption = new ClientEncryption(clientEncryptionOptions);var dataKeyOptions = new DataKeyOptions();var dataKeyId = clientEncryption.CreateDataKey(provider, dataKeyOptions, CancellationToken.None);var dataKeyIdBase64 = Convert.ToBase64String(GuidConverter.ToBytes(dataKeyId, GuidRepresentation.Standard));Console.WriteLine($"DataKeyId [base64]: {dataKeyIdBase64}");

    上記のコードからの出力は、次のようになります。

    DataKeyId [base64]: 3k13WkSZSLy7kwAAP4HDyQ==

Tip

参照: 完全なコード

データ暗号化キーを作成するための完全なコードについては、Githubリポジトリ を参照してください。

4
  1. キーヴォールトコレクションの名前空間の指定

    キーヴォールト コレクションの名前空間としてencryption.__keyVaultを指定します。

    var keyVaultNamespace = CollectionNamespace.FromFullName("encryption.__keyVault");
  2. ローカル カスタマー マスター キーの指定

    KMS プロバイダーを指定し、キーをインラインで指定します。

    var kmsProviders = new Dictionary<string, IReadOnlyDictionary<string, object>>();var provider = "local";var localMasterKeyPath = "master-key.txt";string localMasterKeyBase64Read = File.ReadAllText(localMasterKeyPath);var localMasterKeyBytes = Convert.FromBase64String(localMasterKeyBase64Read);var localOptions = new Dictionary<string, object>{ { "key", localMasterKeyBytes }};kmsProviders.Add(provider, localOptions);
  3. コレクションの暗号化スキーマの作成

    Tip

    データ暗号化キー base64 ID の追加

    base 64 DEK ID を含むように、次のコードを必ず更新してください。 この値は、このガイドの「 データ暗号化キーの生成 」ステップで取得されました。

    var keyId = "<Your base64 DEK ID here>";var schema = new BsonDocument{ { "bsonType", "object" }, { "encryptMetadata", new BsonDocument("keyId", new BsonArray(new[] { new BsonBinaryData(Convert.FromBase64String(keyId), BsonBinarySubType.UuidStandard) })) }, { "properties", new BsonDocument { { "ssn", new BsonDocument { { "encrypt", new BsonDocument { { "bsonType", "int" }, { "algorithm", "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic" } } } } }, { "bloodType", new BsonDocument { { "encrypt", new BsonDocument { { "bsonType", "string" }, { "algorithm", "AEAD_AES_256_CBC_HMAC_SHA_512-Random" } } } } }, { "medicalRecords", new BsonDocument { { "encrypt", new BsonDocument { { "bsonType", "array" }, { "algorithm", "AEAD_AES_256_CBC_HMAC_SHA_512-Random" } } } } }, { "insurance", new BsonDocument { { "bsonType", "object" }, { "properties", new BsonDocument { { "policyNumber", new BsonDocument { { "encrypt", new BsonDocument { { "bsonType", "int" }, { "algorithm", "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic" } } } } } } } } } } }};var schemaMap = new Dictionary<string, BsonDocument>();schemaMap.Add(dbNamespace, schema);
  4. 自動暗号化共有ライブラリのロケーションを指定する

    var mongoBinariesPath = "<Full path to your Automatic Encryption Shared Library>";var extraOptions = new Dictionary<string, object>(){ { "cryptSharedLibPath", mongoBinariesPath },};

    注意

    自動暗号化オプション

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

    自動暗号化共有ライブラリの詳細については、「 CSFLE クエリ分析コンポーネントのインストールと構成 」ページを参照してください。

  5. MongoClient の作成

    次の自動暗号化設定を使用して MongoDB クライアント オブジェクトをインスタンス化します。

    MongoClientSettings.Extensions.AddAutoEncryption(); // .NET/C# Driver v3.0 or later onlyvar clientSettings = MongoClientSettings.FromConnectionString(connectionString);var autoEncryptionOptions = new AutoEncryptionOptions( keyVaultNamespace: keyVaultNamespace, kmsProviders: kmsProviders, schemaMap: schemaMap, extraOptions: extraOptions );clientSettings.AutoEncryptionOptions = autoEncryptionOptions;var secureClient = new MongoClient(clientSettings);
5

CSFLE で有効化されたMongoClientインスタンスで、次のコード スニペットを使用して、暗号化されたフィールドを含むドキュメントをmedicalRecords.patients名前空間に挿入します。

var sampleDocFields = new BsonDocument{ { "name", "Jon Doe" }, { "ssn", 145014000 }, { "bloodType", "AB-" }, { "medicalRecords", new BsonArray { new BsonDocument("weight", 180), new BsonDocument("bloodPressure", "120/80") } }, { "insurance", new BsonDocument { { "policyNumber", 123142 }, { "provider", "MaestCare" } } }}; // Construct an auto-encrypting clientvar secureCollection = secureClient.GetDatabase(db).GetCollection<BsonDocument>(coll); // Insert a document into the collectionsecureCollection.InsertOne(sampleDocFields);

ドキュメントを挿入すると、CSFLE 対応クライアントは次のようにドキュメントのフィールドを暗号化します。

{ "_id": { "$oid": "<_id of your document>" }, "name": "Jon Doe", "ssn": { "$binary": "<cipher-text>", "$type": "6" }, "bloodType": { "$binary": "<cipher-text>", "$type": "6" }, "medicalRecords": { "$binary": "<cipher-text>", "$type": "6" }, "insurance": { "provider": "MaestCare", "policyNumber": { "$binary": "<cipher-text>", "$type": "6" } }}

Tip

参照: 完全なコード

暗号化されたフィールドを含むドキュメントを挿入するための完全なコードについては、Githubリポジトリを参照してください。

6

このガイドの「 暗号化されたフィールドを含むドキュメントの挿入 」ステップで挿入した暗号化されたフィールドを含むドキュメントを取得します。

CSFLE の機能を示すために、次のコード スニペットは、自動 CSFLE 用に構成されたクライアントと、自動 CSFLE 用に構成されていないクライアントを使用して、ドキュメントに対してクエリを実行します。

Console.WriteLine("Finding a document with regular (non-encrypted) client.");var filter = Builders<BsonDocument>.Filter.Eq("name", "Jon Doe");var regularResult = regularCollection.Find(filter).Limit(1).ToList()[0];Console.WriteLine($"\n{regularResult}\n"); Console.WriteLine("Finding a document with encrypted client");var ssnFilter = Builders<BsonDocument>.Filter.Eq("name", "Jon Doe");var secureResult = secureCollection.Find(ssnFilter).Limit(1).First();Console.WriteLine($"\n{secureResult}\n");

上記のコード スニペットの出力は次のようになります。

Finding a document with regular (non-encrypted) client. { _id: new ObjectId("629a452e0861b3130887103a"), name: 'Jon Doe', ssn: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e7910c20697e5f4fa95710aafc9153f0a3dc769c8a132a604b468732ff1f4d8349ded3244b59cbfb41444a210f28b21ea1b6c737508d9d30e8baa30c1d8070c4d5e26", "hex"), 6), bloodType: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e79022e238536dfd8caadb4d7751ac940e0f195addd7e5c67b61022d02faa90283ab69e02303c7e4001d1996128428bf037dea8bbf59fbb20c583cbcff2bf3e2519b4", "hex"), 6), 'key-id': 'demo-data-key', medicalRecords: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e790405163a3207cff175455106f57eef14e5610c49a99bcbd14a7db9c5284e45e3ee30c149354015f941440bf54725d6492fb3b8704bc7c411cff6c868e4e13c58233c3d5ed9593eca4e4d027d76d3705b6d1f3b3c9e2ceee195fd944b553eb27eee69e5e67c338f146f8445995664980bf0", "hex"), 6), insurance: { policyNumber: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e79108decd85c05be3fec099e015f9d26d9234605dc959cc1a19b63072f7ffda99db38c7b487de0572a03b2139ac3ee163bcc40c8508f366ce92a5dd36e38b3c742f7", "hex"), 6), provider: 'MaestCare' }} Finding a document with encrypted client { _id: new ObjectId("629a452e0861b3130887103a"), name: 'Jon Doe', ssn: 241014209, bloodType: 'AB+', 'key-id': 'demo-data-key', medicalRecords: [ { weight: 180, bloodPressure: '120/80' } ], insurance: { policyNumber: 123142, provider: 'MaestCare' }}

Tip

参照: 完全なコード

暗号化されたフィールドを持つドキュメントを検索するための完全なコードについては、Githubリポジトリ を参照してください。

リモート KMS を使用して本番環境に対応できる CSFLE に関するチュートリアルについては、CSFLE チュートリアル を参照してください。

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

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