SSL/TLS 인증서 관리
자동화된 인증서 관리 기능을 통해 보안을 강화합니다.
Let's Encrypt 자동화
자동 발급
- ACME v2 프로토콜 지원
- DNS-01 챌린지를 통한 와일드카드 인증서 발급
- 다중 도메인 (SAN) 인증서 지원
자동 갱신
- 갱신 시점: 만료 30일 전 자동 갱신
- 체크 간격: 6시간마다 만료 확인
- 갱신 이력: 모든 갱신 시도 기록
스테이징 모드
Let's Encrypt Rate Limit을 피하기 위한 테스트 환경 지원
# .env 설정
ACME_STAGING=true # 스테이징 (테스트)
ACME_STAGING=false # 프로덕션
DNS Provider 지원
DNS-01 챌린지를 위한 다양한 DNS Provider를 지원합니다.
지원 Provider
| Provider | 설정 필드 |
|---|---|
| Cloudflare | API Token (권장) 또는 Global API Key + Email, Zone ID(선택) |
| Route53 (AWS) | Access Key ID, Secret Access Key, Region(선택), Hosted Zone ID(선택) |
| DuckDNS | Token |
| Dynu | API Key |
| Manual | 자격 증명 불필요 (TXT 레코드 수동 추가) |
참고: 위 5종이 NPG UI에서 실제로 선택 가능한 DNS-01 Provider입니다. NPG는 내부적으로 go-acme/lego를 사용하며 lego 자체는 수십 종의 DNS Provider를 지원하지만, 현재 NPG가 노출하는 것은 Cloudflare / Route53 / DuckDNS / Dynu / Manual뿐입니다.
Provider 설정
- DNS Provider 생성
- API 자격 증명 입력
- 자격 증명 테스트
- 기본 Provider 설정 (선택)
자격 증명 테스트
Provider 설정 전 연결을 테스트하여 올바른 설정을 확인합니다.
커스텀 인증서
인증서 업로드
기존 인증서를 업로드하여 사용할 수 있습니다.
- 인증서 (cert.pem): 서버 인증서
- 개인 키 (key.pem): 개인 키 파일
- 체인 인증서 (chain.pem): 중간 인증서 (선택)
자체 서명 인증서
테스트 환경을 위한 자체 서명 인증서를 생성합니다.
- 도메인 지정
- 유효 기간 설정
- 즉시 생성
HTTP/3 (QUIC) 지원
프로토콜 지원
| 프로토콜 | 상태 | 특징 |
|---|---|---|
| HTTP/1.1 | 지원 | 기본 호환성 |
| HTTP/2 | 기본 활성화 | 멀티플렉싱, 헤더 압축 |
| HTTP/3 | 지원 | UDP 기반, 빠른 연결 |
HTTP/3 설정
HTTP/3는 UDP 443 포트를 사용합니다.
# docker-compose.yml
ports:
- "443:443/tcp" # HTTP/1.1, HTTP/2
- "443:443/udp" # HTTP/3 (QUIC)
인증서 모니터링
만료 예정 확인
- 만료 30일 이전 인증서 조회
- 대시보드 알림
- 이메일 알림 (설정 시)
인증서 상태
| 상태 | 설명 |
|---|---|
| 유효 | 정상 동작 중 |
| 만료 임박 | 30일 이내 만료 예정 |
| 만료됨 | 인증서 만료 |
| 갱신 실패 | 자동 갱신 실패 |
갱신 이력
모든 인증서 발급 및 갱신 이력이 기록됩니다.
- 발급/갱신 시간
- 성공/실패 여부
- 오류 메시지 (실패 시)
TLS 보안 설정
프로토콜 버전
- TLS 1.2 이상만 허용
- TLS 1.0/1.1 비활성화 (보안 취약)
암호화 스위트
강력한 암호화 알고리즘만 허용합니다.
ECDHE-ECDSA-AES128-GCM-SHA256
ECDHE-RSA-AES128-GCM-SHA256
ECDHE-ECDSA-AES256-GCM-SHA384
ECDHE-RSA-AES256-GCM-SHA384
OCSP Stapling
- 인증서 상태 확인 최적화
- 클라이언트 지연 감소
- 기본 활성화
HSTS (HTTP Strict Transport Security)
HTTPS 사용을 강제합니다.
| 설정 | 설명 |
|---|---|
| max-age | HSTS 유효 기간 (초) |
| includeSubDomains | 서브도메인 포함 |
| preload | HSTS Preload List 등록 |
포스트 퀀텀 TLS (Post-Quantum)
미래의 양자 컴퓨터 공격에 대비한 하이브리드 키 교환을 지원합니다. 클래식(타원곡선) 키 교환과 포스트 퀀텀 알고리즘(ML-KEM)을 결합하여, 지금 가로채 저장한 트래픽을 나중에 양자 컴퓨터로 복호화하는 "harvest now, decrypt later" 공격을 방어합니다.
동작 방식
NPG는 ssl_ecdh_curve 설정에 X25519MLKEM768를 기본 포함합니다. 이는 하이브리드(X25519 + ML-KEM-768) 방식이므로, ML-KEM을 지원하지 않는 기존 클라이언트는 자동으로 X25519 등 클래식 곡선으로 협상되어 정상 연결됩니다.
ssl_ecdh_curve X25519MLKEM768:X25519:secp256r1:secp384r1;
설정 방법
전역 SSL 설정의 ECDH Curve 필드에서 값을 조정할 수 있습니다. 기본값은 다음과 같습니다.
X25519MLKEM768:X25519:secp256r1:secp384r1
목록 앞쪽 곡선이 우선 협상되므로, X25519MLKEM768를 맨 앞에 두면 지원 클라이언트와는 포스트 퀀텀 하이브리드 키 교환을 사용합니다.
요구 사항
| 항목 | 요구 사항 |
|---|---|
| 서버 | OpenSSL 3.5 이상 (NPG 빌드에 포함) |
| 클라이언트 | ML-KEM 하이브리드를 지원하는 최신 브라우저/클라이언트 |
| 미지원 클라이언트 | 클래식 곡선으로 자동 폴백 (연결 유지) |
참고: 하이브리드 방식이므로 포스트 퀀텀을 지원하지 않는 클라이언트도 정상 동작합니다. 별도로 비활성화할 필요 없이 기본값을 그대로 사용하는 것을 권장합니다.
문제 해결
인증서 발급 실패
-
DNS 설정 확인
- 도메인이 서버 IP를 가리키는지 확인
- DNS 전파 대기 (최대 48시간)
-
DNS Provider 자격 증명 확인
- API 토큰 권한 확인
- Zone 편집 권한 필요
-
Rate Limit 확인
- Let's Encrypt Rate Limit에 도달했는지 확인
- 스테이징 모드로 먼저 테스트
-
로그 확인
docker logs npg-api | grep -i cert
갱신 실패
- DNS Provider 연결 상태 확인
- API 토큰 만료 여부 확인
- 도메인 소유권 확인
SSL 오류
- ERR_CERT_INVALID: 인증서 유효성 확인
- ERR_SSL_VERSION_OR_CIPHER_MISMATCH: TLS 설정 확인
- ERR_CERT_DATE_INVALID: 인증서 만료 확인