Field Crypto v1

fieldCrypto는 @k-msg/core, @k-msg/messaging, @k-msg/webhook에서 공통으로 사용하는 필드 단위 암호화 계층입니다.

이 문서가 답하는 질문: 운영자가 알아야 하는 fieldCrypto 기술 정책의 핵심은 무엇인가?

용어가 익숙하지 않다면 먼저 보안 용어집과 보안 레시피를 확인하세요.

지원 모드

• plain: 평문 저장 (기본 정책에서는 비권장)
• encrypt: 암호화 저장
• encrypt+hash: 암호화 저장 + 조회용 해시 생성
• mask: 마스킹 저장

기본 보안 정책

• 기능을 활성화한 소비자는 secure default가 적용됩니다.
• failMode 기본값은 closed입니다.
• openFallback: "plaintext"는 unsafeAllowPlaintextStorage: true가 없으면 거부됩니다.
• Envelope 포맷은 { v, alg, kid, iv, tag, ct } JSON 텍스트를 사용합니다.
• 인코딩은 dialect 공통성을 위해 base64url을 사용합니다.

조회/인덱스 정책

• 전화번호 조회는 deterministic encryption에 의존하지 않습니다.
• to_hash, from_hash 인덱스를 사용합니다.
• 해시는 HMAC-SHA256(normalizedValue) 기준입니다.

AAD 및 키 로테이션

• 기본 AAD: messageId, providerId, tableName, fieldPath (+ tenantId 선택)
• encrypt 시 active kid, decrypt 시 multi-kid 순차 시도로 로테이션을 지원합니다.

운영 시 확인할 지표

• crypto_encrypt_ms
• crypto_decrypt_ms
• crypto_fail_count
• key_kid_usage

장애 대응 포인트

• crypto_fail_count 급증: 키/환경 변수/입력 포맷 점검
• kid 불일치: keyResolver와 active key 배포 상태 점검
• 백필 중단: add columns -> index -> backfill -> legacy drop(optional) 순서 재시도

추가 상세:

• Migration 가이드
• 운영 런북