トラブルシューティングとFAQ

本ドキュメントでは、UPKI電子証明書発行サービスでACMEを利用する際によく発生するエラーとその解決策、およびよくある質問（FAQ）をまとめています。

1. トラブルシューティングの基本（まず確認すること）

エラー時のむやみな再実行は控えてください

UPKI環境では、ドメイン所有権の確認（チャレンジ）に20回失敗すると、翌日まで処理が制限（Rate Limit）されます。エラーが発生した場合は、再実行する前に必ず原因を特定し、クライアントツールのログを確認してください。

主なログの確認場所：
Certbot: /var/log/letsencrypt/letsencrypt.log
acme.sh: 各ユーザーのホームディレクトリ配下（例：~/.acme.sh/acme.sh.log や /root/.acme.sh/acme.sh.log）

2. よくあるエラーと解決策（症状別）

【アカウント登録時のエラー】

症状: EAB Credentials rejected / Unauthorized / MAC key is invalid
- 主な原因と対策:
  - コピーミスの確認: 登録担当者から受け取った MAC Key や Key ID の前後に、不要な空白や改行が含まれていないか確認してください。
  - 再利用の禁止と移行制限: EAB Credentialを用いたACMEアカウント登録は、原則として1サーバー（1つのACMEアカウント）につき1回のみ実行可能です。すでに別のサーバー（別のアカウント）で初期設定に使用したEAB情報を再利用することはできません。また、サーバーの移設や移行に伴う場合も、既存のEABの使い回しやアカウント移行は行えないため、新しくEABを発行し直してください。

【チャレンジ（ドメイン確認）失敗時のエラー】

症状: Timeout / Connection refused / Name does not resolve（ホスト名解決エラー）
- 原因と対策:
  - ファイアウォール・ポートの確認: サーバのファイアウォールや、クラウド環境（AWS, Azure等）のセキュリティグループで、外部からの TCP 80番ポート の通信が遮断されています。外部から対象ドメインの80番ポートにアクセスできるよう設定を変更してください。
  - DNS名前解決の確認: 発行対象のホスト名（FQDN）が学内・組織内の内部DNSのみに登録されており、インターネット上に公開されていない場合、外部の認証局からドメインを解決できずにエラーになります。対象ドメインのAレコードがパブリックDNSサーバーに登録され、外部から名前解決できる状態か確認してください。
症状: 404 Not Found / 403 Forbidden / Unauthorized（検証ファイルアクセスエラー）
- 原因と対策:
  - ドキュメントルートの確認: 指定した Webroot（公開フォルダのパス、例：-w /var/www/html）が間違っています。実際のWebサーバのドキュメントルートと一致しているか確認してください。
  - アクセス制御の確認: Webサーバの設定で、検証用フォルダ（/.well-known/acme-challenge/）へのアクセス制限（BASIC認証やIPアドレス制限など）がかかっていると検証に失敗します。このフォルダ配下については一時的に認証なしでアクセスできるようWebサーバの設定を調整してください。
  - リダイレクト設定の確認: HTTP（ポート80番）へのアクセスに対して、HTTPSへの強制リダイレクトや複雑なURL転送ルールが設定されている場合、検証用ファイルへのアクセスが正しくルーティングされずにエラーになることがあります。検証ディレクトリへのアクセスはリダイレクトをバイパスして直接アクセスできるように設定してください。

【証明書の発行・署名（finalize）失敗時のエラー】

ドメイン所有確認（チャレンジ）は成功するのに、その直後の証明書発行（署名／finalize）の段階で失敗するパターンです。原因の多くは「鍵」に関するものです。

症状: チャレンジ成功後に発行が失敗する。acme.errors.IssuanceError（Certbot）や Signing error: wrong status（acme.sh）が表示され、サーバー応答に "type":"urn:ietf:params:acme:error:malformed" と 異常終了 が含まれる。
- 原因と対策（鍵タイプの不一致）:
  - EAB Credential発行時に指定した証明書プロファイル（RSA / ECDSA）と、ACMEクライアントが生成した鍵の種類が一致していないと、このエラーになります。
  - 近年の Certbot（2.0以降） と acme.sh（3.0.6以降） は、生成する鍵のデフォルトがECDSAに変更されています。UPKIで RSAプロファイル（多くの場合こちら）を利用している場合は、鍵タイプを明示してください。
    - Certbot: --key-type rsa
    - acme.sh: --keylength 2048
    - win-acme: settings.json の Csr.Rsa.KeyBits を 2048 に変更（既定の 3072 はUPKIで拒否され、CSRの設定値が不正です。[鍵長が許可された長さではありません。] エラーになります）
  - ECDSAプロファイルの場合は ECDSA を指定します（UPKIのECDSAは P-384。Certbot: --key-type ecdsa / acme.sh: --keylength ec-384 / win-acme: Csr.DefaultCsr を "ec"）。
  - 詳細は各クライアントガイド（Certbot / acme.sh / win-acme）を参照してください。
症状（更新時のみ）: 新規発行は成功するが、更新（再発行）時だけ失敗する。サーバー応答に 公開鍵が同一の証明書が発行済みのため更新発行を行えません（malformed）が含まれる。
- 原因と対策（更新時の鍵再利用）:
  - UPKIのCAは同一の公開鍵での再発行を許可していません。更新のたびに新しい鍵ペアが必要です。
  - acme.sh はデフォルトで更新時に同じ鍵を再利用するため、このエラーが発生します。発行時に --always-force-new-domain-key を付け、更新ごとに鍵が再生成されるようにしてください（acme.sh ガイド参照）。
  - Certbot と win-acme はデフォルトで更新時に新しい鍵を生成するため、通常この問題は起きません（--reuse-key / --reuse-privatekey は指定しないでください）。

【注文作成時のエラー：ドメイン／EABの不一致】

症状: 注文作成（newOrder）の段階で 403 Forbidden となり、rejectedIdentifier / 事前検証済みのCNと指定されたドメインが一致しません が返る。
- 原因と対策:
  - UPKIでは、EAB Credential ごとに、申請時に事前検証・登録したFQDNのみが発行できます（主体者DNの CN〔1つ〕が固定され、これに加えて CN を含め最大8つのFQDNを SAN〔dNSName〕として1枚の証明書に指定可能）。事前登録外のドメインでは発行できないため、対象FQDN用に発行されたEABで登録してください。
  - 特に win-acme は一度登録したアカウントを再利用するため、別ドメイン用のEABに切り替えるには、保存済みアカウント（%ProgramData%\win-acme\<エンドポイント>\ 内の Registration_v2 / Signer_v2）を削除してから再登録する必要があります（win-acmeガイド参照）。

【制限・上限に関するエラー】

症状: Rate Limit Exceeded
- 原因と対策: チャレンジに20回失敗し、制限がかかっています。設定を見直した上で、制限が解除される翌日以降に再度実行してください。

3. FAQ（よくある質問）

Q. ファイアウォールで許可すべき通信元IPアドレスは決まっていますか？

A. いいえ、UPKI側のACMEサーバーおよび認証局（CA）の検証システム（分散サーバー）側の接続元IPアドレス帯は公開されておらず、随時変動します。一般的なACMEの仕様と同様に、世界中の任意のIPアドレスから対象サーバの TCP 80番ポート へアクセスできるよう、ファイアウォールを開放しておく必要があります。（IPアドレスによるアクセス制限は行わないでください）

Q. ワイルドカード証明書（`*.example.ac.jp`）は発行できますか？

A. いいえ、発行できません。 UPKI電子証明書発行サービスではワイルドカード証明書はサポートされておらず、今後もサポートする予定はありません。サブドメインが必要な場合は、それぞれ個別のドメイン（FQDN）として証明書を発行してください。

【代替手段（SANsの利用）】 1枚の証明書に複数のFQDNを登録する「SANs（Subject Alternative Names：主体者別名）」機能が利用可能です。TSVファイル作成時に対象のFQDNを複数指定することで、1枚の証明書で複数の異なるサブドメインを同時にカバー（検証可能に）できます。ホスト名が多い場合はこの代替手段の活用をご検討ください。

Q. 自動更新が動きません。どこを確認すればよいですか？

A. クライアントツールがOSに登録したスケジューラ（cron や systemd タイマー、Windowsの場合はタスクスケジューラ）が正常に稼働しているか確認してください。また、更新自体は成功しているがWebサーバに反映されていない場合は、更新後の再起動コマンド（--deploy-hook 等）が正しく設定されているか見直してください。

「更新がスキップされる」のは正常な場合があります（ARI）

スケジューラが動いていても、更新の時期がまだ来ていないために意図的にスキップされているだけのこともあります。UPKIのCAは ARI（ACME Renewal Information）に対応しており、対応バージョンのクライアント（acme.sh の新版、Certbot 4.1.0 以降など）は、CAが提示する更新推奨期間（suggestedWindow）が来るまで更新を行いません。これは異常ではなく正常な動作です。実際に更新処理が走るか今すぐ確認したい場合は、強制更新（Certbot: --dry-run、acme.sh: --force）を利用してください。

なお、acme.sh をお使いで、更新時に 公開鍵が同一の証明書が発行済みのため... というエラーが出る場合は、更新時の鍵再利用が原因です。上記「2. よくあるエラーと解決策」の【証明書の発行・署名（finalize）失敗時のエラー】を参照してください。

Q. 証明書の秘密鍵が漏洩した可能性があります。どうすればよいですか？

A. 速やかに証明書の失効（Revoke）手続きを行う必要があります。ACMEクライアントの失効コマンドを実行するか、UPKIポータル等を通じて失効処理を行ってください。その後、安全な環境で新しく秘密鍵と証明書を再発行してください。

Q. 1台のサーバ（Certbot）で複数の異なる EAB Credential を使い分けることはできますか？

A. はい、可能です。通常、Certbot は1つのACMEアカウント（EAB）のみをデフォルトとして保持しますが、設定ディレクトリやアカウント情報を分けることで、複数の EAB Credential を使い分けることができます。複数ドメインや別組織の証明書を1台のサーバで個別に更新したい場合などに有効です。

具体的な設定方法や運用の注意点については、複数EAB環境でのCertbot設定ガイドで詳細に解説していますので、そちらをご参照ください。