"""쇼핑몰 인증정보 암호화 — AES-256-GCM(인증 암호화) + 키 버전. - 라이브러리: `cryptography` 의 AESGCM (직접 만든 알고리즘 없음). - 해시가 아니라 **복호화 가능한** 암호화다 — API Secret/Token 은 나중에 원문이 필요하다. - 마스터 키는 DB 에 두지 않는다. 환경변수(.env)에서만 읽는다. APP_ENCRYPTION_KEY 현재 키(32바이트). `openssl rand -hex 32` 의 64자 hex 또는 32바이트 base64/base64url 둘 다 받는다. APP_ENCRYPTION_KEY_VERSION 현재 키의 버전 번호(기본 1). APP_ENCRYPTION_KEY_V{n} 키 교체 중 남겨 두는 예전 키(버전 n). 재암호화가 끝나면 지운다. 암호문 형식: ``v{버전}:{base64url(nonce 12바이트 + 암호문 + tag 16바이트)}`` AAD(추가 인증 데이터)로 "어느 쇼핑몰의 어느 항목"인지를 묶는다 (예: ``perf:coupang:secret_key``). DB 에서 암호문을 다른 행/칸으로 옮겨 붙이면 복호화가 실패한다. """ from __future__ import annotations import base64 import binascii import os import re from dataclasses import dataclass, field from typing import Mapping KEY_ENV = "APP_ENCRYPTION_KEY" VERSION_ENV = "APP_ENCRYPTION_KEY_VERSION" _OLD_KEY_RE = re.compile(r"^APP_ENCRYPTION_KEY_V(\d+)$") _TOKEN_RE = re.compile(r"^v(\d+):([A-Za-z0-9_\-]+={0,2})$") _NONCE_LEN = 12 class CryptoConfigError(RuntimeError): """마스터 키가 없거나 형식이 틀림 — 설정 문제.""" class DecryptError(RuntimeError): """복호화 실패(키 버전 없음/키 바뀜/손상/다른 칸의 암호문). 원문·키는 메시지에 넣지 않는다.""" def _parse_key(raw: str, *, name: str) -> bytes: value = (raw or "").strip() if not value: raise CryptoConfigError(f"{name} 가 비어 있습니다.") if re.fullmatch(r"[0-9a-fA-F]{64}", value): return bytes.fromhex(value) try: padded = value + "=" * (-len(value) % 4) decoded = base64.urlsafe_b64decode(padded.replace("+", "-").replace("/", "_")) except (binascii.Error, ValueError): decoded = b"" if len(decoded) == 32: return decoded raise CryptoConfigError( f"{name} 형식이 올바르지 않습니다. 32바이트 키가 필요합니다 " "(`openssl rand -hex 32` 로 만든 64자 hex 권장)." ) @dataclass(frozen=True) class KeyRing: """현재 키 + (교체 중이면) 예전 키들. 키 값은 repr 에 나오지 않는다.""" current_version: int _keys: Mapping[int, bytes] = field(repr=False) @classmethod def from_env(cls, environ: Mapping[str, str] | None = None) -> "KeyRing": env = os.environ if environ is None else environ raw_current = (env.get(KEY_ENV) or "").strip() if not raw_current: raise CryptoConfigError( f"{KEY_ENV} 환경변수가 설정되지 않았습니다. " "`openssl rand -hex 32` 로 값을 만들어 .env 에 넣고 컨테이너를 재기동하세요." ) try: version = int((env.get(VERSION_ENV) or "1").strip()) except ValueError: raise CryptoConfigError(f"{VERSION_ENV} 는 1 이상의 정수여야 합니다.") from None if version < 1: raise CryptoConfigError(f"{VERSION_ENV} 는 1 이상의 정수여야 합니다.") keys: dict[int, bytes] = {} for name, raw in env.items(): m = _OLD_KEY_RE.match(name) if m and (raw or "").strip(): keys[int(m.group(1))] = _parse_key(raw, name=name) keys[version] = _parse_key(raw_current, name=KEY_ENV) return cls(current_version=version, _keys=keys) @property def versions(self) -> list[int]: return sorted(self._keys) def key(self, version: int) -> bytes: try: return self._keys[version] except KeyError: raise DecryptError( f"암호화 키 버전 v{version} 이 서버에 없습니다. " f"{KEY_ENV}_V{version} 환경변수를 확인하세요." ) from None def _aesgcm(key: bytes): from cryptography.hazmat.primitives.ciphers.aead import AESGCM # 지연 import return AESGCM(key) def encrypt(plaintext: str, *, aad: str, ring: KeyRing) -> str: """평문 → ``v{버전}:{...}``. 항상 현재 키로 암호화한다.""" if plaintext is None: raise ValueError("암호화할 값이 없습니다.") nonce = os.urandom(_NONCE_LEN) ct = _aesgcm(ring.key(ring.current_version)).encrypt( nonce, plaintext.encode("utf-8"), aad.encode("utf-8") ) body = base64.urlsafe_b64encode(nonce + ct).decode("ascii") return f"v{ring.current_version}:{body}" def key_version_of(token: str) -> int: m = _TOKEN_RE.match(token or "") if not m: raise DecryptError("암호문 형식이 올바르지 않습니다.") return int(m.group(1)) def decrypt(token: str, *, aad: str, ring: KeyRing) -> str: """``v{버전}:{...}`` → 평문. 실패 원인은 알려 주되 값은 절대 담지 않는다.""" m = _TOKEN_RE.match(token or "") if not m: raise DecryptError("암호문 형식이 올바르지 않습니다.") version = int(m.group(1)) try: raw = base64.urlsafe_b64decode(m.group(2)) except (binascii.Error, ValueError): raise DecryptError("암호문이 손상되었습니다.") from None if len(raw) <= _NONCE_LEN: raise DecryptError("암호문이 손상되었습니다.") from cryptography.exceptions import InvalidTag # 지연 import try: pt = _aesgcm(ring.key(version)).decrypt(raw[:_NONCE_LEN], raw[_NONCE_LEN:], aad.encode("utf-8")) except InvalidTag: raise DecryptError( "복호화하지 못했습니다. 마스터 키가 바뀌었거나 값이 손상되었습니다. " "인증정보를 다시 입력해야 할 수 있습니다." ) from None return pt.decode("utf-8") def needs_reencrypt(token: str, ring: KeyRing) -> bool: """현재 키 버전이 아닌 암호문인가(키 교체 후 재암호화 대상).""" try: return key_version_of(token) != ring.current_version except DecryptError: return False