POSA_LEAKSMS/docs/SECURITY_DOCUMENT_CONSISTENCY_AUDIT.md

보안 구현-문서 일치성 점검표

작성일: 2026-05-28 (SHT30 전환 반영: 본 클러스터 정리)
목적: SHT30 온습도 모니터링 전환 구현이 기존 보안대책서 보완 문서, 설치 문서, 증빙 패키지 문서에 일관되게 반영되었는지 확인한다.

1. 구현 기준

구현 통제	코드/파일 근거	문서 반영 상태
관리자 비밀번호 해시	login.php, setup_hash.php, config.php	반영
관리자 TOTP MFA	login.php, setup_mfa.php, admin_security.php, ADMIN_TOTP_SECRET	반영
MFA 최초 등록 토큰	setup_mfa.php, MFA_SETUP_TOKEN	반영
관리자 감사로그	admin_security.php, php/var/admin_audit.log	반영
raw-body API 서명 검증 (HMAC-SHA256)	config.php verify_signature_raw()=hash_hmac('sha256', $raw_body, API_KEY), 펌웨어 sig.c/secrets.h (X-Signature)	반영 (서명 방식 정정 후 일치, 아래 §2.1 참조)
측정값 범위 검증	api/sensor_data.php (온도 -40125℃ / 습도 0100%)	반영
서버 임계 판정·쿨다운	config.php METRIC_*(고온30/저온10·고습70/저습20, 30분 쿨다운, 히스테리시스), api/sensor_data.php	반영
임계 경보/정상복귀 SMS	api/sensor_data.php, leak_sms_log ([고온경보]/[저온경보]/[고습경보]/[저습경보])	반영
장비 오프라인/복구 SMS	cron_heartbeat.php, leak_sensor_status.offline_alerted, leak_sms_log	반영
측정 이력 저장	leak_sensor_metric 테이블	반영
보관기간 정리	retention_cleanup.php --dry-run, --execute (SMS/센서/측정/감사로그)	반영
백업·복구 증빙	scripts/backup_evidence.php	반영
보안 증적 보고서	security_evidence.php?format=md	반영

2.1 서명 방식 정정 (이전 all-clear 정정)

실제 구현의 요청 서명은 HMAC-SHA256 이다.

• 서버: config.php verify_signature_raw() = hash_hmac('sha256', $raw_body, API_KEY), hash_equals() 로 상수시간 비교.
• 펌웨어: sig.c sig_raw_body() = HMAC-SHA256(key=API_KEY, msg=raw_body)(소문자 hex), 호스트 레퍼런스 reference.py 동일.
• 헤더 표기: X-Signature = lowercase_hex(HMAC-SHA256(key=API_KEY, msg=raw_body)).

HMAC 구조를 채택한 이유는 키-접두 sha256(sha256(API_KEY || body))의 길이확장(length-extension) 공격을 차단하기 위함이다.

이전 일부 문서(README.md, INSTALL_PI_SERVER.md, SHT30_SENSOR2_SETUP.md, SOURCE_SECURITY_EVIDENCE.md, stm32f407_migration_plan.md, firmware/README.md, firmware/docs/PORTING_NOTES.md, firmware/docs/BUILD_OFFLINE.md, report_leak_detection_system.md)는 서명을 키-접두 sha256(API_KEY + body) / sha256(API_KEY || body) 로 잘못 기술하고 있었다. 이 문서들은 본 정정으로 모두 HMAC-SHA256 표기로 수정되었으며, 코드와 일치한다. (과거의 키-접두 sha256 기술은 실제 구현과 불일치하는 stale 문구였다.)

2. 수정한 기존 문서

문서	반영 내용
docs/SECURITY_EVIDENCE_PACKAGE.md	MFA 증빙, 측정/임계 경보 증빙, 보관기간 dry-run, 백업·복구 증빙, PNG 재생성은 운영자 몫 명시 (사진 접근통제 증빙 제거)
docs/SOURCE_SECURITY_EVIDENCE.md	raw-body 서명, 측정값 범위 검증, 서버 임계 판정·쿨다운, 오프라인 감지, secrets.h 비밀값 분리로 치환 (사진 업로드/프록시 절 제거)
docs/SECURITY_PLAN_PASS_READINESS.md	보안통제 매트릭스(측정값/임계 경보 행 추가, 사진 행 제거), 관리자 접근통제 문구, 월간 점검표, 개인정보+오발송 방지 문구, 자체 점검표, 증적 목록, 잔여위험 표 갱신
docs/SECURITY_PLAN_HWP_REVIEW.md	최신 리비전(Y수정)(20260528) 기준 before→after, SHT30 구성요소, 임계 경보·오프라인 대응 절차, 사진정보 절 삭제·개인정보만 유지, 반영 순서 갱신
docs/SECURITY_PLAN_ATTACHMENT_GUIDE.md	제공자료 가이드를 온습도·임계 SMS·STM32 기준으로 치환 (사진 보관기간·카메라·photo 항목 제거)
scripts/generate_security_plan_images.py	누수 사고 절차도 함수 제거, 데이터 흐름·목표 구성도·문서맵을 SHT30 측정→임계→SMS 흐름으로 교체

3. HWP에 넣을 때 특히 맞춰야 하는 문구

주제	HWP 표현 기준
사업 범위	“화재/누수/사진”이 아니라 “서버실 온습도(SHT30) 모니터링 + 임계 SMS 경보 + 장비 오프라인 알림”으로 표현
관리자 인증	“비밀번호 해시 + TOTP MFA + 세션 쿠키 보호 + 로그인 실패 제한 + 감사로그”로 표현
MFA 등록	“MFA_SETUP_TOKEN은 최초 등록/교체 때만 임시 사용하고 등록 후 제거”로 표현
Google 연동	“Google API 연동”이 아니라 “Google Authenticator 호환 TOTP”로 표현
임계 경보	“서버 임계 판정(METRIC_*: 고온30/저온10·고습70/저습20) + 30분 쿨다운 + 복구 히스테리시스”로 오발송 방지 표현
개인정보	처리 개인정보는 “SMS 수신자 전화번호”만. 현장 사진/시설정보는 처리하지 않음으로 명시
보관기간	SMS/센서 로그/측정 이력/관리자 감사로그 365일을 기본값으로 쓰고 기관 기준 우선 적용
백업 증빙	백업 수행 자체와 별도로 backup_evidence.php 결과를 복구 가능성 증빙으로 첨부

4. 아직 운영자가 채워야 하는 실제 환경 증적

아래 항목은 코드나 문서만으로 확정할 수 없으므로 운영 환경 기준으로 별도 확보해야 한다.

• 실제 도메인 HTTPS 접속 화면과 인증서 정보
• Cafe24 배포 경로와 SSL 리다이렉트 적용 여부
• 단말(STM32) 네트워크 분리 또는 방화벽 정책 자료
• STM32 보드, SHT30 센서 설치 사진과 자산 정보
• 실제 SMS 수신자 현행화 확인표
• 실제 DB/설정파일 백업 주기와 담당자
• 실제 복구 테스트 결과
• 운영 서버의 retention_cleanup.php --dry-run 결과
• 운영 서버의 scripts/backup_evidence.php 결과
• 보안대책서 구성도/흐름도 PNG 재생성(python scripts/generate_security_plan_images.py)

5. 제출 전 금지 사항

• API 키, SMS secure key, DB 비밀번호, 관리자 원문 비밀번호, ADMIN_TOTP_SECRET 원문을 HWP 또는 첨부자료에 넣지 않는다.
• MFA 화면 캡처에는 운영 비밀키를 노출하지 않는다. 증빙용 임시 키를 사용하거나 운영 키를 마스킹한다.
• 사업 범위를 화재/누수/현장 사진으로 과대 기재하지 않는다. 현재 구현은 온습도 모니터링 + 임계 SMS + 오프라인 알림이다.
• “Google API로 연동”이라고 쓰지 않는다. 실제 구현은 외부 Google API 없이 서버 내부에서 TOTP를 검증하는 방식이다.