Class: Mongo::ClientEncryption

継承:
オブジェクト
  • オブジェクト
すべて表示
定義:
lib/mongo/client_encryption.rb

Overview

ClientEncryption は、MongoClient では直接実行できないキーヴォールト コレクションに対する明示的な操作をカプセル化します。 値を明示的に暗号化および復号化し、データキーを作成するための API を提供します。

インスタンス メソッドの概要を折りたたむ

コンストラクターの詳細

#initialize(key_vault_client, options = {}) ⇒ ClientEncryption

指定されたオプションを使用して新しい ClientEncryption オブジェクトを作成します。

パラメーター:

  • key_vault_client （ Mongo::Client ） —

    キーヴォールト コレクションが保存されている MongoDB インスタンスに接続される Mongo::Client。

  • options （ハッシュ） （デフォルトは{}です） —

    ClientEncryption オプション。

オプション ハッシュ（ options ）:

  • :key_vault_namespace （ string ） —

    " データベース. コレクション "形式の、キーヴォールトコレクションの名前。

  • : kms_providers （ハッシュ） —

    KMS構成情報のハッシュ。 サポートされているすべてのプロバイダーのオプションのリストについては、「 Mongo::Crypt::KMS::認証情報 」を参照してください。 @note 複数の KMS プロバイダーを指定できます。

  • : kms_tls_options （ハッシュ） —

    KMS プロバイダーに接続するための TLS オプション。 ハッシュのキーは、K SM プロバイダー名である必要があります。値は、TLS 接続オプションのハッシュである必要があります。 オプションは、Mongo::Client の TLS 接続オプションと同じです。 TLS オプションのリストについては、「 Mongo::Client#initialize 」を参照してください。

  • :timeout_ms （整数） —

    操作のタイムアウト（ミリ秒単位）。 負でない整数である必要があります。 0 の明示的な値は無限を意味します。 デフォルト値が設定されていない場合は、機能が無効になります。

  • :key_expiration_ms （整数） —

    データ暗号化キー キャッシュの有効期間 (ミリ秒単位)非負整数でなければなりません。0 の明示的な値は、キャッシュが永久に切れないことを意味します。デフォルト値は 60000 です。

次の値が発生します。

  • (ArgumentError) —

    必須 オプションが欠落しているか、形式が正しくない場合。



52
53
54
55
56
57
58
59
60
61
 
# ファイル 'lib/mongo/client_encryption.rb' 行 52

デフォルト 初期化(key_vault_client, options = {})
  @encrypter = 暗号化::明示的暗号化.新着情報(
    key_vault_client,
    options[:key_vault_namespace],
    暗号化::KMS::Credentials.新着情報(options[: kms_providers]),
    暗号化::KMS::検証.validate_tls_options(options[: kms_tls_options]),
    options[:timeout_ms],
    options[:key_expiration_ms]
  )
end

インスタンス メソッドの詳細

#add_key_alt_name(id, key_alt_name) ⇒ BSON::Document | nil

指定された ID を持つキーヴォールト コレクション内のキーの key_alt_name を追加します。

パラメーター:

  • id （ BSON ::Binary ） —

    新しいキー代替名を追加するキーの ID。

  • key_alt_name ( string ) —

    追加する新しいキー代替名。

次の値を返します。

  • (BSON::Document | nil) —

    キーの代替名を追加する前に、識別されたキーを説明するドキュメント。または、そのようなキーがない場合は nil 。



207
208
209
 
# ファイル 'lib/mongo/client_encryption.rb' 行 207

デフォルト add_key_alt_name(id, key_alt_name)
  @encrypter.add_key_alt_name(id, key_alt_name)
end

# create_data_key （kms_provider、オプション={}）= BSON::Binary

暗号化および復号化に使用されるデータキーを生成し、そのキーを KMS コレクションに保存します。 生成されたキーは KMS マスター キーで暗号化されます。

パラメーター:

  • kms_provider ( string ) —

    使用する KMS プロバイダー。有効な値は、"aws" と "local" です。

  • options （ハッシュ） （デフォルトは{}です）

オプション ハッシュ（ options ）:

  • : マスター_キー （ハッシュ） —

    AWSマスターキーに関する情報。kms_provider が「aws」の場合は必須です。

    • :region [ string ] マスターキーのAmazon Web Servicesのリージョン（必須）。
    • :key [ string ] マスターキーのAmazonリソース名（ARN） （必須）。
    • :endpoint [ String ] KMS リクエストを送信する代替ホスト（任意）。エンドポイントは、任意のポート番号をコロンで区切ったホスト名（例:" kms.us-east-1.amazonaws.com" または " kms.us-east-1.Amazonaws.com:443"）。他の形式のエンドポイントは適切に解析されません。
  • :key_alt_names （配列<String> ） —

    新しいデータキーの代替名を指定する文字列の任意の配列。

  • :key_rate （ string | nil ） —

    作成されるデータキーのカスタムキーマテリアルとして使用する任意の96バイト。 :key_rate オプションが指定されている場合、カスタム キー マテリアル はデータの暗号化と復号化に使用されます。

次の値を返します。

  • （ BSON ::Binary ） —

    :uuid 型の BSON::Binary オブジェクトとしての新しいデータキーの16バイト UUID 。



89
90
91
92
93
94
95
 
# ファイル 'lib/mongo/client_encryption.rb' 行 89

デフォルト create_data_key(kms_provider, options = {})
  key_document = 暗号化::KMS::MasterKeyDocument.新着情報(kms_provider, options)

  key_alt_names = options[:key_alt_names]
  key_rate = options[:key_rate]
  @encrypter.create_and_insert_data_key(key_document, key_alt_names, key_rate)
end

# create_encrypted_collection (database, coll_name,coll_opts, kms_provider, Master_key) == Array =======================================

注：

このメソッドでは、クライアントの : auto_encryption_options の :encrypted_fields_map は更新されません。したがって、このメソッドによって作成されたコレクションを自動暗号化と併用するには、 :encrypted_fields が返されたこの関数を呼び出した後、新しいクライアントを作成する必要があります。

暗号化されたフィールドを持つコレクションを作成します。

:encryption_fields に null 値を持つ keyId が含まれている場合、データキーが自動的に生成され、keyId 値に割り当てられます。

パラメーター:

  • database （ Mongo::Database ） —

    コレクションを作成するデータベース。

  • coll_name ( string ) —

    作成するコレクションの名前。

  • coll_opts （ハッシュ） —

    作成するコレクションのオプション。

  • kms_provider ( string ) —

    フィールドを暗号化するための KMS プロバイダー。

  • マスター_キー (ハッシュ | nil ) —

    フィールドを暗号化するためのマスターキーを説明するドキュメント。

次の値を返します。

  • （配列未満操作 ::結果、ハッシュ> ） —

    コレクション作成操作の結果と、コレクションの作成に使用された暗号化されたフィールド マップ。

次の値が発生します。

  • (ArgumentError) 


294
295
296
297
298
299
300
301
302
303
304
305
 
# ファイル 'lib/mongo/client_encryption.rb' 行 294

デフォルト create_encrypted_collection(database, coll_name, coll_opts, kms_provider, マスター_キー)
  発生 ArgumentError, 「 coll_opts には :encrypted_fields が含まれている必要があります」 ただし、 coll_opts[:encrypted_fields]

  encryption_fields = create_data_keys(coll_opts[:encrypted_fields], kms_provider, マスター_キー)
  begin
    new_coll_opts = coll_opts.dup.merge(encryption_fields: encryption_fields)
    [ database[coll_name].create(new_coll_opts), encryption_fields ]
  ヘルプ mongo::エラー => e
    発生 エラー::CryptError, "暗号化されたフィールドを使用したコレクションの作成エラー\ #{ encrypted_fields } : #{ e .クラス} : #{ e .メッセージ} "
  end
end

#decryption （値）=オブジェクト

すでに暗号化されている値を復号化します。

パラメーター:

  • 価値 （ BSON ::Binary ） —

    復号化されるサブタイプ6 （暗号テキスト）の BSON バイナリ オブジェクト。

次の値を返します。

  • （オブジェクト） —

    復号化された値。



196
197
198
 
# ファイル 'lib/mongo/client_encryption.rb' 行 196

デフォルト 解読(価値)
  @encrypter.解読(価値)
end

# delete_key （ ID ） =操作::結果

指定された ID を持つキーをキーヴォールト コレクションから削除します。

パラメーター:

  • id （ BSON ::Binary ） —

    削除するキーの ID。

次の値を返します。

  • （操作 :: 結果） —

    キーを削除する delete_one 操作に対するデータベースからの応答。



217
218
219
 
# ファイル 'lib/mongo/client_encryption.rb' 行 217

デフォルト delete_key(id)
  @encrypter.delete_key(id)
end

#暗号化（値、オプション = {{}） = BSON::Binary

注：

「インデックス」、「範囲」、または「string」アルゴリズムを使用した明示的な暗号化の結果は、挿入またはクエリを行うためにサーバーによって処理される必要があります。このようなペイロードで挿入またはクエリを実行するには、:auto_encryption_optionsで構成されたMongo::クライアントを使用します。:bypass_query_analysisオプションはtrueでも構いませんが、:bypass_auto_encryptionオプションはfalseである必要があります。

注：

「substring」クエリタイプは不安定であり、後方互換性のない重大な変更が行われる可能性があります。

注：

:key_id オプションと :key_alt_name オプションは相互に排他的です。 明示的な暗号化を実行するには 1 つのみが必要です。

指定された暗号化キーとアルゴリズムを使って値を暗号化します。

パラメーター:

  • 価値 （オブジェクト） —

    暗号化する値。

  • options （ハッシュ） （デフォルトは{}です）

オプション ハッシュ（ options ）:

  • :key_id （ BSON::Binary ） —

    キーヴォールトコレクションに保存されている暗号化のキーの UUID を表す :uuid の BSON::Binary オブジェクト。

  • :key_alt_name （ string ） —

    暗号化キーの代替名。

  • : アルゴリズム （ string ） —

    値を暗号化するために使用されるアルゴリズム。有効なアルゴリズムは、「AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic」、「AEAD_AES_256_CBC_HMAC_SHA_512-Random」、「インデックス」、「非インデックス」、「範囲」、「string」です。

  • :contention_factor (Integer | nil) —

    暗号化アルゴリズムが「インデックス」、「範囲」、または「string」に設定されている場合に適用される競合係数。指定されていない場合、デフォルト値は 0 です。競合係数は、暗号化アルゴリズムが「Indexed」、「範囲」、または「String」に設定されている場合にのみ設定する必要があります。

  • query_type （ string | nil ） —

    暗号化アルゴリズムが"インデックス"、"範囲"、または"string"に設定されている場合に適用されるクエリタイプ。許可される値は、「equality」（「Indexed」の場合）、「範囲」（「Range」の場合）、および「prefix」、「suffix」、「substring」（「string」の場合）です。

  • :range_opts （ハッシュ | nil ） —

    「範囲」クエリをサポートするQueryable Encryptionフィールドのインデックスオプションを指定します。アルゴリズムが「範囲」の場合に必須です。許可されるオプションは、:min、:max、:trim_factor、:sparsity、:precisionです。

  • :string_opts （ハッシュ | nil ） —

    「prefix」、「suffix」、または「substring」クエリをサポートするQueryable Encryptionフィールドのインデックスオプションを指定します。アルゴリズムが"string"の場合に必要です。許可されるオプションは、:case_sensitive、:diacritic_sensitive、:prefix、:suffix、:substringです。

次の値を返します。

  • （ BSON ::Binary ） —

    暗号化された値を表すサブタイプ6 （暗号テキスト）の BSON バイナリ オブジェクト。

次の値が発生します。

  • (ArgumentError) —

    contention_factor または query_type のいずれかが設定されており、アルゴリズムが "インデックス"、"範囲"、"string" のいずれでもない場合。



146
147
148
 
# ファイル 'lib/mongo/client_encryption.rb' 行 146

デフォルト 暗号化(価値, options = {})
  @encrypter.暗号化(価値, options)
end

#暗号化_式（式、オプション={{}）= BSON::Binary

注：

:key_id オプションと :key_alt_name オプションは相互に排他的です。 明示的な暗号化を実行するには 1 つのみが必要です。

範囲インデックスをクエリするには、 マッチ式 または 集計式 を暗号化します。

queryType が "範囲" で、アルゴリズムが "範囲" の場合にのみサポートされます。@note: 範囲アルゴリズムは実験的なもののみです。一般的な使用を意図したものではありません。重大な変更が発生する可能性があります。

@ param [ ハッシュ ] オプション

例:

マッチ式を暗号化する。

encryption.encrypt_expression(
  {'$and' =>  [{'field' => {'$gt' => 10}}, {'field' =>  {'$lt' => 20 }}]}
)

集計式を暗号化する。

encryption.encrypt_expression(
  {'$and' =>  [{'$gt' => ['$field', 10]}, {'$lt' => ['$field', 20]}}
)
{$and: [{$gt: [<fieldpath>, <value1>]}, {$lt: [<fieldpath>, <value2>]}]

パラメーター:

  • 式 （ハッシュ） —

    暗号化する 式 。

  • options （ハッシュ） （デフォルトは{}です） —

    カスタマイズ可能なオプションのセット

オプション ハッシュ（ options ）:

  • :key_id （ BSON::Binary ） —

    キーヴォールトコレクションに保存されている暗号化のキーの UUID を表す :uuid の BSON::Binary オブジェクト。

  • :key_alt_name （ string ） —

    暗号化キーの代替名。

  • : アルゴリズム （ string ） —

    式を暗号化するために使用されるアルゴリズム。許可される値は "範囲" のみ

  • :contention_factor (Integer | nil) —

    適用される競合係数。指定されない場合、デフォルトは0の値になります。

  • :query_type （ string | nil ） —

    適用されるクエリのタイプ。許可される値は「範囲」のみです。

次の値を返します。

  • （ BSON ::Binary ） —

    暗号化された式を表すサブタイプ6 （暗号テキスト）の BSON バイナリ オブジェクト。

次の値が発生します。

  • (ArgumentError) —

    オプションで許可されていない値が設定されている場合。



186
187
188
 
# ファイル 'lib/mongo/client_encryption.rb' 行 186

デフォルト encryption_式(式, options = {})
  @encrypter.encryption_式(式, options)
end

#get_key(id) ⇒ BSON::Document | nil

指定された ID を持つ単一のキーを検索します。

パラメーター:

  • id （ BSON ::Binary ） —

    取得するキーの ID。

次の値を返します。

  • (BSON::Document | nil) —

    見つかったキー ドキュメント、または見つからない場合は nil 。



227
228
229
 
# ファイル 'lib/mongo/client_encryption.rb' 行 227

デフォルト get_key(id)
  @encrypter.get_key(id)
end

#get_key_by_alt_name(key_alt_name) ⇒ BSON::Document | nil

指定された key_alt_name を持つキーヴォールト コレクション内のキーを返します。

パラメーター:

  • key_alt_name ( string ) —

    キーを検索するには、 キー代替名 を参照してください。

次の値を返します。

  • (BSON::Document | nil) —

    見つかったキー ドキュメント、または見つからない場合は nil 。



237
238
239
 
# ファイル 'lib/mongo/client_encryption.rb' 行 237

デフォルト get_key_by_alt_name(key_alt_name)
  @encrypter.get_key_by_alt_name(key_alt_name)
end

#get_keys = Collection::Viewとも呼ばれます:

キーヴォールト コレクション内のすべてのキーを返します。

次の値を返します。



244
245
246
 
# ファイル 'lib/mongo/client_encryption.rb' 行 244

デフォルト get_keys
  @encrypter.get_keys
end

#remove_key_alt_name(id, key_alt_name) ⇒ BSON::Document | nil

指定された ID を持つキーヴォールトコレクション内のキーから key_alt_name を削除します。

パラメーター:

  • id （ BSON ::Binary ） —

    キー代替名を削除するキーの ID。

  • key_alt_name ( string ) —

    削除するキーの代替名。

次の値を返します。

  • (BSON::Document | nil) —

    キーの代替名を削除する前に、識別されたキーを説明するドキュメント、またはそのようなキーがない場合は nil 。



256
257
258
 
# ファイル 'lib/mongo/client_encryption.rb' 行 256

デフォルト delete_key_alt_name(id, key_alt_name)
  @encrypter.delete_key_alt_name(id, key_alt_name)
end

# brewp_many_data_key （フィルター、opts = {}） = Crypt::RewriteManyDataKeyResult

複数のデータキーを復号化し、新しいマスター_キーで、または新しいマスター_キーでそれらを（再）暗号化します。新しいマスター_キーが指定されていない場合は、現在のマスター_キーで（再）暗号化します。

パラメーター:

  • フィルター （ハッシュ） —

    更新するキーを検索するために使用されるフィルター。

  • options （ハッシュ）

次の値を返します。



271
272
273
 
# ファイル 'lib/mongo/client_encryption.rb' 行 271

デフォルト rewrap_many_data_key(フィルター, ops = {})
  @encrypter.rewrap_many_data_key(フィルター, ops)
end