# 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는 이 중 아무것도 인증하지 못한다. 아무것도 거부하지 않기 때문이다.