Implement ACME trust verification controls

.gitignore

@@ -8,3 +8,4 @@ secrets.bak/
 site/
 site-pdf-*/
 tmp/
+state.json

Cargo.toml

@@ -17,6 +17,7 @@ reqwest = { version = "0.13", default-features = false, features = [
     "rustls",
 ] }
 ring = "0.17"
+rustls = { version = "0.23", default-features = false, features = ["ring", "std"] }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 thiserror = "2"
@@ -28,6 +29,7 @@ x509-parser = "0.18"
 
 [dev-dependencies]
 tempfile = "3"
+tokio-rustls = "0.26"
 wiremock = "0.6"
 
 [lints.clippy]

agent.toml.compose

@@ -6,6 +6,9 @@ server = "https://bootroot-ca:9000/acme/acme/directory"
 # Format: <instance_id>.<service_name>.<hostname>.<domain>
 domain = "trusted.domain"
 
+[trust]
+verify_certificates = false
+
 [scheduler]
 max_concurrent_issuances = 1
 

agent.toml.example

@@ -33,6 +33,8 @@ http_responder_token_ttl_secs = 300
 
 # Trust settings for CA bundle verification/storage
 [trust]
+# Toggle TLS certificate verification for ACME server connections
+verify_certificates = true
 # Path to save the CA bundle (intermediate/root)
 ca_bundle_path = "certs/ca-bundle.pem"
 # SHA-256 fingerprints of trusted CA certs (hex)

docs/en/cli-examples.md

@@ -276,9 +276,13 @@ Issuing certificate for 001.web-app.web-01.trusted.domain
 Certificate issued successfully.
 ```
 
-## 7) Renewal/rotation (examples)
+## 7) Secret rotation (examples)
 
-bootroot provides rotation commands. Example that rotates all secrets:
+bootroot provides rotation commands for **secrets** (step-ca password, EAB,
+DB credentials, HMAC, AppRole). **Certificate renewal** is handled by
+`bootroot-agent`.
+
+Example that rotates all secrets:
 
 ```bash
 bootroot rotate stepca-password

docs/en/configuration.md

@@ -140,21 +140,58 @@ Controls HTTP-01 responder settings and retry behavior for ACME operations.
 
 ```toml
 [trust]
+verify_certificates = true
 ca_bundle_path = "/etc/bootroot/ca-bundle.pem"
 trusted_ca_sha256 = ["<sha256-hex>"]
 ```
 
-Controls CA bundle storage and verification for mTLS trust.
+Controls mTLS trust and **ACME server TLS verification**.
 
+Concepts:
+
+- **mTLS trust**: the trust bundle used by services to verify peer
+  certificates. bootroot-agent writes the chain (intermediate/root) to
+  `ca_bundle_path`, and services use that file as their trust store.
+- **ACME server TLS verification**: bootroot-agent verifies the step-ca
+  server certificate when communicating with the ACME endpoint. This is
+  separate from mTLS trust.
+
+Settings:
+
+- `verify_certificates`: enables **ACME server TLS verification**.
+  This is not an mTLS setting; it only affects how bootroot-agent validates
+  the step-ca server certificate.
 - `ca_bundle_path`: path where bootroot-agent writes the CA bundle
-  (intermediate/root only).
+  (intermediate/root only). When `verify_certificates = true`, setting this
+  also makes bootroot-agent trust **this bundle** for the ACME server.
 - `trusted_ca_sha256`: list of trusted CA cert fingerprints (SHA-256 hex).
 
 `trusted_ca_sha256` must match **real CA certificate fingerprints** (not
 arbitrary values). `bootroot init` stores CA fingerprints in OpenBao, and
 `bootroot app add` includes the trusted list in the agent.toml snippet.
 In the common workflow, you should use the values printed by app add.
 
+If `verify_certificates = true` and `ca_bundle_path` is **not** set,
+bootroot-agent uses the **system CA store** to validate the ACME server.
+
+Default: `verify_certificates = false` for backward compatibility. For
+production, enable verification and provide a trusted CA source.
+
+Operational notes:
+
+- On the **first** connection to step-ca, a trusted bundle must already exist
+  at `ca_bundle_path` (manual install). If that is inconvenient, you can
+  **temporarily** use `bootroot-agent --insecure` to obtain the first cert.
+- After issuance succeeds, bootroot-agent writes the chain to `ca_bundle_path`.
+  For **renewals** (cron/daemon), do **not** use `--insecure`; keep
+  verification enabled.
+- This workflow lets you keep `verify_certificates = true` in `agent.toml` and
+  use CLI flags only as a temporary bypass.
+
+Note: in a single step-ca deployment, it is practical to reuse the same
+`ca_bundle_path` for both mTLS trust and ACME server verification. The two
+concepts are still different, so keep them distinct in your mental model.
+
 If the snippet does not include `trusted_ca_sha256`, check:
 
 - `secrets/certs/root_ca.crt` and `secrets/certs/intermediate_ca.crt` exist
@@ -185,6 +222,34 @@ hmac = "your-hmac-key"
 EAB can also be passed via CLI (`--eab-kid`, `--eab-hmac`, or `--eab-file`).
 For production, prefer injecting EAB values via OpenBao.
 
+### Command-line options
+
+`bootroot-agent` can only override a subset of settings.
+Apply order is `agent.toml` → environment variables → CLI options, with CLI
+being applied last.
+
+Example: even if `agent.toml` has `email = "admin@example.com"`,
+running `bootroot-agent --email ops@example.com` uses `ops@example.com`.
+
+Options:
+
+- `--config <PATH>`: config file path (default `agent.toml`)
+- `--email <EMAIL>`: support email address
+- `--ca-url <URL>`: ACME directory URL
+- `--http-responder-url <URL>`: HTTP-01 responder URL
+  (env `BOOTROOT_HTTP_RESPONDER_URL`)
+- `--http-responder-hmac <HMAC>`: HTTP-01 responder HMAC
+  (env `BOOTROOT_HTTP_RESPONDER_HMAC`)
+- `--eab-kid <KID>`: EAB Key ID
+- `--eab-hmac <HMAC>`: EAB HMAC key
+- `--eab-file <PATH>`: EAB JSON file path
+- `--oneshot`: issue once and exit (disable daemon loop)
+- `--verify-certificates`: force ACME server TLS verification
+- `--insecure`: disable ACME server TLS verification
+
+All other settings (profiles, retry, scheduler, hooks, CA bundle paths, etc.)
+must be defined in `agent.toml`.
+
 ### Profiles
 
 Each profile represents one daemon instance (one certificate identity).

docs/en/installation.md

@@ -265,6 +265,11 @@ cargo build --release
 `--oneshot` issues once and exits. For daemon mode, omit it. See
 **Configuration** for details.
 
+TLS verification override:
+
+- `--verify-certificates` forces ACME server TLS verification on.
+- `--insecure` disables verification (**insecure**, overrides config).
+
 #### CA bundle consumer permissions
 
 Services using mTLS must be able to read the CA bundle written to
@@ -281,6 +286,13 @@ docker compose up --build -d bootroot-agent
 
 The agent reads `agent.toml.compose` by default in the container.
 
+The image runs the agent in **daemon mode by default** (no `--oneshot`).
+For a sidecar, use a restart policy such as `restart: unless-stopped` to keep
+the container running (the current compose example does **not** set a restart
+policy for bootroot-agent by default). Also ensure Docker/Compose itself is
+managed by systemd (or an equivalent service manager) so it survives host
+reboots.
+
 ## HTTP-01 responder
 
 ### Docker

docs/en/operations.md

@@ -81,6 +81,10 @@ to `ca_bundle_path`. This bundle is used for mTLS peer verification.
 - If `trust.trusted_ca_sha256` is set, the response chain **must pass
   fingerprint verification** or issuance fails.
 - If no chain is present, the CA bundle is not written (logged).
+- With `trust.verify_certificates = true`, bootroot-agent verifies the ACME
+  server TLS certificate. If `ca_bundle_path` is set, it uses that bundle;
+  otherwise it uses the system CA store.
+- CLI override: `bootroot-agent --verify-certificates` or `--insecure`.
 
 Permissions/ownership:
 

docs/en/troubleshooting.md

@@ -63,7 +63,10 @@ files are missing, init fails.
 ## ACME directory fetch retries
 
 - Confirm step-ca is up and reachable
-- Check TLS trust for the CA endpoint
+- Check TLS trust for the CA endpoint:
+  - If using system trust, ensure the CA is installed in the OS store
+  - If using `trust.ca_bundle_path`, ensure the bundle exists and is readable
+  - For temporary diagnosis, use `bootroot-agent --insecure` (not for prod)
 - Verify `server` URL in `agent.toml`
 
 ## Hook execution errors

docs/ko/cli-examples.md

@@ -280,9 +280,12 @@ Issuing certificate for 001.web-app.web-01.trusted.domain
 Certificate issued successfully.
 ```
 
-## 7) 인증서 갱신/회전(예시)
+## 7) 시크릿 회전(예시)
 
-bootroot는 회전 명령을 제공합니다. 모든 시크릿을 갱신하는 예:
+bootroot의 `rotate`는 **시크릿 회전**(step-ca 비밀번호, EAB, DB, HMAC, AppRole)을
+수행합니다. **인증서 갱신**은 `bootroot-agent`가 처리합니다.
+
+모든 시크릿을 갱신하는 예:
 
 ```bash
 bootroot rotate stepca-password

docs/ko/configuration.md

@@ -142,20 +142,58 @@ HTTP-01 리스폰더와 ACME 재시도 동작을 제어합니다.
 
 ```toml
 [trust]
+verify_certificates = true
 ca_bundle_path = "/etc/bootroot/ca-bundle.pem"
 trusted_ca_sha256 = ["<sha256-hex>"]
 ```
 
-mTLS 신뢰를 위해 CA 번들을 저장하고 검증하는 설정입니다.
+mTLS 신뢰와 **ACME 서버 TLS 검증**을 제어하는 설정입니다.
 
-- `ca_bundle_path`: bootroot-agent가 CA 번들(중간/루트)을 **저장할 경로**입니다.
+개념 정리:
+
+- **mTLS 신뢰**: 서비스가 서로의 인증서를 검증할 때 사용할 **신뢰 번들**입니다.
+  bootroot-agent가 발급 응답의 체인(중간/루트)을 `ca_bundle_path`에 저장하면,
+  이 파일을 서비스의 trust store로 사용합니다.
+- **ACME 서버 TLS 검증**: bootroot-agent가 step-ca(ACME 서버)와 통신할 때
+  **서버 인증서를 검증하는 동작**입니다. 이는 mTLS와 별개의 개념입니다.
+
+설정 항목:
+
+- `verify_certificates`: **ACME 서버 TLS 검증** 여부입니다.
+  mTLS 신뢰 설정이 아니라, step-ca와 통신할 때 bootroot-agent가
+  서버 인증서를 검증할지 결정합니다.
+- `ca_bundle_path`: bootroot-agent가 **CA 번들(중간/루트)을 저장할 경로**입니다.
+  `verify_certificates = true`일 때 이 값을 설정하면 **이 번들을 ACME 서버
+  신뢰 번들로도 사용**합니다.
 - `trusted_ca_sha256`: 신뢰할 CA 인증서 지문 목록(SHA-256 hex)입니다.
 
 `trusted_ca_sha256`는 **임의 값이 아니라 실제 CA 인증서 지문**입니다.
 `bootroot init`이 CA 지문을 OpenBao에 저장하며,
 `bootroot app add` 출력의 agent.toml 스니펫에 **신뢰 지문 목록이 포함**됩니다.
 따라서 일반적인 운영 흐름에서는 app add가 제시한 값을 그대로 사용하면 됩니다.
 
+`verify_certificates = true`인데 `ca_bundle_path`가 없으면,
+bootroot-agent는 **시스템 CA 저장소**로 ACME 서버를 검증합니다.
+
+기본값: `verify_certificates = false` (호환성 유지 목적). 운영 환경에서는
+검증을 활성화하고 신뢰할 CA 소스를 제공하는 것을 권장합니다.
+
+운영 팁:
+
+- bootroot-agent가 **처음** step-ca와 통신할 때는 `ca_bundle_path`에
+  신뢰할 CA 번들이 **미리 존재해야** 합니다(수동 설치 필요).
+  이 과정이 번거롭다면, **일시적으로** `bootroot-agent --insecure`로
+  발급을 진행할 수 있습니다.
+- 한 번 발급이 성공하면 bootroot-agent가 체인을 `ca_bundle_path`에
+  저장합니다. 이후 **정기 갱신(cron/daemon)** 단계에서는
+  `--insecure`를 사용하지 말고 **검증을 유지**하는 것이 안전합니다.
+- 위 흐름을 사용하면 `agent.toml`의 `verify_certificates = true`는
+  그대로 두고, 필요 시에만 CLI로 임시 우회할 수 있습니다.
+
+참고: 단일 step-ca를 사용하는 환경에서는 mTLS 신뢰 번들과
+ACME 서버 검증에 **같은 `ca_bundle_path`를 재사용하는 운영**이 가능합니다.
+다만 두 개념은 목적이 다르므로 필요 시 분리할 수 있다는 점은 기억하세요.
+
 만약 스니펫에 `trusted_ca_sha256`가 나오지 않는다면 다음을 확인하세요.
 
 - step-ca 초기화로 `secrets/certs/root_ca.crt`,
@@ -250,20 +288,35 @@ backoff_secs = [5, 10, 30]
 - `max_output_bytes`: stdout/stderr 제한
 - `on_failure`: `continue` 또는 `stop`
 
-### CLI 재정의
+### 명령행 옵션
 
-```bash
-bootroot-agent --config agent.toml --oneshot
-bootroot-agent --config agent.toml --email admin@example.com
-bootroot-agent --config agent.toml --eab-kid X --eab-hmac Y
-```
+`bootroot-agent`는 아래 옵션만 설정을 덮어쓸 수 있습니다.
+적용 순서는 `agent.toml` → 환경변수 → CLI 옵션이며, 마지막에 적용되는 CLI가
+가장 우선입니다.
 
-CLI 값이 제공되면 파일 설정을 덮어씁니다.
-우선순위는 `agent.toml` → 환경변수 → CLI 옵션이며, CLI가 가장 우선입니다.
-예를 들어 `agent.toml`에 `email = "admin@example.com"`이 있어도
+예: `agent.toml`에 `email = "admin@example.com"`이 있어도
 `bootroot-agent --email ops@example.com`으로 실행하면 실제로는
 `ops@example.com`이 사용됩니다.
 
+옵션 목록:
+
+- `--config <PATH>`: 설정 파일 경로(기본 `agent.toml`)
+- `--email <EMAIL>`: 지원 이메일
+- `--ca-url <URL>`: ACME 디렉터리 URL
+- `--http-responder-url <URL>`: HTTP-01 리스폰더 URL
+  (env `BOOTROOT_HTTP_RESPONDER_URL`)
+- `--http-responder-hmac <HMAC>`: HTTP-01 리스폰더 HMAC
+  (env `BOOTROOT_HTTP_RESPONDER_HMAC`)
+- `--eab-kid <KID>`: EAB Key ID
+- `--eab-hmac <HMAC>`: EAB HMAC Key
+- `--eab-file <PATH>`: EAB JSON 파일 경로
+- `--oneshot`: 1회 발급 후 종료(데몬 루프 비활성화)
+- `--verify-certificates`: ACME 서버 TLS 검증 강제
+- `--insecure`: ACME 서버 TLS 검증 비활성화
+
+그 외 설정(프로필, 재시도, 스케줄러, 훅, CA 번들 경로 등)은
+`agent.toml`에 정의해야 합니다.
+
 ## HTTP-01 리스폰더 (responder.toml)
 
 리스폰더는 `responder.toml`(또는 `BOOTROOT_RESPONDER__*` 환경변수)을 읽습니다.

docs/ko/installation.md

@@ -278,6 +278,13 @@ cargo build --release
 `--oneshot`은 인증서를 **한 번만 발급**하고 종료하는 옵션입니다. 데몬
 모드로 주기적 갱신을 하려면 이 옵션을 빼고 실행합니다.
 자세한 설정 방법은 **설정** 섹션을 참고하세요.
+bootroot-agent가 중단 없이 실행되도록 하려면 systemd 등 서비스 관리자에
+등록해 상시 실행되게 구성하세요.
+
+TLS 검증 오버라이드:
+
+- `--verify-certificates`: ACME 서버 TLS 검증 강제
+- `--insecure`: ACME 서버 TLS 검증 비활성화
 
 #### CA 번들 소비 서비스 권한
 
@@ -293,6 +300,12 @@ docker compose up --build -d bootroot-agent
 
 컨테이너는 기본으로 `agent.toml.compose`를 사용합니다.
 
+이미지는 기본적으로 **데몬 모드**(no `--oneshot`)로 실행됩니다.
+사이드카로 운용할 때는 `restart: unless-stopped` 같은 재시작 정책을
+설정해 컨테이너가 계속 돌도록 하세요(현재 compose 예시는
+bootroot-agent에 restart 정책이 기본으로 들어 있지 않습니다). 또한 호스트 재부팅에도 유지되도록
+Docker/Compose 서비스 자체를 systemd 등으로 관리해야 합니다.
+
 ## HTTP-01 리스폰더
 
 ### Docker

docs/ko/operations.md

@@ -80,6 +80,10 @@ WantedBy=timers.target
 - `trust.trusted_ca_sha256`를 지정하면 응답의 체인이 **지문 검증을 통과해야**
   저장됩니다. 불일치 시 발급이 실패합니다.
 - 체인이 없는 응답이라면 CA 번들을 저장하지 않습니다(로그에 남습니다).
+- `trust.verify_certificates = true`이면 bootroot-agent가 ACME 서버 TLS
+  인증서를 검증합니다. `ca_bundle_path`가 있으면 그 번들을 사용하고,
+  없으면 시스템 CA 저장소를 사용합니다.
+- CLI 오버라이드: `bootroot-agent --verify-certificates` 또는 `--insecure`.
 
 권한/소유권:
 

docs/ko/troubleshooting.md

@@ -63,7 +63,10 @@ step-ca 프로비저너 정책과 요청 DNS SAN을 확인하세요.
 ## ACME 디렉터리 재시도 반복
 
 - step-ca 기동 여부 확인
-- TLS 신뢰 설정 확인
+- TLS 신뢰 설정 확인:
+  - 시스템 CA를 쓰는 경우 OS 저장소에 CA가 설치됐는지 확인
+  - `trust.ca_bundle_path`를 쓰는 경우 파일 존재/읽기 권한 확인
+  - 임시 진단 용도로는 `bootroot-agent --insecure` 사용 가능 (운영 비권장)
 - `server` URL 확인
 
 ## 훅 실행 오류