：從SSL證書到雙向認證與客戶端調(diào)用)
1. 為什么非要給Spring Boot套上HTTPS一次對接把我從HTTP逼到了TLS好幾年前做某內(nèi)部模擬項目的時候我圖省事Spring Boot的接口全用HTTP。當時覺得反正在內(nèi)網(wǎng)拿到地址就能調(diào)結(jié)果對接方的安全清單直接紅字標注傳輸敏感數(shù)據(jù)必須加密。我這才老老實實把證書、密鑰庫、客戶端調(diào)用整套鏈路從頭理了一遍。所以這篇內(nèi)容的核心很明確怎么讓Spring Boot應用自己以HTTPS方式發(fā)布接口以及別人怎么才能正確調(diào)用這個HTTPS接口。服務端配置只是前半場后半場的客戶端信任鏈路往往才是大家真正卡殼的地方。你會在下文看到完整的配置樣例、SSL握手失敗的完整排查鏈路、一個雙向認證的實戰(zhàn)方案以及一堆我踩過之后才總結(jié)出來的細節(jié)。1.1 HTTP明文傳輸?shù)碾[患比想象中更直接HTTP本身不加密數(shù)據(jù)在網(wǎng)絡上以明文漂著。你在辦公室連同一個局域網(wǎng)別人開個抓包工具就能看到請求里帶了什么參數(shù)。假如接口里傳的是賬號、密碼、訂單號這類數(shù)據(jù)被拿走之后很難亡羊補牢。HTTPS做的事情通俗點說就是三層加密傳輸內(nèi)容防止被中間人偷看校驗服務器身份防止連到一個假冒的服務校驗內(nèi)容完整性防止數(shù)據(jù)在傳輸過程中被篡改。Spring Boot本身不會自動給你套上這層保護它默認啟動后還是HTTP。你需要在應用層面把SSL證書配上讓內(nèi)嵌的Tomcat以HTTPS協(xié)議對外提供服務。1.2 什么場景才需要Spring Boot自己開HTTPS很多項目里Spring Boot應用前面會有一層Nginx之類的反向代理TLS證書是在代理層終結(jié)的Spring Boot內(nèi)部仍然走HTTP。這是常見且推薦的部署方式不用動應用代碼。但有些場景繞不開比如服務直接暴露在容器網(wǎng)絡中或者對方的接入規(guī)范要求應用本身必須以HTTPS協(xié)議對外又或者你在沒有前置代理的環(huán)境里做聯(lián)調(diào)。這時候就得讓Spring Boot自己的嵌入式容器處理TLS。這也是我寫這篇內(nèi)容的主要場景——沒有中間層靠應用自己把HTTPS這事扛起來。2. 證書這關躲不過去自簽名與CA怎么選、怎么生成2.1 證書和信任鏈用一張身份證來理解HTTPS能成立靠的是TLS握手階段的三件事協(xié)商加密算法、驗證服務器身份、生成會話密鑰。服務器身份靠數(shù)字證書證明證書里寫了域名、公鑰、有效期、簽發(fā)者再由簽發(fā)者用自己的私鑰簽名。你可以把證書理解成服務器的身份證客戶端驗證證書時其實是在檢查這張身份證是不是由一家公認機構簽發(fā)的這個機構就是CA。驗證通過后客戶端拿到服務器公鑰用公鑰加密一個隨機數(shù)發(fā)給服務器服務器用私鑰解密雙方就確定了對稱加密的會話密鑰。整個體系里證書是開門憑證私鑰是只有服務器自己知道的保險箱鑰匙。2.2 自簽名證書能滿足什么場景自簽名證書意思是簽發(fā)者就是證書持有者自己沒有上級CA背書所以瀏覽器和操作系統(tǒng)默認都不信任它。但這不代表它安全性就差你完全可以用RSA 2048甚至更高位數(shù)TLS協(xié)商的加密強度一樣不低。內(nèi)網(wǎng)開發(fā)、聯(lián)調(diào)、單元測試用自簽名完全可行因為你可以把證書手工塞進客戶端的信任庫。生產(chǎn)環(huán)境對外給真實用戶訪問還是得用正式CA簽發(fā)的證書否則用戶瀏覽器每次訪問都彈不安全警告沒人敢繼續(xù)用。所以我的建議很簡單開發(fā)測試環(huán)境自簽名生產(chǎn)環(huán)境走正規(guī)CA別混。2.3 keytool生成自簽名證書的完整命令與參數(shù)解析JDK自帶keytool生成自簽名證書最省事。以我常用的命令為例keytool -genkeypair \ -alias app-server \ -keyalg RSA \ -keysize 2048 \ -validity 365 \ -storetype PKCS12 \ -keystore server.p12 \ -dname CNlocalhost, OUDevOps, OExample \ -ext SANdns:localhost,dns:myserver.internal,ip:127.0.0.1逐個拆解一下-keyalg RSA -keysize 2048生成RSA 2048位密鑰對當前主流業(yè)務場景夠用。-validity 365證書有效期365天。內(nèi)網(wǎng)調(diào)試隨意生產(chǎn)證書一般一年或兩年。-storetype PKCS12密鑰庫格式。PKCS12是跨平臺標準Spring Boot兼容性最好現(xiàn)在JDK默認也是它。-dname CNlocalhost...證書主體信息CN填訪問時用的域名。-ext SAN...這是最容易忽略的一步。Java 9以后和新版瀏覽器都只認SAN不認CN。如果SAN沒填Chrome會報NET::ERR_CERT_COMMON_NAME_INVALIDJava客戶端可能報No subject alternative names present。所以生成時就把域名、IP寫全。執(zhí)行完會生成server.p12。keytool會讓你設置storepass這個密碼一定要記牢后面Spring Boot配置里就是它。PKCS12格式下密鑰密碼默認和密鑰庫密碼一致所以配置文件里寫一個密碼就行不用額外處理key-password。2.4 生產(chǎn)環(huán)境申請CA證書的流程正式CA證書的申請流程一般是先準備好私鑰生成證書簽發(fā)請求CSR提交給CA機構審核審核通過后拿到證書再把證書和私鑰裝配成Spring Boot能用的PKCS12密鑰庫。用openssl做私鑰和CSR比較常見# 生成私鑰 openssl genpkey -algorithm RSA -out server.key -pkeyopt rsa_keygen_bits:2048 # 生成CSRCommon Name填對外域名 openssl req -new -key server.key -out server.csr -subj /CNmyserver.example.com拿到CA簽發(fā)的證書后把私鑰和證書合并成.p12openssl pkcs12 -export -in server.crt -inkey server.key -out server.p12 -name app-server -passout pass:changeit如果證書鏈里包含中間證書記得把它們一起合并進.p12否則某些客戶端會報unable to find valid certification path to requested target。我自己習慣無論自簽名還是正式CA證書到Spring Boot這一層都統(tǒng)一成PKCS12格式別名固定后續(xù)配置和維護就不容易亂。3. Spring Boot服務端配置從yml到HTTP自動跳轉(zhuǎn)3.1 最小可用配置把上一步生成的server.p12復制到src/main/resources目錄下然后在application.yml里追加server: port: 8443 ssl: key-store: classpath:server.p12 key-store-type: PKCS12 key-store-password: changeit key-alias: app-server enabled-protocols: TLSv1.2,TLSv1.3在Spring Boot 2.x里還有個server.ssl.enabled配置默認就是true。到了Spring Boot 3.x這個配置項直接移除了只要key-store有值就自動啟用HTTPS不用再手動寫enabled: true。啟動后控制臺會出現(xiàn)類似Tomcat initialized with port(s): 8443 (https)的日志說明你的應用已經(jīng)在以HTTPS對外提供服務了。3.2 配置項逐條解析這些參數(shù)看起來簡單但每一條都對應著一個常見的翻車點。配置項作用注意事項server.portHTTPS服務監(jiān)聽端口內(nèi)網(wǎng)常用8443443需要root權限server.ssl.key-store密鑰庫路徑classpath:開頭是打包進jar生產(chǎn)建議外部路徑server.ssl.key-store-type密鑰庫格式推薦PKCS12別用舊JKSserver.ssl.key-store-password密鑰庫密碼必須和生成時的storepass一致server.ssl.key-alias證書條目別名必須和keytool生成時一致server.ssl.protocol協(xié)議名一般填TLS不填走JDK默認server.ssl.enabled-protocols允許的TLS版本老客戶端只支持TLSv1.2時別只開TLSv1.3server.ssl.client-auth是否需要客戶端證書NONE / WANT / NEED雙向認證用NEED配置里最常踩的坑就是key-store-password和生成時的storepass不一致啟動直接報password was incorrect。其次是key-alias配錯報錯信息會讓你懷疑人生。如果啟動日志里出現(xiàn)這些異常先別懷疑證書本身回去核對密碼和別名。3.3 HTTP端口自動跳轉(zhuǎn)HTTPS生產(chǎn)上很多場景希望用戶訪問HTTP端口時自動跳到HTTPS。Spring Boot內(nèi)置Tomcat可以讓主端口跑HTTPS再額外加一個HTTP連接器做跳轉(zhuǎn)不需要寫一堆Filter來干這事。package com.example.config; import org.apache.catalina.connector.Connector; import org.springframework.boot.web.embedded.tomcat.TomcatServletWebServerFactory; import org.springframework.boot.web.server.WebServerFactoryCustomizer; import org.springframework.stereotype.Component; Component public class HttpsRedirectConfig implements WebServerFactoryCustomizerTomcatServletWebServerFactory { Override public void customize(TomcatServletWebServerFactory factory) { Connector httpConnector new Connector(TomcatServletWebServerFactory.DEFAULT_PROTOCOL); httpConnector.setScheme(http); httpConnector.setPort(8080); httpConnector.setSecure(false); httpConnector.setRedirectPort(8443); factory.addAdditionalTomcatConnectors(httpConnector); } }這段配置會讓服務同時監(jiān)聽8080和8443。需要注意redirectPort只是告訴Tomcat“這個連接器如果要求安全傳輸就跳到8443”它本身不會像魔法一樣把所有HTTP請求都強制轉(zhuǎn)成HTTPS。想做到強制跳轉(zhuǎn)要么配合安全框架的requiresSecure()要么加一個輕量過濾器對非HTTPS請求做302。我一般用下面這個過濾器簡單直接Component public class HttpsRedirectFilter implements Filter { Override public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException { HttpServletRequest req (HttpServletRequest) request; HttpServletResponse resp (HttpServletResponse) response; if (!req.isSecure()) { String location https:// req.getServerName() :8443 req.getRequestURI() (req.getQueryString() ! null ? ? req.getQueryString() : ); resp.sendRedirect(location); } else { chain.doFilter(request, response); } } }這個過濾器適合快速場景。如果項目里已經(jīng)用了安全框架建議直接用它的Channel配置語義更清晰。3.4 證書放jar包里面還是外面開發(fā)階段我會把server.p12放在src/main/resources里打成fat jar直接帶證書啟動不用管外部依賴。但這個做法有個隱患證書一旦更新整個jar要重新構建發(fā)布而且密鑰庫和代碼一起分發(fā)泄露面更大。生產(chǎn)環(huán)境我建議把密鑰庫放到應用外部目錄配置改成server: ssl: key-store: file:/data/app/certs/server.p12這樣運維更新證書時不用重新發(fā)布應用重啟服務就行。密碼也不要硬編碼在配置文件里用環(huán)境變量注入例如${SSL_STORE_PASSWORD}。我見過不少團隊把密鑰庫密碼直接寫在application.yml里提交到代碼倉庫這比用HTTP還讓人頭疼。4. 客戶端調(diào)用翻車現(xiàn)場SSL握手失敗的完整排查鏈路4.1 最常見的報錯長什么樣服務端HTTPS配好瀏覽器訪問也OK但別人用Java程序一調(diào)立刻拋異常。我第一次遇到時看到的底層錯誤是這樣javax.net.ssl.SSLHandshakeException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target看到PKIX三個字母基本可以斷定是信任鏈問題客戶端TrustManager里找不到能驗證服務端證書的CA。自簽名證書沒有上級CAJDK默認信任庫cacerts里自然沒有它于是握手失敗。還有一種容易混淆的報錯是主機名不匹配javax.net.ssl.SSLHandshakeException: java.security.cert.CertificateException: No subject alternative names matching IP address 127.0.0.1 found這個意思是即使證書被信任了你訪問時用的IP/域名和證書SAN對不上一樣握手失敗。所以生成證書那一步SAN到底填了什么直接決定客戶端后面用什么地址訪問。4.2 排查過程三步定位法踩過幾次坑之后我總結(jié)出一套固定排查順序。第一步也是最重要的一步用openssl直接看服務端證書openssl s_client -connect localhost:8443 -showcerts /dev/null 21 | grep -A10 Certificate chain這里能看到證書鏈內(nèi)容。如果正常輸出說明服務端TLS層沒問題如果connection error說明服務端配置有問題回到Spring Boot去調(diào)。第二步確認客戶端JVM信任庫里有沒有對應證書。Java進程默認讀取$JAVA_HOME/lib/security/cacertskeytool -list -keystore $JAVA_HOME/lib/security/cacerts -storepass changeit | grep app-server這一步能直接確認是不是信任鏈缺失。如果沒有對應條目問題基本鎖定。第三步看目標URL和證書SAN是否匹配。URL是IP證書SAN只有域名絕對過不了。三步走完90%的握手失敗都能定位不用一上來就改代碼跳過校驗。搞清楚是哪一環(huán)斷了才知道該改哪邊。4.3 正規(guī)解法把證書導入客戶端信任庫開發(fā)環(huán)境下最省事的正規(guī)做法是導出服務端證書再導入客戶端JVM的cacerts# 服務端側(cè)導出證書 keytool -exportcert -alias app-server -keystore server.p12 -storepass changeit -file server.cer # 客戶端側(cè)導入信任庫 keytool -importcert -alias app-server -file server.cer -keystore $JAVA_HOME/lib/security/cacerts -storepass changeit導入過程中會提示確認輸入yes即可。重新跑客戶端握手直接成功。但有三點要注意cacerts的JDK初始密碼是changeit不少公司會統(tǒng)一改掉別硬試。導入cacerts是全局信任所有使用該JDK的應用都會放行這個證書測試機無所謂生產(chǎn)環(huán)境要謹慎。更干凈的做法是單獨做一個truststore文件通過JVM參數(shù)指定不用動JDK自帶的cacertsjava -Djavax.net.ssl.trustStore/data/app/certs/truststore.p12 \ -Djavax.net.ssl.trustStorePasswordchangeit \ -jar client-app.jartruststore里同樣用keytool導入服務端證書。影響范圍可控交付時跟著應用走也方便在不同環(huán)境之間切換。4.4 調(diào)用側(cè)代碼怎么寫兩種可落地的寫法如果你不想改JVM參數(shù)可以在代碼里指定信任庫。最簡單的寫法是在程序啟動早期設置系統(tǒng)屬性System.setProperty(javax.net.ssl.trustStore, /data/app/certs/truststore.p12); System.setProperty(javax.net.ssl.trustStorePassword, changeit);之后用RestTemplate、HttpClient、Feign等發(fā)HTTPS請求都會自動讀取這個信任庫。代價是全局生效同一個JVM里其他需要不同信任策略的請求也會被影響。更可控的方式是自己構造SSLContext。以JDK自帶的HttpsURLConnection為例講清楚原理public static SSLContext buildSslContext(String trustStorePath, String storePassword) throws Exception { KeyStore trustStore KeyStore.getInstance(PKCS12); try (InputStream in new FileInputStream(trustStorePath)) { trustStore.load(in, storePassword.toCharArray()); } TrustManagerFactory tmf TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm()); tmf.init(trustStore); SSLContext sslContext SSLContext.getInstance(TLS); sslContext.init(null, tmf.getTrustManagers(), new SecureRandom()); return sslContext; } // 使用 SSLContext sslContext buildSslContext(/data/app/certs/truststore.p12, changeit); HttpsURLConnection connection (HttpsURLConnection) new URL(https://localhost:8443/api).openConnection(); connection.setSSLSocketFactory(sslContext.getSocketFactory());如果你想用RestTemplate思路完全一樣把構造好的SSLContext塞給底層的HttpClient請求工廠。Feign、WebClient也都是換湯不換藥核心都是讓客戶端在驗證服務端證書時能走一條包含目標證書的信任鏈。4.5 開發(fā)環(huán)境能不能跳過校驗能但我只建議本地聯(lián)調(diào)時用。跳過校驗的本質(zhì)是讓TrustManager接收任何證書同時放開HostnameVerifierTrustManager[] trustAll new TrustManager[]{ new X509TrustManager() { public java.security.cert.X509Certificate[] getAcceptedIssuers() { return new java.security.cert.X509Certificate[0]; } public void checkServerTrusted(java.security.cert.X509Certificate[] chain, String authType) {} public void checkClientTrusted(java.security.cert.X509Certificate[] chain, String authType) {} } }; SSLContext sslContext SSLContext.getInstance(TLS); sslContext.init(null, trustAll, new SecureRandom()); HttpsURLConnection.setDefaultSSLSocketFactory(sslContext.getSocketFactory()); HttpsURLConnection.setDefaultHostnameVerifier((hostname, session) - true);這段代碼我調(diào)試時加過幾次確實一把梭。但生產(chǎn)環(huán)境真這么干HTTPS形同虛設中間人攻擊完全防不住。如果最后要交付別人的系統(tǒng)這種代碼不只是被code review打回的問題安全掃描直接就能標記出來。5. 雙向認證當服務端反過來要驗明調(diào)用者5.1 單向和雙向的區(qū)別前面講的都是單向HTTPS客戶端驗證服務器身份服務器不關心客戶端是誰。但在系統(tǒng)對系統(tǒng)的接口場景里有些安全要求高的對接方希望自己也驗證調(diào)用方的身份這就是雙向認證也叫mTLS。Spring Boot開啟雙向認證很簡單核心就一個配置server: ssl: client-auth: need trust-store: file:/data/app/certs/server-truststore.p12 trust-store-type: PKCS12 trust-store-password: changeitclient-auth有三個取值none不要求客戶端證書want請求客戶端證書但不強制客戶端不給也能繼續(xù)need強制必須有沒有直接握手失敗。做接口鑒權場景直接need。5.2 一套可以落地的mTLS配法雙向認證需要準備兩個密鑰庫服務端自己的server.p12以及客戶端自己的client.p12。為了演示我簡化成直接用自簽名的客戶端證書生產(chǎn)環(huán)境建議走完整CA體系。先生成客戶端證書keytool -genkeypair -alias client-1 -keyalg RSA -keysize 2048 \ -storetype PKCS12 -keystore client.p12 -validity 365 \ -dname CNclient-1, OUInternal, OExample \ -ext SANdns:client-1.internal然后把客戶端證書導出導入服務端的truststorekeytool -exportcert -alias client-1 -keystore client.p12 -storepass changeit -file client.cer keytool -importcert -alias client-1 -file client.cer -keystore server-truststore.p12 -storetype PKCS12 -storepass changeit反過來客戶端也要信任服務端證書所以把服務端證書導入客戶端的truststorekeytool -exportcert -alias app-server -keystore server.p12 -storepass changeit -file server.cer keytool -importcert -alias app-server -file server.cer -keystore client-truststore.p12 -storetype PKCS12 -storepass changeit客戶端調(diào)用代碼要同時加載自己的密鑰庫和信任服務端的truststoreKeyStore clientKeyStore KeyStore.getInstance(PKCS12); clientKeyStore.load(new FileInputStream(client.p12), changeit.toCharArray()); KeyManagerFactory kmf KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm()); kmf.init(clientKeyStore, changeit.toCharArray()); KeyStore clientTrustStore KeyStore.getInstance(PKCS12); clientTrustStore.load(new FileInputStream(client-truststore.p12), changeit.toCharArray()); TrustManagerFactory tmf TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm()); tmf.init(clientTrustStore); SSLContext sslContext SSLContext.getInstance(TLS); sslContext.init(kmf.getKeyManagers(), tmf.getTrustManagers(), new SecureRandom());然后把sslContext塞給調(diào)用HTTP的客戶端。如果漏了kmf.init這一步服務端通常報Client not authenticated或者bad certificate意思就是客戶端沒出示有效證書直接被拒了。5.3 mTLS踩坑記錄第一個坑是證書鏈。自建CA簽發(fā)證書時最好帶上完整鏈服務端truststore里不能只放根證書要把客戶端證書鏈上的各級證書都放進去否則驗證時找不到中間證書會報無法構建有效鏈。第二個坑是別名和密碼管理。PKCS12格式下密鑰庫密碼和密鑰密碼一致但導出導入時別名容易搞混。我有一次給三個系統(tǒng)各生成一套證書結(jié)果某個系統(tǒng)導錯了別名聯(lián)調(diào)時半天找不出問題。后來我固定了一套命名規(guī)范服務端別名統(tǒng)一app-server客戶端別名統(tǒng)一client-序號測試環(huán)境和生產(chǎn)環(huán)境分開維護再沒亂過。第三個坑是時間。證書有效期過了立刻握手失敗。雙向認證會兩邊都檢查任何一邊過期都不行。生產(chǎn)環(huán)境提前規(guī)劃續(xù)期窗口不要等到線上報錯了才想起來。6. 驗證三板斧與收尾細節(jié)curl、瀏覽器、日志外加我踩過的坑6.1 用curl快速驗證服務端重啟服務后我第一件事不是寫代碼調(diào)用而是先curl探一遍curl -v --cacert ca.crt https://localhost:8443/actuator/health-v能看到完整握手過程包括證書指紋、加密套件和是否被信任。想臨時跳過校驗可以用-kcurl -k https://localhost:8443/actuator/health能正常返回說明服務端TLS沒問題。接著用openssl s_client確認證書鏈、有效期和SAN能過濾掉一半以上的配置問題。6.2 瀏覽器訪問和Java客戶端行為不一樣瀏覽器和Java客戶端對證書不信任時的處理方式完全不同。瀏覽器會彈警告讓你點“繼續(xù)訪問”Java客戶端則是直接拋異常中斷。也就是說你在瀏覽器上點兩下能過的對方Java程序根本不會給你點“繼續(xù)”的機會。所以我交付前習慣用一個干凈環(huán)境跑一遍客戶端代碼先把證書導入信任庫確認正常再把證書移出確認拋出的異常是我們預期的證書異常。兩步走完就能確定還沒有補上的環(huán)節(jié)在哪里。6.3 日志怎么看Spring Boot默認日志基本看不到TLS握手細節(jié)。排查時可以先臨時打開DEBUGlogging: level: org.apache.tomcat: DEBUG org.apache.catalina: DEBUG org.springframework.boot.web.embedded.tomcat: DEBUG但真實項目里TLS握手問題在服務端日志經(jīng)常只有一行Handshake failed信息量有限。所以我更建議把問題帶到客戶端側(cè)看客戶端堆棧里的異常信息比服務端日志豐富得多。確認服務端證書沒問題后重點還是回到客戶端去查信任庫和主機名校驗。6.4 其他容易翻車的配置細節(jié)補充幾個我在實際項目里反復踩到的點8443端口被占用時啟動會報BindException用netstat -tlnp | grep 8443查一下。如果把server.port配成443Linux下非root用戶啟動會失敗因為小于1024端口需要特權。內(nèi)網(wǎng)環(huán)境我一般用8443避開這個限制。有些老版本JDK不支持TLSv1.3或某些客戶端只支持TLSv1.2enabled-protocols按需放寬。但別為了兼容老設備把TLSv1.0/1.1重新打開那等于舊漏洞又開了門。證書更新后一定要確認新證書的SAN和舊證書一致。我見過有人更新證書忘了SAN結(jié)果半個系統(tǒng)的調(diào)用全掛日志里全是主機名校驗失敗。最后分享一點個人體會搞明白HTTPS發(fā)布和調(diào)用真正難的不是Spring Boot那幾行配置而是證書信任模型的建立。你只要理解了證書、信任庫、私鑰、SSLContext這幾者的關系不管換什么框架、什么客戶端都能快速定位問題。我在實際項目中習慣把證書生成、導出、導入寫成一整套腳本放到運維目錄里換人接手也不至于對著命令行發(fā)懵。開發(fā)環(huán)境可以偶爾用跳過校驗偷懶但生產(chǎn)環(huán)境千萬別在這種地方省事。 Spring Boot HTTPS配置實戰(zhàn)：從SSL證書到雙向認證與客戶端調(diào)用
1. 為什么非要給Spring Boot套上HTTPS一次對接把我從HTTP逼到了TLS好幾年前做某內(nèi)部模擬項目的時候我圖省事Spring Boot的接口全用HTTP。當時覺得反正在內(nèi)網(wǎng)拿到地址就能調(diào)結(jié)果對接方的安全清單直接紅字標注傳輸敏感數(shù)據(jù)必須加密。我這才老老實實把證書、密鑰庫、客戶端調(diào)用整套鏈路從頭理了一遍。所以這篇內(nèi)容的核心很明確怎么讓Spring Boot應用自己以HTTPS方式發(fā)布接口以及別人怎么才能正確調(diào)用這個HTTPS接口。服務端配置只是前半場后半場的客戶端信任鏈路往往才是大家真正卡殼的地方。你會在下文看到完整的配置樣例、SSL握手失敗的完整排查鏈路、一個雙向認證的實戰(zhàn)方案以及一堆我踩過之后才總結(jié)出來的細節(jié)。1.1 HTTP明文傳輸?shù)碾[患比想象中更直接HTTP本身不加密數(shù)據(jù)在網(wǎng)絡上以明文漂著。你在辦公室連同一個局域網(wǎng)別人開個抓包工具就能看到請求里帶了什么參數(shù)。假如接口里傳的是賬號、密碼、訂單號這類數(shù)據(jù)被拿走之后很難亡羊補牢。HTTPS做的事情通俗點說就是三層加密傳輸內(nèi)容防止被中間人偷看校驗服務器身份防止連到一個假冒的服務校驗內(nèi)容完整性防止數(shù)據(jù)在傳輸過程中被篡改。Spring Boot本身不會自動給你套上這層保護它默認啟動后還是HTTP。你需要在應用層面把SSL證書配上讓內(nèi)嵌的Tomcat以HTTPS協(xié)議對外提供服務。1.2 什么場景才需要Spring Boot自己開HTTPS很多項目里Spring Boot應用前面會有一層Nginx之類的反向代理TLS證書是在代理層終結(jié)的Spring Boot內(nèi)部仍然走HTTP。這是常見且推薦的部署方式不用動應用代碼。但有些場景繞不開比如服務直接暴露在容器網(wǎng)絡中或者對方的接入規(guī)范要求應用本身必須以HTTPS協(xié)議對外又或者你在沒有前置代理的環(huán)境里做聯(lián)調(diào)。這時候就得讓Spring Boot自己的嵌入式容器處理TLS。這也是我寫這篇內(nèi)容的主要場景——沒有中間層靠應用自己把HTTPS這事扛起來。2. 證書這關躲不過去自簽名與CA怎么選、怎么生成2.1 證書和信任鏈用一張身份證來理解HTTPS能成立靠的是TLS握手階段的三件事協(xié)商加密算法、驗證服務器身份、生成會話密鑰。服務器身份靠數(shù)字證書證明證書里寫了域名、公鑰、有效期、簽發(fā)者再由簽發(fā)者用自己的私鑰簽名。你可以把證書理解成服務器的身份證客戶端驗證證書時其實是在檢查這張身份證是不是由一家公認機構簽發(fā)的這個機構就是CA。驗證通過后客戶端拿到服務器公鑰用公鑰加密一個隨機數(shù)發(fā)給服務器服務器用私鑰解密雙方就確定了對稱加密的會話密鑰。整個體系里證書是開門憑證私鑰是只有服務器自己知道的保險箱鑰匙。2.2 自簽名證書能滿足什么場景自簽名證書意思是簽發(fā)者就是證書持有者自己沒有上級CA背書所以瀏覽器和操作系統(tǒng)默認都不信任它。但這不代表它安全性就差你完全可以用RSA 2048甚至更高位數(shù)TLS協(xié)商的加密強度一樣不低。內(nèi)網(wǎng)開發(fā)、聯(lián)調(diào)、單元測試用自簽名完全可行因為你可以把證書手工塞進客戶端的信任庫。生產(chǎn)環(huán)境對外給真實用戶訪問還是得用正式CA簽發(fā)的證書否則用戶瀏覽器每次訪問都彈不安全警告沒人敢繼續(xù)用。所以我的建議很簡單開發(fā)測試環(huán)境自簽名生產(chǎn)環(huán)境走正規(guī)CA別混。2.3 keytool生成自簽名證書的完整命令與參數(shù)解析JDK自帶keytool生成自簽名證書最省事。以我常用的命令為例keytool -genkeypair \ -alias app-server \ -keyalg RSA \ -keysize 2048 \ -validity 365 \ -storetype PKCS12 \ -keystore server.p12 \ -dname CNlocalhost, OUDevOps, OExample \ -ext SANdns:localhost,dns:myserver.internal,ip:127.0.0.1逐個拆解一下-keyalg RSA -keysize 2048生成RSA 2048位密鑰對當前主流業(yè)務場景夠用。-validity 365證書有效期365天。內(nèi)網(wǎng)調(diào)試隨意生產(chǎn)證書一般一年或兩年。-storetype PKCS12密鑰庫格式。PKCS12是跨平臺標準Spring Boot兼容性最好現(xiàn)在JDK默認也是它。-dname CNlocalhost...證書主體信息CN填訪問時用的域名。-ext SAN...這是最容易忽略的一步。Java 9以后和新版瀏覽器都只認SAN不認CN。如果SAN沒填Chrome會報NET::ERR_CERT_COMMON_NAME_INVALIDJava客戶端可能報No subject alternative names present。所以生成時就把域名、IP寫全。執(zhí)行完會生成server.p12。keytool會讓你設置storepass這個密碼一定要記牢后面Spring Boot配置里就是它。PKCS12格式下密鑰密碼默認和密鑰庫密碼一致所以配置文件里寫一個密碼就行不用額外處理key-password。2.4 生產(chǎn)環(huán)境申請CA證書的流程正式CA證書的申請流程一般是先準備好私鑰生成證書簽發(fā)請求CSR提交給CA機構審核審核通過后拿到證書再把證書和私鑰裝配成Spring Boot能用的PKCS12密鑰庫。用openssl做私鑰和CSR比較常見# 生成私鑰 openssl genpkey -algorithm RSA -out server.key -pkeyopt rsa_keygen_bits:2048 # 生成CSRCommon Name填對外域名 openssl req -new -key server.key -out server.csr -subj /CNmyserver.example.com拿到CA簽發(fā)的證書后把私鑰和證書合并成.p12openssl pkcs12 -export -in server.crt -inkey server.key -out server.p12 -name app-server -passout pass:changeit如果證書鏈里包含中間證書記得把它們一起合并進.p12否則某些客戶端會報unable to find valid certification path to requested target。我自己習慣無論自簽名還是正式CA證書到Spring Boot這一層都統(tǒng)一成PKCS12格式別名固定后續(xù)配置和維護就不容易亂。3. Spring Boot服務端配置從yml到HTTP自動跳轉(zhuǎn)3.1 最小可用配置把上一步生成的server.p12復制到src/main/resources目錄下然后在application.yml里追加server: port: 8443 ssl: key-store: classpath:server.p12 key-store-type: PKCS12 key-store-password: changeit key-alias: app-server enabled-protocols: TLSv1.2,TLSv1.3在Spring Boot 2.x里還有個server.ssl.enabled配置默認就是true。到了Spring Boot 3.x這個配置項直接移除了只要key-store有值就自動啟用HTTPS不用再手動寫enabled: true。啟動后控制臺會出現(xiàn)類似Tomcat initialized with port(s): 8443 (https)的日志說明你的應用已經(jīng)在以HTTPS對外提供服務了。3.2 配置項逐條解析這些參數(shù)看起來簡單但每一條都對應著一個常見的翻車點。配置項作用注意事項server.portHTTPS服務監(jiān)聽端口內(nèi)網(wǎng)常用8443443需要root權限server.ssl.key-store密鑰庫路徑classpath:開頭是打包進jar生產(chǎn)建議外部路徑server.ssl.key-store-type密鑰庫格式推薦PKCS12別用舊JKSserver.ssl.key-store-password密鑰庫密碼必須和生成時的storepass一致server.ssl.key-alias證書條目別名必須和keytool生成時一致server.ssl.protocol協(xié)議名一般填TLS不填走JDK默認server.ssl.enabled-protocols允許的TLS版本老客戶端只支持TLSv1.2時別只開TLSv1.3server.ssl.client-auth是否需要客戶端證書NONE / WANT / NEED雙向認證用NEED配置里最常踩的坑就是key-store-password和生成時的storepass不一致啟動直接報password was incorrect。其次是key-alias配錯報錯信息會讓你懷疑人生。如果啟動日志里出現(xiàn)這些異常先別懷疑證書本身回去核對密碼和別名。3.3 HTTP端口自動跳轉(zhuǎn)HTTPS生產(chǎn)上很多場景希望用戶訪問HTTP端口時自動跳到HTTPS。Spring Boot內(nèi)置Tomcat可以讓主端口跑HTTPS再額外加一個HTTP連接器做跳轉(zhuǎn)不需要寫一堆Filter來干這事。package com.example.config; import org.apache.catalina.connector.Connector; import org.springframework.boot.web.embedded.tomcat.TomcatServletWebServerFactory; import org.springframework.boot.web.server.WebServerFactoryCustomizer; import org.springframework.stereotype.Component; Component public class HttpsRedirectConfig implements WebServerFactoryCustomizerTomcatServletWebServerFactory { Override public void customize(TomcatServletWebServerFactory factory) { Connector httpConnector new Connector(TomcatServletWebServerFactory.DEFAULT_PROTOCOL); httpConnector.setScheme(http); httpConnector.setPort(8080); httpConnector.setSecure(false); httpConnector.setRedirectPort(8443); factory.addAdditionalTomcatConnectors(httpConnector); } }這段配置會讓服務同時監(jiān)聽8080和8443。需要注意redirectPort只是告訴Tomcat“這個連接器如果要求安全傳輸就跳到8443”它本身不會像魔法一樣把所有HTTP請求都強制轉(zhuǎn)成HTTPS。想做到強制跳轉(zhuǎn)要么配合安全框架的requiresSecure()要么加一個輕量過濾器對非HTTPS請求做302。我一般用下面這個過濾器簡單直接Component public class HttpsRedirectFilter implements Filter { Override public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException { HttpServletRequest req (HttpServletRequest) request; HttpServletResponse resp (HttpServletResponse) response; if (!req.isSecure()) { String location https:// req.getServerName() :8443 req.getRequestURI() (req.getQueryString() ! null ? ? req.getQueryString() : ); resp.sendRedirect(location); } else { chain.doFilter(request, response); } } }這個過濾器適合快速場景。如果項目里已經(jīng)用了安全框架建議直接用它的Channel配置語義更清晰。3.4 證書放jar包里面還是外面開發(fā)階段我會把server.p12放在src/main/resources里打成fat jar直接帶證書啟動不用管外部依賴。但這個做法有個隱患證書一旦更新整個jar要重新構建發(fā)布而且密鑰庫和代碼一起分發(fā)泄露面更大。生產(chǎn)環(huán)境我建議把密鑰庫放到應用外部目錄配置改成server: ssl: key-store: file:/data/app/certs/server.p12這樣運維更新證書時不用重新發(fā)布應用重啟服務就行。密碼也不要硬編碼在配置文件里用環(huán)境變量注入例如${SSL_STORE_PASSWORD}。我見過不少團隊把密鑰庫密碼直接寫在application.yml里提交到代碼倉庫這比用HTTP還讓人頭疼。4. 客戶端調(diào)用翻車現(xiàn)場SSL握手失敗的完整排查鏈路4.1 最常見的報錯長什么樣服務端HTTPS配好瀏覽器訪問也OK但別人用Java程序一調(diào)立刻拋異常。我第一次遇到時看到的底層錯誤是這樣javax.net.ssl.SSLHandshakeException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target看到PKIX三個字母基本可以斷定是信任鏈問題客戶端TrustManager里找不到能驗證服務端證書的CA。自簽名證書沒有上級CAJDK默認信任庫cacerts里自然沒有它于是握手失敗。還有一種容易混淆的報錯是主機名不匹配javax.net.ssl.SSLHandshakeException: java.security.cert.CertificateException: No subject alternative names matching IP address 127.0.0.1 found這個意思是即使證書被信任了你訪問時用的IP/域名和證書SAN對不上一樣握手失敗。所以生成證書那一步SAN到底填了什么直接決定客戶端后面用什么地址訪問。4.2 排查過程三步定位法踩過幾次坑之后我總結(jié)出一套固定排查順序。第一步也是最重要的一步用openssl直接看服務端證書openssl s_client -connect localhost:8443 -showcerts /dev/null 21 | grep -A10 Certificate chain這里能看到證書鏈內(nèi)容。如果正常輸出說明服務端TLS層沒問題如果connection error說明服務端配置有問題回到Spring Boot去調(diào)。第二步確認客戶端JVM信任庫里有沒有對應證書。Java進程默認讀取$JAVA_HOME/lib/security/cacertskeytool -list -keystore $JAVA_HOME/lib/security/cacerts -storepass changeit | grep app-server這一步能直接確認是不是信任鏈缺失。如果沒有對應條目問題基本鎖定。第三步看目標URL和證書SAN是否匹配。URL是IP證書SAN只有域名絕對過不了。三步走完90%的握手失敗都能定位不用一上來就改代碼跳過校驗。搞清楚是哪一環(huán)斷了才知道該改哪邊。4.3 正規(guī)解法把證書導入客戶端信任庫開發(fā)環(huán)境下最省事的正規(guī)做法是導出服務端證書再導入客戶端JVM的cacerts# 服務端側(cè)導出證書 keytool -exportcert -alias app-server -keystore server.p12 -storepass changeit -file server.cer # 客戶端側(cè)導入信任庫 keytool -importcert -alias app-server -file server.cer -keystore $JAVA_HOME/lib/security/cacerts -storepass changeit導入過程中會提示確認輸入yes即可。重新跑客戶端握手直接成功。但有三點要注意cacerts的JDK初始密碼是changeit不少公司會統(tǒng)一改掉別硬試。導入cacerts是全局信任所有使用該JDK的應用都會放行這個證書測試機無所謂生產(chǎn)環(huán)境要謹慎。更干凈的做法是單獨做一個truststore文件通過JVM參數(shù)指定不用動JDK自帶的cacertsjava -Djavax.net.ssl.trustStore/data/app/certs/truststore.p12 \ -Djavax.net.ssl.trustStorePasswordchangeit \ -jar client-app.jartruststore里同樣用keytool導入服務端證書。影響范圍可控交付時跟著應用走也方便在不同環(huán)境之間切換。4.4 調(diào)用側(cè)代碼怎么寫兩種可落地的寫法如果你不想改JVM參數(shù)可以在代碼里指定信任庫。最簡單的寫法是在程序啟動早期設置系統(tǒng)屬性System.setProperty(javax.net.ssl.trustStore, /data/app/certs/truststore.p12); System.setProperty(javax.net.ssl.trustStorePassword, changeit);之后用RestTemplate、HttpClient、Feign等發(fā)HTTPS請求都會自動讀取這個信任庫。代價是全局生效同一個JVM里其他需要不同信任策略的請求也會被影響。更可控的方式是自己構造SSLContext。以JDK自帶的HttpsURLConnection為例講清楚原理public static SSLContext buildSslContext(String trustStorePath, String storePassword) throws Exception { KeyStore trustStore KeyStore.getInstance(PKCS12); try (InputStream in new FileInputStream(trustStorePath)) { trustStore.load(in, storePassword.toCharArray()); } TrustManagerFactory tmf TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm()); tmf.init(trustStore); SSLContext sslContext SSLContext.getInstance(TLS); sslContext.init(null, tmf.getTrustManagers(), new SecureRandom()); return sslContext; } // 使用 SSLContext sslContext buildSslContext(/data/app/certs/truststore.p12, changeit); HttpsURLConnection connection (HttpsURLConnection) new URL(https://localhost:8443/api).openConnection(); connection.setSSLSocketFactory(sslContext.getSocketFactory());如果你想用RestTemplate思路完全一樣把構造好的SSLContext塞給底層的HttpClient請求工廠。Feign、WebClient也都是換湯不換藥核心都是讓客戶端在驗證服務端證書時能走一條包含目標證書的信任鏈。4.5 開發(fā)環(huán)境能不能跳過校驗能但我只建議本地聯(lián)調(diào)時用。跳過校驗的本質(zhì)是讓TrustManager接收任何證書同時放開HostnameVerifierTrustManager[] trustAll new TrustManager[]{ new X509TrustManager() { public java.security.cert.X509Certificate[] getAcceptedIssuers() { return new java.security.cert.X509Certificate[0]; } public void checkServerTrusted(java.security.cert.X509Certificate[] chain, String authType) {} public void checkClientTrusted(java.security.cert.X509Certificate[] chain, String authType) {} } }; SSLContext sslContext SSLContext.getInstance(TLS); sslContext.init(null, trustAll, new SecureRandom()); HttpsURLConnection.setDefaultSSLSocketFactory(sslContext.getSocketFactory()); HttpsURLConnection.setDefaultHostnameVerifier((hostname, session) - true);這段代碼我調(diào)試時加過幾次確實一把梭。但生產(chǎn)環(huán)境真這么干HTTPS形同虛設中間人攻擊完全防不住。如果最后要交付別人的系統(tǒng)這種代碼不只是被code review打回的問題安全掃描直接就能標記出來。5. 雙向認證當服務端反過來要驗明調(diào)用者5.1 單向和雙向的區(qū)別前面講的都是單向HTTPS客戶端驗證服務器身份服務器不關心客戶端是誰。但在系統(tǒng)對系統(tǒng)的接口場景里有些安全要求高的對接方希望自己也驗證調(diào)用方的身份這就是雙向認證也叫mTLS。Spring Boot開啟雙向認證很簡單核心就一個配置server: ssl: client-auth: need trust-store: file:/data/app/certs/server-truststore.p12 trust-store-type: PKCS12 trust-store-password: changeitclient-auth有三個取值none不要求客戶端證書want請求客戶端證書但不強制客戶端不給也能繼續(xù)need強制必須有沒有直接握手失敗。做接口鑒權場景直接need。5.2 一套可以落地的mTLS配法雙向認證需要準備兩個密鑰庫服務端自己的server.p12以及客戶端自己的client.p12。為了演示我簡化成直接用自簽名的客戶端證書生產(chǎn)環(huán)境建議走完整CA體系。先生成客戶端證書keytool -genkeypair -alias client-1 -keyalg RSA -keysize 2048 \ -storetype PKCS12 -keystore client.p12 -validity 365 \ -dname CNclient-1, OUInternal, OExample \ -ext SANdns:client-1.internal然后把客戶端證書導出導入服務端的truststorekeytool -exportcert -alias client-1 -keystore client.p12 -storepass changeit -file client.cer keytool -importcert -alias client-1 -file client.cer -keystore server-truststore.p12 -storetype PKCS12 -storepass changeit反過來客戶端也要信任服務端證書所以把服務端證書導入客戶端的truststorekeytool -exportcert -alias app-server -keystore server.p12 -storepass changeit -file server.cer keytool -importcert -alias app-server -file server.cer -keystore client-truststore.p12 -storetype PKCS12 -storepass changeit客戶端調(diào)用代碼要同時加載自己的密鑰庫和信任服務端的truststoreKeyStore clientKeyStore KeyStore.getInstance(PKCS12); clientKeyStore.load(new FileInputStream(client.p12), changeit.toCharArray()); KeyManagerFactory kmf KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm()); kmf.init(clientKeyStore, changeit.toCharArray()); KeyStore clientTrustStore KeyStore.getInstance(PKCS12); clientTrustStore.load(new FileInputStream(client-truststore.p12), changeit.toCharArray()); TrustManagerFactory tmf TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm()); tmf.init(clientTrustStore); SSLContext sslContext SSLContext.getInstance(TLS); sslContext.init(kmf.getKeyManagers(), tmf.getTrustManagers(), new SecureRandom());然后把sslContext塞給調(diào)用HTTP的客戶端。如果漏了kmf.init這一步服務端通常報Client not authenticated或者bad certificate意思就是客戶端沒出示有效證書直接被拒了。5.3 mTLS踩坑記錄第一個坑是證書鏈。自建CA簽發(fā)證書時最好帶上完整鏈服務端truststore里不能只放根證書要把客戶端證書鏈上的各級證書都放進去否則驗證時找不到中間證書會報無法構建有效鏈。第二個坑是別名和密碼管理。PKCS12格式下密鑰庫密碼和密鑰密碼一致但導出導入時別名容易搞混。我有一次給三個系統(tǒng)各生成一套證書結(jié)果某個系統(tǒng)導錯了別名聯(lián)調(diào)時半天找不出問題。后來我固定了一套命名規(guī)范服務端別名統(tǒng)一app-server客戶端別名統(tǒng)一client-序號測試環(huán)境和生產(chǎn)環(huán)境分開維護再沒亂過。第三個坑是時間。證書有效期過了立刻握手失敗。雙向認證會兩邊都檢查任何一邊過期都不行。生產(chǎn)環(huán)境提前規(guī)劃續(xù)期窗口不要等到線上報錯了才想起來。6. 驗證三板斧與收尾細節(jié)curl、瀏覽器、日志外加我踩過的坑6.1 用curl快速驗證服務端重啟服務后我第一件事不是寫代碼調(diào)用而是先curl探一遍curl -v --cacert ca.crt https://localhost:8443/actuator/health-v能看到完整握手過程包括證書指紋、加密套件和是否被信任。想臨時跳過校驗可以用-kcurl -k https://localhost:8443/actuator/health能正常返回說明服務端TLS沒問題。接著用openssl s_client確認證書鏈、有效期和SAN能過濾掉一半以上的配置問題。6.2 瀏覽器訪問和Java客戶端行為不一樣瀏覽器和Java客戶端對證書不信任時的處理方式完全不同。瀏覽器會彈警告讓你點“繼續(xù)訪問”Java客戶端則是直接拋異常中斷。也就是說你在瀏覽器上點兩下能過的對方Java程序根本不會給你點“繼續(xù)”的機會。所以我交付前習慣用一個干凈環(huán)境跑一遍客戶端代碼先把證書導入信任庫確認正常再把證書移出確認拋出的異常是我們預期的證書異常。兩步走完就能確定還沒有補上的環(huán)節(jié)在哪里。6.3 日志怎么看Spring Boot默認日志基本看不到TLS握手細節(jié)。排查時可以先臨時打開DEBUGlogging: level: org.apache.tomcat: DEBUG org.apache.catalina: DEBUG org.springframework.boot.web.embedded.tomcat: DEBUG但真實項目里TLS握手問題在服務端日志經(jīng)常只有一行Handshake failed信息量有限。所以我更建議把問題帶到客戶端側(cè)看客戶端堆棧里的異常信息比服務端日志豐富得多。確認服務端證書沒問題后重點還是回到客戶端去查信任庫和主機名校驗。6.4 其他容易翻車的配置細節(jié)補充幾個我在實際項目里反復踩到的點8443端口被占用時啟動會報BindException用netstat -tlnp | grep 8443查一下。如果把server.port配成443Linux下非root用戶啟動會失敗因為小于1024端口需要特權。內(nèi)網(wǎng)環(huán)境我一般用8443避開這個限制。有些老版本JDK不支持TLSv1.3或某些客戶端只支持TLSv1.2enabled-protocols按需放寬。但別為了兼容老設備把TLSv1.0/1.1重新打開那等于舊漏洞又開了門。證書更新后一定要確認新證書的SAN和舊證書一致。我見過有人更新證書忘了SAN結(jié)果半個系統(tǒng)的調(diào)用全掛日志里全是主機名校驗失敗。最后分享一點個人體會搞明白HTTPS發(fā)布和調(diào)用真正難的不是Spring Boot那幾行配置而是證書信任模型的建立。你只要理解了證書、信任庫、私鑰、SSLContext這幾者的關系不管換什么框架、什么客戶端都能快速定位問題。我在實際項目中習慣把證書生成、導出、導入寫成一整套腳本放到運維目錄里換人接手也不至于對著命令行發(fā)懵。開發(fā)環(huán)境可以偶爾用跳過校驗偷懶但生產(chǎn)環(huán)境千萬別在這種地方省事。