문서 메뉴

문서 홈 → 애플리케이션 개발 → MongoDB 매뉴얼

KeyVault.createKey()

이 페이지의 내용

  • 행동
  • 예제

버전 4.2에 추가되었습니다.

KeyVault.createKey(keyManagementService, customerMasterKey, ["keyAltName"])

데이터베이스 연결과 연결된 주요 키 모음에 데이터 암호화 키를 추가합니다. 클라이언트 측 필드 레벨 암호화 는 데이터 암호화 키를 사용하여 필드 값의 암호화 및 암호 해독을 지원합니다.

createKey() 의 구문은 다음과 같습니다:

keyVault = db.getMongo().getKeyVault()
keyVault.createKey(
  keyManagementService,
  customerMasterKey,
  [ "keyAltName" ]
)
매개변수
유형
설명
keyManagementService
문자열

필수 사항

고객 마스터 키(CMK)를 검색하는 데 사용할 키 관리 서비스(KMS) 입니다. 다음 매개변수를 허용합니다:

  • aws Amazon Web Services KMS 용 . customerMasterKey 에 대한 고객 마스터 키(CMK) 문자열을 지정해야 합니다.

  • azure Azure Key Vault 의 경우 . customerMasterKey 에 대한 고객 마스터 키(CMK) 문서를 지정해야 합니다.

    버전 5.0에 추가.

  • gcp Google Cloud Platform KMS 용 . customerMasterKey 에 대한 고객 마스터 키(CMK) 문서를 지정해야 합니다.

    버전 5.0에 추가.

  • local 로컬 managed 키의 경우.

지정된 KMS로 database connection 이(가) 구성되지 않은 경우 데이터 암호화 키 생성이 실패합니다.

customerMasterKey
문자열 또는 문서

데이터 암호화 키를 암호화하는 데 사용할 고객 마스터 키(CMK)입니다. keyManagementService 이 aws, azure 또는 gcp 인 경우 필수 사항입니다.

KMS 제공자에 따라 다음과 같이 고객 마스터 키를 제공합니다.

createKey() 은(는) KMS에 지정된 CMK를 사용하여 데이터 암호화 키 자료를 암호화하도록 요청합니다. CMK가 존재하지 않거나 AutoEncryptionOpts 구성에 CMK를 사용할 수 있는 충분한 권한이 없는 경우 createKey() 에서 오류를 반환합니다.

버전 4.2.3에서 변경됨: 이 매개변수는 keyManagementService 가 local 인 경우에는 효과가 없으며 생략해도 됩니다. MongoDB 4.2.3 이전 버전에서는 keyManagementService 가 local 인 경우 이 매개 변수는 빈 문자열 " 이어야 합니다 .

keyAltName
문자열 배열

옵션

데이터 암호화 키의 대체 이름입니다. keyAltName 을(를) 사용하여 특정 데이터 암호화 키의 찾기를 개선하거나 댓글과 유사한 기능을 수행합니다.

메서드는 가 존재하는 문서에 대해서만 부분 인덱스 필터를 사용하여 필드에 고유 getKeyVault() 인덱스 를 자동으로 생성합니다.keyAltNames keyAltNames

options
문서

옵션

새 키에 대한 옵션을 지정하는 문서입니다. options 에는 다음과 같은 필드가 있습니다.

  • masterKey: 데이터를 암호화하기 위한 새 마스터 키입니다.

  • keyAltNames: 마스터 키당 하나씩 대체 이름의 배열입니다.

  • keyMaterial: 키를 생성하는 데 사용되는 빈데이터입니다.

반환합니다:생성된 데이터 암호화 키의 UUID 고유 식별자입니다.

행동

데이터베이스 연결 시 클라이언트 측 필드 레벨 암호화 구성 필요

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

예제

다음 예제는 클라이언트 사이드 필드 수준 암호화를 빠르게 평가하기 위한 것입니다. 지원되는 KeyVault.createKey() 각 KMS 제공자와 함께 를 사용하는 구체적인 예 는 데이터 키 생성을 참조하세요.

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
)

keyVault 객체를 검색하고 KeyVault.createKey() 메서드를 사용하여 로컬로 관리되는 키를 사용하여 새 데이터 암호화 키를 생성합니다.

keyVault = encryptedClient.getKeyVault()
keyVault.createKey("local", ["data-encryption-key"])

성공하면 createKey() 는 새 데이터 암호화 키의 UUID 를 반환합니다. 키 볼트에서 새 데이터 암호화 키 문서를 검색하려면 다음 중 하나를 수행합니다.

  • getKey() 을(를) 사용하여 UUID 에서 생성한 키를 조회합니다.

    -또는-

  • 대체 이름으로 키를 조회하려면 getKeyByAltName() 를 사용합니다.

← getKeyVault()
KeyVault.deleteKey() →

이 페이지의 내용