{{tag>[acme certbot tls ssl https certificate letsencrypt rfc8555]}}

====== ACME (Automatic Certificate Management Environment) ======

ACME는 CA가 domain control을 검증하고 X.509 certificate의 발급, 갱신, 폐기를 자동화하도록 정의한 RFC 8555 protocol이다. Certbot은 이 protocol을 구현한 ACME client다.

===== Summary =====
  * client가 account key를 만들고 ACME server의 directory에서 endpoint를 찾는다.
  * certificate order에 domain identifier를 제출하면 CA가 authorization과 challenge를 반환한다.
  * client가 challenge를 준비하고 CA가 domain control을 검증한다.
  * 검증 후 CSR을 제출하면 CA가 certificate chain을 발급한다.
  * 갱신도 새 order와 validation을 수행하는 재발급 절차이며 기존 certificate의 단순 만료 연장이 아니다.

===== Protocol Flow =====
<code text>
Directory discovery
  -> Account registration
  -> New order
  -> Authorization / challenge
  -> Domain-control validation
  -> CSR finalize
  -> Certificate download and deployment
  -> Renewal or revocation
</code>

===== Challenge Types =====
==== HTTP-01 ====
  * CA가 ''http://DOMAIN/.well-known/acme-challenge/TOKEN''을 TCP/80으로 조회한다.
  * 일반 web server에서는 Certbot의 ''--nginx'', ''--apache'', ''--webroot''와 잘 맞는다.
  * inbound port 80을 열 수 없거나 여러 frontend가 challenge file을 공유하지 못하면 실패할 수 있다.
  * wildcard identifier에는 사용할 수 없다.

==== DNS-01 ====
  * ''_acme-challenge.DOMAIN'' 아래 TXT record로 domain control을 증명한다.
  * wildcard certificate와 web server를 직접 노출하지 않는 환경에 사용할 수 있다.
  * 자동 갱신에는 DNS provider API plugin이나 안전한 hook이 필요하다.
  * DNS API token은 필요한 zone과 record 권한만 부여하고 web server와 분리 보관하는 편이 안전하다.

==== TLS-ALPN-01 ====
  * TCP/443에서 특별한 ALPN protocol과 일회성 certificate로 domain control을 증명한다.
  * HTTP-01을 쓸 수 없는 일부 TLS termination 환경에서 사용되지만 client/plugin 지원을 먼저 확인해야 한다.

===== Certbot Examples =====
<code bash>
# HTTP-01: webroot
sudo certbot certonly --webroot -w /var/www/html -d example.com

# HTTP-01: temporary standalone server
sudo certbot certonly --standalone -d example.com

# DNS-01: manual wildcard test (interactive; hooks 없이는 자동 갱신 불가)
sudo certbot certonly --manual --preferred-challenges dns \
  --test-cert -d example.com -d '*.example.com'

# 기존 lineage의 renewal path를 staging CA로 검증
sudo certbot renew --dry-run
</code>

<note important>
처음부터 production CA를 반복 호출하지 말고 ''--test-cert'' 또는 ''--staging'', ''renew --dry-run''으로 validation과 deployment hook을 검증한다. staging certificate는 browser가 신뢰하지 않으므로 운영 배포용이 아니다.
</note>

===== Selecting a Challenge =====
  * 단일 public web server이며 TCP/80 접근이 가능하면 HTTP-01이 단순하다.
  * wildcard certificate가 필요하면 DNS-01을 선택한다.
  * 여러 frontend나 CDN 뒤에 있다면 모든 validation request가 올바른 challenge response에 도달하도록 구성하거나 DNS-01을 검토한다.
  * 자동 갱신이 목표라면 interactive ''--manual''보다 web server/webroot/DNS API plugin을 우선한다.

===== Security =====
  * ACME account private key와 certificate private key를 백업·접근 통제 대상으로 취급한다.
  * DNS credential은 전체 account 권한 대신 제한된 zone/record 권한을 사용한다.
  * CAA record를 운영한다면 선택한 CA가 발급할 수 있도록 ''issue''와 wildcard용 ''issuewild'' 정책을 확인한다.
  * hook script에는 secret을 command line literal로 넣지 말고 root 전용 file이나 secret manager에서 읽게 한다.

===== Troubleshooting =====
  * ''unauthorized'': DNS가 잘못된 host를 가리키거나 challenge response/TXT value가 일치하지 않는 경우가 많다.
  * ''connection'': firewall, NAT, load balancer, TCP/80 또는 TCP/443 접근성을 확인한다.
  * DNS-01 timeout: authoritative nameserver에서 TXT record를 직접 조회하고 TTL과 negative cache를 기다린다.
  * rate limit: production 요청을 중단하고 staging에서 원인을 재현한다.

===== Compatibility =====
  * RFC 8555가 정의한 기본 validation method는 HTTP-01과 DNS-01이다. 추가 challenge는 별도 RFC와 client/server 지원 여부를 확인한다.
  * ACME server URL과 지원 기능은 CA마다 다르다. Certbot에서는 ''--server DIRECTORY_URL''로 다른 ACME directory를 지정할 수 있다.

===== See Also =====
  * [[acme-sh:ko]]
  * [[certbot:ko]]
  * [[certbot:installation]]
  * [[openssl:ko]]
  * [[https://www.rfc-editor.org/rfc/rfc8555|RFC 8555: Automatic Certificate Management Environment]]
  * [[https://letsencrypt.org/docs/challenge-types/|Let's Encrypt Challenge Types]]

===== History =====
  * codex:: 2026-07-19 Linked the acme.sh CLI reference as an alternative ACME client.
  * codex:: 2026-07-19 Added an ACME protocol and challenge selection guide for Certbot workflows.

{{indexmenu>.#1|js}}