API 키 저장 방법: 해싱과 암호화의 차이, Fernet 예제

외부 서비스 호출에 다시 사용할 API 키는 해시만 저장하면 안 됩니다. 원문이 필요한 키는 비밀 관리 서비스나 복호화 가능한 저장 방식을 사용하고, 들어온 키가 맞는지만 확인하는 서버 발급 키는 검증용 저장 방식을 설계해야 합니다.

먼저 API 키의 용도를 나누세요

용도	원문 복구	검토할 방식
외부 API에 인증 헤더로 전송	필요	비밀 관리 서비스 또는 키를 분리한 인증된 암호화
내 서비스가 발급한 키의 일치 여부 확인	보통 불필요	충분한 무작위성의 키 발급과 해시·HMAC 검증 설계
개발용 임시 키	필요	환경변수 등으로 코드에서 분리하고 저장소에 포함하지 않기

해싱은 암호화의 다른 이름이 아닙니다. 해시값을 외부 서비스의 원래 API 키 자리에 넣으면 인증되지 않습니다. 비밀번호용 반복 해시 설정을 API 키 전체에 일률적으로 적용하는 것도 적절하지 않습니다. 비밀번호와 고엔트로피 무작위 토큰은 위협 모델이 다릅니다.

Fernet으로 암호화와 복호화 흐름 확인하기

다음은 Python 3 환경과 cryptography 패키지에서 흐름을 이해하기 위한 로컬 예제입니다. 설치는 python -m pip install cryptography로 진행합니다. 예제는 실제 서비스 키를 사용하지 않으며, 운영용 키 보관 시스템 전체를 구현한 코드는 아닙니다.

from cryptography.fernet import Fernet

encryption_key = Fernet.generate_key()
cipher = Fernet(encryption_key)
sample_key = b"demo-key-not-for-production"

ciphertext = cipher.encrypt(sample_key)
restored = cipher.decrypt(ciphertext)
assert restored == sample_key
print("roundtrip ok")

출력은 roundtrip ok입니다. 암호문은 생성할 때마다 달라질 수 있습니다. 생성한 암호화 키까지 DB의 같은 레코드나 같은 백업에 보관하면 DB가 유출될 때 함께 노출될 수 있습니다. 운영 환경에서는 권한 분리, 접근 감사, 키 교체 및 복구 절차를 별도로 마련해야 합니다.

키를 바꾸거나 잃어버리면 어떻게 되나요?

암호화 키를 잃으면 암호문을 복구할 수 없습니다. 키를 교체할 때는 기존 암호문을 어떤 키로 읽을지 식별하는 버전 정보를 관리하고, 재암호화와 이전 키 폐기 절차를 정해야 합니다. 암호문이 변조되거나 키가 다르면 복호화가 실패하므로 그 예외를 정상적인 빈 문자열로 바꾸어 숨기지 마세요.

이미 원문 키가 노출됐다면

저장 방식 변경만으로 유출된 키가 안전해지지는 않습니다. 해당 제공자의 관리 화면에서 키를 폐기·재발급하고, 로그·백업·저장소 기록 등 노출 범위를 조사해야 합니다. 요청 헤더 전체를 로그에 출력하는 디버깅 코드도 확인하세요.

참고 자료와 다음 단계

cryptography의 Fernet 공식 문서에서 키 보관, 잘못된 토큰 처리와 키 교체 기능을 확인할 수 있습니다. 관련 글: API JSON 응답 검증, 요청 간격과 재시도. 전체 흐름은 API·운영 가이드를 참고하세요.

작성: 로그 · 2026-10-17 수정: API 키의 용도별 저장 방식을 구분하고 근거 없는 보안·성능 보장 표현을 제거했습니다.