TWCA SSL 憑證鏈離線更新工具(Tomcat / Apache / Nginx)
=====================================================

【本工具程式無連網功能，無須擔心金鑰外洩】
・不會連線到任何網站或伺服器(包含 TWCA)，所有處理都在這台電腦上完成。
・私鑰只在本機讀取，用來確認新憑證與私鑰是同一對，不會被傳送或複製到其他地方。
・程式中沒有任何網路功能，也不會呼叫其他程式。
・不會停止、重新啟動或重新載入伺服器，只更新檔案；由管理人員手動進行。

整個工具只有 twca-cert-updater.jar 一個檔案，需要 Java 8 以上(Tomcat 主機用 Tomcat 本身的 Java 即可)。
選擇的目錄會自動判斷是哪一種伺服器：
  ・Tomcat：根目錄(裡面有 conf\server.xml)
  ・Apache：安裝目錄或設定目錄(httpd.conf / apache2.conf)，例如 C:\Apache24、/etc/httpd、/etc/apache2
  ・Nginx ：nginx.conf 所在目錄，例如 C:\nginx、/etc/nginx
也可以直接選 server.xml、httpd.conf、nginx.conf 這個檔案。


一、下載新憑證
--------------
在可上網的電腦開啟以下網址(sn 為憑證序號，工具畫面上可直接複製)：
  https://ssl2.twca.com.tw/NCWebSSL/cert.htm?sn=<序號>&type=zip
把下載的 zip 檔(不用解壓縮)複製到 Tomcat 所在的伺服器。


二、Windows(圖形介面)
----------------------
1. 雙擊 twca-cert-updater.jar 開啟。
   若雙擊沒有反應，請開啟命令提示字元執行：java -jar twca-cert-updater.jar
   Tomcat 裝在 C:\Program Files 等受保護的目錄時，請以「系統管理員身分」開啟命令提示字元再執行。
2. ① 按[瀏覽…]選擇伺服器目錄(Tomcat / Apache / Nginx，見上方說明)。
   工具會自動讀取設定檔，找出憑證、私鑰與 keystore 的位置。
3. ② 按[瀏覽…]選擇剛才的 zip 檔(也可以選一個資料夾，裡面放多個網域的 zip 檔)。
   工具會用公鑰自動配對，表格顯示「√ 公鑰相符」即可更新。
4. ③ 按[開始更新]。
5. 完成後請自行重新啟動或重新載入伺服器，新的憑證鏈才會生效：
     Tomcat：重新啟動服務或 startup.bat
     Apache：httpd -k graceful(Windows 服務)、apachectl graceful 或 systemctl reload httpd / apache2
     Nginx ：nginx -s reload 或 systemctl reload nginx


三、Linux / Unix(命令列)
------------------------
請用 root 或 Tomcat 檔案的擁有者執行(工具會保留原檔的擁有者與權限)。

  # 試跑：只顯示配對結果，不修改任何檔案
  java -jar twca-cert-updater.jar --cli --tomcat /opt/tomcat --source /tmp/cert.zip

  # 確認沒問題後實際更新
  java -jar twca-cert-updater.jar --cli --tomcat /opt/tomcat --source /tmp/cert.zip --apply

  # 還原上次備份
  java -jar twca-cert-updater.jar --cli --tomcat /opt/tomcat --rollback

keystore 密碼讀不到時(例如密碼寫在啟動參數 -D 裡)，工具會在主控台詢問(輸入時不顯示)；
也可以用參數提供：--keystore-pass <密碼>，私鑰另有密碼時再加 --key-pass <密碼>。
注意：寫在命令列的密碼可能留在命令歷史中，建議優先用主控台輸入。

更新後請自行重新啟動或重新載入伺服器(例如 systemctl restart tomcat、apachectl graceful、nginx -s reload)。
--tomcat 也可以寫成 --server，後面接 Apache / Nginx 的目錄同樣適用。
命令列模式在 Windows 上也可以使用。


四、工具會做的事
----------------
・備份：更新前一律先備份，即使這次不會修改：
    憑證檔、既有的 chain 檔、keystore、私鑰檔、主設定檔與站台所在的設定檔
    (Tomcat 另外備份 catalina.properties)，複製到 twca-cert-backup/<日期時間>/
  (Tomcat 在 conf 底下；Apache / Nginx 在主設定檔所在目錄底下；備份檔名加上 .bak，
  不會被 *.conf 萬用字元引用到)。私鑰與 keystore 的備份保留原檔的存取權限；
  還原時只覆寫內容有變動的檔案(私鑰本來就不會被修改，所以不會被覆寫)
・寫入：
    - PEM 設定(certificateFile / SSLCertificateFile)：憑證檔只放伺服器憑證，
      中繼憑證寫入 chain 檔；原本沒有設定 chain 檔時，會在 server.xml 補上
      certificateChainFile / SSLCertificateChainFile(Tomcat 使用 OpenSSL 時，
      串在憑證檔裡的中繼憑證不會送出，一定要用 chain 檔)。
    - Apache 2.4.8 以後：中繼憑證直接放進 SSLCertificateFile(不改設定檔)；
      已設定 SSLCertificateChainFile 的站台則沿用 chain 檔。
      Apache 2.4.7 以前(或判斷不出版本)：補上 SSLCertificateChainFile。
      版本由 httpd 執行檔 / libhttpd.dll 裡的版本字串判斷(只讀檔，不執行)。
    - Nginx：ssl_certificate 檔案寫成「伺服器憑證 + 中繼憑證」完整鏈(不改設定檔)。
      使用變數(例如 $ssl_server_name)的 ssl_certificate 無法判斷檔案，會略過並提示。
    - keystore 設定(JKS / PKCS12 / PFX)：保留原本的私鑰與密碼，只替換憑證鏈。
      密碼自動從 server.xml / catalina.properties 讀取；讀不到或不正確時才會請你輸入，
      輸入的密碼只用來開啟檔案，不會儲存，也不會寫進執行紀錄。
・同一把私鑰在檔案裡配到多張憑證時：排除已過期的，從「已生效」的憑證中挑到期日最晚的一張；
  到期日最晚的若還沒生效(生效日在未來)就不挑它，以免網站立刻出錯。執行紀錄會列出所有候選憑證與挑選原因。
・權限：改寫的檔案保留原本的擁有者與存取權限；新建的 chain 檔比照憑證檔。
  無法保留時(例如不是用 root 執行)，整批自動還原，不會留下權限不對的檔案。
・驗證：寫入後重新讀取 server.xml 與憑證檔，確認憑證鏈正確、與私鑰相符；
  不符就自動還原。
・私鑰與目前使用中的憑證不相符時(設定可能有誤)，該組設定不處理。
・私鑰內容不會被修改。私鑰與憑證放在同一個檔案時，私鑰區塊原樣保留，
  寫入後逐字比對，有任何差異就自動還原。


五、還原
--------
重新啟動 / 重新載入伺服器後網站若無法連線：
・圖形介面：按[還原上次備份]，再重新啟動 / 重新載入一次伺服器。
・命令列：java -jar twca-cert-updater.jar --cli --tomcat <伺服器目錄> --rollback
・手動：把 twca-cert-backup/<日期時間>/ 裡的 .bak 檔案去掉 .bak 複製回原位置(對照表在 backup.properties)。
