문제: docs/mongodb 아래 살아 있는 문서 14개가 영어였고(문서 검사 language 예외), 몇 가지 주장이 지금 코드와 달랐다. - repository-adaptation.md가 registry의 leaf 수(19)와 Spring Boot 버전을 옮겨 적었다(number 예외 두 줄). - 같은 문서와 advanced/signoff/README.md가 scripts/verify-mongodb-platform.sh· verify-mongodb-advanced.sh를 2026-08-15에 지웠다고 했다. 두 스크립트는 지금도 있고 lane을 돌린다. - testkit을 `testkit` source set에 둔다고 했다. 지금은 `testFixtures`(ADR-BUILD-001)와 `mongoProviderTestkit`이다. `…mongo.architecture`도 main이 아니라 testFixtures에 있다. - ArchUnit 규칙 이름 `stableNeverDependsOnAdvanced`·`productionNeverDependsOnTestkit`은 없다. 실제는 MongoModuleBoundaryTest의 `noStablePackageDependsOnAnAdvancedCapability`· `noProductionPackageDependsOnTheTestkit`이다. - support-matrix.md의 Boot·Spring Data·driver·Micrometer·Testcontainers 버전이 lockfile과 달랐다(예: driver 5.6.1 → 5.6.5). - consumer-leaf-guide.md가 템플릿에 없는 Gradle 경로를 인라인 코드로 적었다 (reference 예외). - document-modeling-guide.md가 타입 metadata를 bson-mapping-guide §4로 가리켰다(§5). 고친 방법: 뜻을 그대로 옮기고 식별자·명령·경로·표 구조는 원문으로 둔다. 버전과 leaf 수는 숫자 대신 정본(src/gradle/libs.versions.toml, registry, gradle.lockfile, container-images.properties)을 가리킨다. 서비스가 만들 leaf의 확인 명령은 다른 단계와 같이 코드 블록에 두고 템플릿에 없는 경로라고 밝힌다. 버린 대안: support-matrix 버전을 lockfile 값으로 고쳐 적기. 다음 업그레이드에서 다시 틀리고, 같은 시간에 도는 의존성 세션과 같은 줄을 고치게 된다. 위험·한계: 내용 감사는 하지 않았다. 번역하며 본 불일치만 고쳤다. 설계 번호(§, D-xx)는 그대로 두었다. 검증: python3 scripts/check-docs.py rc=0(이 폴더 language·reference·number 예외 줄 0). docs/mongodb를 읽는 테스트는 주석뿐이다(`grep -rn 'docs/mongodb' src --include=*.java` — package-info.java·MongoModuleBoundaryTest 주석). scripts/verify-mongodb-advanced.sh는 advanced 문서의 파일 존재만 본다.
6.2 KiB
Advanced — CSFLE와 Queryable Encryption
Capability: MongoCapability.CSFLE, MongoCapability.QUERYABLE_ENCRYPTION
켜는 법: 라이브러리 API다. 설정 속성은 없다. 서비스의 어댑터가 진입점을 만들 때
MongoAdvancedCapabilityGuard를 넘긴다. 이 guard는 그 capability를 켠 MongoAdvancedCapabilityFlags로
만든다. 켜지 않았으면 생성 자체가 거부된다.
상태: Advanced.
요구 사항
| 토폴로지 | replica set 또는 sharded cluster. |
| 서버 | MongoDB 7.0 또는 8.0(8.0의 query type 제한은 4절). |
| 권한 | key vault에는 MongoPrincipalRole.ENCRYPTION_ADMIN이 필요하다. 애플리케이션 role은 이 권한을 갖지 않는다. |
| 환경 | 실제 KMS와 key vault. 로컬 key provider는 중요한 실패 모드를 하나도 재현하지 못한다. |
1. CSFLE
MongoCsfleProfile은 collection 하나(database + collection)를 세 가지에 묶는다:
MongoCsfleFieldPolicy 목록, key vault용 MongoCredentialReference, key vault namespace.
MongoCsfleClientFactory가 이 profile로 암호화 client 설정을 만든다.
$jsonSchema는 field policy에서 생성한다. 점으로 이은 경로는 중첩된properties가 된다.- schema의 키는 namespace
database.collection이다. - key vault client는 profile 자신의 credential로
MongoCredentialResolver를 거쳐 만든다.
자동 암호화 schema는 data key를 별칭이 아니라 id로 가리킨다. 그래서 도입하는 쪽이 각
MongoCsfleFieldPolicy.keyAlias()를 key vault에서 찾아(예: ClientEncryption.getKeyByAltName)
별칭 → key id 맵을 settingsFor에 넘긴다. id가 없는 별칭은 거부한다. deterministic 필드는 schema에서
string 타입이다.
MongoCsfleMode:
| 모드 | 조회 가능 | 득실 |
|---|---|---|
RANDOMIZED |
아니다 | 같은 평문도 매번 다르게 암호화된다. 안전한 기본값이다. |
DETERMINISTIC |
같음 비교만 | 같은 평문은 늘 같은 암호문이 된다. 그래서 같음 비교가 된다. 빈도 분석도 같이 된다. |
UNINDEXED |
아니다 | 암호화해 저장하고 어떤 index에도 넣지 않는다. |
MongoCsfleFieldPolicy.forPii(field, queryable)는 조회하지 않는 필드면 RANDOMIZED를 고른다.
deterministic 암호화에는 글로 쓴 equalityQueryJustification이 필요하다. 생성자는 빈 값을 거부하고
빈도 분석을 이유로 든다. 값의 가짓수가 적은 deterministic 필드(상태, 국가, boolean)는 collection을 읽을
수 있는 누구에게나 분포를 드러낸다. 그 누구가 바로 암호화가 막으려던 상대다.
2. Queryable Encryption
MongoQueryableEncryptionProfile은 collection 하나를 MongoEncryptedFieldDescriptor 항목들에 묶는다.
MongoQueryableEncryptionQueryType의 값은 둘뿐이다.
EQUALITYRANGE— 값의 범위(min,max)를 선언해야 한다. 생성자는 범위가 없는 range 필드를 거부한다. 범위를 나중에 바꾸면 그 필드를 다시 암호화해야 하기 때문이다.
MongoQueryableEncryptionCollectionManager가 collection의 생성부터 삭제까지를 맡는다. QE collection은
collection 하나로 끝나지 않고 metadata collection을 같이 달고 다니기 때문이다.
3. Metadata 소유
MongoEncryptionMetadataOwnership은 customers를 enxcol_.customers.esc와
enxcol_.customers.ecoc에 대응시킨다. 그리고 __safeContent__로 시작하는 index를
MongoMetadataOwnership.ENCRYPTION_MANAGED로 보고한다.
이것들은 애플리케이션 소유가 아니다. drift 정리(선언과 실제의 차이를 맞추는 작업)가 지울 수도 없다.
drift 도구가 enxcol_.customers.ecoc를 지우면 그 collection은 조회 능력을 잃는다. 암호화와
ADR-MONGO-004가 만나는 곳 중 가장 중요한 지점이다.
4. 지원하지 않는 조합
실행 중에 발견하지 않고 선언할 때 거부한다.
| 조합 | 이유 |
|---|---|
| 같은 collection에 CSFLE 와 QE | namespace 하나에 서로 맞지 않는 암호화 방식 둘이다. 두 profile 생성자가 모두 거부한다. |
| time series collection에 CSFLE | requireNotTimeSeries(true)가 MongoOperationRejectedException을 던진다. |
QE prefix / suffix / substring |
플랫폼의 8.0 기준에서 쓸 수 없다. factory 메서드가 나중에 실패할 profile을 돌려주지 않고 바로 UnsupportedOperationException을 던진다. |
| 근거 없는 deterministic CSFLE | 빈도 분석을 이유로 든 IllegalArgumentException. |
| 범위를 선언하지 않은 range QE | 재암호화를 이유로 든 IllegalArgumentException. |
5. 실패 복구
| 증상 | 원인 | 조치 |
|---|---|---|
읽을 때 MongoEncryptionException |
data key가 틀렸거나 key vault에 닿지 못한다 | KMS 연결과 key vault credential을 확인한다. 데이터는 그대로다. client가 복호화하지 못할 뿐이다. |
쓸 때 MongoEncryptionException |
작업 도중 KMS 권한이 회수됐다 | 권한을 되돌린다. 쓰기는 닫힌 쪽으로 실패한다. 평문으로 쓴 것은 없다. |
| deterministic 필드 조회가 아무것도 돌려주지 않는다 | 필드의 key를 바꿨다 | 같음 비교는 암호문끼리 한다. 새 key는 다른 암호문을 만든다. 필드를 다시 암호화한다. |
| drift 정리 뒤 QE 조회가 실패한다 | metadata collection이 지워졌다 | 백업에서 복구한다. 그래서 삭제를 소유 여부로 막는다. |
key 교체. customer master key를 바꾸면 data key를 다시 감쌀 뿐이고 문서를 다시 암호화하지 않는다. data key를 바꾸면 그 key를 쓴 문서를 모두 다시 암호화해야 한다. 둘은 비용이 다른 별개의 작업이다. 둘을 헷갈리면 key 교체가 장애가 된다.
6. 승격 증거
ADR-MONGO-ADV-001에 따라 승격하려면 실제 KMS와 key vault가 필요하다. 닫힌 쪽으로 실패하는 부정 사례도 필요하다: 틀린 key, 빠진 권한, 작업 도중 key 교체. 로컬 key provider는 이 중 아무것도 인증하지 못한다. 아무것도 거부하지 않기 때문이다.