Files
clean-architecture-backend-…/docs/mongodb/advanced/encryption.md
T
DongHyeonka 24eb1be36d docs(mongodb): MongoDB 운영 문서를 한국어로 옮기고 코드와 맞춘다
문제: 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 문서의 파일 존재만 본다.
2026-11-07 17:29:57 +09:00

98 lines
6.2 KiB
Markdown

# 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`의 값은 둘뿐이다.
- `EQUALITY`
- `RANGE` — 값의 범위(`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](../../adr/ADR-MONGO-004-index-schema-admin-plane.md)가 만나는 곳 중 가장 중요한 지점이다.
## 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](../../adr/ADR-MONGO-ADV-001-capability-promotion.md)에 따라 승격하려면 실제 KMS와
key vault가 필요하다. 닫힌 쪽으로 실패하는 부정 사례도 필요하다: 틀린 key, 빠진 권한, 작업 도중 key 교체.
로컬 key provider는 이 중 아무것도 인증하지 못한다. 아무것도 거부하지 않기 때문이다.