类：Mongo::Crypt::ExplicitEncrypter Private

继承：
对象
  • 对象
显示全部
扩展方式：
可转发
定义于：
lib/ Mongo/crypt/explicit_encrypter.rb

Overview

此类是私有 API 的一部分。 应尽可能避免使用此类，因为它将来可能会被删除或更改。

ExplicitEncrypter 是执行显式加密操作并处理所有关联选项和实例变量的对象。

实例方法摘要折叠

构造函数详情

#initialize(key_vault_client, key_vault_namespace, kms_providers, kms_tls_options, timeout_ms = nil, key_expiration_ms = nil) ⇒ ExplicitEncrypter

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

创建一个新的 ExplicitEncrypter 对象。

参数：

  • key_vault_client ( Mongo::Client ) —

    用于连接到密钥保管库集合的 Mongo::Client实例。

  • key_vault_namespace ( string ) —

    密钥保管库集合的命名空间，格式为“db_name.collection_name”。

  • kms_providers ( Crypt:: KMS::Credentials ) —

    KMS 配置信息的哈希值。

  • kms_tls_options (哈希) —

    用于连接到 KMS 提供商的 TLS 选项。 哈希键应为 KSM 提供程序名称；值应该是 TLS 连接选项的哈希值。 这些选项相当于 Mongo::Client 的 TLS 连接选项。

  • timeout_ms ( Integer | nil ) （默认为： nil ） —

    在此对象上执行的每个操作的超时时间。

  • key_expiration_ms ( Integer | nil ) （默认为： nil ） —

    数据加密密钥缓存的生命周期（以毫秒为单位）。值为 0 表示缓存永不过期。当 nil 时，使用 libmongocrypt 的默认60000。



43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
 
# File 'lib/ Mongo/crypt/explicit_encrypter.rb', line 43

def 初始化(
  key_vault_client, key_vault_namespace, kms_providers, kms_tls_options,
  timeout_ms = nil, key_expiration_ms = nil
)
  Crypt.validate_ffi!
  @crypt_handle = 句柄.new(
    kms_providers,
    kms_tls_options,
    explicit_encryption_only: true,
    key_expiration_ms: key_expiration_ms
  )
  @encryption_io = EncryptionIO.new(
    key_vault_client: key_vault_client,
    metadata_client: nil,
    key_vault_namespace: key_vault_namespace
  )
  @timeout_ms = timeout_ms
end

实例方法详细信息

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

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

在具有给定 ID 的密钥保管库集合中为密钥添加 key_alt_name。

参数：

  • id ( BSON::Binary ) —

    用于添加新密钥替代名称的密钥 ID。

  • key_alt_name ( string ) —

    要添加的新密钥替代名称。

返回：

  • ( BSON::Document | nil ) —

    在添加密钥替代名称之前描述已识别密钥的文档，如果没有此类密钥，则为 nil。



218
219
220
 
# File 'lib/ Mongo/crypt/explicit_encrypter.rb', line 218

def add_key_alt_name(id, key_alt_name)
  @encryption_io.add_key_alt_name(id, key_alt_name, timeout_ms: @timeout_ms)
end

# create_and_insert_data_key (master_key_document, key_alt_names, key_material = nil) ⇒ BSON::Binary

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

生成用于加密/解密的数据密钥，并将该密钥存储在 KMS 集合中。 生成的密钥使用 KMS 主密钥进行加密。

参数：

  • master_key_document ( Mongo::Crypt::KMS::MasterKeyDocument ) —

    包含主加密密钥参数的主密钥文档。

  • key_alt_names ( Array<String> | nil ) —

    一个可选的字符串数组，用于指定新数据键的备用名称。

  • key_material ( string | nil ) （默认为： nil ） —

    可选的96字节用作正在创建的数据密钥的自定义密钥材料。 如果给出了 key_material 选项，则使用自定义密钥材料加密和解密数据。

返回：

  • ( BSON::Binary ) —

    新数据密钥的16字节 UUID，为BSON::Binary对象，类型为 :uuid。



77
78
79
80
81
82
83
84
85
86
87
88
89
 
# File 'lib/ Mongo/crypt/explicit_encrypter.rb', line 77

def create_and_insert_data_key(master_key_document, key_alt_names, key_material = nil)
  data_key_document = Crypt::DataKeyContext.new(
    @crypt_handle,
    @encryption_io,
    master_key_document,
    key_alt_names,
    key_material
  ).run_state_machine(timeout_holder)

  @encryption_io.insert_data_key(
    data_key_document, timeout_ms: timeout_holder.剩余超时毫秒！
  ).Inserted_id
end

#解密（值） ⇒对象

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

对已加密的值进行解密

参数：

  • 值 ( BSON::Binary ) —

    将要解密的子类型为6 （密文）的 BSON 二进制对象

返回：

  • ( Object ) —

    解密后的值



203
204
205
206
207
208
209
 
# File 'lib/ Mongo/crypt/explicit_encrypter.rb', line 203

def 解密(值)
  Crypt::ExplicitDecryptionContext.new(
    @crypt_handle,
    @encryption_io,
    { v: 值 }
  ).run_state_machine(timeout_holder)[' v ']
end

# delete_key ( ID ) = "Operation::Result"

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

从密钥保管库集合中删除具有给定 ID 的密钥。

参数：

  • id ( BSON::Binary ) —

    要删除的密钥的 ID。

返回：



228
229
230
 
# File 'lib/ Mongo/crypt/explicit_encrypter.rb', line 228

def delete_key(id)
  @encryption_io.delete_key(id, timeout_ms: @timeout_ms)
end

# encrypt (value, options) ⇒ BSON::Binary

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

注意：

:key_id 和 :key_alt_name 选项是互斥的。 只需一次即可执行显式加密。

使用指定的加密密钥和算法加密值

参数：

  • 值 ( Object ) —

    要加密的值

  • 选项 （哈希）

选项哈希 ( options )：

  • :key_id ( BSON::Binary ) —

    :uuid 类型的BSON::Binary对象，表示存储在密钥保管库集合中的加密密钥的 UUID。

  • :key_alt_name （ string ） —

    加密密钥的备用名称。

  • :algorithm （ string ） —

    用于加密值的算法。有效算法为 "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"、"AEAD_AES_256_CBC_HMAC_SHA_512-Random"、"Indexed"、"Unindexed"、"Range"、"String" 。

  • :contention_factor ( Integer | nil ) —

    如果加密算法设立为“Indexed”（索引）、“Range”（范围）或“String”（字符串），则要应用的争用因子。如果未提供，则默认值为 0。仅当加密算法设立为“Indexed”（索引）、“Range”（范围）或“String”（字符串）时，才应设立争用因子。

  • :query_type ( string | nil ) —

    如果加密算法设立为“Indexed”（索引）、“Range”（范围）或“String”（字符串），则要应用的查询类型。允许的值为“equals”（相等）。 (for "Indexed"), "range" and （针对“范围”）和“前缀”、“后缀”、“子串” （对于“String”）。

  • :range_opts （哈希 | nil ） —

    为支持“范围”的Queryable Encryption字段指定索引选项查询。当算法为“Range”时必需。

  • :string_opts （哈希 | nil ） —

    指定支持“前缀”、“后缀”或“子字符串”索引的 Queryable Encryption字段的索引选项。查询。当算法为“String”时为必填项。

返回：

  • ( BSON::Binary ) —

    表示加密值的子类型为6 （密文）的 BSON 二进制对象

引发：

  • ( ArgumentError ) —

    如果设立了contention_factor或query_type，并且算法不是“Indexed”、“Range”或“String”。



128
129
130
131
132
133
134
135
 
# File 'lib/ Mongo/crypt/explicit_encrypter.rb', line 128

def 加密(值, 选项)
  Crypt::ExplicitEncryptionContext.new(
    @crypt_handle,
    @encryption_io,
    { v: 值 },
    选项
  ).run_state_machine(timeout_holder)[' v ']
end

# encrypt_expression (表达式, options) ⇒ BSON::Binary

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

注意：

范围算法仅处于实验阶段。 它不是

注意：

:key_id 和 :key_alt_name 选项是互斥的。 只需一次即可执行显式加密。

加密匹配表达式或聚合表达式以查询范围索引。

仅当 queryType 为 "范围" 且算法为 "Range" 时才支持。@note：范围算法仅处于实验阶段。它不适合公众使用。它可能会进行破坏性变更 (breaking change)。

@param [ Hash ] 选项

供公众使用。

例子：

加密匹配表达式。

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>]}]

参数：

  • 表达式(expression) (哈希) —

    要加密的表达式。

  • 选项 (哈希) —

    一组可自定义的选项

选项哈希 ( options )：

  • :key_id ( BSON::Binary ) —

    :uuid 类型的BSON::Binary对象，表示存储在密钥保管库集合中的加密密钥的 UUID。

  • :key_alt_name （ string ） —

    加密密钥的备用名称。

  • :algorithm （ string ） —

    用于加密表达式的算法。唯一允许的值为“Range”

  • :contention_factor ( Integer | nil ) —

    要应用的争用系数 如果未提供，则默认值为0 。

  • query_type ( string | nil ) —

    要应用的查询类型。唯一允许的值为 "范围"。

  • :range_opts （哈希 | nil ） —

    为支持“ 范围 ”查询的Queryable Encryption字段指定索引选项。允许的选项包括：

    • :min
    • :max
    • :trim_factor
    • :sparsity
    • :精度 min、max、trim_factor、稀疏性和精度必须与目标集合的encryptedFields中设立的值相匹配。对于 double 和十进制128，最小/最大/精度必须全部设立，或者全部取消设置。

返回：

  • ( BSON::Binary ) —

    子类型为6 （密文）的BSON二进制对象，表示加密的表达式。

引发：

  • ( ArgumentError ) —

    如果在选项中设立了不允许的值。



188
189
190
191
192
193
194
195
 
# File 'lib/ Mongo/crypt/explicit_encrypter.rb', line 188

def encrypt_expression(表达式(expression), 选项)
  Crypt::ExplicitEncryptionExpressionContext.new(
    @crypt_handle,
    @encryption_io,
    { v: 表达式(expression) },
    选项
  ).run_state_machine(timeout_holder)[' v ']
end

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

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

查找具有给定 ID 的单个键。

参数：

  • id ( BSON::Binary ) —

    要获取的密钥的 ID。

返回：

  • ( BSON::Document | nil ) —

    找到的密钥文档，如果未找到，则返回 nil。



238
239
240
 
# File 'lib/ Mongo/crypt/explicit_encrypter.rb', line 238

def get_key(id)
  @encryption_io.get_key(id, timeout_ms: @timeout_ms)
end

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

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

返回密钥保管库集合中具有给定 key_alt_name 的密钥。

参数：

  • key_alt_name ( string ) —

    用于查找密钥的密钥替代名称。

返回：

  • ( BSON::Document | nil ) —

    找到的密钥文档，如果未找到，则返回 nil。



248
249
250
 
# File 'lib/ Mongo/crypt/explicit_encrypter.rb', line 248

def get_key_by_alt_name(key_alt_name)
  @encryption_io.get_key_by_alt_name(key_alt_name, timeout_ms: @timeout_ms)
end

# get_keys ⇒ Collection::View

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

返回密钥保管库集合中的所有密钥。

rubocop:disable Naming/AccessorMethodName 此方法的名称在 FLE 规范中定义

返回：



257
258
259
 
# File 'lib/ Mongo/crypt/explicit_encrypter.rb', line 257

def get_keys
  @encryption_io.get_keys(timeout_ms: @timeout_ms)
end

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

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

从密钥保管库集合中具有给定 ID 的密钥中删除 key_alt_name。

参数：

  • id ( BSON::Binary ) —

    要删除密钥替代名称的密钥的 ID。

  • key_alt_name ( string ) —

    要删除的密钥替代名称。

返回：

  • ( BSON::Document | nil ) —

    在删除密钥替代名称之前描述已识别密钥的文档，如果没有此类密钥，则为 nil。



269
270
271
 
# File 'lib/ Mongo/crypt/explicit_encrypter.rb', line 269

def remove_key_alt_name(id, key_alt_name)
  @encryption_io.remove_key_alt_name(id, key_alt_name, timeout_ms: @timeout_ms)
end

# rewrap_many_data_key (过滤, opts = {}) ⇒ Crypt::RewrapManyDataKeyResult

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

解密多个数据密钥，并使用新的 master_key（重新）加密它们；如果未给出新密钥，则使用当前的 master_key。

参数：

  • 筛选器 (哈希) —

    用于查找要更新的密钥的筛选器。

  • 选项 （哈希）

返回：



284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
 
# File 'lib/ Mongo/crypt/explicit_encrypter.rb', line 284

def rewrap_many_data_key(筛选器, opts = {})
  validate_rewrap_options!(opts)

  master_key_document = master_key_for_provider(opts)

  rewrap_result = Crypt::RewrapManyDataKeyContext.new(
    @crypt_handle,
    @encryption_io,
    筛选器,
    master_key_document
  ).run_state_machine(timeout_holder)

  return RewrapManyDataKeyResult.new(nil) if rewrap_result.nil?

  更新 = update_from_data_key_documents(rewrap_result.获取(' v '))
  RewrapManyDataKeyResult.new(
    @encryption_io.update_data_keys(更新, timeout_ms: @timeout_ms)
  )
end