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
객체에서 해당 옵션을 구성하려고 시도합니다.bsonType
은 상속될 수 없으며algorithm
값에 따라 필요할 수도 있습니다.자동 암호화 공유 라이브러리가 객체에 지정된 필드와 필수
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-Random
인encrypt
경우encrypt.bsonType
객체 에는 필드 가 포함될 수 있습니다.
encrypt.bsonType
문자열 | 문자열 배열
암호화됨 되는 필드 의 BSON 입니다.
encrypt.algorithm
가AEAD_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
객체를 찾습니다.encryptMetadata
는bsonType: "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.provider
및 medicalRecords
필드를 암호화하도록 표시합니다.
passportId
,bloodType
,insurance.policyNumber
및provider
필드에는 지정된 키를 사용한 결정론적 암호화가 필요합니다.medicalRecords
필드에는 지정된 키를 사용하여 무작위 암호화해야 합니다.
Queryable Encryption은 개별 배열 요소 암호화를 지원하지 않지만 무작위 암호화는 필드의 개별 요소가 아닌 전체 배열 필드 암호화를 지원합니다. 자동 암호화 규칙 예제에서는 medicalRecords
필드에 무작위 암호화를 지정하여 전체 배열을 암호화합니다. 자동 암호화 규칙이 encrypt
또는 encryptMetadata
내에{medicalRecords.items
또는 를 지정한 경우 medicalRecords.additionalItems
자동 필드 수준 암호화가 실패하고 오류를 반환합니다.
공식 MongoDB 드라이버 mongosh
및 레거시 mongo
shell 에서는 데이터베이스 연결 객체를 생성할 때 자동 암호화 규칙을 지정해야 합니다.
mongosh
의 경우Mongo()
생성자를 사용하여 데이터베이스 연결을 만듭니다.AutoEncryptionOpts
매개변수의schemaMap
키에 자동 암호화 규칙을 지정합니다. See Connect to a Cluster with Automatic Client-Side Encryption Enabled for a complete example.공식 MongoDB 드라이버의 경우 드라이버별 데이터베이스 연결 생성자(
MongoClient
)를 사용하여 Queryable Encryption 구성 객체 의 일부로 포함된 자동 암호화 규칙으로 데이터베이스 연결을 생성합니다. 자세한 내용은 운전자 API 참조 를 참조하여 자세한 설명서와 튜토리얼을 확인하세요.
모든 클라이언트의 경우, Queryable Encryption 매개변수에 지정된 keyVault
및 kmsProviders
는 자동 암호화 규칙에 지정된 데이터 암호화 키 와 데이터 암호화 키를 암호화하는 데 사용되는 고객 마스터 키 모두에 대한 액세스 권한을 부여 해야 합니다 .
암호화 스키마 - 상속이 있는 여러 필드
각 문서가 다음과 같은 구조를 가진 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.provider
및 medicalRecords
필드를 암호화하도록 표시합니다.
passportId
,bloodType
,insurance.policyNumber
및provider
필드는 상위encryptMetadata
필드에서 암호화 설정을 상속합니다. 특히 이러한 필드는 지정된 데이터 암호화 키를 사용하여 결정적 암호화를 지정하는algorithm
및keyId
값을 상속합니다.medicalRecords
필드에는 지정된 키를 사용하여 무작위 암호화해야 합니다.encrypt
옵션은 상위encryptMetadata
필드에 지정된 옵션을 재정의합니다.
Queryable Encryption은 개별 배열 요소 암호화를 지원하지 않지만 무작위 암호화는 필드의 개별 요소가 아닌 전체 배열 필드 암호화를 지원합니다. 자동 암호화 규칙 예제에서는 medicalRecords
필드에 무작위 암호화를 지정하여 전체 배열을 암호화합니다. 자동 암호화 규칙이 encrypt
또는 encryptMetadata
내에{medicalRecords.items
또는 를 지정한 경우 medicalRecords.additionalItems
자동 필드 수준 암호화가 실패하고 오류를 반환합니다.
공식 MongoDB 드라이버 mongosh
및 레거시 mongo
shell 에서는 데이터베이스 연결 객체를 생성할 때 자동 암호화 규칙을 지정해야 합니다.
mongosh
의 경우Mongo()
생성자를 사용하여 데이터베이스 연결을 만듭니다.AutoEncryptionOpts
매개변수의schemaMap
키에 자동 암호화 규칙을 지정합니다. See Connect to a Cluster with Automatic Client-Side Encryption Enabled for a complete example.공식 MongoDB 드라이버의 경우 드라이버별 데이터베이스 연결 생성자(
MongoClient
)를 사용하여 Queryable Encryption 구성 객체 의 일부로 포함된 자동 암호화 규칙으로 데이터베이스 연결을 생성합니다. 자세한 내용은 운전자 API 참조 를 참조하여 자세한 설명서와 튜토리얼을 확인하세요.
모든 클라이언트의 경우, Queryable Encryption 매개변수에 지정된 keyVault
및 kmsProviders
는 자동 암호화 규칙에 지정된 데이터 암호화 키 와 데이터 암호화 키를 암호화하는 데 사용되는 고객 마스터 키 모두에 대한 액세스 권한을 부여 해야 합니다 .
고객 마스터 키 및 키 볼트 컬렉션에 대해 자세히 알아보려면 키 볼트 페이지를 참조하세요.
암호화 알고리즘에 대해 자세히 알아보려면 암호화 알고리즘 페이지를 참조하세요.
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 키워드를 참조하세요.