Class: Mongo::ClientEncryption

상속:
객체
  • 객체
모두 표시
다음에 정의됨:
lib/ Mongo/client_encryption.rb

개요

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 구성 정보의 해시입니다. 지원되는 모든 제공자에 대한 옵션 목록은 @Mongo::Crypt::KMS::Credentials를 참조하세요. @note 둘 이상의 KMS 제공자가 지정되었을 수 있습니다.

  • :kms_tls_options (해시) —

    KMS 제공자에 연결하기 위한 TLS 옵션. 해시의 키는 KSM 제공자 이름이어야 합니다. 값은 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

def 초기화(key_Vault_client, 옵션 = {})
  @encrypter = 암호화::명시적 암호화 프로그램(ExplicitEncrypter).신규(
    key_Vault_client,
    옵션[:key_vault_namespace],
    암호화::KMS::자격 증명.신규(옵션[:kms_providers]),
    암호화::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
 
# 파일 'lib/ Mongo/client_encryption.rb', 줄 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)입니다(필수).
    • :엔드포인트 [ 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로, 유형이 :uuid인 BSON::Binary 객체 입니다.



89
90
91
92
93
94
95
 
# 파일 'lib/ Mongo/client_encryption.rb', 줄 89

def create_data_key(kms_provider, 옵션 = {})
  key_document = 암호화::KMS::MasterKeyDocument.신규(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<Operation::Result, Hash>) —

    컬렉션 생성 작업의 결과와 컬렉션 생성에 사용된 암호화된 필드 맵입니다.

다음을 발생시킵니다.

  • (ArgumentError) 


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

def create_encrypted_collection(database, coll_name, coll_opts, kms_provider, master_key)
  올리다 ArgumentError, 'coll_opts에는 반드시 :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].create(new_coll_opts), encryption_fields ]
  구출 mongo::오류 => e
    올리다 오류::CRYPTError, " 암호화 된 필드 가 있는 컬렉션 을 만드는 동안 오류 가 발생 했습니다
          ._ _ _
  end
end

#Decrypt(value) ⇒ 객체

이미 암호화된 값을 해독합니다.

매개변수:

  • value (BSON::Binary) —

    해독될 하위 유형 6 (암호 텍스트)의 BSON 바이너리 객체입니다.

반환합니다:

  • (객체) —

    암호 해독된 값입니다.



196
197
198
 
# 파일 'lib/ Mongo/client_encryption.rb', 줄 196

def 암호 해독(value)
  @encrypter.암호 해독(value)
end

#delete_key(ID) ⇒ Operation::Result

키 볼트 컬렉션 에서 지정된 ID의 키를 제거합니다.

매개변수:

  • id (BSON::Binary) —

    삭제 키의 ID입니다.

반환합니다:

  • (Operation::Result) —

    키를 삭제하는 delete_one 작업에 대한 데이터베이스의 응답입니다.



217
218
219
 
# 파일 'lib/ Mongo/client_encryption.rb', 줄 217

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

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

참고:

"Indexed", "Range" 또는 "String" 을 사용한 명시적 암호화 의 결과입니다. 알고리즘 삽입하거나 쿼리 하려면 서버 에서 처리되어야 합니다. 이러한 페이로드를 삽입하거나 쿼리 하려면 :auto_encryption_options로 구성된 Mongo::Client를 사용하세요. :bypass_query_analysis 옵션이 true일 수 있습니다. :bypass_auto_encryption 옵션은 false여야 합니다.

참고:

"하위 문자열" 쿼리 유형이 불안정하며 이전 버전과의 호환성이 손상될 수 있습니다.

참고:

:key_id 및 :key_alt_name 옵션은 상호 배타적입니다. 명시적 암호화를 수행하는 데는 하나만 필요합니다.

지정된 암호화 키와 알고리즘을 사용하여 값을 암호화합니다.

매개변수:

  • value (객체) —

    암호화할 값입니다.

  • 옵션 (해시) (기본값: {})

옵션 해시(options):

  • :key_id (BSON::Binary) —

    키 볼트 컬렉션 에 저장된 암호화 키 의 UUID를 나타내는 :uuid 유형의 BSON::Binary 객체 입니다.

  • :key_alt_name (string) —

    암호화 키의 대체 이름입니다.

  • :algorithm (string) —

    The algorithm used to encrypt the value. Valid algorithms are "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic", "AEAD_AES_256_CBC_HMAC_SHA_512-Random", "Indexed", "Unindexed", "Range", "String".

  • :contention_factor (정수 | nil) —

    암호화 알고리즘 'Indexed(인덱스)', 'Range(범위)' 또는 'String(문자열)'으로 설정하다 경우 적용되는 경합 요인입니다. 제공하지 않으면 기본값은 0입니다. 경합 요인은 암호화 알고리즘 'Indexed(인덱스)', 'Range(범위)' 또는 'String(문자열)'으로 설정하다 경우에만 설정하다 해야 합니다.

  • query_type (string | nil) —

    암호화 알고리즘 '인덱스', '범위' 또는 '문자열'로 설정하다 경우 적용할 쿼리 유형입니다. 허용되는 값은 다음과 같습니다. ('인덱스됨'의 경우), '범위' ('Range'의 경우) 및 'prefix', 'suffix', 'substring' ('String'의 경우).

  • :range_opts (해시 | nil) —

    "range"를 지원하는 Queryable Encryption 필드 에 대한 인덱스 옵션을 지정합니다. 쿼리. 알고리즘 '범위'인 경우 필수 사항입니다. 허용되는 옵션은 :min, :max, :trim_factor, :sparsity, :precision입니다.

  • :string_opts (해시 | nil) —

    "prefix", "suffix" 또는 "substring" 을 지원하는 Queryable Encryption 필드 에 대한 인덱스 옵션을 지정합니다. 쿼리. 알고리즘 '문자열'인 경우 필수 사항입니다. 허용되는 옵션은 :대소문자 구분, : 발음 구별 부호, :접두사, :접미사, :하위 문자열입니다.

반환합니다:

  • (BSON::Binary) —

    암호화된 값을 나타내는 하위 유형 6 (암호 텍스트)의 BSON 바이너리 객체입니다.

다음을 발생시킵니다.

  • (ArgumentError) —

    경쟁 요소 또는 쿼리 유형이 설정하다 알고리즘 '인덱스', '범위' 또는 '문자열'이 아닌 경우.



146
147
148
 
# 파일 'lib/ Mongo/client_encryption.rb', 줄 146

def 암호화(value, 옵션 = {})
  @encrypter.암호화(value, 옵션)
end

# 암호화 표현식 (표현식, 옵션 = {}) ⇒BSON ::Binary

참고:

:key_id 및 :key_alt_name 옵션은 상호 배타적입니다. 명시적 암호화를 수행하는 데는 하나만 필요합니다.

범위 인덱스를 쿼리하기 위해 일치 표현식 또는 애그리게이션 표현식을 암호화합니다.

queryType이 ' 범위'이고 알고리즘 이 'Range'인 경우에만 지원됩니다. @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):

  • :key_id (BSON::Binary) —

    키 볼트 컬렉션 에 저장된 암호화 키 의 UUID를 나타내는 :uuid 유형의 BSON::Binary 객체 입니다.

  • :key_alt_name (string) —

    암호화 키의 대체 이름입니다.

  • :algorithm (string) —

    표현식 을 암호화하는 데 사용되는 알고리즘 . 허용되는 유일한 값은 'Range'입니다.

  • :contention_factor (정수 | nil) —

    적용할 경합 요인을 제공하지 않으면 기본값은 0 입니다.

  • :query_type (string | nil) —

    적용할 쿼리 유형입니다. 허용되는 유일한 값은 "범위"입니다.

반환합니다:

  • (BSON::Binary) —

    암호화됨 표현식 나타내는 하위 유형 6 (암호 텍스트)의 BSON 바이너리 객체 입니다.

다음을 발생시킵니다.

  • (ArgumentError) —

    options 에 허용되지 않는 값이 설정하다 경우.



186
187
188
 
# 파일 'lib/ Mongo/client_encryption.rb', 줄 186

def 암호화 표현식(표현식, 옵션 = {})
  @encrypter.암호화 표현식(표현식, 옵션)
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

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
 
# 파일 'lib/ Mongo/client_encryption.rb', 줄 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
 
# 파일 'lib/ Mongo/client_encryption.rb', 줄 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
 
# 파일 'lib/ Mongo/client_encryption.rb', 줄 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

여러 데이터 키를 해독하고 새 마스터 키로 데이터 키를 (재)암호화하거나, 새 키가 제공되지 않은 경우 현재 마스터 키로 암호화합니다.

매개변수:

  • 필터 (해시) —

    업데이트할 키를 찾는 데 사용되는 필터입니다.

  • 옵션 (해시)

반환합니다:



271
272
273
 
# 파일 'lib/ Mongo/client_encryption.rb', 줄 271

def rerap_many_data_key(필터, opts = {})
  @encrypter.rerap_many_data_key(필터, opts)
end