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。

  • 选项 （哈希） （默认为： {} ） —

    ClientEncryption 选项。

选项哈希 ( options )：

  • :key_vault_namespace （ string ） —

    密钥保管集合的名称，格式为“ 数据库 ”。

  • :kms_providers （哈希） —

    KMS 配置信息的哈希值。 @see Mongo::Crypt::KMS::Credentials 了解每个受支持提供程序的选项列表。 @note 可能指定了多个 KMS 提供程序。

  • :kms_tls_options （哈希） —

    用于连接到KMS提供商的 TLS 选项。 哈希键应为 KSM提供商名称；值应该是 TLS 连接选项的哈希值。 这些选项相当于 Mongo::Client 的 TLS 连接选项。 @see Mongo::Client#initialize 以获取 TLS 选项列表。

  • :timeout_ms （整数） —

    操作超时（以毫秒为单位）。 必须是非负整数。 0 的显式值表示无限。 默认值未设置，这意味着该功能已禁用。

  • :key_expiration_ms （整数） —

    数据加密密钥缓存的生存期，以毫秒为单位。必须是非负整数。0 的明确值意味着缓存永不过期。默认为 60000。

引发：

  • ( ArgumentError ) —

    如果必需的选项丢失或格式不正确。



52
53
54
55
56
57
58
59
60
61
 
# File 'lib/ Mongo/client_encryption.rb', line 52

def 初始化(key_vault_client, 选项 = {})
  @encrypter = Crypt::ExplicitEncrypter.new(
    key_vault_client,
    选项[:key_vault_namespace],
    Crypt::KMS::凭证.new(选项[:kms_providers]),
    Crypt::KMS::验证.validate_tls_options(选项[:kms_tls_options]),
    选项[:timeout_ms],
    选项[: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
 
# File 'lib/ Mongo/client_encryption.rb', line 207

def add_key_alt_name(id, key_alt_name)
  @encrypter.add_key_alt_name(id, key_alt_name)
end

# create_data_key (kms_provider, options = {}) ⇒ BSON::Binary

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

参数：

  • kms_provider ( string ) —

    要使用的KMS提供商。有效值为“aws”和“local”。

  • 选项 （哈希） （默认为： {} ）

选项哈希 ( options )：

  • :master_key （哈希） —

    有关 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 ( Array<String> ) —

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

  • :key_material ( string | nil ) —

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

返回：

  • ( BSON::Binary ) —

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



89
90
91
92
93
94
95
 
# File 'lib/ Mongo/client_encryption.rb', line 89

def create_data_key(kms_provider, 选项 = {})
  key_document = Crypt::KMS::MasterKeyDocument.new(kms_provider, 选项)

  key_alt_names = 选项[:key_alt_names]
  key_material = 选项[:key_material]
  @encrypter.create_and_insert_data_key(key_document, key_alt_names, key_material)
end

# create_encrypted_collection (数据库, coll_name, coll_opts, kms_provider, master_key) ⇒ Array< Operation::Result , Hash>

注意：

此方法不会更新客户端的 :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提供商。

  • master_key ( Hash | nil ) —

    描述用于加密字段的主密钥的文档。

返回：

  • ( Array< Operator::Result , Hash> ) —

    创建集合操作的结果以及用于创建集合的加密字段映射。

引发：

  • ( ArgumentError ) 


294
295
296
297
298
299
300
301
302
303
304
305
 
# File 'lib/ Mongo/client_encryption.rb', line 294

def create_encrypted_collection(database, coll_name, coll_opts, kms_provider, master_key)
  提高 ArgumentError, ' coll_opts must contains :encrypted_fields ' 除非 coll_opts[:encrypted_fields]

  encryption_fields = create_data_keys(coll_opts[:encrypted_fields], kms_provider, master_key)
  开始
    new_coll_opts = coll_opts.dup.合并(merge)(encryption_fields: encryption_fields)
    [ database[coll_name].创建(new_coll_opts), encryption_fields ]
  救援 mongo::错误 => e
    提高 错误::CryptError, " 创建包含加密字段的集合时出错 \ # { encryption_fields } : #{ e . class } : #{ e . message } "
  end
end

#解密（值） ⇒对象

对已加密的值进行解密。

参数：

  • 值 ( BSON::Binary ) —

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

返回：

  • ( Object ) —

    解密的值。



196
197
198
 
# File 'lib/ Mongo/client_encryption.rb', line 196

def 解密(值)
  @encrypter.解密(值)
end

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

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

参数：

  • id ( BSON::Binary ) —

    要删除的密钥的 ID。

返回：



217
218
219
 
# File 'lib/ Mongo/client_encryption.rb', line 217

def delete_key(id)
  @encrypter.delete_key(id)
end

# encrypt (value, options = {}) ⇒ BSON::Binary

注意：

使用“Indexed”、“范围”或“string”算法进行显式加密的结果必须由服务器处理才能进行插入或查询。要使用此类有效负载进行插入或查询，请使用配置了 :auto_encryption_options 的 Mongo::Client。:bypass_query_analysis 选项可以为 true；:bypass_auto_encryption 选项必须为 false。

注意：

“substring”查询类型目前不稳定，可能会发生向后破坏性变更 (breaking change)。

注意：

: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”、“索引”、“未索引”、“范围”、“string”。

  • :contention_factor ( Integer | nil ) —

    如果加密算法设置为“索引”、“范围”或“string”，则应用争用因子。如果未提供，则默认为 0。仅当加密算法设置为“Indexed”、“范围”或“string”时，才应设置争用因子 (Contention factor)。

  • query_type ( string | nil ) —

    如果加密算法设置为“索引”、“范围”或“String”，则应用查询类型。允许的值为“equality”（用于“索引”）、“范围”（用于“范围”）以及“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
 
# File 'lib/ Mongo/client_encryption.rb', line 146

def 加密(值, 选项 = {})
  @encrypter.加密(值, 选项)
end

# encrypt_expression (expression, options = {}) ⇒ BSON::Binary

注意：

: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 ) —

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

返回：

  • ( BSON::Binary ) —

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

引发：

  • ( ArgumentError ) —

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



186
187
188
 
# File 'lib/ Mongo/client_encryption.rb', line 186

def encrypt_expression(表达式(expression), 选项 = {})
  @encrypter.encrypt_expression(表达式(expression), 选项)
end

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

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

参数：

  • id ( BSON::Binary ) —

    要获取的密钥的 ID。

返回：

  • ( BSON::Document | nil ) —

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



227
228
229
 
# File 'lib/ Mongo/client_encryption.rb', line 227

def 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
 
# File 'lib/ Mongo/client_encryption.rb', line 237

def 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
 
# File 'lib/ Mongo/client_encryption.rb', line 244

def 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
 
# File 'lib/ Mongo/client_encryption.rb', line 256

def remove_key_alt_name(id, key_alt_name)
  @encrypter.remove_key_alt_name(id, key_alt_name)
end

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

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

参数：

  • 筛选器 (哈希) —

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

  • 选项 （哈希）

返回：



271
272
273
 
# File 'lib/ Mongo/client_encryption.rb', line 271

def rewrap_many_data_key(筛选器, opts = {})
  @encrypter.rewrap_many_data_key(筛选器, opts)
end