문서 메뉴
문서 홈
/
MongoDB 매뉴얼
/
참조
/
Mongo쉬 방법
/
Client-Side Field Level Encryption

ClientEncryption.encrypt()

이 페이지의 내용

  • 구문
  • 행동
  • 예제
  • 자세히 알아보기
ClientEncryption.encrypt(keyId, value, algorithm or encOptions)

ClientEncryption.encrypt() 은 지정된 keyId 와 algorithm 또는 encOptions 로 지정된 알고리즘을 사용하여 value 를 암호화합니다. encrypt() 는 필드 값의 명시적(수동) 암호화를 지원합니다.

반환합니다:하위 유형이 6 인 binary data 객체 .

구문

clientEncryption = db.getMongo().getClientEncryption()
clientEncryption.encrypt(
  keyId,
  value,
  algorithm or encOptions,
)
매개 변수
유형
설명
keyId
UUID

value를 암호화하는 데 사용할 데이터 암호화 키입니다.

UUID 는 특정 데이터 암호화 키를 식별하는 하위 유형 4 이 있는 BSON binary data 객체입니다. 데이터베이스 연결에 대해 구성된 키 볼트에 데이터 암호화 키가 없는 경우 encrypt() 에서 오류를 반환합니다. 키 볼트 및 데이터 암호화 키에 대한 자세한 내용은 키 볼트 컬렉션 을 참조하세요.

value
암호화할 값입니다.
algorithm 또는 encOptions
문자열 또는 문서

  • 클라이언트측 필드 수준 암호화를 사용하여 필드를 명시적으로 암호화하려면 다음을 수행합니다.

    algorithm을 문자열로 지정하거나 encOptions를 필드 algorithm이 포함된 문서로 지정합니다.

    지원되는 알고리즘은 다음과 같습니다.

    • AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic

    • AEAD_AES_256_CBC_HMAC_SHA_512-Random

    예제 는 클라이언트 측 필드 레벨 암호화 알고리즘 설정을 참조하세요.

    지원되는 암호화 알고리즘에 대한 전체 문서는 필드 및 암호화 유형을 참조하세요.

  • Queryable Encryption으로 필드를 명시적으로 암호화하려면 다음을 수행합니다.

    algorithm을 문자열로 지정하거나 encOptions를 다음 필드가 포함된 문서로 지정합니다.

    • algorithm: value를 암호화하는 데 사용할 암호화 알고리즘입니다. 지원되는 알고리즘은 다음과 같습니다.

      • Indexed

      • Unindexed

    • contentionFactor: algorithm이 Indexed로 설정된 경우 필요합니다. 이 필드에 대한 값의 빈도와 관련이 있습니다.

    • queryType: 현재 지원되는 유일한 쿼리 유형은 "equality"입니다. 알고리즘이 Indexed가 아닌 경우 queryType을 설정해야 합니다.

    예제 는 Queryable Encryption 알고리즘 설정을 참조하세요.

    지원되는 암호화 알고리즘에 대한 자세한 내용은 알고리즘 선택을 참조하세요.

행동

mongosh 클라이언트 사이드 필드 수준 및 Queryable Encryption 메서드를 사용하려면 클라이언트 사이드 암호화를 위해 구성된 데이터베이스 연결이 필요합니다. 클라이언트 사이드 필드 수준 암호화가 활성화된 상태에서 현재 데이터베이스 연결이 시작되지 않은 경우 다음 중 하나를 수행합니다.

또는

지원되지 않는 BSON type

encrypt() 를 사용하여 다음 BSON types 의 값을 암호화할 수 없습니다.

  • minKey

  • maxKey

  • null

  • undefined

AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic 를 사용하여 필드를 암호화하는 경우 encrypt() 는 다음 BSON types를 지원하지 않습니다 .

  • double

  • decimal128

  • bool

  • object

  • array

예제

Client-Side Field Level Encryption

다음 예에서는 클라이언트 사이드 필드 수준 암호화 구성을 위해 로컬로 managed KMS를 사용합니다.

1

암호화된 연결 만들기

1
mongosh 시작

mongosh 클라이언트를 시작합니다.

mongosh --nodb
2
키 생성

로컬로 managed 키에 대한 클라이언트 사이드 필드 수준 암호화를 구성하려면 줄바꿈 없이 base64로 인코딩된 96바이트 문자열을 생성합니다.

const TEST_LOCAL_KEY = require("crypto").randomBytes(96).toString("base64")
3
클라이언트 측 필드 레벨 암호화 옵션 생성

생성된 로컬 키 문자열을 사용하여 클라이언트 사이드 필드 수준 암호화 옵션을 생성합니다.

 var autoEncryptionOpts = {
   "keyVaultNamespace" : "encryption.__dataKeys",
   "kmsProviders" : {
     "local" : {
       "key" : BinData(0, TEST_LOCAL_KEY)
     }
   }
 }
4
암호화된 클라이언트 만들기

Mongo() 생성자를 클라이언트 사이드 필드 수준 암호화 옵션과 함께 사용하여 데이터베이스 연결을 생성합니다. mongodb://myMongo.example.net URI를 대상 cluster의 연결 문자열 URI 로 바꿉니다.

encryptedClient = Mongo(
  "mongodb://myMongo.example.net:27017/?replSetName=myMongo",
   autoEncryptionOpts
)
2

데이터 암호화

ClientEncryption 객체를 검색하고 ClientEncryption.encrypt() 메서드를 사용하여 특정 데이터 암호화 키 UUID 및 암호화 알고리즘을 사용하여 값을 암호화합니다.

clientEncryption = encryptedClient.getClientEncryption();
clientEncryption.encrypt(
  UUID("64e2d87d-f168-493c-bbdf-a394535a2cb9"),
  "123-45-6789",
  "AEAD_AES_256_CBC_HMAC_SHA_512-Random"
)

algorithm 필드가 있는 문서를 사용하여 알고리즘을 지정할 수도 있습니다.

clientEncryption = encryptedClient.getClientEncryption();
clientEncryption.encrypt(
  UUID("64e2d87d-f168-493c-bbdf-a394535a2cb9"),
  "123-45-6789",
  { algorithm: "AEAD_AES_256_CBC_HMAC_SHA_512-Random" }
)

결과 예시

성공하면 encrypt() 는 암호화된 값을 반환합니다.

BinData(6,"AmTi2H3xaEk8u9+jlFNaLLkC3Q/+kmwDbbWrq+h9nuv9W+u7A5a0UnpULBNZH+Q21fAztPpU09wpKPrju9dKfpN1Afpj1/ZhFcH6LYZOWSBBOAuUNjPLxMNSYOOuITuuYWo=")

클라이언트 사이드 필드 레벨 암호화가 활성화된 상태에서 MongoDB 연결을 시작하는 방법에 대한 전체 설명서는 Mongo() 를 참조하세요.

Queryable Encryption

다음 예에서는 Queryable Encryption 구성을 위해 로컬로 관리되는 KMS를 사용합니다.

1

암호화된 연결 만들기

1
mongosh 시작

mongosh 클라이언트를 시작합니다.

mongosh --nodb
2
키 생성

로컬로 관리되는 키에 대해 Queryable Encryption 을 구성하려면 줄 바꿈 없이 기본64인코딩된 96바이트 string 을 생성합니다.

const TEST_LOCAL_KEY = require("crypto").randomBytes(96).toString("base64")
3
Queryable Encryption 옵션 생성

생성된 로컬 키 문자열을 사용하여 Queryable Encryption 옵션을 생성합니다.

 var autoEncryptionOpts = {
   "keyVaultNamespace" : "encryption.__dataKeys",
   "kmsProviders" : {
     "local" : {
       "key" : BinData(0, TEST_LOCAL_KEY)
     }
   }
 }
4
암호화된 클라이언트 만들기

Queryable Encryption옵션이 구성된 Mongo() 생성자를 사용하여 데이터베이스 연결을 생성합니다. mongodb://myMongo.example.net URI를 대상 클러스터의 연결 문자열 URI로 바꿉니다.

encryptedClient = Mongo(
  "mongodb://myMongo.example.net:27017/?replSetName=myMongo",
   autoEncryptionOpts
)
2

데이터 암호화

ClientEncryption 객체를 검색하고 ClientEncryption.encrypt() 메서드를 사용하여 특정 데이터 암호화 키 UUID 및 암호화 알고리즘을 사용하여 값을 암호화합니다.

const eDB = "encrypted"
const eKV = "__keyVault"
const clientEncryption = encryptedClient.getClientEncryption();
const keyVaultClient = Mongo().getDB(eDB).getCollection(eKV)
const dek = keyVaultClient.findOne({ keyAltNames: "dataKey1" })
clientEncryption.encrypt(
  dek._id,
  "123-45-6789",
  "Unindexed"
)

필드가 포함된 문서를 사용하여 알고리즘을 지정할 수도 있습니다.

  • algorithm

  • queryType

  • contentionFactor

const eDB = "encrypted"
const eKV = "__keyVault"
const clientEncryption = encryptedClient.getClientEncryption();
const keyVaultClient = Mongo().getDB(eDB).getCollection(eKV)
const dek = keyVaultClient.findOne({ keyAltNames: "dataKey1" })
clientEncryption.encrypt(
  dek._id,
  "123-45-6789",
  {
    algorithm: "Indexed",
    queryType: "equality",
    contentionFactor: 4
  }
)

결과 예시

성공하면 encrypt() 는 암호화된 값을 반환합니다.

Binary(Buffer.from("05b100000005640020000000005ab3581a43e39a8e855b1ac87013e841735c09d19ae86535eea718dd56122ba50573002000000000703d2cba9832d90436c6c92eb232aa5b968cdcd7a3138570bc87ef0a9eb3a0e905630020000000009cb61df010b1bb54670a5ad979f25f4c48889059dfd8920782cf03dd27d1a50b05650020000000003f5acea703ea357d3eea4c6a5b19139a580089341424a247839fd4d5cf0d312a12636d00040000000000000000", "hex"), 6)

자세히 알아보기

클라이언트 사이드 필드 레벨 암호화가 활성화된 상태에서 MongoDB 연결을 시작하는 방법에 대한 전체 설명서는 Mongo() 를 참조하세요.

돌아가기

ClientEncryption.createEncryptedCollection

다음

ClientEncryption.decrypt

이 페이지의 내용