Docs Menu
Docs Home
/
MongoDB 매뉴얼
/ / / / /

CSFLE 암호화 스키마

이 페이지의 내용

  • 개요
  • 정의
  • 예시
  • 암호화 스키마 - 여러 필드
  • 암호화 스키마 - 상속이 있는 여러 필드
  • 암호화 스키마 - 패턴 속성을 사용하여 암호화

참고

엔터프라이즈 기능

필드 레벨 암호화의 자동 기능은 MongoDB Enterprise 4.2 이상 및 MongoDB Atlas 4.2 이상 cluster에서만 사용할 수 있습니다.

암호화 스키마에는 암호화해야 하는 필드와 해당 필드를 암호화하는 방법을 식별하는 사용자 지정 규칙이 포함되어 있습니다. JSON schema 4 애플리케이션은 초안 표준 구문 의 엄격한 하위 집합을 사용하여 자동 암호화 규칙을 지정해야 합니다. 및 다음과 같은 암호화별 키워드를 포함합니다.

  • 암호화 는 현재 필드 를 암호화할 때 사용할 암호화 옵션을 지정합니다.

  • 메타데이터 암호화는 상속 가능한 암호화 옵션을 지정합니다.

MongoDB shell 의 경우 Mongo() 생성자를 사용하여 클라이언트 사이드 필드 레벨 암호화 구성 객체 의 일부로 포함된 자동 암호화 규칙으로 데이터베이스 연결을 만듭니다. 예제 는 자동 클라이언트 측 암호화를 활성화하여 클러스터에 연결을 참조하세요.

공식 MongoDB 드라이버의 경우 드라이버별 데이터베이스 연결 생성자(MongoClient)를 사용하여 클라이언트 사이드 필드 레벨 암호화 구성 객체 의 일부로 포함된 자동 암호화 규칙으로 데이터베이스 연결을 만듭니다. CSFLE 관련 MongoClient 옵션에 학습 보려면 mongo 클라이언트 페이지를 참조하세요.

중요

암호화 스키마에 문서 유효성 검사 키워드를 지정하지 마세요

자동 암호화 규칙에 문서 유효성 검사 키워드를 지정하지 마세요 . 문서 유효성 검사 규칙을 정의하려면 스키마 유효성 검사를 구성합니다.

encrypt

객체

"bsonType" : "object",
"properties" : {
"<fieldName>" : {
"encrypt" : {
"algorithm" : "<string>",
"bsonType" : "<string>" | [ "<string>" ],
"keyId" : [ <UUID> ]
}
}
}

<fieldName> 을(를) 암호화해야 함을 나타냅니다. encrypt 객체에는 다음과 같은 요구 사항이 있습니다.

  • encrypt <fieldName> 객체에 형제 필드를 가질 수 없습니다. encrypt 은(는) <fieldName> 객체의 유일한 하위 객체여야 합니다.

  • encrypt items 또는 additionalItems 키워드의 하위 스키마 내에서 지정할 수 없습니다. 특히 자동 클라이언트 측 필드 레벨 암호화는 배열의 개별 요소 암호화를 지원하지 않습니다.

encrypt 객체에는 다음 필드 포함될 수 있습니다.

encrypt 객체에 다른 필드를 포함하면 자동으로 암호화된 읽기 또는 쓰기 작업을 실행할 때 오류가 발생합니다.

keyId 또는 algorithm 이(가) 생략되면 공유 라이브러리 는 모든 상위 필드를 확인하고 옵션을 지정하는 가장 가까운 encryptMetadata 객체에서 해당 옵션을 구성하려고 시도합니다. algorithm bsonType 상속될 수 없으며 의 값에 따라 필요할 수 있습니다.

공유 라이브러리가 객체에 지정된 필드와 필수 encryptMetadata상속 키를 사용하여 전체 encrypt 객체를 구성할 수 없는 경우 자동 암호화가 실패하고 오류를 반환합니다.

encrypt.algorithm

문자열

<fieldName> 의 값을 암호화할 때 사용할 암호화 알고리즘을 나타냅니다. 다음 알고리즘 지원합니다.

  • AEAD_AES_256_CBC_HMAC_SHA_512-Random

  • AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic

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

생략하면 공유 라이브러리 는 모든 상위 필드에서 encryptMetadata.algorithm 키를 포함하는 가장 가까운 조상을 확인하고 해당 값을 상속합니다. 상위 algorithm 이(가) 없으면 자동 필드 수준 암호화 가 실패하고 오류를 반환합니다.

  • encrypt.algorithm 또는 상속된 값이 AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic 인 경우 encrypt 객체에는 encrypt.bsonType 필드가 필요합니다.

  • 또는 encrypt.algorithm 상속된 값이 AEAD_AES_256_CBC_HMAC_SHA_512-Randomencrypt 경우 encrypt.bsonType 객체 에는 필드 가 포함될 수 있습니다.

encrypt.bsonType

문자열 | 문자열 배열

암호화됨 되는 필드 의 BSON 입니다. encrypt.algorithmAEAD_AES_256_CBC_HMAC_SHA_512-Deterministic 인 경우 필수 사항입니다.

encrypt.algorithm 또는 상속된 값이 AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic 인 경우 bsonType(은)는 단일 유형을 지정 해야 합니다 . bsonType(은)는 결정론적 암호화 알고리즘을 사용하여 다음 BSON types을 지원하지 않습니다 .

  • double

  • decimal128

  • bool

  • object

  • array

encrypt.algorithm 또는 상속된 값이 AED_AES_256_CBC_HMAC_SHA_512-Random인 경우, bsonType은 선택 사항이며, 지원되는 BSON 유형의 배열을 지정할 수 있습니다. bsonType 또는 array 또는 object 필드의 경우 클라이언트는 개별 요소가 아닌 전체 배열 또는 객체를 암호화합니다.

encrypt.bsonType 또는 상속된 값에 encrypt.algorithm 관계없이 다음 유형을 지원하지 않습니다 .

  • minKey

  • maxKey

  • null

  • undefined

encrypt.keyId

단일 UUID 배열

필드 값을 암호화하는 데 사용할 데이터 암호화 키 의 UUID입니다. UUID는 BSON 바이너리 데이터 4입니다. 하위 유형 의 요소입니다.

배열 내부에 하나 의 문자열을 지정합니다.

생략하면 공유 라이브러리 는 모든 상위 필드에서 encryptMetadata.keyId 키를 포함하는 가장 가까운 조상을 확인하고 해당 값을 상속합니다. 상위 keyId 이(가) 없으면 자동 필드 수준 암호화 가 실패하고 오류를 반환합니다.

또는 keyId 상속된 값이 자동 암호화 구성 옵션 의 일부로 지정된 키 볼트 컬렉션에 있어야 합니다. 지정된 데이터 암호화 키가 존재하지 않으면 자동 암호화가 실패합니다.

공식 MongoDB 드라이버에는 언어별로 UUID 지정 요구 사항이 있습니다. 클라이언트 사이드 필드 레벨 암호화 구현에 대한 전체 설명서는 드라이버 설명서를 따르세요.

encryptMetadata

객체

{
"bsonType" : "object",
"encryptMetadata" : {
"algorithm" : "<string>",
"keyId" : [ <UUID> ]
},
"properties" : {
"encrypt" : {}
}
}

형제 properties 에 중첩된 encrypt 객체가 상속할 수 있는 암호화 옵션을 정의합니다. encrypt 에 암호화를 지원하는 데 필요한 옵션이 누락된 경우 공유 라이브러리는 모든 상위 객체를 검색하여 누락된 옵션을 지정하는 encryptMetadata 객체를 찾습니다.

encryptMetadatabsonType: "object" 을 사용하여 하위 스키마로 지정되어야 합니다. encryptMetadata 또는 키워드의 하위 스키마에 items additionalItems 을(를) 지정할 수 없습니다. 특히 자동 클라이언트 측 필드 레벨 암호화는 배열의 개별 요소 암호화를 지원하지 않습니다.

encryptMetadata 객체에는 다음 필드 포함될 수 있습니다. encrypt 객체에 다른 필드를 포함하면 자동으로 암호화된 읽기 또는 쓰기 작업을 실행할 때 오류가 발생합니다.

encryptMetadata.algorithm

문자열

지정된 필드를 암호화하는 데 사용할 암호화 알고리즘입니다. encrypt 객체에 algorithm 필드가 누락된 경우 공유 라이브러리는 모든 상위 객체를 검색하여encryptMetadata.algorithm를 지정하는 encryptMetadata 객체를 찾습니다

다음 알고리즘 지원합니다.

  • AEAD_AES_256_CBC_HMAC_SHA_512-Random

  • AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic

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

을 지정하는 경우 해당 AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic encrypt 값을 상속하는 모든 객체 는 를 지정 해야 encrypt.bsonType 합니다 .

encryptMetadata.keyId

단일 UUID 배열

데이터 암호화 키 의 UUID입니다. UUID는 BSON 바이너리 데이터 4입니다. 하위 유형 의 요소입니다.

배열 내부에 하나 의 문자열을 지정합니다.

encrypt 객체에 keyId 필드가 누락된 경우 공유 라이브러리는 모든 상위 객체를 검색하여encryptMetadata.keyId를 지정하는 encryptMetadata 객체를 찾습니다

데이터 암호화 키는 자동 암호화 구성 옵션 의 일부로 지정된 키 볼트 컬렉션에 있어야 합니다. 지정된 구성 옵션에는 데이터 키를 생성하는 데 사용된 키 관리 서비스(KMS) 및 고객 마스터 키(CMK)에 대한 적절한 액세스 권한 도 포함되어야 합니다. 데이터 암호화 키가 없거나 클라이언트가 지정된 KMS 및 CMK로 키를 해독할 수 없는 경우 자동 암호화가 실패합니다.

공식 MongoDB 드라이버에는 언어별로 UUID 지정 요구 사항이 있습니다. 클라이언트 사이드 필드 레벨 암호화 구현에 대한 전체 설명서는 드라이버 설명서를 따르세요.

각 문서가 다음과 같은 구조를 가진 collection MedCo.patients 을 가정해 보겠습니다.

{
"fname" : "<String>",
"lname" : "<String>",
"passportId" : "<String>",
"bloodType" : "<String>",
"medicalRecords" : [
{<object>}
],
"insurance" : {
"policyNumber" : "<string>",
"provider" : "<string>"
}
}

다음 필드에는 쿼리될 수 있는 개인 식별 정보(PII)가 포함되어 있습니다.

  • passportId

  • bloodType

  • insurance.policyNumber

  • insurance.provider

결정론적 암호화 알고리즘은 값의 암호화된 출력이 정적으로 유지되도록 보장합니다. 이를 통해 특정 값에 대한 쿼리로 의미 있는 결과를 반환할 수 있지만 빈도 분석 복구에 대한 취약성이 높아집니다. 따라서 결정론적 암호화 알고리즘은 데이터의 암호화 및 쿼리 가능성 요구 사항을 모두 충족합니다.

다음 필드에는 절대 쿼리할 수 없는 법적으로 보호되는 개인 식별 정보(PII)가 포함되어 있습니다.

  • medicalRecords

무작위 암호화 알고리즘은 값의 암호화된 출력이 항상 고유하도록 보장합니다. 이렇게 하면 특정 필드 값에 대한 쿼리가 의미 있는 결과를 반환하는 것을 방지하면서 필드 콘텐츠를 최대한 보호할 수 있습니다. 따라서 무작위 암호화 알고리즘은 데이터의 암호화 및 쿼리 가능성 요구 사항을 모두 충족합니다.

다음 스키마는 MedCo.patients collection에 대한 위의 요구 사항을 충족하는 자동 암호화 규칙을 지정합니다.

{
"MedCo.patients" : {
"bsonType" : "object",
"properties" : {
"passportId" : {
"encrypt" : {
"keyId" : [UUID("bffb361b-30d3-42c0-b7a4-d24a272b72e3")],
"algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
"bsonType" : "string"
}
},
"bloodType" : {
"encrypt" : {
"keyId" : [UUID("bffb361b-30d3-42c0-b7a4-d24a272b72e3")],
"algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
"bsonType" : "string"
}
},
"medicalRecords" : {
"encrypt" : {
"keyId" : [UUID("f3821212-e697-4d65-b740-4a6791697c6d")],
"algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Random",
"bsonType" : "array"
}
},
"insurance" : {
"bsonType" : "object",
"properties" : {
"policyNumber" : {
"encrypt" : {
"keyId" : [UUID("bffb361b-30d3-42c0-b7a4-d24a272b72e3")],
"algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
"bsonType" : "string"
}
},
"provider" : {
"encrypt" : {
"keyId" : [UUID("bffb361b-30d3-42c0-b7a4-d24a272b72e3")],
"algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
"bsonType" : "string"
}
}
}
}
}
}
}

위의 자동 암호화 규칙은 passportId, bloodType, insurance.policyNumber, insurance.providermedicalRecords 필드를 암호화하도록 표시합니다.

  • passportId, bloodType, insurance.policyNumberprovider 필드에는 지정된 키를 사용한 결정론적 암호화가 필요합니다.

  • medicalRecords 필드에는 지정된 키를 사용하여 무작위 암호화해야 합니다.

클라이언트 측 필드 레벨 암호화 는 개별 배열 요소 암호화를 지원 하지 않지만 무작위 암호화 는 필드 의 개별 요소가 아닌 전체 배열 필드 암호화를 지원합니다. 자동 암호화 규칙 예시 에서는 medicalRecords 필드 에 무작위 암호화 를 지정하여 전체 배열 을 암호화합니다. 자동 암호화 규칙이 encrypt 또는 encryptMetadata 내에{medicalRecords.items 또는 를 지정한 경우 medicalRecords.additionalItems 자동 필드 수준 암호화 가 실패하고 오류를 반환합니다.

공식 MongoDB 4.2 이상의 호환 드라이버, mongosh 및 4.2 이상 레거시 mongo 셸에서는 데이터베이스 연결 객체를 생성할 때 자동 암호화 규칙을 지정해야 합니다.

  • mongosh 의 경우 Mongo() 생성자를 사용하여 데이터베이스 연결을 만듭니다. AutoEncryptionOpts 매개변수의 schemaMap 키에 자동 암호화 규칙을 지정합니다. See Connect to a Cluster with Automatic Client-Side Encryption Enabled for a complete example.

  • 공식 MongoDB 4.2+ 호환 드라이버의 경우 드라이버별 데이터베이스 연결 생성자( MongoClient )를 사용하여 클라이언트 사이드 필드 레벨 암호화 구성 객체의 일부로 포함된 자동 암호화 규칙으로 데이터베이스 연결을 만듭니다. 자세한 내용은 드라이버 API 참조 문서를 참조하세요.

모든 클라이언트의 경우, 클라이언트 측 필드 레벨 암호화 매개변수에 지정된 keyVaultkmsProviders 는 자동 암호화 규칙에 지정된 데이터 암호화 키 데이터 암호화 키를 암호화하는 데 사용되는 고객 마스터 키 모두에 대한 액세스 권한을 부여 해야 합니다 .

각 문서가 다음과 같은 구조를 가진 collection MedCo.patients 을 가정해 보겠습니다.

{
"fname" : "<String>",
"lname" : "<String>",
"passportId" : "<String>",
"bloodType" : "<String>",
"medicalRecords" : [
{<object>}
],
"insurance" : {
"policyNumber" : "<string>",
"provider" : "<string>"
}
}

다음 필드에는 쿼리될 수 있는 비공개 데이터가 포함되어 있습니다.

  • passportId

  • bloodType

  • insurance.policyNumber

  • insurance.provider

결정론적 암호화 알고리즘은 값의 암호화된 출력이 정적으로 유지되도록 보장합니다. 이를 통해 특정 값에 대한 쿼리로 의미 있는 결과를 반환할 수 있지만 빈도 분석 복구에 대한 취약성이 높아집니다. 따라서 결정론적 암호화 알고리즘은 데이터의 암호화 및 쿼리 가능성 요구 사항을 모두 충족합니다.

다음 필드에는 절대 쿼리할 수 없는 비공개 데이터가 포함되어 있습니다.

  • medicalRecords

무작위 암호화 알고리즘은 값의 암호화된 출력이 항상 고유하도록 보장합니다. 이렇게 하면 특정 필드 값에 대한 쿼리가 의미 있는 결과를 반환하는 것을 방지하면서 필드 콘텐츠를 최대한 보호할 수 있습니다. 따라서 무작위 암호화 알고리즘은 데이터의 암호화 및 쿼리 가능성 요구 사항을 모두 충족합니다.

다음 스키마는 MedCo.patients 컬렉션의 암호화 요구 사항을 충족하는 자동 암호화 규칙을 지정합니다.

{
"MedCo.patients" : {
"bsonType" : "object",
"encryptMetadata" : {
"keyId" : [UUID("6c512f5e-09bc-434f-b6db-c42eee30c6b1")],
"algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
},
"properties" : {
"passportId" : {
"encrypt" : {
"bsonType" : "string"
}
},
"bloodType" : {
"encrypt" : {
"bsonType" : "string"
}
},
"medicalRecords" : {
"encrypt" : {
"keyId" : [UUID("6c512f5e-09bc-434f-b6db-c42eee30c6b1")],
"algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Random",
"bsonType" : "array"
}
},
"insurance" : {
"bsonType" : "object",
"properties" : {
"policyNumber" : {
"encrypt" : {
"bsonType" : "string"
}
},
"provider" : {
"encrypt" : {
"bsonType" : "string"
}
}
}
}
}
}
}

위의 자동 암호화 규칙은 passportId, bloodType, insurance.policyNumber, insurance.providermedicalRecords 필드를 암호화하도록 표시합니다.

  • passportId, bloodType, insurance.policyNumberprovider 필드는 상위 encryptMetadata 필드에서 암호화 설정을 상속합니다. 특히 이러한 필드는 지정된 데이터 암호화 키를 사용하여 결정적 암호화를 지정하는 algorithmkeyId 값을 상속합니다.

  • medicalRecords 필드에는 지정된 키를 사용하여 무작위 암호화해야 합니다. encrypt 옵션은 상위 encryptMetadata 필드에 지정된 옵션을 재정의합니다.

클라이언트 측 필드 레벨 암호화 는 개별 배열 요소 암호화를 지원 하지 않지만 무작위 암호화 는 필드 의 개별 요소가 아닌 전체 배열 필드 암호화를 지원합니다. 자동 암호화 규칙 예시 에서는 medicalRecords 필드 에 무작위 암호화 를 지정하여 전체 배열 을 암호화합니다. 자동 암호화 규칙이 encrypt 또는 encryptMetadata 내에{medicalRecords.items 또는 를 지정한 경우 medicalRecords.additionalItems 자동 필드 수준 암호화 가 실패하고 오류를 반환합니다.

공식 MongoDB 4.2 이상의 호환 드라이버, mongosh 및 4.2 이상 레거시 mongo 셸에서는 데이터베이스 연결 객체를 생성할 때 자동 암호화 규칙을 지정해야 합니다.

  • mongosh 의 경우 Mongo() 생성자를 사용하여 데이터베이스 연결을 만듭니다. AutoEncryptionOpts 매개변수의 schemaMap 키에 자동 암호화 규칙을 지정합니다. See Connect to a Cluster with Automatic Client-Side Encryption Enabled for a complete example.

  • 공식 MongoDB 4.2+ 호환 드라이버의 경우 드라이버별 데이터베이스 연결 생성자( MongoClient )를 사용하여 클라이언트 사이드 필드 레벨 암호화 구성 객체의 일부로 포함된 자동 암호화 규칙으로 데이터베이스 연결을 만듭니다. 자세한 내용은 드라이버 API 참조 문서를 참조하세요.

모든 클라이언트의 경우, 클라이언트 측 필드 레벨 암호화 매개변수에 지정된 keyVaultkmsProviders 는 자동 암호화 규칙에 지정된 데이터 암호화 키 데이터 암호화 키를 암호화하는 데 사용되는 고객 마스터 키 모두에 대한 액세스 권한을 부여 해야 합니다 .

고객 마스터 키 및 키 볼트 컬렉션에 대해 자세히 알아보려면 키 볼트 페이지를 참조하세요.

암호화 알고리즘에 대해 자세히 알아보려면 암호화 알고리즘 페이지를 참조하세요.

CSFLE 관련 MongoClient 옵션에 대해 자세히 알아보려면 mongo 클라이언트 페이지를 참조하세요.

암호화 스키마에서 patternProperties 키워드를 사용하여 정규 표현식과 일치하는 이름을 가진 모든 필드에 대한 암호화 규칙을 정의할 수 있습니다.

각 문서가 다음과 같은 구조를 가진 collection MedCo.patients 을 가정해 보겠습니다.

{
"fname" : "<string>",
"lname" : "<string>",
"passportId_PIIString" : "<string>",
"bloodType_PIIString" : "<string>",
"medicalRecords_PIIArray" : [
{<object>}
],
"insurance" : {
"policyNumber_PIINumber" : "<number>",
"provider_PIIString" : "<string>"
}
}

비공개 데이터가 포함된 필드는 필드 이름 끝에 "_PII<type>" 태그가 추가되어 식별됩니다.

  • passportId_PIIString

  • bloodType_PIIString

  • medicalRecords_PIIArray

  • insurance.policyNumber_PIINumber

  • insurance.provider_PIIString

patternProperties 키워드를 사용하면 각 필드를 개별적으로 식별하거나 전체 필드 이름을 사용하지 않고도 이러한 필드를 암호화하도록 구성할 수 있습니다. "_PII<type>" 태그로 끝나는 모든 필드와 일치하는 정규 표현식을 사용하여 이 작업을 수행합니다.

다음 JSON schema는 patternProperties 및 정규 표현식을 사용하여 암호화할 필드를 지정합니다.

{
"MedCo.patients": {
"bsonType": "object",
"patternProperties": {
"_PIIString$": {
"encrypt": {
"keyId": [UUID("6c512f5e-09bc-434f-b6db-c42eee30c6b1")],
"bsonType": "string",
"algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
},
},
"_PIIArray$": {
"encrypt": {
"keyId": [UUID("6c512f5e-09bc-434f-b6db-c42eee30c6b1")],
"bsonType": "array",
"algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Random",
},
},
"insurance": {
"bsonType": "object",
"patternProperties": {
"_PIINumber$": {
"encrypt": {
"keyId": [UUID("6c512f5e-09bc-434f-b6db-c42eee30c6b1")],
"bsonType": "int",
"algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
},
},
"_PIIString$": {
"encrypt": {
"keyId": [UUID("6c512f5e-09bc-434f-b6db-c42eee30c6b1")],
"bsonType": "string",
"algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
},
},
},
},
},
},
}

위의 자동 암호화 규칙은 passportId_PIIString, bloodType_PIIString, medicalRecords_PIIArray, insurance.policyNumber_PIINumber, insurance.provider_PIIString 필드를 암호화를 위해 표시합니다.

patternProperties 키워드에 대해 자세히 알아보려면 patternProperties 키워드를 참조하세요.

돌아가기

CSFLE 제한