CSFLE の暗号化スキーマ

項目一覧

Overview

定義
例
暗号化スキーマ - 複数のフィールド
暗号化スキーマ - 継承する複数のフィールド
暗号化スキーマ - パターンプロパティで暗号化

Overview

注意

エンタープライズ機能

フィールドレベル暗号化の自動機能は、MongoDB Enterprise 4.2 以降と MongoDB Atlas 4.2 以降のクラスターでのみ使用できます。

暗号化スキーマには、どのフィールドを暗号化する必要があるか、またそれらのフィールドを暗号化する方法を識別するユーザー指定のルールが含まれています。アプリケーションは、JSON schema 4ドラフト標準構文の厳密なサブセットを使用して自動暗号化ルールを指定する必要がありますおよび次の暗号化固有のキーワード。

暗号化は、現在のフィールドを暗号化するときに使用する暗号化オプションを指定します。
メタデータの暗号化では、継承可能な暗号化オプションを指定します。

MongoDBshellMongo()の場合は、{3 コンストラクターを使用して、クライアント側フィールドレベル暗号化構成オブジェクトの一部として含まれる自動暗号化ルールとのデータベース接続を作成します。の例については、「自動クライアント側暗号化が有効になっているクラスターへの接続」を参照してください。

公式 MongoDB ドライバーの場合は、ドライバー固有のデータベース接続コンストラクター（ MongoClient ）を使用して、クライアント側フィールドレベル暗号化構成オブジェクトの一部として含まれる自動暗号化ルールとのデータベース接続を作成します。 CSFLE 固有のMongoClientオプションの詳細については、 mongo クライアントページを参照してください。

重要

暗号化スキーマでドキュメント検証キーワードを指定しない

自動暗号化ルールでドキュメント検証キーワードを指定しないでください。ドキュメント検証ルールを定義するには、スキーマ検証を構成します。

定義

encrypt

オブジェクト

"bsonType" : "object",
"properties" : {
  "<fieldName>" : {
    "encrypt" : {
      "algorithm" : "<string>",
      "bsonType" : "<string>" | [ "<string>" ],
      "keyId" : [ <UUID> ]
    }
  }
}

<fieldName>を暗号化する必要があることを示します。 encryptオブジェクトには次の要件があります。

encrypt は、 <fieldName>オブジェクトに兄弟フィールドを含めることはできません。 encryptは、 <fieldName>オブジェクトの唯一の子である必要があります。
encrypt は、 itemsまたはadditionalItemsキーワードのサブスキーマ内では指定できません。具体的には、自動クライアント側フィールドレベル暗号化では、配列の個々の要素の暗号化はサポートされていません。

encryptオブジェクトには次のフィールドのみを含めることができます。

algorithm
bsonType
keyId

encryptオブジェクトに他のフィールドを含めると、自動暗号化された読み取りまたは書込み操作の発行時にエラーが発生します

keyIdまたはalgorithmが省略されている場合、自動暗号化共有ライブラリはすべての親フィールドをチェックし、オプションを指定する最も近いencryptMetadataオブジェクトからそれらのオプションを構築しようとします。 bsonTypeは継承できず、の値によっては必須となる場合algorithm があります。

自動暗号化共有ライブラリが、オブジェクトに指定されたフィールドと必要なencryptMetadata継承されたキーを使用して、完全なencryptオブジェクトを構築できない場合、自動暗号化は失敗し、エラーが返されます。

encrypt.algorithm

文字列

<fieldName>の値を暗号化するときに使用する暗号化アルゴリズムを示します。次のアルゴリズムのみをサポートします。

AEAD_AES_256_CBC_HMAC_SHA_512-Random
AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic

暗号化アルゴリズムに関する完全なドキュメントについては、「フィールドと暗号化タイプ」を参照してください。

省略した場合、自動暗号化共有ライブラリは、 encryptMetadata.algorithmキーを含む最も近い祖先のすべての親フィールドをチェックし、その値を継承します。親algorithmが存在しない場合、自動フィールドレベル暗号化は失敗し、エラーが返されます。

encrypt.algorithmまたはその継承値がAEAD_AES_256_CBC_HMAC_SHA_512-Deterministic の場合、encrypt オブジェクトにはフィールドが必要 encrypt.bsonTypeです。
encrypt.algorithmまたはその継承値がAEAD_AES_256_CBC_HMAC_SHA_512-Random の場合、encrypt オブジェクトにはフィールドencrypt.bsonType が含まれる可能性があります。

encrypt.bsonType

string |文字列の配列

暗号化されるフィールドのBSON type 。 encrypt.algorithmがAEAD_AES_256_CBC_HMAC_SHA_512-Deterministicの場合は必須です。

encrypt.algorithmまたはその継承値がAEAD_AES_256_CBC_HMAC_SHA_512-Deterministicの場合、 bsonTypeは単一の型を指定する必要があります。は、決定的な暗号化アルゴリズムを持つ次のbsonType のいずれもサポートしていません。BSON types

double
decimal128
bool
object
array

encrypt.algorithmまたはその継承値が AED_AES_256_CBC_HMAC_SHA_512-Random の場合、bsonType は任意であり、サポートされているBSON typesの配列を指定できます。 arrayまたはobjectのbsonTypeを持つフィールドの場合、クライアントは配列またはオブジェクト全体ではなく、個々の要素ではなく、配列またはオブジェクト全体を暗号化します。

encrypt.bsonType は、 encrypt.algorithmまたはその継承値に関係なく、次のタイプをサポートしていません。

minKey
maxKey
null
undefined

encrypt.keyId

単一 UUID の配列

フィールド値の暗号化に使用するデータ暗号化キーの UUID 。 UUID は BSON バイナリデータですサブタイプ4 の要素。

配列内に1 つのstringを指定します。

省略した場合、自動暗号化共有ライブラリは、 encryptMetadata.keyIdキーを含む最も近い祖先のすべての親フィールドをチェックし、その値を継承します。親keyIdが存在しない場合、自動フィールドレベル暗号化は失敗し、エラーが返されます。

keyIdまたはその継承値は、自動暗号化構成オプションの一部として指定された Key Vault コレクションに存在する必要があります。指定されたデータ暗号化キーが存在しない場合、自動暗号化は失敗します。

公式 MongoDB ドライバーには、UUID を指定するための言語固有の要件があります。クライアント側のフィールドレベル暗号化の実装に関する完全なドキュメントについては、ドライバーのドキュメントを参照してください。

encryptMetadata

オブジェクト

{
  "bsonType" : "object",
  "encryptMetadata" : {
    "algorithm" : "<string>",
    "keyId" : [ <UUID> ]
  },
  "properties" : {
    "encrypt" : {}
  }
}

存在のpropertiesにネストされたencryptオブジェクトが継承できる暗号化オプションを定義します。 encryptに暗号化をサポートするために必要なオプションがない場合、自動暗号化共有ライブラリはすべての親オブジェクトを検索して、欠落しているオプションを指定するencryptMetadataオブジェクトを見つけます。

encryptMetadata は、 bsonType: "object"を使用してサブスキーマで指定する必要があります。 encryptMetadataは、 itemsまたはadditionalItemsキーワードのサブスキーマには指定できません。具体的には、自動クライアント側フィールドレベル暗号化では、配列の個々の要素の暗号化はサポートされていません。

encryptMetadataオブジェクトには次のフィールドのみを含めることができます。 encryptオブジェクトに他のフィールドを含めると、自動暗号化された読み取りまたは書込み操作を発行するときにエラーが発生します。

algorithm
keyId

encryptMetadata.algorithm

文字列

特定のフィールドを暗号化するために使用する暗号化アルゴリズム。 encryptオブジェクトにalgorithm フィールドがない場合、自動暗号化共有ライブラリはすべての親オブジェクトを検索して、を指定するencryptMetadata encryptMetadata.algorithmオブジェクトを見つけます。

次のアルゴリズムのみをサポートします。

AEAD_AES_256_CBC_HMAC_SHA_512-Random
AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic

暗号化アルゴリズムに関する完全なドキュメントについては、「フィールドと暗号化タイプ」を参照してください。

AEAD_AES_256_CBC_HMAC_SHA_512-Deterministicencryptを指定する場合、その値を継承するオブジェクトはを指定する 必要がありencrypt.bsonType ます。

encryptMetadata.keyId

単一 UUID の配列

データ暗号化キーの UUID 。 UUID は BSON バイナリデータですサブタイプ4 の要素。

配列内に1 つのstringを指定します。

encryptオブジェクトにkeyId フィールドがない場合、自動暗号化共有ライブラリはすべての親オブジェクトを検索して、を指定するencryptMetadata encryptMetadata.keyIdオブジェクトを見つけます。

データ暗号化キーは、自動暗号化構成オプションの一部として指定されたキーヴォールトコレクション内に存在する必要があります。KMS指定された構成オプションには、データキーの作成に使用される（KMS ）と CMK（Customer Master Key）への適切なアクセス権も 含める必要があります。データ暗号化キーが存在しない場合、またはクライアントが指定された KMS および CMK でキーを復号化できない場合、自動暗号化は失敗します。

例

暗号化スキーマ - 複数のフィールド

各ドキュメントが次の構造を持つコレクションMedCo.patientsを例に考えてみましょう。

{
  "fname" : "<String>",
  "lname" : "<String>",
  "passportId" : "<String>",
  "bloodType" : "<String>",
  "medicalRecords" : [
    {<object>}
  ],
  "insurance" : {
    "policyNumber" : "<string>",
    "provider" : "<string>"
  }
}

次のフィールドには、クエリされる可能性のある個人を特定できる情報（PII）が含まれています。

passportId
bloodType
insurance.policyNumber
insurance.provider

決定的な暗号化アルゴリズムは、値の暗号化された出力が静的であることを保証します。これにより、特定の値のクエリは意味のある結果を返すことができますが、頻度分析の回復の可能性が高まります。したがって、決定的な暗号化アルゴリズムは、データの暗号化とクエリ可能性の両方の要件を満たします。

次のフィールドには、法的に保護された個人を特定できる情報（PII）が含まれており、クエリされることはありません。

medicalRecords

ランダム化された暗号化アルゴリズムにより、値の暗号化された出力が常に一意であることが保証されます。これにより、フィールドの内容を最大限に保護しながら、特定のフィールド値に対するクエリが意味のある結果を返すのを防止できます。したがって、ランダム化された暗号化アルゴリズムは、データの暗号化とクエリ可能性の両方の要件を満たします。

次のスキーマでは、 MedCo.patientsコレクションの上記の要件を満たす自動暗号化ルールを指定します。

{
  "MedCo.patients" : {
    "bsonType" : "object",
    "properties" : {
      "passportId" : {
        "encrypt" : {
          "keyId" : [UUID("bffb361b-30d3-42c0-b7a4-d24a272b72e3")],
          "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
          "bsonType" : "string"
        }
      },
      "bloodType" : {
        "encrypt" : {
          "keyId" : [UUID("bffb361b-30d3-42c0-b7a4-d24a272b72e3")],
          "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
          "bsonType" : "string"
        }
      },
      "medicalRecords" : {
        "encrypt" : {
          "keyId" : [UUID("f3821212-e697-4d65-b740-4a6791697c6d")],
          "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Random",
          "bsonType" : "array"
        }
      },
      "insurance" : {
        "bsonType" : "object",
        "properties" : {
          "policyNumber" : {
            "encrypt" : {
              "keyId" : [UUID("bffb361b-30d3-42c0-b7a4-d24a272b72e3")],
              "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
              "bsonType" : "string"
            }
          },
          "provider" : {
            "encrypt" : {
              "keyId" : [UUID("bffb361b-30d3-42c0-b7a4-d24a272b72e3")],
              "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
              "bsonType" : "string"
            }
          }
        }
      }
    }
  }
}

上記の自動暗号化ルールは、 passportId 、 bloodType 、 insurance.policyNumber 、 insurance.provider 、 medicalRecordsフィールドを暗号化用にマークします。

passportId 、 bloodType 、 insurance.policyNumber 、およびproviderフィールドは、指定されたキーを使用する決定的な暗号化を必要とします。
medicalRecordsフィールドでは、指定されたキーを使用したランダム化された暗号化が必要です。

Queryable Encryption では配列要素の個々の暗号化はサポートされていませんが、ランダム化された暗号化ではフィールド内の個々の要素ではなく、配列フィールド全体の暗号化がサポートされています。自動暗号化ルールの例では、配列全体を暗号化するためにmedicalRecordsフィールドにランダム化された暗号化を指定しています。自動暗号化ルールがmedicalRecords.itemsまたはmedicalRecords.additionalItems内でencryptまたはencryptMetadataを指定した場合、フィールドレベルの自動暗号化は失敗し、エラーが返されます。

公式 MongoDB ドライバー、 mongosh 、およびレガシーmongo shell では、データベース接続オブジェクトの作成の一部として自動暗号化ルールを指定する必要があります。

mongoshの場合は、 Mongo()コンストラクタを使用してデータベース接続を作成します。 AutoEncryptionOptsパラメータのschemaMapキーに自動暗号化ルールを指定します。完全な例については、「自動クライアント側暗号化が有効になっているクラスターへの接続」を参照してください。
公式 MongoDB ドライバーの場合は、ドライバー固有のデータベース接続コンストラクター（ MongoClient ）を使用して、 Queryable Encryption 構成オブジェクトの一部として含まれる自動暗号化ルールとのデータベース接続を作成します。より完全なドキュメントとチュートリアルについては、ドライバー API リファレンスを参照してください。

Queryable Encryption パラメータに指定されたkeyVaultとkmsProvidersは、すべてのクライアントで、自動暗号化ルールで指定されたデータ暗号化キーと、データ暗号化キーの暗号化に使用される CMK の両方へのアクセスを許可する必要があります。

暗号化スキーマ - 継承する複数のフィールド

各ドキュメントが次の構造を持つコレクションMedCo.patientsを例に考えてみましょう。

{
  "fname" : "<String>",
  "lname" : "<String>",
  "passportId" : "<String>",
  "bloodType" : "<String>",
  "medicalRecords" : [
    {<object>}
  ],
  "insurance" : {
    "policyNumber" : "<string>",
    "provider" : "<string>"
  }
}

次のフィールドには、クエリされる可能性のあるプライベートデータが含まれています。

passportId
bloodType
insurance.policyNumber
insurance.provider

次のフィールドには、クエリされることのないプライベートデータが含まれています。

medicalRecords

次のスキーマでは、 MedCo.patientsコレクションの暗号化要件を満たす自動暗号化ルールを指定します。

{
  "MedCo.patients" : {
    "bsonType" : "object",
    "encryptMetadata" : {
      "keyId" : [UUID("6c512f5e-09bc-434f-b6db-c42eee30c6b1")],
      "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
    },
    "properties" : {
      "passportId" : {
        "encrypt" : {
          "bsonType" : "string"
        }
      },
      "bloodType" : {
        "encrypt" : {
          "bsonType" : "string"
        }
      },
      "medicalRecords" : {
        "encrypt" : {
          "keyId" : [UUID("6c512f5e-09bc-434f-b6db-c42eee30c6b1")],
          "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Random",
          "bsonType" : "array"
        }
      },
      "insurance" : {
        "bsonType" : "object",
        "properties" : {
          "policyNumber" : {
            "encrypt" : {
              "bsonType" : "string"
            }
          },
          "provider" : {
            "encrypt" : {
              "bsonType" : "string"
            }
          }
        }
      }
    }
  }
}

上記の自動暗号化ルールは、 passportId 、 bloodType 、 insurance.policyNumber 、 insurance.provider 、 medicalRecordsフィールドを暗号化用にマークします。

passportId 、 bloodType 、 insurance.policyNumber 、およびproviderフィールドは、親のencryptMetadataフィールドから暗号化設定を継承します。具体的には、これらのフィールドは、指定されたデータ暗号化キーによる決定的な暗号化を指定するalgorithmとkeyIdの値を継承します。
medicalRecordsフィールドでは、指定されたキーを使用したランダム化された暗号化が必要です。 encryptオプションは、親のencryptMetadataフィールドに指定されたオプションを上書きします。

mongoshの場合は、 Mongo()コンストラクタを使用してデータベース接続を作成します。 AutoEncryptionOptsパラメータのschemaMapキーに自動暗号化ルールを指定します。完全な例については、「自動クライアント側暗号化が有効になっているクラスターへの接続」を参照してください。
公式 MongoDB ドライバーの場合は、ドライバー固有のデータベース接続コンストラクター（ MongoClient ）を使用して、 Queryable Encryption 構成オブジェクトの一部として含まれる自動暗号化ルールとのデータベース接続を作成します。より完全なドキュメントとチュートリアルについては、ドライバー API リファレンスを参照してください。

CMK とキーヴォールトコレクションの詳細については、「キーヴォールト」ページを参照してください。

暗号化アルゴリズムの詳細については、「暗号化アルゴリズムのページ」を参照してください。

CSFLE 固有のMongoClientオプションの詳細については、 mongo クライアントページを参照してください。

暗号化スキーマ - パターンプロパティで暗号化

暗号化スキーマのpatternPropertiesキーワードを使用して、正規表現と一致する名前を持つすべてのフィールドの暗号化ルールを定義できます。

各ドキュメントが次の構造を持つコレクションMedCo.patientsを例に考えてみましょう。

{
  "fname" : "<string>",
  "lname" : "<string>",
  "passportId_PIIString" : "<string>",
  "bloodType_PIIString" : "<string>",
  "medicalRecords_PIIArray" : [
    {<object>}
  ],
  "insurance" : {
    "policyNumber_PIINumber" : "<number>",
    "provider_PIIString" : "<string>"
  }
}

プライベート<type> データを含むフィールドは、フィールド名の末尾に追加された "_PII" タグによって識別されます。

passportId_PIIString
bloodType_PIIString
medicalRecords_PIIArray
insurance.policyNumber_PIINumber
insurance.provider_PIIString

patternPropertiesキーワードを使用すると、各フィールドを個別に識別したり、完全なフィールド名を使用したりせずに、これらのフィールドを暗号化するように構成できます。これを行うには、"_PII"<type> タグで終わるすべてのフィールドに一致する正規表現を使用します。

次のJSON schemaでは、暗号化するフィールドを指定するために patternProperties と正規表現を使用します。

{
  "MedCo.patients": {
  "bsonType": "object",
  "patternProperties": {
    "_PIIString$": {
      "encrypt": {
        "keyId": [UUID("6c512f5e-09bc-434f-b6db-c42eee30c6b1")],
        "bsonType": "string",
        "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
      },
    },
    "_PIIArray$": {
      "encrypt": {
        "keyId": [UUID("6c512f5e-09bc-434f-b6db-c42eee30c6b1")],
        "bsonType": "array",
        "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Random",
      },
    },
    "insurance": {
      "bsonType": "object",
      "patternProperties": {
        "_PIINumber$": {
          "encrypt": {
            "keyId": [UUID("6c512f5e-09bc-434f-b6db-c42eee30c6b1")],
            "bsonType": "int",
            "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
          },
        },
        "_PIIString$": {
          "encrypt": {
            "keyId": [UUID("6c512f5e-09bc-434f-b6db-c42eee30c6b1")],
            "bsonType": "string",
            "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
          },
        },
      },
    },
  },
  },
}

上記の自動暗号化ルールは、 passportId_PIIString 、 bloodType_PIIString 、 medicalRecords_PIIArray 、 insurance.policyNumber_PIINumber 、 insurance.provider_PIIStringフィールドを暗号化用にマークします。

patternPropertiesキーワードの詳細については、 patternProperties キーワードを参照してください。

戻る

参照

スキーマの強制

Overview

注意

エンタープライズ機能

重要

暗号化スキーマでドキュメント検証キーワードを指定しない

定義

例

暗号化スキーマ - 複数のフィールド

暗号化スキーマ - 継承する複数のフィールド

暗号化スキーマ - パターン プロパティで暗号化

暗号化スキーマ - パターンプロパティで暗号化