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 的显式值表示无限。 默认值未设置，这意味着该功能已禁用。

引发：

  • ( ArgumentError ) —

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



48
49
50
51
52
53
54
55
 
# File 'lib/ Mongo/client_encryption.rb', line 48

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])
  )
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。



182
183
184
 
# File 'lib/ Mongo/client_encryption.rb', line 182

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。



83
84
85
86
87
88
89
 
# File 'lib/ Mongo/client_encryption.rb', line 83

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 ) 


269
270
271
272
273
274
275
276
277
278
279
280
 
# File 'lib/ Mongo/client_encryption.rb', line 269

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

    解密的值。



171
172
173
 
# File 'lib/ Mongo/client_encryption.rb', line 171

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

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

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

参数：

  • id ( BSON::Binary ) —

    要删除的密钥的 ID。

返回：



192
193
194
 
# File 'lib/ Mongo/client_encryption.rb', line 192

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

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

注意：

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

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

如果加密算法设立为“Indexed”。仅当加密算法设立为“Indexed”时，才应设立查询类型。唯一允许的值为“equality”。

参数：

  • 值 ( 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"。

  • :contention_factor ( Integer | nil ) —

    将加密算法设立为“已索引”时要应用的争用因子。如果未提供，则默认值为 0。仅当加密算法设立为“已索引”时，才应设立争用因子。

  • query_type ( string | nil ) —

    要应用的查询类型

返回：

  • ( BSON::Binary ) —

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

引发：

  • ( ArgumentError ) —

    如果设立了contention_factor或query_type，并且算法不是“已索引”。



121
122
123
 
# File 'lib/ Mongo/client_encryption.rb', line 121

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

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



161
162
163
 
# File 'lib/ Mongo/client_encryption.rb', line 161

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

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

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

参数：

  • id ( BSON::Binary ) —

    要获取的密钥的 ID。

返回：

  • ( BSON::Document | nil ) —

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



202
203
204
 
# File 'lib/ Mongo/client_encryption.rb', line 202

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。



212
213
214
 
# File 'lib/ Mongo/client_encryption.rb', line 212

def get_key_by_alt_name(key_alt_name)
  @encrypter.get_key_by_alt_name(key_alt_name)
end

# get_keys ⇒ Collection::View也称为：键

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

返回：



219
220
221
 
# File 'lib/ Mongo/client_encryption.rb', line 219

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。



231
232
233
 
# File 'lib/ Mongo/client_encryption.rb', line 231

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。

参数：

  • 筛选器 (哈希) —

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

  • 选项 （哈希）

返回：



246
247
248
 
# File 'lib/ Mongo/client_encryption.rb', line 246

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