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 의 명시적 값은 무한대를 의미합니다. 기본값 은 '설정되지 않음'으로, 이 기능 이 비활성화됩니다.

다음을 발생시킵니다.

  • (ArgumentError) —

    필수 옵션이 누락되었거나 형식이 잘못된 경우.



48
49
50
51
52
53
54
55
 
# 파일 'lib/ Mongo/client_encryption.rb', 줄 48

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



83
84
85
86
87
88
89
 
# 파일 'lib/ Mongo/client_encryption.rb', 줄 83

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) 


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

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 바이너리 객체입니다.

반환합니다:

  • (객체) —

    암호 해독된 값입니다.



171
172
173
 
# 파일 'lib/ Mongo/client_encryption.rb', 줄 171

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

#delete_key(ID) ⇒ Operation::Result

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

매개변수:

  • id (BSON::Binary) —

    삭제 키의 ID입니다.

반환합니다:

  • (Operation::Result) —

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



192
193
194
 
# 파일 'lib/ Mongo/client_encryption.rb', 줄 192

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

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

참고:

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

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

암호화 알고리즘 '인덱싱됨'으로 설정하다 경우. 쿼리 유형은 암호화 알고리즘 '인덱싱됨'으로 설정하다 경우에만 설정하다 해야 합니다. 허용되는 유일한 값은 "동등성"입니다.

매개변수:

  • value (객체) —

    암호화할 값입니다.

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

옵션 해시(options):

  • :key_id (BSON::Binary) —

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

  • :key_alt_name (string) —

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

  • :algorithm (string) —

    값을 암호화하는 데 사용되는 알고리즘 입니다. 유효한 알고리즘은 'AEAD_AES_256_CBC_HMAC_SHA_512-결정적', 'AEAD_AES_256_CBC_HMAC_SHA_512-랜덤', '인덱싱됨', '인덱싱되지 않음'입니다.

  • :contention_factor (정수 | nil) —

    암호화 알고리즘 '인덱싱됨'으로 설정하다 경우 적용되는 경합 요인입니다. 지정하지 않으면 기본값은 0입니다. 경합 요인은 암호화 알고리즘 '인덱싱됨'으로 설정하다 경우에만 설정하다 해야 합니다.

  • query_type (string | nil) —

    적용할 쿼리 유형

반환합니다:

  • (BSON::Binary) —

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

다음을 발생시킵니다.

  • (ArgumentError) —

    contention_factor 또는 query_type이 설정하다 있고 알고리즘 '인덱싱'되지 않은 경우입니다.



121
122
123
 
# 파일 'lib/ Mongo/client_encryption.rb', 줄 121

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 에 허용되지 않는 값이 설정하다 경우.



161
162
163
 
# 파일 'lib/ Mongo/client_encryption.rb', 줄 161

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

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

지정된 ID를 가진 단일 키를 찾습니다.

매개변수:

  • id (BSON::Binary) —

    가져올 키의 ID입니다.

반환합니다:

  • (BSON::Document | nil) —

    발견된 키 문서 를 반환하거나, 찾을 수 없는 경우 nil을 반환합니다.



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

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

매개변수:

  • 필터 (해시) —

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

  • 옵션 (해시)

반환합니다:



246
247
248
 
# 파일 'lib/ Mongo/client_encryption.rb', 줄 246

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