Feature #1255
openFeature #1226: [MDGU] 학사관리 시스템 v1 개발 (8주, 2026-11-05 시작)
Feature #1235: [MDGU-02] 보안·개인정보 (김예주, P0)
[MDGU-02-03] 암호화·키 관리 구현
90%
Description
목적¶
개인정보와 민감 첨부를 저장할 때 암호화하고, 키는 DB·백업과 분리해 관리합니다. (NFR-SEC-004, 007)
쉬운 설명¶
개인정보와 첨부 파일을 저장할 때 암호화하고, 암호 키를 코드와 따로 관리하는 기능입니다.
기술 스택¶
Python cryptography(AES-256-GCM 또는 Fernet, 후보), Django 필드 래퍼, 환경변수/별도 보안 저장소.
예상 결과(산출물)¶
암호화 필드/서비스, 키 로딩 모듈, 키 교체·분실 대응 절차 문서, 테스트.
개발 작업 상세¶
- 암호화 방식을 확정한다(키 길이, nonce, 인증 포함).
- 암호화 필드 래퍼(저장 시 암호화, 인가된 서비스 함수만 복호화)를 만든다.
- 키를 환경변수 또는 별도 저장소에서 읽고 DB·백업에 함께 저장하지 않는다.
- 키 교체(재암호화) 절차와 키 분실 시 복구 정책을 문서화한다.
- 단위 테스트: 암호문만으로 복원 불가, 잘못된 키 실패, 키 교체 후 복호화.
완료 기준¶
- 암호화 저장 테스트가 통과한다(인수 테스트 4의 일부).
- 키가 저장소·로그에 노출되지 않는다.
충돌 방지(소유 범위)¶
security/ 안에서만 작업합니다.
선행·후행·위험¶
선행: 02-02 개인정보 분리 구조 설계·구현 골격(김예주, 11/17 종료)
후행: 02-04 역할·권한(RBAC) 구현(김예주) / 07-01 학생 기본 모델·개인정보 참조·조회 화면(우섭) / 12-01 증빙 파일 업로드·암호화 저장·접근통제·다운로드 이력(김예주)
결과 확인 방법¶
"완료 기준"의 각 항목을 화면 또는 명령으로 직접 확인합니다.
- 암호화 저장 테스트가 통과한다(인수 테스트 4의 일부).
- 키가 저장소·로그에 노출되지 않는다.
- pytest가 모두 통과한다.
- 확인 결과(화면 캡처 또는 명령 출력 요약)를 일감 메모에 남긴다.
시작 전 준비¶
- 선행 일감의 결과물(문서·코드)을 먼저 읽고 약속된 이름·구조를 확인한다.
- 저장소를 최신으로 맞춘다: git switch main 후 git pull --ff-only origin main
- 저장소 README 8번과 팀 로컬 세팅 안내 순서대로 환경을 준비한다. 보통 py -3.12 -m venv .venv, 가상환경 켜기, python -m pip install -r requirements-dev.txt, Windows에 설치한 PostgreSQL 18에서 개인 로컬 DB(university_dev) 생성, .env.local 설정(DB_NAME, DB_USER, DB_PASSWORD, DB_HOST, DB_PORT), python manage.py check, python manage.py migrate 순서이다. 최초 실행에 makemigrations는 필요 없고, .env.local과 비밀번호는 공유·커밋하지 않는다.
- #1226의 폴더 소유 표에서 내가 고칠 수 있는 폴더를 확인한다.
작업 진행 순서¶
- 브랜치를 만든다: git switch -c feature/1255-<짧은영문설명>
- "개발 작업 상세"의 번호 순서대로 한 단계씩 구현하고, 단계마다 pytest로 확인한다.
- 모델을 바꾸면 python manage.py makemigrations, 그다음 python manage.py migrate를 실행한다.
- 화면은 python manage.py runserver로 실행해 직접 열어 보고 "완료 기준"과 하나씩 대조한다.
- git add, git commit, git push 후 PR을 만든다. PR 템플릿의 체크리스트를 채우고 폴더 소유자의 리뷰를 받는다.
- 병합 후 이 일감 메모에 PR 링크와 확인 결과를 적고 상태와 진행률을 갱신한다.
막힐 때 확인¶
키를 잃으면 복구가 불가능합니다. 키 보관과 교체 절차를 문서에 적고 테스트용 키와 운영 키를 반드시 분리하세요.
그래도 해결되지 않으면 일감 메모에 "무엇을 했고, 어떤 오류가 났는지"를 붙여 담당 분류 소유자 또는 팀장에게 질문하세요.
용어 풀이¶
- 암호화·키 관리: 데이터를 열쇠(키) 없이는 읽을 수 없게 바꾸는 일과, 그 키를 안전하게 보관·교체하는 일입니다. 키는 코드와 따로 보관합니다.
- 서비스 함수: 다른 앱이 직접 DB를 건드리지 않고 이 함수를 통해서만 기능을 쓰게 만든 창구입니다.
성양 Updated by 성용 양 19 days ago
- Follows Feature #1254: [MDGU-02-02] 개인정보 분리 구조 설계·구현 골격 added
성양 Updated by 성용 양 19 days ago
- Precedes Feature #1256: [MDGU-02-04] 역할·권한(RBAC) 구현 added
성양 Updated by 성용 양 19 days ago
- Precedes Feature #1290: [MDGU-12-01] 증빙 파일 업로드·암호화 저장·접근통제·다운로드 이력 added
성양 Updated by 성용 양 14 days ago
- Precedes Feature #1276: [MDGU-07-01] 학생 기본 모델·개인정보 참조·조회 화면 added
성양 Updated by 성용 양 5 days ago
- Status changed from New to In Progress
- % Done changed from 0 to 70
[성용] 진행 기록 (2026-11-12) — 예주님 일감 대리 구현
[한 일]
- PR #49 병합(main 7b8d21f): https://github.com/GilbertMoon/university-academic-system/pull/49
- AES-256-GCM 암호화 서비스(security/_crypto.py): 암호화마다 새 96비트 nonce, 128비트 인증 태그, 포맷·키 버전을 인증 데이터로 묶음
- 키 로딩: 환경변수(FIELD_ENCRYPTION_ACTIVE_KEY_VERSION, FIELD_ENCRYPTION_KEYS)에서만 읽고 DB·백업에 저장하지 않음. 값이 비면 설정 오류로 실패
- 키 교체(새 버전으로 쓰고 이전 키로 읽기)·분실·유출 대응 절차 문서: docs/security/key-management.md
- 테스트: 잘못된 키·변조·없는 키 버전 거부, 키 교체 후 복호화, 예외·로그에 평문·키 미노출
- 리뷰: 예주님 승인, 우섭님 공통 파일 확인
[남은 것]
- 개인정보 필드 래퍼와 실제 암호화 저장(인가된 서비스만 복호화)은 #1254에서 연결. 이때 행·필드 문맥을 인증 데이터에 넣는 context 인자를 함께 추가(예주님 제안)
- 운영 배포 전 .env.production에 운영 키를 준비하고 compose 값을 필수로 바꿈(#1254 배포 전)
성양 Updated by 성용 양 4 days ago
- % Done changed from 70 to 90
[성용] 진행 기록 (2026-11-13)
[한 일]
- 남은 것이었던 행·필드 문맥 인증(context 인자)이 #1254(PR #52, main db70350)에서 연결됨: https://github.com/GilbertMoon/university-academic-system/pull/52
- PR #58 병합(main ec9aa92, 예주님): https://github.com/GilbertMoon/university-academic-system/pull/58 — 키 관리 문서에 로그인 이력 IP 해시 키 절과 #52 이후 운영 반영 순서 추가
[남은 것]
- 운영 키 준비와 compose 값 필수화는 실제 데이터 입력 직전에 운영 담당이 진행(그 전에는 운영에서 개인정보 등록·조회를 쓰지 않음)