證失敗排查指南：從TLS握手到根證書修復(fù))
先說一個(gè)結(jié)論代碼里蹦出[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed這一長串報(bào)錯(cuò)大多數(shù)情況下不是你的業(yè)務(wù)代碼邏輯出了問題而是當(dāng)前運(yùn)行環(huán)境里缺少一份能被信任的根證書清單。你向某個(gè) HTTPS 地址發(fā)請(qǐng)求服務(wù)器把自己的證書遞過來本地的證書校驗(yàn)組件核對(duì)一番之后直接表示不信任TLS 握手就會(huì)停在最后一步于是異常信息里除了證書驗(yàn)證失敗之外還會(huì)帶上“握手失敗”的描述。這個(gè)問題我在幾個(gè)項(xiàng)目里都踩過。某次內(nèi)部報(bào)表服務(wù)調(diào)用另一個(gè)團(tuán)隊(duì)的結(jié)算接口請(qǐng)求發(fā)過去就拋這個(gè)錯(cuò)當(dāng)時(shí)排查了大半天最后發(fā)現(xiàn)只是服務(wù)器上的根證書庫沒更新。還有一次是 Python 爬蟲在灰度環(huán)境里批量抓數(shù)據(jù)跑著跑著突然成片報(bào)錯(cuò)原因是調(diào)試代理工具替換了證書代碼里又沒把對(duì)應(yīng) CA 加入信任列表。不同語言、不同框架下的報(bào)錯(cuò)原文不完全一樣但它們背后的機(jī)制是相通的要么證書鏈斷了要么根證書缺失要么中間層的證書被換了。這篇文章把 root cause、排查方法、各語言下的修復(fù)方式都捋一遍碰到同類問題可以直接照著處理。1. Cert verify failed 是什么先搞清楚 TLS 握手里發(fā)生了什么1.1 報(bào)錯(cuò)長什么樣通常發(fā)生在哪些場景先看幾個(gè)典型的報(bào)錯(cuò)形態(tài)。Python 的 requests 或者 urllib3 通常會(huì)拋requests.exceptions.SSLError: HTTPSConnectionPool(hostapi.example.com, port443): Max retries exceeded with url: /v1/data (Caused by SSLError(SSLCertVerificationError(1, [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1125))))Node.js 里請(qǐng)求 HTTPS 接口時(shí)可能會(huì)看到Error: certificate has expired at TLSSocket.onConnectSecure ...用 curl 命令行訪問時(shí)也可能直接輸出curl: (60) SSL certificate problem: unable to get local issuer certificate雖然各家報(bào)錯(cuò)措辭不同但關(guān)鍵點(diǎn)都指向同一件事無法獲得本地簽發(fā)者證書也就是無法完成證書鏈的校驗(yàn)。這說明客戶端在驗(yàn)證“對(duì)方證書是不是由可信的 CA 簽發(fā)”時(shí)找不到可信的根。這種問題經(jīng)常出現(xiàn)在這么幾個(gè)場景里新裝好的 Python、Node.js 環(huán)境直接跑 HTTPS 請(qǐng)求就報(bào)錯(cuò)系統(tǒng)證書庫本身不完整。內(nèi)網(wǎng)服務(wù)調(diào)用對(duì)方使用了私有 CA 簽發(fā)的證書本機(jī)沒有信任這個(gè) CA。本地聯(lián)調(diào)時(shí)開了抓包代理代理生成的根證書沒導(dǎo)入系統(tǒng)信任區(qū)。服務(wù)器系統(tǒng)時(shí)間不對(duì)導(dǎo)致證書有效性判斷失敗。某個(gè)服務(wù)長期運(yùn)行系統(tǒng)根證書過期后沒有執(zhí)行系統(tǒng)更新。1.2 TLS 握手的基本流程與證書驗(yàn)證的位置要弄明白這個(gè)錯(cuò)需要回顧一下 TLS 握手過程。以 TLS 1.2 為例一次正常的握手大致經(jīng)過這么幾步ClientHello客戶端告訴服務(wù)器支持的 TLS 版本、加密套件以及一個(gè)隨機(jī)數(shù)。ServerHello服務(wù)器選擇協(xié)議版本和加密套件也發(fā)一個(gè)隨機(jī)數(shù)。服務(wù)器發(fā)送 Certificate把自己的證書一般是證書鏈包括葉子證書和中間證書交給客戶端。服務(wù)器發(fā)送 ServerKeyExchange / CertificateRequest按需和 ServerHelloDone。客戶端驗(yàn)證服務(wù)器證書生成預(yù)主密鑰pre-master secret用服務(wù)器公鑰加密后送回。雙方各自計(jì)算會(huì)話密鑰交換 ChangeCipherSpec完成握手。CERTIFICATE_VERIFY_FAILED發(fā)生在第 5 步也就是客戶端驗(yàn)證服務(wù)器證書的階段。客戶端拿到服務(wù)器傳來的證書之后要沿著證書鏈一層一層往上找信任錨最終必須落到一個(gè)本機(jī)預(yù)先信任的根證書上。任何一環(huán)斷裂或者某個(gè)證書過期、被撤銷、主機(jī)名不匹配驗(yàn)證都會(huì)失敗。TLS 1.3 在握手階段把所有證書消息合并在一起順序稍有不同但驗(yàn)證邏輯一致。所謂的“握手失敗”本質(zhì)就是驗(yàn)證失敗之后客戶端拒絕繼續(xù)協(xié)商密鑰直接中斷連接。所以這個(gè)錯(cuò)誤看起來是“連接層”報(bào)錯(cuò)實(shí)際是“信任層”問題。1.3 證書驗(yàn)證失敗的幾個(gè)信任原則理解這個(gè)錯(cuò)誤還要記住證書驗(yàn)證的三個(gè)基本原則鏈?zhǔn)叫湃谓K端實(shí)體證書必須由可信 CA 簽發(fā)。證書鏈可以一層套一層但最終要能找到本機(jī)信任庫里的根證書。有效期校驗(yàn)每個(gè)證書都有生效時(shí)間和失效時(shí)間。系統(tǒng)時(shí)間超出這個(gè)范圍驗(yàn)證就會(huì)失敗。尤其要注意服務(wù)器證書本身有效但中間證書或根證書過期同樣會(huì)導(dǎo)致失敗。用途校驗(yàn)證書的擴(kuò)展項(xiàng)里限制了用途比如只能用于服務(wù)端認(rèn)證。如果請(qǐng)求的連接方式與證書用途不匹配也會(huì)報(bào)錯(cuò)。很多人在排查時(shí)報(bào)錯(cuò)定位到了“證書驗(yàn)證失敗”就停了其實(shí)應(yīng)該繼續(xù)追問是哪一層驗(yàn)證失敗是找不到根證書還是證書鏈不完整還是時(shí)間不正確還是主機(jī)名不匹配這幾個(gè)方向?qū)?yīng)完全不同的修復(fù)手段。2. 六大根因定位為什么證書驗(yàn)證會(huì)失敗2.1 根證書缺失或過期是最常見的原因開發(fā)機(jī)、測試服務(wù)器上的根證書不是一成不變的。操作系統(tǒng)和運(yùn)行語言各自維護(hù)一份證書庫。常見的 Linux 發(fā)行版安裝了ca-certificates包之后根證書會(huì)放在/etc/ssl/certs/下并生成一個(gè)哈希索引。如果這個(gè)包長期沒更新新出現(xiàn)的商業(yè) CA 根證書就不會(huì)出現(xiàn)在里邊客戶端自然無法驗(yàn)證新簽發(fā)的服務(wù)器證書。某些國外或國內(nèi) CA 在特定時(shí)間段啟用了新的根證書同時(shí)服務(wù)器端只發(fā)新鏈不完全兼容舊根。這種情況在老舊鏡像里特別容易出現(xiàn)因?yàn)殓R像構(gòu)建時(shí)打包的系統(tǒng)包快照已經(jīng)過時(shí)?，F(xiàn)象就是同樣的代碼在本機(jī)能跑通放到某個(gè)服務(wù)器或容器的鏡像里就報(bào)錯(cuò)這就是兩個(gè)環(huán)境的證書庫內(nèi)容不一致。2.2 語言運(yùn)行環(huán)境與系統(tǒng)證書庫不同步Python 是一個(gè)重災(zāi)區(qū)。Python 默認(rèn)使用 OpenSSL 來執(zhí)行 TLS 連接而 OpenSSL 讀取證書庫的位置取決于編譯參數(shù)和運(yùn)行環(huán)境配置。有些 Python 發(fā)行版在安裝時(shí)會(huì)附帶自己的 OpenSSL 庫和證書文件它可能并不讀取系統(tǒng)的/etc/ssl/certs而是讀取安裝目錄下的某個(gè)證書文件。這就解釋了為什么會(huì)出現(xiàn)“明明系統(tǒng)配置好了 CAPython 還是報(bào)錯(cuò)”的怪現(xiàn)象。你在系統(tǒng)層面信任的根證書跟 Python 進(jìn)程實(shí)際讀取的根證書可能是兩份完全不同的文件。Node.js 也一樣。Node 的 TLS 實(shí)現(xiàn)默認(rèn)使用系統(tǒng)內(nèi)置的根證書集合但當(dāng)運(yùn)行環(huán)境中存在NODE_EXTRA_CA_CERTS變量時(shí)加載邏輯又會(huì)發(fā)生變化。如果該文件路徑不存在或格式不合法Node 可能退回到不完整的內(nèi)置證書集合甚至導(dǎo)致額外的驗(yàn)證失敗。2.3 系統(tǒng)時(shí)間漂移導(dǎo)致的驗(yàn)證失敗證書有效期校驗(yàn)依賴一方是相對(duì)精確的系統(tǒng)時(shí)間。如果服務(wù)器或客戶端的時(shí)間差了很遠(yuǎn)比如分鐘級(jí)錯(cuò)誤證書的“not before”和“not after”判斷就會(huì)失敗。曾有一個(gè)案例一臺(tái)物理機(jī)因?yàn)橹靼?CMOS 電池沒電系統(tǒng)時(shí)間停在了初始化那一年跑任何 HTTPS 請(qǐng)求全部報(bào)證書驗(yàn)證失敗。用date命令看了一眼時(shí)間立刻反應(yīng)過來。還有一種隱蔽情況是虛擬機(jī)或容器的時(shí)區(qū)設(shè)置正確但硬件時(shí)鐘偏低。Linux 虛機(jī)沒有同步硬件時(shí)間啟動(dòng)后時(shí)間停留在上次關(guān)機(jī)時(shí)間點(diǎn)也會(huì)觸發(fā)這個(gè)問題。2.4 本地開啟調(diào)試代理或抓包工具導(dǎo)致證書被替換客戶端與服務(wù)器之間如果多了一層代理代理為了解密流量會(huì)生成自己的 CA 證書并用這個(gè) CA 動(dòng)態(tài)簽發(fā)目標(biāo)域名的證書從而實(shí)現(xiàn)中間人解密。Charles、Fiddler、Wireshark 配合的相關(guān) SSL 代理還有瀏覽器抓包插件都是這種做法。當(dāng)你開著這種代理代碼里的 HTTPS 請(qǐng)求實(shí)際拿到的并不是服務(wù)器真正的證書而是代理簽發(fā)的證書。只要代理的根證書沒有被加入系統(tǒng)或語言的信任區(qū)證書驗(yàn)證一定失敗。此時(shí)你去看報(bào)錯(cuò)的服務(wù)器證書信息會(huì)發(fā)現(xiàn)它指向的域名雖然是目標(biāo)域名但證書鏈頂端不是公開的根 CA而是代理自己的根證書。這種情況在本地開發(fā)時(shí)非常常見不少人折騰半天甚至還會(huì)反過來懷疑是服務(wù)器證書出了問題。2.5 自簽名證書與私有 CA 的信任問題有些內(nèi)網(wǎng)系統(tǒng)、開發(fā)環(huán)境、或者私有化交付的軟件會(huì)使用自簽名證書。自簽名證書沒有上級(jí) CA 為其背書它的信任和權(quán)威完全取決于客戶端是否提前導(dǎo)入。如果代碼所在機(jī)器沒有導(dǎo)入對(duì)應(yīng)的證書驗(yàn)證必然失敗。私有 CA 情況稍微復(fù)雜一點(diǎn)。它雖然有自己的根證書和中間證書但公共系統(tǒng)默認(rèn)不會(huì)信任這些私有根。你需要把私有根證書導(dǎo)入操作系統(tǒng)、語言、或者在代碼里顯式指定。2.6 服務(wù)器端證書鏈不完整客戶端驗(yàn)證證書鏈時(shí)需要拿到完整鏈路。如果服務(wù)器只發(fā)了葉子證書而沒有把中間證書一并發(fā)送客戶端在本地證書庫中找不到對(duì)應(yīng)的上級(jí)證書就會(huì)提示unable to get local issuer certificate。這種情況適合用openssl s_client直接檢查服務(wù)器返回的證書鏈能一眼看出少了一層。3. 實(shí)操一套通用的修復(fù)流程3.1 先確認(rèn)到底是誰的證書不信任拿到這個(gè)報(bào)錯(cuò)之后第一步不是改代碼而是驗(yàn)證服務(wù)端證書本身?？梢韵扔妹钚泄ぞ呖匆谎蹖?duì)方服務(wù)器返回的證書鏈openssl s_client -connect api.example.com:443 -showcerts -servername api.example.com如果verify return code: 0 (ok)說明服務(wù)端證書鏈本身沒問題問題大概率出在本機(jī)信任庫。如果返回不是 0比如unable to get local issuer certificate或unable to verify the first certificate要重點(diǎn)檢查服務(wù)器發(fā)送的證書鏈?zhǔn)欠裢暾?。再檢查本機(jī)時(shí)間date偏差超過幾分鐘可以直接修正時(shí)間后再測。這是成本最低的排查手段。檢查當(dāng)前環(huán)境的證書庫是否完整也是這里的關(guān)鍵步驟。3.2 更新系統(tǒng)級(jí)證書庫如果是系統(tǒng)證書庫過期在 Debian 系的 Linux 發(fā)行版上可以執(zhí)行sudo apt-get update sudo apt-get install --reinstall ca-certificates sudo update-ca-certificatesupdate-ca-certificates命令會(huì)掃描/usr/local/share/ca-certificates/下的自定義證書并重新生成/etc/ssl/certs/下的證書索引。執(zhí)行完之后大部分的“系統(tǒng)級(jí)”報(bào)錯(cuò)都能解決。RHEL 系的發(fā)行版使用update-ca-trustsudo yum install -y ca-certificates sudo update-ca-trust force-enable sudo update-ca-trust extract更新完系統(tǒng)證書庫之后用 curl 再測試一次同一個(gè)地址curl https://api.example.com/v1/data如果 curl 已經(jīng)能連通說明問題確實(shí)出在系統(tǒng)信任層。后面再逐個(gè)檢查語言環(huán)境。3.3 Python 環(huán)境里利用 certifi 顯式指定證書在 Python 里最簡單可靠的修復(fù)就是把 requests 使用的證書指向 certifi 提供的 CA 包。certifi 是一個(gè)維護(hù)得很及時(shí)的根證書集合它會(huì)跟隨 requests 等庫一起分發(fā)。pip install --upgrade certifi然后在代碼里顯式傳入import requests import certifi resp requests.get(https://api.example.com/v1/data, verifycertifi.where())這樣 requests 在構(gòu)建 SSLContext 時(shí)會(huì)使用 certifi 的 CA 文件而不是默認(rèn)的 system store。如果項(xiàng)目里用到了 urllib3 的 PoolManager也可以指定 ca_certsimport urllib3 import certifi http urllib3.PoolManager( cert_reqsCERT_REQUIRED, ca_certscertifi.where() ) resp http.request(GET, https://api.example.com/v1/data)如果系統(tǒng)級(jí) CA 已經(jīng)修好理論上 requests 也會(huì)正常工作。但顯式指定 certifi 有個(gè)好處它不依賴系統(tǒng)目錄權(quán)限也不怕 Python 環(huán)境里的 OpenSSL 配置混亂。我建議在腳本化的項(xiàng)目里直接把它寫進(jìn)公共請(qǐng)求封裝里。對(duì)于 aiohttp 或 httpx則可以分別參考下面的寫法import aiohttp import certifi import ssl ssl_ctx ssl.create_default_context(cafilecertifi.where()) async with aiohttp.ClientSession(connectoraiohttp.TCPConnector(sslssl_ctx)) as session: ...import httpx client httpx.Client(verifycertifi.where())3.4 設(shè)置環(huán)境變量解決 OpenSSL 證書路徑問題OpenSSL 類的程序會(huì)讀取SSL_CERT_FILE和SSL_CERT_DIR環(huán)境變量。當(dāng)發(fā)現(xiàn) OpenSSL 讀的證書跟系統(tǒng)不同步時(shí)可以直接把變量指到系統(tǒng)證書目錄export SSL_CERT_FILE/etc/ssl/certs/ca-certificates.crt export SSL_CERT_DIR/etc/ssl/certs也可以指到 certifi 的證書文件export SSL_CERT_FILE$(python -m certifi)這種方式對(duì)很多用 libcurl 編寫、或者使用系統(tǒng) OpenSSL 的組件有效。把它寫進(jìn)項(xiàng)目的啟動(dòng)腳本或者部署配置里不用改代碼就能全局生效。CURL_CA_BUNDLE環(huán)境變量可以影響 curl 的證書加載不過沒有SSL_CERT_FILE的范圍廣兩處最好保持一致。3.5 Node.js 導(dǎo)入額外 CANode.js 項(xiàng)目如果遇到系統(tǒng) CA 不匹配臨時(shí)方式是指定NODE_EXTRA_CA_CERTS環(huán)境變量指向一個(gè)包含額外 CA 證書的文件export NODE_EXTRA_CA_CERTS/path/to/extra-ca.pem node app.js這個(gè)環(huán)境變量會(huì)把指定的 CA 追加到 Node 默認(rèn)證書集合里。它適合處理私有 CA、企業(yè)內(nèi)網(wǎng) CA 的場景。如果是全局信任的問題可以把根證書放到/etc/ssl/certs/并執(zhí)行update-ca-certificatesNode 在多數(shù) Linux 發(fā)行版上會(huì)讀取系統(tǒng)信任鏈。不過要注意不同版本的 Node 對(duì)系統(tǒng)證書庫的加載方式略有差異某些版本基于內(nèi)置的根證書列表某些版本會(huì)直接走系統(tǒng) OpenSSL。所以最穩(wěn)妥的方式是環(huán)境變量顯式追加。npm 如果連 registry 都拉不動(dòng)出現(xiàn)證書驗(yàn)證失敗可以優(yōu)先看下 npm 的配置npm config list檢查cafile和strict-ssl配置。正常情況下strict-ssl應(yīng)該保持true不要為了省事把它關(guān)掉。如果內(nèi)網(wǎng) npm 源使用私有證書用cafile指向?qū)?yīng)證書文件即可。4. 自簽名證書與私有 CA 的工程化處理4.1 導(dǎo)出證書內(nèi)容與抓取證書鏈處理自簽名證書最常用的命令是通過openssl s_client拿到證書鏈并導(dǎo)出openssl s_client -connect inner.example.com:443 -showcerts -servername inner.example.com /dev/null /tmp/chain.pem文件里會(huì)有多個(gè)證書塊。找到根證書一般是最后一個(gè)證書塊保存為my-ca.crt。如果連的是內(nèi)網(wǎng) HTTPS 服務(wù)且先前能通過瀏覽器訪問也可以在瀏覽器里點(diǎn)擊地址欄的鎖圖標(biāo)選擇“查看證書”導(dǎo)出根證書。導(dǎo)出格式選 Base64 編碼的 PEM 格式就可以。4.2 信任自簽名證書或私有 CA拿到根證書之后在系統(tǒng)層面配置信任。Debian 系發(fā)行版的做法是把證書放到/usr/local/share/ca-certificates/目錄下文件后綴必須是.crtsudo cp my-ca.crt /usr/local/share/ca-certificates/my-ca.crt sudo chmod 644 /usr/local/share/ca-certificates/my-ca.crt sudo update-ca-certificates這樣系統(tǒng)級(jí)信任就建立起來了curl、一部分通過系統(tǒng) OpenSSL 入網(wǎng)的程序都會(huì)生效。如果不想動(dòng)系統(tǒng)目錄只影響單個(gè) Python 項(xiàng)目就把根證書文件放到項(xiàng)目里并在 requests 請(qǐng)求時(shí)指定requests.get(https://inner.example.com, verify./certs/my-ca.crt)Node.js 側(cè)繼續(xù)用NODE_EXTRA_CA_CERTS環(huán)境變量處理。4.3 容器環(huán)境里的證書更新Docker 鏡像是證書驗(yàn)證失敗的另一個(gè)常見場景。鏡像往往是在幾個(gè)月甚至一年前構(gòu)建的內(nèi)部沒有運(yùn)行包管理器的升級(jí)流程。運(yùn)行鏡像后連接互聯(lián)網(wǎng) HTTPS 服務(wù)報(bào)錯(cuò)提示找不到簽發(fā)者證書。推薦的做法是修改 Dockerfile在構(gòu)建階段刷新證書庫RUN apt-get update \ apt-get install -y ca-certificates \ rm -rf /var/lib/apt/lists/*如果鏡像運(yùn)行時(shí)需要訪問內(nèi)網(wǎng)服務(wù)且內(nèi)網(wǎng)服務(wù)使用私有 CA可以把 CA 證書 COPY 進(jìn)鏡像然后在構(gòu)建時(shí)執(zhí)行COPY my-ca.crt /usr/local/share/ca-certificates/my-ca.crt RUN chmod 644 /usr/local/share/ca-certificates/my-ca.crt update-ca-certificates在 Kubernetes 或容器平臺(tái)里也可以把 CA 以 ConfigMap 掛載到指定位置然后讓應(yīng)用啟動(dòng)腳本在執(zhí)行時(shí)調(diào)用update-ca-certificates。不過掛載目錄的動(dòng)態(tài)更新不會(huì)自動(dòng)刷新系統(tǒng)證書索引所以更可靠的方案是在啟動(dòng)命令里加一步調(diào)用。4.4 代碼里臨時(shí)信任一張證書的注意點(diǎn)調(diào)試階段如果你只是臨時(shí)請(qǐng)求某個(gè)內(nèi)網(wǎng)端口測試可以加載證書對(duì)象import ssl import socket hostname inner.example.com port 443 context ssl.create_default_context(cafile./my-ca.crt) with socket.create_connection((hostname, port)) as sock: with context.wrap_socket(sock, server_hostnamehostname) as tls_sock: print(tls_sock.version())這個(gè)方式?jīng)]有全局修改任何系統(tǒng)狀態(tài)適合快速驗(yàn)證一個(gè)證書是否有效。但我得特別提醒盡量不要在真實(shí)代碼中使用verifyFalse來掩蓋錯(cuò)誤。那是把安全防線直接拆掉。這個(gè)寫法只能用于徹底隔離的調(diào)試環(huán)境而且換環(huán)境前必須改回。真到了生產(chǎn)環(huán)境無論如何都要維護(hù)正確的 CA 鏈。4.5 自己簽發(fā)證書的正確姿勢如果你每天都在自簽證書建議不要直接簽出葉子證書而是先創(chuàng)建一套私有 CA然后由這套 CA 簽發(fā)各個(gè)服務(wù)的證書。這樣只需要在客戶端信任這一個(gè) CA 根證書以后簽新證書不用再逐臺(tái)機(jī)器導(dǎo)入。創(chuàng)建私有 CA 的最小流程是# 生成 CA 私鑰 openssl genrsa -out ca-key.pem 2048 # 生成 CA 自簽名證書 openssl req -new -x509 -days 3650 -key ca-key.pem -out ca-cert.pem \ -subj /CNInternal Demo CA之后每個(gè)服務(wù)生成自己的私鑰和證書簽署請(qǐng)求openssl req -newkey rsa:2048 -nodes -keyout service-key.pem \ -out service.csr -subj /CNinner.example.com openssl x509 -req -days 825 -in service.csr \ -CA ca-cert.pem -CAkey ca-key.pem -CAcreateserial \ -out service-cert.pem -extfile ext.confext.conf里配置subjectAltNameDNS:inner.example.com這一步不能省?，F(xiàn)代客戶端校驗(yàn)證書時(shí)基本都會(huì)檢查 SAN忽略它的話即使 CA 已信任也無法避免主機(jī)名不匹配的問題。5. 不同場景下的修復(fù)差異與常見問題速查5.1 報(bào)錯(cuò)信息對(duì)照與處理方法報(bào)錯(cuò)關(guān)鍵字可能原因優(yōu)先處理方式unable to get local issuer certificate證書鏈不完整或根證書缺失更新系統(tǒng)證書庫或顯式指定 CA 文件certificate has expired證書過期或系統(tǒng)時(shí)間偏差檢查服務(wù)端證書同時(shí)校對(duì)本機(jī)時(shí)間self-signed certificate對(duì)方使用自簽證書導(dǎo)入自簽根證書或私有 CAhostname mismatch域名與證書 CN/SAN 不匹配使用正確的服務(wù)域名訪問或重新簽發(fā)匹配域名的證書wrong version number該地址其實(shí)不是 HTTPS 或端口不對(duì)檢查協(xié)議與端口配置tlsv1 alert protocol version本地 TLS 版本過低或服務(wù)器不支持該版本升級(jí) OpenSSL 與運(yùn)行語言版本5.2 Python 的 Mac 開發(fā)環(huán)境特殊案例在 macOS 上裝完 Python有時(shí)會(huì)出現(xiàn)“明明瀏覽器訪問都沒問題但 Python 請(qǐng)求就報(bào)證書驗(yàn)證失敗”。這通常是因?yàn)?Python 在安裝時(shí)沒有自動(dòng)讀取系統(tǒng)鑰匙串里的根證書。處理辦法是安裝 certifi 并配置默認(rèn)證書pip install certifi然后可以直接把 certifi 的證書路徑設(shè)置為 Python 環(huán)境變量export SSL_CERT_FILE$(python3 -m certifi)把這一行寫進(jìn)~/.zshrc或~/.bashrc。經(jīng)過這個(gè)調(diào)整Python 的 URLLIB 和 requests 就能正常訪問大多數(shù) HTTPS 服務(wù)了。如果代理工具也在用確認(rèn)代理根證書同時(shí)加入了鑰匙串與 certifi 文件。5.3 Node.js 請(qǐng)求外部服務(wù)時(shí)報(bào) verify 錯(cuò)誤Node.js 的fetch或http模塊走的是內(nèi)置 TLS。遇到證書錯(cuò)誤時(shí)先檢查是不是有NODE_EXTRA_CA_CERTS這個(gè)變量被設(shè)置成了不存在的文件路徑。有時(shí)候全局配置里殘留了早期調(diào)試的 export導(dǎo)致 Node 加載異常。用下面的命令確認(rèn)node -p process.env.NODE_EXTRA_CA_CERTS如果為空或已失效直接重設(shè)后再啟動(dòng)應(yīng)用。還想再提供一個(gè)小命令查看 Node 實(shí)際使用的 CA 數(shù)量node -e console.log(require(crypto).X509Certificate.prototype.toString.length)這個(gè)不太常用大多數(shù)時(shí)候直接看環(huán)境變量和系統(tǒng)證書庫就夠了。5.4 調(diào)試代理場景下的證書修復(fù)本地開著抓包代理時(shí)出現(xiàn)這個(gè)報(bào)錯(cuò)我的處理順序是先導(dǎo)出代理根證書。把這個(gè)根證書導(dǎo)入到系統(tǒng)信任區(qū)。Windows 證書管理器、macOS 鑰匙串、Linux 的/usr/local/share/ca-certificates/都可以。對(duì) Python如果 requests 顯式指定了verifycertifi.where()還需要把代理根證書追加到 certifi 的證書文件里。對(duì) Node.js可以通過NODE_EXTRA_CA_CERTS指定包含代理根證書的文件。驗(yàn)證時(shí)間與代理自身的有效性。debug 完成關(guān)閉代理以后如果不再需要把信任的根證書移除避免以后對(duì)正式環(huán)境的請(qǐng)求誤信任代理 CA。5.5 檢查證書庫是否生效更新完證書之后要驗(yàn)證是否真正生效。Python 里可以這樣查看當(dāng)前信任的證書路徑import ssl print(ssl.get_default_verify_paths())輸出里cafile和capath就是當(dāng)前默認(rèn)配置會(huì)去尋找的證書位置。如果和預(yù)期不符就知道問題出在哪一層。還可以用 Python 直接確認(rèn)某個(gè)證書文件能否被 OpenSSL 正確讀取python -c import ssl; ssl.create_default_context(cafile/etc/ssl/certs/ca-certificates.crt); print(ok)如果打印 ok說明證書文件格式和路徑都沒問題。5.6 生產(chǎn)環(huán)境里要不要關(guān)驗(yàn)證聽我一句生產(chǎn)環(huán)境里不要通過關(guān)閉驗(yàn)證來修復(fù)問題。verifyFalse是一時(shí)爽后續(xù)是災(zāi)難。一旦 TLS 校驗(yàn)失效中間人攻擊就變成了實(shí)際風(fēng)險(xiǎn)而且出現(xiàn)問題后很難排查。生產(chǎn)環(huán)境正確的做法是把 CA 納入版本管理隨代碼一起部署并在部署腳本里執(zhí)行證書刷新。把 CA 集中在一個(gè)受控倉庫里每次有證書更新就走變更流程才是一套可持續(xù)的方案。6. 我踩過的一些坑和最終建議最后分享幾條在實(shí)際處理中總結(jié)出的經(jīng)驗(yàn)。第一碰到這個(gè)報(bào)錯(cuò)先修系統(tǒng)時(shí)間再做后續(xù)排查。時(shí)間的坑太隱蔽了往往會(huì)消耗很久。我以前有一次排查接口報(bào)錯(cuò)檢查了證書鏈、環(huán)境變量、代理配置最后才發(fā)現(xiàn)是測試服務(wù)器的時(shí)間與標(biāo)準(zhǔn)時(shí)間差了將近三小時(shí)。當(dāng)時(shí)的感覺真是哭笑不得。第二Python 跟系統(tǒng)證書不要混在一起想。系統(tǒng) CA 更新了不代表 Python 就能立刻讀到。很多人在服務(wù)器上執(zhí)行完update-ca-certificates以為 Python 會(huì)自動(dòng)好起來實(shí)際上 Python 的 OpenSSL 不一定讀取這個(gè)路徑。顯式傳verifycertifi.where()或者設(shè)置SSL_CERT_FILE是最穩(wěn)的。第三調(diào)試代理留下的根證書要記得清理。曾經(jīng)一個(gè)項(xiàng)目在代碼里加入了抓包工具的根證書用于本地調(diào)試結(jié)果部署到預(yù)發(fā)布環(huán)境后忘了解除預(yù)發(fā)布環(huán)境的所有 HTTPS 請(qǐng)求都經(jīng)過了代理 CA 信任鏈幸好監(jiān)控發(fā)現(xiàn)得早否則生產(chǎn)環(huán)境也會(huì)帶病上線。如果你有類似調(diào)試工具一定要按環(huán)境去隔離信任配置不要一份配置通吃全部環(huán)境。第四容器鏡像的證書更新要寫進(jìn)構(gòu)建流程。不要依賴某個(gè)基礎(chǔ)鏡像自帶的證書因?yàn)殓R像構(gòu)建日期早、證書過期是很容易被忽略的定時(shí)炸彈。加一行apt-get install ca-certificates并清理緩存成本極低收益卻很直接。這幾招用下來絕大多數(shù)CERTIFICATE_VERIFY_FAILED問題都能在幾分鐘內(nèi)定位。以后再看到“握手失敗”就不至于手足無措了。 SSL證書驗(yàn)證失敗排查指南：從TLS握手到根證書修復(fù)
先說一個(gè)結(jié)論代碼里蹦出[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed這一長串報(bào)錯(cuò)大多數(shù)情況下不是你的業(yè)務(wù)代碼邏輯出了問題而是當(dāng)前運(yùn)行環(huán)境里缺少一份能被信任的根證書清單。你向某個(gè) HTTPS 地址發(fā)請(qǐng)求服務(wù)器把自己的證書遞過來本地的證書校驗(yàn)組件核對(duì)一番之后直接表示不信任TLS 握手就會(huì)停在最后一步于是異常信息里除了證書驗(yàn)證失敗之外還會(huì)帶上“握手失敗”的描述。這個(gè)問題我在幾個(gè)項(xiàng)目里都踩過。某次內(nèi)部報(bào)表服務(wù)調(diào)用另一個(gè)團(tuán)隊(duì)的結(jié)算接口請(qǐng)求發(fā)過去就拋這個(gè)錯(cuò)當(dāng)時(shí)排查了大半天最后發(fā)現(xiàn)只是服務(wù)器上的根證書庫沒更新。還有一次是 Python 爬蟲在灰度環(huán)境里批量抓數(shù)據(jù)跑著跑著突然成片報(bào)錯(cuò)原因是調(diào)試代理工具替換了證書代碼里又沒把對(duì)應(yīng) CA 加入信任列表。不同語言、不同框架下的報(bào)錯(cuò)原文不完全一樣但它們背后的機(jī)制是相通的要么證書鏈斷了要么根證書缺失要么中間層的證書被換了。這篇文章把 root cause、排查方法、各語言下的修復(fù)方式都捋一遍碰到同類問題可以直接照著處理。1. Cert verify failed 是什么先搞清楚 TLS 握手里發(fā)生了什么1.1 報(bào)錯(cuò)長什么樣通常發(fā)生在哪些場景先看幾個(gè)典型的報(bào)錯(cuò)形態(tài)。Python 的 requests 或者 urllib3 通常會(huì)拋requests.exceptions.SSLError: HTTPSConnectionPool(hostapi.example.com, port443): Max retries exceeded with url: /v1/data (Caused by SSLError(SSLCertVerificationError(1, [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1125))))Node.js 里請(qǐng)求 HTTPS 接口時(shí)可能會(huì)看到Error: certificate has expired at TLSSocket.onConnectSecure ...用 curl 命令行訪問時(shí)也可能直接輸出curl: (60) SSL certificate problem: unable to get local issuer certificate雖然各家報(bào)錯(cuò)措辭不同但關(guān)鍵點(diǎn)都指向同一件事無法獲得本地簽發(fā)者證書也就是無法完成證書鏈的校驗(yàn)。這說明客戶端在驗(yàn)證“對(duì)方證書是不是由可信的 CA 簽發(fā)”時(shí)找不到可信的根。這種問題經(jīng)常出現(xiàn)在這么幾個(gè)場景里新裝好的 Python、Node.js 環(huán)境直接跑 HTTPS 請(qǐng)求就報(bào)錯(cuò)系統(tǒng)證書庫本身不完整。內(nèi)網(wǎng)服務(wù)調(diào)用對(duì)方使用了私有 CA 簽發(fā)的證書本機(jī)沒有信任這個(gè) CA。本地聯(lián)調(diào)時(shí)開了抓包代理代理生成的根證書沒導(dǎo)入系統(tǒng)信任區(qū)。服務(wù)器系統(tǒng)時(shí)間不對(duì)導(dǎo)致證書有效性判斷失敗。某個(gè)服務(wù)長期運(yùn)行系統(tǒng)根證書過期后沒有執(zhí)行系統(tǒng)更新。1.2 TLS 握手的基本流程與證書驗(yàn)證的位置要弄明白這個(gè)錯(cuò)需要回顧一下 TLS 握手過程。以 TLS 1.2 為例一次正常的握手大致經(jīng)過這么幾步ClientHello客戶端告訴服務(wù)器支持的 TLS 版本、加密套件以及一個(gè)隨機(jī)數(shù)。ServerHello服務(wù)器選擇協(xié)議版本和加密套件也發(fā)一個(gè)隨機(jī)數(shù)。服務(wù)器發(fā)送 Certificate把自己的證書一般是證書鏈包括葉子證書和中間證書交給客戶端。服務(wù)器發(fā)送 ServerKeyExchange / CertificateRequest按需和 ServerHelloDone。客戶端驗(yàn)證服務(wù)器證書生成預(yù)主密鑰pre-master secret用服務(wù)器公鑰加密后送回。雙方各自計(jì)算會(huì)話密鑰交換 ChangeCipherSpec完成握手。CERTIFICATE_VERIFY_FAILED發(fā)生在第 5 步也就是客戶端驗(yàn)證服務(wù)器證書的階段。客戶端拿到服務(wù)器傳來的證書之后要沿著證書鏈一層一層往上找信任錨最終必須落到一個(gè)本機(jī)預(yù)先信任的根證書上。任何一環(huán)斷裂或者某個(gè)證書過期、被撤銷、主機(jī)名不匹配驗(yàn)證都會(huì)失敗。TLS 1.3 在握手階段把所有證書消息合并在一起順序稍有不同但驗(yàn)證邏輯一致。所謂的“握手失敗”本質(zhì)就是驗(yàn)證失敗之后客戶端拒絕繼續(xù)協(xié)商密鑰直接中斷連接。所以這個(gè)錯(cuò)誤看起來是“連接層”報(bào)錯(cuò)實(shí)際是“信任層”問題。1.3 證書驗(yàn)證失敗的幾個(gè)信任原則理解這個(gè)錯(cuò)誤還要記住證書驗(yàn)證的三個(gè)基本原則鏈?zhǔn)叫湃谓K端實(shí)體證書必須由可信 CA 簽發(fā)。證書鏈可以一層套一層但最終要能找到本機(jī)信任庫里的根證書。有效期校驗(yàn)每個(gè)證書都有生效時(shí)間和失效時(shí)間。系統(tǒng)時(shí)間超出這個(gè)范圍驗(yàn)證就會(huì)失敗。尤其要注意服務(wù)器證書本身有效但中間證書或根證書過期同樣會(huì)導(dǎo)致失敗。用途校驗(yàn)證書的擴(kuò)展項(xiàng)里限制了用途比如只能用于服務(wù)端認(rèn)證。如果請(qǐng)求的連接方式與證書用途不匹配也會(huì)報(bào)錯(cuò)。很多人在排查時(shí)報(bào)錯(cuò)定位到了“證書驗(yàn)證失敗”就停了其實(shí)應(yīng)該繼續(xù)追問是哪一層驗(yàn)證失敗是找不到根證書還是證書鏈不完整還是時(shí)間不正確還是主機(jī)名不匹配這幾個(gè)方向?qū)?yīng)完全不同的修復(fù)手段。2. 六大根因定位為什么證書驗(yàn)證會(huì)失敗2.1 根證書缺失或過期是最常見的原因開發(fā)機(jī)、測試服務(wù)器上的根證書不是一成不變的。操作系統(tǒng)和運(yùn)行語言各自維護(hù)一份證書庫。常見的 Linux 發(fā)行版安裝了ca-certificates包之后根證書會(huì)放在/etc/ssl/certs/下并生成一個(gè)哈希索引。如果這個(gè)包長期沒更新新出現(xiàn)的商業(yè) CA 根證書就不會(huì)出現(xiàn)在里邊客戶端自然無法驗(yàn)證新簽發(fā)的服務(wù)器證書。某些國外或國內(nèi) CA 在特定時(shí)間段啟用了新的根證書同時(shí)服務(wù)器端只發(fā)新鏈不完全兼容舊根。這種情況在老舊鏡像里特別容易出現(xiàn)因?yàn)殓R像構(gòu)建時(shí)打包的系統(tǒng)包快照已經(jīng)過時(shí)?，F(xiàn)象就是同樣的代碼在本機(jī)能跑通放到某個(gè)服務(wù)器或容器的鏡像里就報(bào)錯(cuò)這就是兩個(gè)環(huán)境的證書庫內(nèi)容不一致。2.2 語言運(yùn)行環(huán)境與系統(tǒng)證書庫不同步Python 是一個(gè)重災(zāi)區(qū)。Python 默認(rèn)使用 OpenSSL 來執(zhí)行 TLS 連接而 OpenSSL 讀取證書庫的位置取決于編譯參數(shù)和運(yùn)行環(huán)境配置。有些 Python 發(fā)行版在安裝時(shí)會(huì)附帶自己的 OpenSSL 庫和證書文件它可能并不讀取系統(tǒng)的/etc/ssl/certs而是讀取安裝目錄下的某個(gè)證書文件。這就解釋了為什么會(huì)出現(xiàn)“明明系統(tǒng)配置好了 CAPython 還是報(bào)錯(cuò)”的怪現(xiàn)象。你在系統(tǒng)層面信任的根證書跟 Python 進(jìn)程實(shí)際讀取的根證書可能是兩份完全不同的文件。Node.js 也一樣。Node 的 TLS 實(shí)現(xiàn)默認(rèn)使用系統(tǒng)內(nèi)置的根證書集合但當(dāng)運(yùn)行環(huán)境中存在NODE_EXTRA_CA_CERTS變量時(shí)加載邏輯又會(huì)發(fā)生變化。如果該文件路徑不存在或格式不合法Node 可能退回到不完整的內(nèi)置證書集合甚至導(dǎo)致額外的驗(yàn)證失敗。2.3 系統(tǒng)時(shí)間漂移導(dǎo)致的驗(yàn)證失敗證書有效期校驗(yàn)依賴一方是相對(duì)精確的系統(tǒng)時(shí)間。如果服務(wù)器或客戶端的時(shí)間差了很遠(yuǎn)比如分鐘級(jí)錯(cuò)誤證書的“not before”和“not after”判斷就會(huì)失敗。曾有一個(gè)案例一臺(tái)物理機(jī)因?yàn)橹靼?CMOS 電池沒電系統(tǒng)時(shí)間停在了初始化那一年跑任何 HTTPS 請(qǐng)求全部報(bào)證書驗(yàn)證失敗。用date命令看了一眼時(shí)間立刻反應(yīng)過來。還有一種隱蔽情況是虛擬機(jī)或容器的時(shí)區(qū)設(shè)置正確但硬件時(shí)鐘偏低。Linux 虛機(jī)沒有同步硬件時(shí)間啟動(dòng)后時(shí)間停留在上次關(guān)機(jī)時(shí)間點(diǎn)也會(huì)觸發(fā)這個(gè)問題。2.4 本地開啟調(diào)試代理或抓包工具導(dǎo)致證書被替換客戶端與服務(wù)器之間如果多了一層代理代理為了解密流量會(huì)生成自己的 CA 證書并用這個(gè) CA 動(dòng)態(tài)簽發(fā)目標(biāo)域名的證書從而實(shí)現(xiàn)中間人解密。Charles、Fiddler、Wireshark 配合的相關(guān) SSL 代理還有瀏覽器抓包插件都是這種做法。當(dāng)你開著這種代理代碼里的 HTTPS 請(qǐng)求實(shí)際拿到的并不是服務(wù)器真正的證書而是代理簽發(fā)的證書。只要代理的根證書沒有被加入系統(tǒng)或語言的信任區(qū)證書驗(yàn)證一定失敗。此時(shí)你去看報(bào)錯(cuò)的服務(wù)器證書信息會(huì)發(fā)現(xiàn)它指向的域名雖然是目標(biāo)域名但證書鏈頂端不是公開的根 CA而是代理自己的根證書。這種情況在本地開發(fā)時(shí)非常常見不少人折騰半天甚至還會(huì)反過來懷疑是服務(wù)器證書出了問題。2.5 自簽名證書與私有 CA 的信任問題有些內(nèi)網(wǎng)系統(tǒng)、開發(fā)環(huán)境、或者私有化交付的軟件會(huì)使用自簽名證書。自簽名證書沒有上級(jí) CA 為其背書它的信任和權(quán)威完全取決于客戶端是否提前導(dǎo)入。如果代碼所在機(jī)器沒有導(dǎo)入對(duì)應(yīng)的證書驗(yàn)證必然失敗。私有 CA 情況稍微復(fù)雜一點(diǎn)。它雖然有自己的根證書和中間證書但公共系統(tǒng)默認(rèn)不會(huì)信任這些私有根。你需要把私有根證書導(dǎo)入操作系統(tǒng)、語言、或者在代碼里顯式指定。2.6 服務(wù)器端證書鏈不完整客戶端驗(yàn)證證書鏈時(shí)需要拿到完整鏈路。如果服務(wù)器只發(fā)了葉子證書而沒有把中間證書一并發(fā)送客戶端在本地證書庫中找不到對(duì)應(yīng)的上級(jí)證書就會(huì)提示unable to get local issuer certificate。這種情況適合用openssl s_client直接檢查服務(wù)器返回的證書鏈能一眼看出少了一層。3. 實(shí)操一套通用的修復(fù)流程3.1 先確認(rèn)到底是誰的證書不信任拿到這個(gè)報(bào)錯(cuò)之后第一步不是改代碼而是驗(yàn)證服務(wù)端證書本身?？梢韵扔妹钚泄ぞ呖匆谎蹖?duì)方服務(wù)器返回的證書鏈openssl s_client -connect api.example.com:443 -showcerts -servername api.example.com如果verify return code: 0 (ok)說明服務(wù)端證書鏈本身沒問題問題大概率出在本機(jī)信任庫。如果返回不是 0比如unable to get local issuer certificate或unable to verify the first certificate要重點(diǎn)檢查服務(wù)器發(fā)送的證書鏈?zhǔn)欠裢暾?。再檢查本機(jī)時(shí)間date偏差超過幾分鐘可以直接修正時(shí)間后再測。這是成本最低的排查手段。檢查當(dāng)前環(huán)境的證書庫是否完整也是這里的關(guān)鍵步驟。3.2 更新系統(tǒng)級(jí)證書庫如果是系統(tǒng)證書庫過期在 Debian 系的 Linux 發(fā)行版上可以執(zhí)行sudo apt-get update sudo apt-get install --reinstall ca-certificates sudo update-ca-certificatesupdate-ca-certificates命令會(huì)掃描/usr/local/share/ca-certificates/下的自定義證書并重新生成/etc/ssl/certs/下的證書索引。執(zhí)行完之后大部分的“系統(tǒng)級(jí)”報(bào)錯(cuò)都能解決。RHEL 系的發(fā)行版使用update-ca-trustsudo yum install -y ca-certificates sudo update-ca-trust force-enable sudo update-ca-trust extract更新完系統(tǒng)證書庫之后用 curl 再測試一次同一個(gè)地址curl https://api.example.com/v1/data如果 curl 已經(jīng)能連通說明問題確實(shí)出在系統(tǒng)信任層。后面再逐個(gè)檢查語言環(huán)境。3.3 Python 環(huán)境里利用 certifi 顯式指定證書在 Python 里最簡單可靠的修復(fù)就是把 requests 使用的證書指向 certifi 提供的 CA 包。certifi 是一個(gè)維護(hù)得很及時(shí)的根證書集合它會(huì)跟隨 requests 等庫一起分發(fā)。pip install --upgrade certifi然后在代碼里顯式傳入import requests import certifi resp requests.get(https://api.example.com/v1/data, verifycertifi.where())這樣 requests 在構(gòu)建 SSLContext 時(shí)會(huì)使用 certifi 的 CA 文件而不是默認(rèn)的 system store。如果項(xiàng)目里用到了 urllib3 的 PoolManager也可以指定 ca_certsimport urllib3 import certifi http urllib3.PoolManager( cert_reqsCERT_REQUIRED, ca_certscertifi.where() ) resp http.request(GET, https://api.example.com/v1/data)如果系統(tǒng)級(jí) CA 已經(jīng)修好理論上 requests 也會(huì)正常工作。但顯式指定 certifi 有個(gè)好處它不依賴系統(tǒng)目錄權(quán)限也不怕 Python 環(huán)境里的 OpenSSL 配置混亂。我建議在腳本化的項(xiàng)目里直接把它寫進(jìn)公共請(qǐng)求封裝里。對(duì)于 aiohttp 或 httpx則可以分別參考下面的寫法import aiohttp import certifi import ssl ssl_ctx ssl.create_default_context(cafilecertifi.where()) async with aiohttp.ClientSession(connectoraiohttp.TCPConnector(sslssl_ctx)) as session: ...import httpx client httpx.Client(verifycertifi.where())3.4 設(shè)置環(huán)境變量解決 OpenSSL 證書路徑問題OpenSSL 類的程序會(huì)讀取SSL_CERT_FILE和SSL_CERT_DIR環(huán)境變量。當(dāng)發(fā)現(xiàn) OpenSSL 讀的證書跟系統(tǒng)不同步時(shí)可以直接把變量指到系統(tǒng)證書目錄export SSL_CERT_FILE/etc/ssl/certs/ca-certificates.crt export SSL_CERT_DIR/etc/ssl/certs也可以指到 certifi 的證書文件export SSL_CERT_FILE$(python -m certifi)這種方式對(duì)很多用 libcurl 編寫、或者使用系統(tǒng) OpenSSL 的組件有效。把它寫進(jìn)項(xiàng)目的啟動(dòng)腳本或者部署配置里不用改代碼就能全局生效。CURL_CA_BUNDLE環(huán)境變量可以影響 curl 的證書加載不過沒有SSL_CERT_FILE的范圍廣兩處最好保持一致。3.5 Node.js 導(dǎo)入額外 CANode.js 項(xiàng)目如果遇到系統(tǒng) CA 不匹配臨時(shí)方式是指定NODE_EXTRA_CA_CERTS環(huán)境變量指向一個(gè)包含額外 CA 證書的文件export NODE_EXTRA_CA_CERTS/path/to/extra-ca.pem node app.js這個(gè)環(huán)境變量會(huì)把指定的 CA 追加到 Node 默認(rèn)證書集合里。它適合處理私有 CA、企業(yè)內(nèi)網(wǎng) CA 的場景。如果是全局信任的問題可以把根證書放到/etc/ssl/certs/并執(zhí)行update-ca-certificatesNode 在多數(shù) Linux 發(fā)行版上會(huì)讀取系統(tǒng)信任鏈。不過要注意不同版本的 Node 對(duì)系統(tǒng)證書庫的加載方式略有差異某些版本基于內(nèi)置的根證書列表某些版本會(huì)直接走系統(tǒng) OpenSSL。所以最穩(wěn)妥的方式是環(huán)境變量顯式追加。npm 如果連 registry 都拉不動(dòng)出現(xiàn)證書驗(yàn)證失敗可以優(yōu)先看下 npm 的配置npm config list檢查cafile和strict-ssl配置。正常情況下strict-ssl應(yīng)該保持true不要為了省事把它關(guān)掉。如果內(nèi)網(wǎng) npm 源使用私有證書用cafile指向?qū)?yīng)證書文件即可。4. 自簽名證書與私有 CA 的工程化處理4.1 導(dǎo)出證書內(nèi)容與抓取證書鏈處理自簽名證書最常用的命令是通過openssl s_client拿到證書鏈并導(dǎo)出openssl s_client -connect inner.example.com:443 -showcerts -servername inner.example.com /dev/null /tmp/chain.pem文件里會(huì)有多個(gè)證書塊。找到根證書一般是最后一個(gè)證書塊保存為my-ca.crt。如果連的是內(nèi)網(wǎng) HTTPS 服務(wù)且先前能通過瀏覽器訪問也可以在瀏覽器里點(diǎn)擊地址欄的鎖圖標(biāo)選擇“查看證書”導(dǎo)出根證書。導(dǎo)出格式選 Base64 編碼的 PEM 格式就可以。4.2 信任自簽名證書或私有 CA拿到根證書之后在系統(tǒng)層面配置信任。Debian 系發(fā)行版的做法是把證書放到/usr/local/share/ca-certificates/目錄下文件后綴必須是.crtsudo cp my-ca.crt /usr/local/share/ca-certificates/my-ca.crt sudo chmod 644 /usr/local/share/ca-certificates/my-ca.crt sudo update-ca-certificates這樣系統(tǒng)級(jí)信任就建立起來了curl、一部分通過系統(tǒng) OpenSSL 入網(wǎng)的程序都會(huì)生效。如果不想動(dòng)系統(tǒng)目錄只影響單個(gè) Python 項(xiàng)目就把根證書文件放到項(xiàng)目里并在 requests 請(qǐng)求時(shí)指定requests.get(https://inner.example.com, verify./certs/my-ca.crt)Node.js 側(cè)繼續(xù)用NODE_EXTRA_CA_CERTS環(huán)境變量處理。4.3 容器環(huán)境里的證書更新Docker 鏡像是證書驗(yàn)證失敗的另一個(gè)常見場景。鏡像往往是在幾個(gè)月甚至一年前構(gòu)建的內(nèi)部沒有運(yùn)行包管理器的升級(jí)流程。運(yùn)行鏡像后連接互聯(lián)網(wǎng) HTTPS 服務(wù)報(bào)錯(cuò)提示找不到簽發(fā)者證書。推薦的做法是修改 Dockerfile在構(gòu)建階段刷新證書庫RUN apt-get update \ apt-get install -y ca-certificates \ rm -rf /var/lib/apt/lists/*如果鏡像運(yùn)行時(shí)需要訪問內(nèi)網(wǎng)服務(wù)且內(nèi)網(wǎng)服務(wù)使用私有 CA可以把 CA 證書 COPY 進(jìn)鏡像然后在構(gòu)建時(shí)執(zhí)行COPY my-ca.crt /usr/local/share/ca-certificates/my-ca.crt RUN chmod 644 /usr/local/share/ca-certificates/my-ca.crt update-ca-certificates在 Kubernetes 或容器平臺(tái)里也可以把 CA 以 ConfigMap 掛載到指定位置然后讓應(yīng)用啟動(dòng)腳本在執(zhí)行時(shí)調(diào)用update-ca-certificates。不過掛載目錄的動(dòng)態(tài)更新不會(huì)自動(dòng)刷新系統(tǒng)證書索引所以更可靠的方案是在啟動(dòng)命令里加一步調(diào)用。4.4 代碼里臨時(shí)信任一張證書的注意點(diǎn)調(diào)試階段如果你只是臨時(shí)請(qǐng)求某個(gè)內(nèi)網(wǎng)端口測試可以加載證書對(duì)象import ssl import socket hostname inner.example.com port 443 context ssl.create_default_context(cafile./my-ca.crt) with socket.create_connection((hostname, port)) as sock: with context.wrap_socket(sock, server_hostnamehostname) as tls_sock: print(tls_sock.version())這個(gè)方式?jīng)]有全局修改任何系統(tǒng)狀態(tài)適合快速驗(yàn)證一個(gè)證書是否有效。但我得特別提醒盡量不要在真實(shí)代碼中使用verifyFalse來掩蓋錯(cuò)誤。那是把安全防線直接拆掉。這個(gè)寫法只能用于徹底隔離的調(diào)試環(huán)境而且換環(huán)境前必須改回。真到了生產(chǎn)環(huán)境無論如何都要維護(hù)正確的 CA 鏈。4.5 自己簽發(fā)證書的正確姿勢如果你每天都在自簽證書建議不要直接簽出葉子證書而是先創(chuàng)建一套私有 CA然后由這套 CA 簽發(fā)各個(gè)服務(wù)的證書。這樣只需要在客戶端信任這一個(gè) CA 根證書以后簽新證書不用再逐臺(tái)機(jī)器導(dǎo)入。創(chuàng)建私有 CA 的最小流程是# 生成 CA 私鑰 openssl genrsa -out ca-key.pem 2048 # 生成 CA 自簽名證書 openssl req -new -x509 -days 3650 -key ca-key.pem -out ca-cert.pem \ -subj /CNInternal Demo CA之后每個(gè)服務(wù)生成自己的私鑰和證書簽署請(qǐng)求openssl req -newkey rsa:2048 -nodes -keyout service-key.pem \ -out service.csr -subj /CNinner.example.com openssl x509 -req -days 825 -in service.csr \ -CA ca-cert.pem -CAkey ca-key.pem -CAcreateserial \ -out service-cert.pem -extfile ext.confext.conf里配置subjectAltNameDNS:inner.example.com這一步不能省?，F(xiàn)代客戶端校驗(yàn)證書時(shí)基本都會(huì)檢查 SAN忽略它的話即使 CA 已信任也無法避免主機(jī)名不匹配的問題。5. 不同場景下的修復(fù)差異與常見問題速查5.1 報(bào)錯(cuò)信息對(duì)照與處理方法報(bào)錯(cuò)關(guān)鍵字可能原因優(yōu)先處理方式unable to get local issuer certificate證書鏈不完整或根證書缺失更新系統(tǒng)證書庫或顯式指定 CA 文件certificate has expired證書過期或系統(tǒng)時(shí)間偏差檢查服務(wù)端證書同時(shí)校對(duì)本機(jī)時(shí)間self-signed certificate對(duì)方使用自簽證書導(dǎo)入自簽根證書或私有 CAhostname mismatch域名與證書 CN/SAN 不匹配使用正確的服務(wù)域名訪問或重新簽發(fā)匹配域名的證書wrong version number該地址其實(shí)不是 HTTPS 或端口不對(duì)檢查協(xié)議與端口配置tlsv1 alert protocol version本地 TLS 版本過低或服務(wù)器不支持該版本升級(jí) OpenSSL 與運(yùn)行語言版本5.2 Python 的 Mac 開發(fā)環(huán)境特殊案例在 macOS 上裝完 Python有時(shí)會(huì)出現(xiàn)“明明瀏覽器訪問都沒問題但 Python 請(qǐng)求就報(bào)證書驗(yàn)證失敗”。這通常是因?yàn)?Python 在安裝時(shí)沒有自動(dòng)讀取系統(tǒng)鑰匙串里的根證書。處理辦法是安裝 certifi 并配置默認(rèn)證書pip install certifi然后可以直接把 certifi 的證書路徑設(shè)置為 Python 環(huán)境變量export SSL_CERT_FILE$(python3 -m certifi)把這一行寫進(jìn)~/.zshrc或~/.bashrc。經(jīng)過這個(gè)調(diào)整Python 的 URLLIB 和 requests 就能正常訪問大多數(shù) HTTPS 服務(wù)了。如果代理工具也在用確認(rèn)代理根證書同時(shí)加入了鑰匙串與 certifi 文件。5.3 Node.js 請(qǐng)求外部服務(wù)時(shí)報(bào) verify 錯(cuò)誤Node.js 的fetch或http模塊走的是內(nèi)置 TLS。遇到證書錯(cuò)誤時(shí)先檢查是不是有NODE_EXTRA_CA_CERTS這個(gè)變量被設(shè)置成了不存在的文件路徑。有時(shí)候全局配置里殘留了早期調(diào)試的 export導(dǎo)致 Node 加載異常。用下面的命令確認(rèn)node -p process.env.NODE_EXTRA_CA_CERTS如果為空或已失效直接重設(shè)后再啟動(dòng)應(yīng)用。還想再提供一個(gè)小命令查看 Node 實(shí)際使用的 CA 數(shù)量node -e console.log(require(crypto).X509Certificate.prototype.toString.length)這個(gè)不太常用大多數(shù)時(shí)候直接看環(huán)境變量和系統(tǒng)證書庫就夠了。5.4 調(diào)試代理場景下的證書修復(fù)本地開著抓包代理時(shí)出現(xiàn)這個(gè)報(bào)錯(cuò)我的處理順序是先導(dǎo)出代理根證書。把這個(gè)根證書導(dǎo)入到系統(tǒng)信任區(qū)。Windows 證書管理器、macOS 鑰匙串、Linux 的/usr/local/share/ca-certificates/都可以。對(duì) Python如果 requests 顯式指定了verifycertifi.where()還需要把代理根證書追加到 certifi 的證書文件里。對(duì) Node.js可以通過NODE_EXTRA_CA_CERTS指定包含代理根證書的文件。驗(yàn)證時(shí)間與代理自身的有效性。debug 完成關(guān)閉代理以后如果不再需要把信任的根證書移除避免以后對(duì)正式環(huán)境的請(qǐng)求誤信任代理 CA。5.5 檢查證書庫是否生效更新完證書之后要驗(yàn)證是否真正生效。Python 里可以這樣查看當(dāng)前信任的證書路徑import ssl print(ssl.get_default_verify_paths())輸出里cafile和capath就是當(dāng)前默認(rèn)配置會(huì)去尋找的證書位置。如果和預(yù)期不符就知道問題出在哪一層。還可以用 Python 直接確認(rèn)某個(gè)證書文件能否被 OpenSSL 正確讀取python -c import ssl; ssl.create_default_context(cafile/etc/ssl/certs/ca-certificates.crt); print(ok)如果打印 ok說明證書文件格式和路徑都沒問題。5.6 生產(chǎn)環(huán)境里要不要關(guān)驗(yàn)證聽我一句生產(chǎn)環(huán)境里不要通過關(guān)閉驗(yàn)證來修復(fù)問題。verifyFalse是一時(shí)爽后續(xù)是災(zāi)難。一旦 TLS 校驗(yàn)失效中間人攻擊就變成了實(shí)際風(fēng)險(xiǎn)而且出現(xiàn)問題后很難排查。生產(chǎn)環(huán)境正確的做法是把 CA 納入版本管理隨代碼一起部署并在部署腳本里執(zhí)行證書刷新。把 CA 集中在一個(gè)受控倉庫里每次有證書更新就走變更流程才是一套可持續(xù)的方案。6. 我踩過的一些坑和最終建議最后分享幾條在實(shí)際處理中總結(jié)出的經(jīng)驗(yàn)。第一碰到這個(gè)報(bào)錯(cuò)先修系統(tǒng)時(shí)間再做后續(xù)排查。時(shí)間的坑太隱蔽了往往會(huì)消耗很久。我以前有一次排查接口報(bào)錯(cuò)檢查了證書鏈、環(huán)境變量、代理配置最后才發(fā)現(xiàn)是測試服務(wù)器的時(shí)間與標(biāo)準(zhǔn)時(shí)間差了將近三小時(shí)。當(dāng)時(shí)的感覺真是哭笑不得。第二Python 跟系統(tǒng)證書不要混在一起想。系統(tǒng) CA 更新了不代表 Python 就能立刻讀到。很多人在服務(wù)器上執(zhí)行完update-ca-certificates以為 Python 會(huì)自動(dòng)好起來實(shí)際上 Python 的 OpenSSL 不一定讀取這個(gè)路徑。顯式傳verifycertifi.where()或者設(shè)置SSL_CERT_FILE是最穩(wěn)的。第三調(diào)試代理留下的根證書要記得清理。曾經(jīng)一個(gè)項(xiàng)目在代碼里加入了抓包工具的根證書用于本地調(diào)試結(jié)果部署到預(yù)發(fā)布環(huán)境后忘了解除預(yù)發(fā)布環(huán)境的所有 HTTPS 請(qǐng)求都經(jīng)過了代理 CA 信任鏈幸好監(jiān)控發(fā)現(xiàn)得早否則生產(chǎn)環(huán)境也會(huì)帶病上線。如果你有類似調(diào)試工具一定要按環(huán)境去隔離信任配置不要一份配置通吃全部環(huán)境。第四容器鏡像的證書更新要寫進(jìn)構(gòu)建流程。不要依賴某個(gè)基礎(chǔ)鏡像自帶的證書因?yàn)殓R像構(gòu)建日期早、證書過期是很容易被忽略的定時(shí)炸彈。加一行apt-get install ca-certificates并清理緩存成本極低收益卻很直接。這幾招用下來絕大多數(shù)CERTIFICATE_VERIFY_FAILED問題都能在幾分鐘內(nèi)定位。以后再看到“握手失敗”就不至于手足無措了。