修復 SSL Certificate Problem，如何定位及常見問題的處理策略

Lonexw發表於2021-10-30

在開發過程中，使用 curl 進行請求或 git 克隆遠端倉庫時，可能會經常遇見一些 https 證照相關的錯誤，我們整理了一些常見的錯誤以及解決方案的彙總，保持更新，也歡迎你在評論中提供其他更好的方案。

知識補充：SSL / TLS 是什麼？

傳輸層安全協議（Transport Layer Security，縮寫：TLS）及其前身 SSL（ Secure Sockets Layer），是客戶端（Web 瀏覽器）與伺服器端（Web sever）之間 ? 加密通訊的安全標準協議，目的是為網際網路通訊提供安全及資料完整性保障，目前已經成為網際網路保密通訊的工業標準。

SSL 最新的技術應用趨勢及供應商（SSL certificate authority）的市場分佈，可以點選查閱。
SSL 證照線上檢查工具：What’s My Chain Cert? ｜ SSL Certificate Checker - Diagnostic Tool | DigiCert.com
如果你想為 Server 站點構建免費的 SSL 證照，可以考慮使用 Let’s Encrypt ：Let’s Encrypt ｜ Certbot

如何定位和分析錯誤資訊

Tips: 設定 debug 模式有助於你追蹤和定位具體問題真實原因所在（GIT_CURL_VERBOS 僅在 http/s 傳輸協議下有效）

# On Linux
export GIT_CURL_VERBOSE=1
export GIT_TRACE_PACKET=1
export GIT_TRACE=1

# On Window
set GIT_TRACE_PACKET=1
set GIT_TRACE=1 
set GIT_CURL_VERBOSE=1

# 如果當前機器有安裝 python，可以快速檢查證照路徑，輔助定位解決問題
python -c "import ssl; print(ssl.get_default_verify_paths())" 

# 使用 openssl 檢查站點的證照情況
openssl s_client -showcerts -connect

常見問題

問題：SSL certificate problem: unable to get local issuer certificate

原因：

如果使用自簽名證照（self-signed certificate）無法被認證時，git 或者 curl 等客戶端程式無法信任該 server 的證照，且在 Window 環境中，會因為環境配置的問題導致該類問題的出現。

解決方案：

遇到該類問題，臨時的全域性處理方案是去禁用證照驗證, ⚠️ 要注意這種做法會有潛在的安全風險（可能引發中間人攻擊 MitM attacks）。

# 使用 git 操作的全域性處理措施
# http.sslBackend: Name of the SSL backend to use (e.g. "openssl" or "schannel"). 
# This option is ignored if cURL lacks support for choosing the SSL backend at runtime.
git config --global http.sslBackend schannel

# 或者
# http.sslVerify: A boolean to enable/disable verification of the server certificate used by the SSL/TLS connection.
# ⚠️ Do NOT do this!
git config --global http.sslVerify false

# 亦可以直接設定環境變數執行 git 操作
GIT_SSL_NO_VERIFY=true git clone https://username@git.example.com/scm/repository.git

# Git Config Option Ref: https://git-scm.com/docs/git-config

如果可以從 server 端拿到 certificate.pem 檔案，可以嘗試告訴 git 程式，CA（Certificate Authority） bundle 檔案的位置來解決該問題：

# Convert the file into the X.509 format
# openssl-x509, x509 - Certificate display and signing utility
# https://www.openssl.org/docs/man1.0.2/man1/x509.html
openssl x509 -in certificate.pem -out certificate.crt
git config --system http.sslCAInfo /path/certificate.crt

# 或者可以修改 .gitconfig 的配置專案，然後重新安裝一下 git
git config --global -e

[http "https://your.domain.com"]
  # MUST be PEM format
  # Some situations require both the CAPath AND CAInfo 
  sslCAInfo = /path/to/selfCA/self-signed-certificate.crt
  sslCAPath = /path/to/selfCA/
  sslVerify = true

  # Must be PEM format and include BEGIN CERTIFICATE / END CERTIFICATE, 
  # not just the BEGIN PRIVATE KEY / END PRIVATE KEY for Git to recognise it.
  sslCert = /path/to/privatekey/myprivatecert.pem

  # Even if your PEM file is password protected, set this to false.
  # Setting this to true always asks for a password even if you don't have one.
  # When you do have a password, even with this set to false it will prompt anyhow. 
  sslCertPasswordProtected = 0

Tips：CA bundle 是一個包含根證照和中間證照的檔案，與實際證照檔案構成了完整的證照鏈。可以透過以下方式來獲取 bundle 檔案：cURL：curl.se/docs/caextract.html

~~如何獲取自簽名證照的方法不在這裡贅述。~~

其他客戶端程式也會遇到類似問題，比如 pip / conda / node，可以嘗試用類似的思路來解決：

# curl code:
    curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);

# python package
pip config set global.cert path/to/ca-bundle.crt

# conda package
conda config --set ssl_verify path/to/ca-bundle.crt

另外，有一些極少數的情況，被防火牆或防毒禁止也會出現該問題，可以嘗試關閉這些軟體來驗證是否可以解決。

相關問題：fatal: unable to access ‘https://company.domain/project.git’: SSL certificate problem: certificate has expired

如果你是在 2021 年 9 月之後遇到該問題，有可能是受到了 Let’s Encrypt DST Root CA X3 Expiration (September 2021) 的影響，可以嘗試以下的方法來解決。

Ubuntu 14.04 LTS (Trusty Tahr) or Ubuntu 16.04.6 LTS (Xenial Xerus) 執行環境：

# 編輯檔案 /etc/ca-certificates.conf, 找到該證照並註釋
!mozilla/DST_Root_CA_X3.crt

# 或者直接命令列處理
sudo sed -i -e 's/mozilla\/DST_Root_CA_X3\.crt/!mozilla\/DST_Root_CA_X3\.crt/g' /etc/ca-certificates.conf

# 儲存檔案後執行命令
sudo rm /usr/share/ca-certificates/mozilla/DST_Root_CA_X3.crt
sudo update-ca-certificates

Mac OS X 10.13.6 (High Sierra) 上面, cURL(and therefore Git) 依賴於 /etc/ssl/cert.pem 去處理根證照認證，你可以手動移除 DST Root CA X3
如果你有使用 certbot 也需要升級到最新版本，renew 站點證照去移除 DST Root CA X3 的潛在問題

sudo certbot renew --force-renewal --preferred-chain "ISRG Root X1"

在 Window 環境中，你可以嘗試把 git 升級到最新版本，會解決該問題。