：Web Crypto API、密鑰格式與混合加密全解析)
1. 項目緣起為什么前端要自己去實現(xiàn)RSA加密先說結(jié)論HTTPS已經(jīng)是事實標配但很多業(yè)務場景里前端依然需要單獨做一層RSA加密。舉幾個我實際遇到過的場景。第一個是登錄密碼的傳輸很多系統(tǒng)的登錄接口走的是HTTP內(nèi)網(wǎng)網(wǎng)關或者雖然有HTTPS但證書鏈本身有歷史遺留問題。這種情況下如果前端直接拿明文密碼往上傳風險不小。第二個場景是第三方對接對方接口要求客戶端提供公鑰加密后的RSA密文比如一些銀行對接、政務平臺對接密鑰體系是人家定死的你必須按對方的規(guī)則來。第三個場景是防抓包移動端或Web端提交的敏感數(shù)據(jù)即使有HTTPS如果設備本身被安裝了抓包工具加了RSA這一層抓到的也只是密文解密成本會高出很多。那有人會問既然有HTTPS為什么還要多此一舉我個人理解是這樣的HTTPS解決的是傳輸鏈路安全RSA解決的是數(shù)據(jù)本身的不可讀性。兩者不是替代關系而是疊加關系。尤其當你無法完全掌控服務器端和客戶端之間的每一跳網(wǎng)絡設備時應用層加密就是最后一道防線。這個項目我會圍繞JavaScript實現(xiàn)RSA加密和解密來做一次完整的落地記錄。會涉及瀏覽器端、Node.js端兩種環(huán)境包含密鑰生成、公鑰加密、私鑰解密、跨語言對接、長度限制、填充模式等核心環(huán)節(jié)。適合前端開發(fā)、全棧開發(fā)、以及對接口安全有要求的測試或運維同學參考。我不會只貼代碼更多會講清楚每一步為什么要這么做以及我踩過哪些坑。2. 方案選型原生Web Crypto API還是第三方庫2.1 原生Web Crypto API是首選先說說技術選型?，F(xiàn)代瀏覽器和Node.js原生都內(nèi)置了Web Crypto API也就是crypto.subtle這一套。它的最大優(yōu)勢是底層實現(xiàn)由瀏覽器或操作系統(tǒng)提供性能穩(wěn)定不依賴任何第三方包而且密鑰不會暴露到JavaScript堆內(nèi)存中安全級別更高。用原生API實現(xiàn)RSA加解密核心操作是這幾個// 生成RSA密鑰對 const keyPair await crypto.subtle.generateKey( { name: RSA-OAEP, modulusLength: 2048, publicExponent: new Uint8Array([1, 0, 1]), hash: SHA-256, }, true, [encrypt, decrypt] );modulusLength: 2048是當前最穩(wěn)妥的密鑰長度安全性夠性能也OK。1024位在2024年已經(jīng)明確不安全不建議使用。4096位則意味著更長的加解密耗時實際業(yè)務中大多是2048位。hash: SHA-256這個參數(shù)很多人會忽略。RSA-OAEP填充算法內(nèi)部需要一個哈希函數(shù)來生成掩碼這里選用SHA-256兼容性比SHA-1更好也符合當前安全基線。2.2 第三方庫的適用場景那第三方庫還有存在的必要嗎有。Web Crypto API雖然強大但有一個明顯痛點它只支持RSA-OAEP和RSA-PSS這兩種填充模式。RSA-PSS是簽名用的加解密只能用RSA-OAEP。但很多老系統(tǒng)和第三方接口用的是PKCS#1 v1.5填充也就是傳統(tǒng)意義上的RSA/ECB/PKCS1Padding。遇到這種情況我們就需要node-forge或jsencrypt來處理。另外一個場景是兼容性。雖然crypto.subtle在主流瀏覽器上普及率已經(jīng)很高但如果你需要兼容一些老舊內(nèi)核的WebView原生API可能不可用這時候第三方庫反而是救命稻草。2.3 選型對比維度Web Crypto APInode-forgejsencrypt依賴無需引入NPM包需引入NPM包填充模式RSA-OAEPOAEP PKCS#1 v1.5主要是PKCS#1 v1.5密鑰格式SPKI/PKCS#8支持PKCS#1、PKCS#8等多種格式主要PKCS#1性能原生實現(xiàn)性能最好純JS性能中等純JS體量更小適用場景瀏覽器端、Node.js端標準環(huán)境需要兼容老接口、復雜密鑰格式快速實現(xiàn)、前端表單加密我的建議是大部分新項目直接用Web Crypto API就夠了不需要引入任何第三方依賴。只有在對接老系統(tǒng)、對方強制要求PKCS#1 v1.5填充、或者密鑰格式比較特殊時才考慮引入node-forge。jsencrypt適合快速搞定一個簡單的公鑰加密功能但它的實現(xiàn)相對老舊功能也比較單一。這個項目中我主要用Web Crypto API來演示同時會給出node-forge的對照代碼方便你遇到老接口時能切換。3. 密鑰格式詳解不要輸在起跑線上3.1 SPKI、PKCS#8、PKCS#1是什么RSA加解密過程中最容易出錯的地方就是密鑰格式。很多人從后端拿到一串公鑰字符串直接丟給加密庫結(jié)果報錯完全摸不著頭腦。先說清楚三個標準SPKISubjectPublicKeyInfoX.509證書體系中的公鑰格式也是Web Crypto API導出公鑰時的默認格式。它包含算法標識、參數(shù)、RSA公鑰本體是一棵完整的ASN.1結(jié)構(gòu)樹。PKCS#8私鑰的標準化封裝格式同樣包含算法信息Web Crypto API導出私鑰時默認使用它。PKCS#1這是RSA密鑰最初的定義格式只包含RSA的數(shù)學參數(shù)本身沒有算法標識。老系統(tǒng)的Java、PHP代碼經(jīng)常輸出這種格式。打個比方SPKI像是一個帶標簽的快遞盒上面寫著這是RSA-OAEP的公鑰參數(shù)是SHA-256PKCS#1則像一個光溜溜的U盤里面只有數(shù)據(jù)本身你要知道它是什么格式才能正確讀取。在后端接口中最常見的公鑰字符串格式是PKCS#1的PEM文本以-----BEGIN RSA PUBLIC KEY-----開頭。而Web Crypto API導出的是SPKI格式以-----BEGIN PUBLIC KEY-----開頭。這兩者不能直接互換使用導入的時候必須指定正確的格式或者做轉(zhuǎn)換。3.2 導出、轉(zhuǎn)換與傳遞用Web Crypto API生成密鑰對后我們會把公鑰發(fā)給后端自己保存私鑰用于解密。公鑰默認導出的是ArrayBuffer我們需要轉(zhuǎn)成Base64字符串方便傳輸// 導出公鑰為SPKI格式的Base64字符串 async function exportPublicKeyBase64(keyPair) { const spkiBuffer await crypto.subtle.exportKey(spki, keyPair.publicKey); return arrayBufferToBase64(spkiBuffer); } // ArrayBuffer轉(zhuǎn)Base64這里用分片編碼避免大字符串溢出 function arrayBufferToBase64(buffer) { const bytes new Uint8Array(buffer); let binary ; for (let i 0; i bytes.length; i) { binary String.fromCharCode(bytes[i]); } return btoa(binary); }如果你需要PKCS#1格式的公鑰給Java后端用最簡單的方式是用node-forge做轉(zhuǎn)換。我在這里也踩過一次坑后面會展開說。私鑰的導出方式和公鑰類似只是格式是PKCS#8const privateKeyBuffer await crypto.subtle.exportKey(pkcs8, keyPair.privateKey);需要特別注意私鑰字符串絕對不能通過日志、接口響應等途徑暴露出去。私鑰永遠只應該保存在服務端的安全存儲中或者是客戶端的本地安全存儲里。前端持有私鑰的場景通常只出現(xiàn)在端到端加密這樣的特殊業(yè)務中。4. 核心實現(xiàn)瀏覽器端的RSA加密與解密全流程4.1 完整代碼生成密鑰對、加密、解密下面是一套可以在現(xiàn)代瀏覽器中直接運行的完整實現(xiàn)。這段代碼解決的是最典型的需求前端生成密鑰對把公鑰交給服務端服務端用公鑰加密數(shù)據(jù)前端用私鑰解密。class RSAHelper { constructor() { this.keyPair null; } // 初始化生成RSA-OAEP密鑰對 async init() { this.keyPair await crypto.subtle.generateKey( { name: RSA-OAEP, modulusLength: 2048, publicExponent: new Uint8Array([1, 0, 1]), hash: SHA-256, }, true, [encrypt, decrypt] ); } // 公鑰Base64字符串SPKI格式 async getPublicKey() { const spki await crypto.subtle.exportKey(spki, this.keyPair.publicKey); return arrayBufferToBase64(spki); } // 私鑰Base64字符串PKCS#8格式 async getPrivateKey() { const pkcs8 await crypto.subtle.exportKey(pkcs8, this.keyPair.privateKey); return arrayBufferToBase64(pkcs8); } // 使用別人的公鑰加密 static async encryptWithPublicKey(publicKeyBase64, plainText) { const publicKey await crypto.subtle.importKey( spki, base64ToArrayBuffer(publicKeyBase64), { name: RSA-OAEP, hash: SHA-256, }, false, [encrypt] ); const encoded new TextEncoder().encode(plainText); const encryptedBuffer await crypto.subtle.encrypt( { name: RSA-OAEP, }, publicKey, encoded ); return arrayBufferToBase64(encryptedBuffer); } // 使用自己的私鑰解密 static async decryptWithPrivateKey(privateKeyBase64, cipherBase64) { const privateKey await crypto.subtle.importKey( pkcs8, base64ToArrayBuffer(privateKeyBase64), { name: RSA-OAEP, hash: SHA-256, }, false, [decrypt] ); const decryptedBuffer await crypto.subtle.decrypt( { name: RSA-OAEP, }, privateKey, base64ToArrayBuffer(cipherBase64) ); return new TextDecoder().decode(decryptedBuffer); } }配套的Base64轉(zhuǎn)換函數(shù)需要兩個方向都寫完整我在真實項目里發(fā)現(xiàn)很多人只寫了arrayBufferToBase64忘了base64ToArrayBuffer也需要處理二進制數(shù)據(jù)結(jié)果解密時拿到的是亂碼或者直接報錯。// Base64字符串轉(zhuǎn)ArrayBuffer function base64ToArrayBuffer(base64String) { const binaryString atob(base64String); const bytes new Uint8Array(binaryString.length); for (let i 0; i binaryString.length; i) { bytes[i] binaryString.charCodeAt(i); } return bytes.buffer; }4.2 使用說明上面的代碼中init()方法在頁面加載時調(diào)用一次即可。生成密鑰對之后把公鑰字符串發(fā)給后端后端用它加密返回數(shù)據(jù)。解密時調(diào)用decryptWithPrivateKey傳入你保存的私鑰和密文就能得到明文。需要注意私鑰保存后不要直接塞到localStorage里如果一定要在客戶端保存建議配合IndexedDB加權(quán)限隔離或者用Web Crypto API的crypto.subtle.wrapKey先包裝一層。關于TextEncoder和TextDecoderRSA加密操作的對象是字節(jié)序列不是字符串。直接用JSON.stringify后的字符串去加密是沒問題的但解密后要記得用JSON.parse還原或者統(tǒng)一走TextEncoder/TextDecoder處理避免中文亂碼和特殊字符錯亂。我在實際調(diào)試中遇到過這樣的情況加密正常后端能解密但是解密出來中文是寰堝ソ這種亂碼。排查后發(fā)現(xiàn)問題出在后端把字符串按UTF-8編碼時前端傳過去的密文是Base64字符串后端沒有先解碼成字節(jié)就直接做了解密。這類問題不是RSA本身的問題而是編碼鏈路沒對齊。4.3 填充模式與最大明文長度這一點必須單獨拿出來講因為它經(jīng)常成為生產(chǎn)事故的根源。RSA-OAEP加密時2048位密鑰對應256字節(jié)的密文塊明文長度上限是最大明文長度 密鑰字節(jié)數(shù) - 2 * 哈希長度 - 2當hash選擇SHA-256時哈希長度是32字節(jié)所以計算公式為256 - 2 * 32 - 2 190字節(jié)也就是說在RSA-OAEP SHA-256 2048位密鑰的組合下單次最多只能加密190字節(jié)的明文。如果明文超過這個長度crypto.subtle.encrypt直接會拋DataError異常。這是很多人第一次接觸RSA時最容易忽略的點。RSA本身不是用來加密大體積數(shù)據(jù)的它適合加密對稱密鑰、小字段、短文本。如果你要加密的內(nèi)容超過190字節(jié)常規(guī)做法是走混合加密用RSA加密一個AES對稱密鑰再用AES去加密實際數(shù)據(jù)。后面第6節(jié)我會給出一個完整的混合加密例子那是實際項目中更通用的方案。5. 服務端對接跨語言兼容的實戰(zhàn)要點5.1 和Node.js后端對接最常見的場景是前端調(diào)用后端接口后端返回一個RSA公鑰前端用這個公鑰加密請求體中的某個字段。Node.js端可以使用crypto內(nèi)置模塊完成解密不需要額外安裝東西const crypto require(crypto); function decryptWithPrivateKey(privateKeyPem, encryptedBase64) { // 注意這里默認前端傳入的密文是Base64格式 const buffer Buffer.from(encryptedBase64, base64); const decrypted crypto.privateDecrypt( { key: privateKeyPem, padding: crypto.constants.RSA_PKCS1_OAEP_PADDING, oaepHash: sha256, }, buffer ); return decrypted.toString(utf8); }關鍵點在于oaepHash: sha256必須和前端生成密鑰時指定的hash: SHA-256一致。如果前端用SHA-1后端用SHA-256或者反過來解密必然報錯。5.2 和Java后端對接Java端常見寫法是Cipher cipher Cipher.getInstance(RSA/ECB/OAEPWithSHA-256AndMGF1Padding); cipher.init(Cipher.DECRYPT_MODE, privateKey); byte[] plainBytes cipher.doFinal(Base64.getDecoder().decode(encryptedBase64));這里的OAEPWithSHA-256AndMGF1Padding對應前端的RSA-OAEP SHA-256但Java默認的MGF1摘要可能也是SHA-256有些版本默認MGF1用的SHA-1這會導致前端加密、后端解密時出現(xiàn)javax.crypto.BadPaddingException。遇到這種情況需要顯式指定MGF1參數(shù)或者前端調(diào)整Hash算法。我在實際對接中踩過一個特別典型的坑Java后端返回的公鑰是PKCS#1格式前端importKey時指定了spki結(jié)果直接報錯。后來我把前端的導入格式改成pkcs1但Web Crypto API原生并不支持直接導入PKCS#1格式必須先用node-forge轉(zhuǎn)成SPKI。下面是一段node-forge的轉(zhuǎn)換示例const forge require(node-forge); // 將PKCS#1 PEM轉(zhuǎn)換為SPKI PEM function pkcs1ToSpki(pkcs1Pem) { const publicKey forge.pki.publicKeyFromPem(pkcs1Pem); const asn1 forge.pki.publicKeyToAsn1(publicKey); const spkiPem forge.pki.publicKeyToPem( forge.pki.publicKeyFromAsn1(asn1) ); return spkiPem; }記住一個原則不同語言、不同庫之間互調(diào)密鑰格式和填充模式必須兩邊對齊。上線前先打印日志確認兩邊的密鑰格式字符串和算法參數(shù)能省掉大量排查時間。5.3 常見錯誤速查對接過程中如果報錯可以從這張表快速定位問題報錯信息可能原因解決方向TypeError: Cannot read properties of undefined (reading encrypt)瀏覽器環(huán)境不支持crypto.subtle檢查協(xié)議是否為HTTPS或localhost檢查瀏覽器版本DOMException: The operation is for an incompatible object導入密鑰時指定的算法參數(shù)與密鑰實際生成參數(shù)不一致統(tǒng)一指定相同的hash算法Error: Error during decryption填充模式不匹配確認OAEP與PKCS#1 v1.5的一致性javax.crypto.BadPaddingExceptionJava解密時MGF1摘要算法與前端不一致顯式設置MGF1參數(shù)或調(diào)整前端hashDataError明文長度超過190字節(jié)改用混合加密或分段加密還有一個容易被忽略的問題Base64字符串中如果混入了換行符atob會解析失敗。很多PEM格式的密鑰在傳輸過程中會被自動換行前端拿到的字符串里可能帶了\n最好先做一次replace(/\r?\n/g, )再處理。6. 混合加密實踐RSA加密長文本的通用方案6.1 為什么必須用混合加密前面提到RSA的明文長度上限是190字節(jié)這在真實業(yè)務中遠遠不夠。一個JSON請求體比如{ userId: 10001, timestamp: 1700000000000, data: { name: 張三, phone: 13800138000, remark: 這是一段比較長的備注信息 } }轉(zhuǎn)成字符串后很容易超過190字節(jié)。如果用RSA直接加密分分鐘報錯。解決思路是混合加密用AES加密實際內(nèi)容再用RSA加密AES的密鑰。這個方案在HTTPS中也是這么干的握手時用非對稱算法協(xié)商對稱密鑰之后所有數(shù)據(jù)走對稱加密。6.2 前端混合加密完整代碼// 生成AES密鑰并用RSA公鑰加密 async function hybridEncrypt(rsaPublicKeyBase64, plainText) { // 1. 生成AES-GCM密鑰 const aesKey await crypto.subtle.generateKey( { name: AES-GCM, length: 256, }, true, [encrypt, decrypt] ); // 2. 生成IV const iv crypto.getRandomValues(new Uint8Array(12)); // 3. AES-GCM加密明文 const encodedData new TextEncoder().encode(plainText); const encryptedData await crypto.subtle.encrypt( { name: AES-GCM, iv: iv, }, aesKey, encodedData ); // 4. 導出AES密鑰并使用RSA公鑰加密 const rawAesKey await crypto.subtle.exportKey(raw, aesKey); const publicKey await crypto.subtle.importKey( spki, base64ToArrayBuffer(rsaPublicKeyBase64), { name: RSA-OAEP, hash: SHA-256, }, false, [encrypt] ); const encryptedAesKey await crypto.subtle.encrypt( { name: RSA-OAEP, }, publicKey, rawAesKey ); // 5. 打包返回加密后的AES密鑰 IV 密文 return { encryptedAesKey: arrayBufferToBase64(encryptedAesKey), iv: arrayBufferToBase64(iv.buffer), encryptedData: arrayBufferToBase64(encryptedData), }; }6.3 后端解密對應的Node.js實現(xiàn)const crypto require(crypto); function hybridDecrypt(privateKeyPem, payload) { const { encryptedAesKey, iv, encryptedData } payload; // 1. 用RSA私鑰解密出AES密鑰 const aesKeyBuffer crypto.privateDecrypt( { key: privateKeyPem, padding: crypto.constants.RSA_PKCS1_OAEP_PADDING, oaepHash: sha256, }, Buffer.from(encryptedAesKey, base64) ); // 2. 用AES-GCM解密數(shù)據(jù) const decipher crypto.createDecipheriv( aes-256-gcm, aesKeyBuffer, Buffer.from(iv, base64) ); // 這里注意GCM模式需要處理auth tag const encryptedBuffer Buffer.from(encryptedData, base64); const authTag encryptedBuffer.subarray(encryptedBuffer.length - 16); const dataBuffer encryptedBuffer.subarray(0, encryptedBuffer.length - 16); decipher.setAuthTag(authTag); const decrypted Buffer.concat([ decipher.update(dataBuffer), decipher.final(), ]); return decrypted.toString(utf8); }這段代碼有幾個細節(jié)值得注意。AES-GCM的認證標簽默認是16字節(jié)前端crypto.subtle.encrypt返回的密文中已經(jīng)包含了認證標簽所以后端需要從密文末尾拆出tag再調(diào)用setAuthTag。如果不設置解密時會直接拋錯提示Unsupported state or unable to authenticate data?；旌霞用艿暮锰幰皇侵С秩我忾L度的數(shù)據(jù)二是因為數(shù)據(jù)主體走的是AES對稱加密加解密性能遠高于純RSA。思路和應用層如何實現(xiàn)都建立在這套方案上。6.4 什么時候不需要混合加密如果你的數(shù)據(jù)量很小比如就是加密個驗證碼、手機號、身份證號長度不超過190字節(jié)直接用RSA就夠了不需要引入AES那套復雜度。業(yè)務簡單性也是工程價值的一部分。我見過不少項目為了看起來安全把混合加密寫上去了結(jié)果增加了前后端聯(lián)調(diào)成本卻沒有帶來本質(zhì)收益。密鑰管理、密鑰輪換、審計日志這些沒跟上方案再復雜也是白搭。7. 安全底線與常見坑現(xiàn)場排查實錄7.1 再強調(diào)一遍RSA加密不等于絕對安全分享一段我經(jīng)歷過的真實排查過程。有一個系統(tǒng)前端用RSA公鑰加密登錄密碼后端用私鑰解密看起來沒啥問題。但后來安全團隊測試發(fā)現(xiàn)只要抓包拿到密文直接重放到接口上服務端照樣解密成功登錄照樣通過。問題出在哪缺少防重放機制。RSA加密解決的是數(shù)據(jù)傳輸過程中的不可讀性但密文本身可以被錄制、復制、重放。這就像你寫了一封加密信但信被偷看后小偷可以把信原封不動再交一次。真正安全的接口必須有時間戳、隨機數(shù)、序列號之類的機制結(jié)合驗證。我建議在前端加密時把當前時間戳和隨機字符串拼進明文服務端解密后校驗時間戳的時效性比如允許5分鐘內(nèi)有效同時維護一個已使用隨機數(shù)列表來防重放。7.2 密鑰管理的前端注意事項另一個高頻問題是密鑰的存儲安全。前端瀏覽器環(huán)境中任何保存在localStorage、sessionStorage中的數(shù)據(jù)都面臨XSS攻擊的威脅。如果攻擊者能在頁面注入腳本他就能直接讀取私鑰字符串。我在項目中的做法是前端私鑰只在本次會話中保留在內(nèi)存變量里不寫入localStorage。如果一定要持久化使用IndexedDB并配合CSP內(nèi)容安全策略降低XSS風險。加密私鑰時用crypto.subtle.wrapKey配合另一個密鑰來包裹私鑰。7.3 一次完整的聯(lián)調(diào)排查記錄有一次我負責的項目里前端在Chrome上加密正常但測試同學在某個國產(chǎn)瀏覽器的極速模式下解密失敗。打開控制臺發(fā)現(xiàn)crypto.subtle是undefined說明內(nèi)核比較舊。當時的處理方案是在初始化時做一個特性檢測if (window.crypto window.crypto.subtle) { // 使用Web Crypto API } else { // 降級到node-forge }后來項目組要求兼容的瀏覽器列表里移除了那個老內(nèi)核版本才徹底砍掉了降級邏輯。但這里也說明一個經(jīng)驗產(chǎn)品規(guī)劃階段就要明確兼容目標技術方案要和兼容矩陣對齊。7.4 實用檢查清單我把自己每次上線的自檢項整理成了一張清單供參考[ ] 密鑰長度是否不低于2048位[ ] 前后端hash算法是否完全一致SHA-256[ ] 公鑰導入格式是否與后端導出一致SPKI還是PKCS#1[ ] 加密數(shù)據(jù)的長度是否在190字節(jié)以內(nèi)如果超出是否已走混合加密[ ] Base64字符串是否處理過換行符[ ] 是否加入了時間戳和隨機數(shù)防重放[ ] 私鑰是否未寫入localStorage[ ] 是否做了crypto.subtle特性檢測[ ] 是否處理過中文編碼TextEncoder/TextDecoder[ ] 是否確認服務端日志不會打印私鑰和明文8. 個人實操心得在這個項目的整個過程中我最大的體會是RSA加解密的代碼本身并不復雜真正的復雜度在于格式對齊、參數(shù)對齊和場景判斷。crypto.subtle.generateKey、encrypt、decrypt這些API用起來很快但如果你不去理解SPKI和PKCS#1的區(qū)別不理解為什么RSA-OAEP限制了明文長度不理解為什么Java后端的MGF1參數(shù)會導致解密失敗那么代碼寫得再順手聯(lián)調(diào)時也會被各種詭異的報錯折騰到懷疑人生。最后再分享一個小技巧。在聯(lián)調(diào)階段我習慣在前端和后端各寫一個自測用例前端用公鑰加密一段固定字符串解密后對拍后端用私鑰解密前端生成的密文再對拍明文。兩邊能對上同一個值接口聯(lián)調(diào)才真正有把握。這個習慣幫我節(jié)省了大量時間也避免了上線后才發(fā)現(xiàn)兩邊算法不一致的尷尬。 前端RSA加密實戰(zhàn)：Web Crypto API、密鑰格式與混合加密全解析
1. 項目緣起為什么前端要自己去實現(xiàn)RSA加密先說結(jié)論HTTPS已經(jīng)是事實標配但很多業(yè)務場景里前端依然需要單獨做一層RSA加密。舉幾個我實際遇到過的場景。第一個是登錄密碼的傳輸很多系統(tǒng)的登錄接口走的是HTTP內(nèi)網(wǎng)網(wǎng)關或者雖然有HTTPS但證書鏈本身有歷史遺留問題。這種情況下如果前端直接拿明文密碼往上傳風險不小。第二個場景是第三方對接對方接口要求客戶端提供公鑰加密后的RSA密文比如一些銀行對接、政務平臺對接密鑰體系是人家定死的你必須按對方的規(guī)則來。第三個場景是防抓包移動端或Web端提交的敏感數(shù)據(jù)即使有HTTPS如果設備本身被安裝了抓包工具加了RSA這一層抓到的也只是密文解密成本會高出很多。那有人會問既然有HTTPS為什么還要多此一舉我個人理解是這樣的HTTPS解決的是傳輸鏈路安全RSA解決的是數(shù)據(jù)本身的不可讀性。兩者不是替代關系而是疊加關系。尤其當你無法完全掌控服務器端和客戶端之間的每一跳網(wǎng)絡設備時應用層加密就是最后一道防線。這個項目我會圍繞JavaScript實現(xiàn)RSA加密和解密來做一次完整的落地記錄。會涉及瀏覽器端、Node.js端兩種環(huán)境包含密鑰生成、公鑰加密、私鑰解密、跨語言對接、長度限制、填充模式等核心環(huán)節(jié)。適合前端開發(fā)、全棧開發(fā)、以及對接口安全有要求的測試或運維同學參考。我不會只貼代碼更多會講清楚每一步為什么要這么做以及我踩過哪些坑。2. 方案選型原生Web Crypto API還是第三方庫2.1 原生Web Crypto API是首選先說說技術選型?，F(xiàn)代瀏覽器和Node.js原生都內(nèi)置了Web Crypto API也就是crypto.subtle這一套。它的最大優(yōu)勢是底層實現(xiàn)由瀏覽器或操作系統(tǒng)提供性能穩(wěn)定不依賴任何第三方包而且密鑰不會暴露到JavaScript堆內(nèi)存中安全級別更高。用原生API實現(xiàn)RSA加解密核心操作是這幾個// 生成RSA密鑰對 const keyPair await crypto.subtle.generateKey( { name: RSA-OAEP, modulusLength: 2048, publicExponent: new Uint8Array([1, 0, 1]), hash: SHA-256, }, true, [encrypt, decrypt] );modulusLength: 2048是當前最穩(wěn)妥的密鑰長度安全性夠性能也OK。1024位在2024年已經(jīng)明確不安全不建議使用。4096位則意味著更長的加解密耗時實際業(yè)務中大多是2048位。hash: SHA-256這個參數(shù)很多人會忽略。RSA-OAEP填充算法內(nèi)部需要一個哈希函數(shù)來生成掩碼這里選用SHA-256兼容性比SHA-1更好也符合當前安全基線。2.2 第三方庫的適用場景那第三方庫還有存在的必要嗎有。Web Crypto API雖然強大但有一個明顯痛點它只支持RSA-OAEP和RSA-PSS這兩種填充模式。RSA-PSS是簽名用的加解密只能用RSA-OAEP。但很多老系統(tǒng)和第三方接口用的是PKCS#1 v1.5填充也就是傳統(tǒng)意義上的RSA/ECB/PKCS1Padding。遇到這種情況我們就需要node-forge或jsencrypt來處理。另外一個場景是兼容性。雖然crypto.subtle在主流瀏覽器上普及率已經(jīng)很高但如果你需要兼容一些老舊內(nèi)核的WebView原生API可能不可用這時候第三方庫反而是救命稻草。2.3 選型對比維度Web Crypto APInode-forgejsencrypt依賴無需引入NPM包需引入NPM包填充模式RSA-OAEPOAEP PKCS#1 v1.5主要是PKCS#1 v1.5密鑰格式SPKI/PKCS#8支持PKCS#1、PKCS#8等多種格式主要PKCS#1性能原生實現(xiàn)性能最好純JS性能中等純JS體量更小適用場景瀏覽器端、Node.js端標準環(huán)境需要兼容老接口、復雜密鑰格式快速實現(xiàn)、前端表單加密我的建議是大部分新項目直接用Web Crypto API就夠了不需要引入任何第三方依賴。只有在對接老系統(tǒng)、對方強制要求PKCS#1 v1.5填充、或者密鑰格式比較特殊時才考慮引入node-forge。jsencrypt適合快速搞定一個簡單的公鑰加密功能但它的實現(xiàn)相對老舊功能也比較單一。這個項目中我主要用Web Crypto API來演示同時會給出node-forge的對照代碼方便你遇到老接口時能切換。3. 密鑰格式詳解不要輸在起跑線上3.1 SPKI、PKCS#8、PKCS#1是什么RSA加解密過程中最容易出錯的地方就是密鑰格式。很多人從后端拿到一串公鑰字符串直接丟給加密庫結(jié)果報錯完全摸不著頭腦。先說清楚三個標準SPKISubjectPublicKeyInfoX.509證書體系中的公鑰格式也是Web Crypto API導出公鑰時的默認格式。它包含算法標識、參數(shù)、RSA公鑰本體是一棵完整的ASN.1結(jié)構(gòu)樹。PKCS#8私鑰的標準化封裝格式同樣包含算法信息Web Crypto API導出私鑰時默認使用它。PKCS#1這是RSA密鑰最初的定義格式只包含RSA的數(shù)學參數(shù)本身沒有算法標識。老系統(tǒng)的Java、PHP代碼經(jīng)常輸出這種格式。打個比方SPKI像是一個帶標簽的快遞盒上面寫著這是RSA-OAEP的公鑰參數(shù)是SHA-256PKCS#1則像一個光溜溜的U盤里面只有數(shù)據(jù)本身你要知道它是什么格式才能正確讀取。在后端接口中最常見的公鑰字符串格式是PKCS#1的PEM文本以-----BEGIN RSA PUBLIC KEY-----開頭。而Web Crypto API導出的是SPKI格式以-----BEGIN PUBLIC KEY-----開頭。這兩者不能直接互換使用導入的時候必須指定正確的格式或者做轉(zhuǎn)換。3.2 導出、轉(zhuǎn)換與傳遞用Web Crypto API生成密鑰對后我們會把公鑰發(fā)給后端自己保存私鑰用于解密。公鑰默認導出的是ArrayBuffer我們需要轉(zhuǎn)成Base64字符串方便傳輸// 導出公鑰為SPKI格式的Base64字符串 async function exportPublicKeyBase64(keyPair) { const spkiBuffer await crypto.subtle.exportKey(spki, keyPair.publicKey); return arrayBufferToBase64(spkiBuffer); } // ArrayBuffer轉(zhuǎn)Base64這里用分片編碼避免大字符串溢出 function arrayBufferToBase64(buffer) { const bytes new Uint8Array(buffer); let binary ; for (let i 0; i bytes.length; i) { binary String.fromCharCode(bytes[i]); } return btoa(binary); }如果你需要PKCS#1格式的公鑰給Java后端用最簡單的方式是用node-forge做轉(zhuǎn)換。我在這里也踩過一次坑后面會展開說。私鑰的導出方式和公鑰類似只是格式是PKCS#8const privateKeyBuffer await crypto.subtle.exportKey(pkcs8, keyPair.privateKey);需要特別注意私鑰字符串絕對不能通過日志、接口響應等途徑暴露出去。私鑰永遠只應該保存在服務端的安全存儲中或者是客戶端的本地安全存儲里。前端持有私鑰的場景通常只出現(xiàn)在端到端加密這樣的特殊業(yè)務中。4. 核心實現(xiàn)瀏覽器端的RSA加密與解密全流程4.1 完整代碼生成密鑰對、加密、解密下面是一套可以在現(xiàn)代瀏覽器中直接運行的完整實現(xiàn)。這段代碼解決的是最典型的需求前端生成密鑰對把公鑰交給服務端服務端用公鑰加密數(shù)據(jù)前端用私鑰解密。class RSAHelper { constructor() { this.keyPair null; } // 初始化生成RSA-OAEP密鑰對 async init() { this.keyPair await crypto.subtle.generateKey( { name: RSA-OAEP, modulusLength: 2048, publicExponent: new Uint8Array([1, 0, 1]), hash: SHA-256, }, true, [encrypt, decrypt] ); } // 公鑰Base64字符串SPKI格式 async getPublicKey() { const spki await crypto.subtle.exportKey(spki, this.keyPair.publicKey); return arrayBufferToBase64(spki); } // 私鑰Base64字符串PKCS#8格式 async getPrivateKey() { const pkcs8 await crypto.subtle.exportKey(pkcs8, this.keyPair.privateKey); return arrayBufferToBase64(pkcs8); } // 使用別人的公鑰加密 static async encryptWithPublicKey(publicKeyBase64, plainText) { const publicKey await crypto.subtle.importKey( spki, base64ToArrayBuffer(publicKeyBase64), { name: RSA-OAEP, hash: SHA-256, }, false, [encrypt] ); const encoded new TextEncoder().encode(plainText); const encryptedBuffer await crypto.subtle.encrypt( { name: RSA-OAEP, }, publicKey, encoded ); return arrayBufferToBase64(encryptedBuffer); } // 使用自己的私鑰解密 static async decryptWithPrivateKey(privateKeyBase64, cipherBase64) { const privateKey await crypto.subtle.importKey( pkcs8, base64ToArrayBuffer(privateKeyBase64), { name: RSA-OAEP, hash: SHA-256, }, false, [decrypt] ); const decryptedBuffer await crypto.subtle.decrypt( { name: RSA-OAEP, }, privateKey, base64ToArrayBuffer(cipherBase64) ); return new TextDecoder().decode(decryptedBuffer); } }配套的Base64轉(zhuǎn)換函數(shù)需要兩個方向都寫完整我在真實項目里發(fā)現(xiàn)很多人只寫了arrayBufferToBase64忘了base64ToArrayBuffer也需要處理二進制數(shù)據(jù)結(jié)果解密時拿到的是亂碼或者直接報錯。// Base64字符串轉(zhuǎn)ArrayBuffer function base64ToArrayBuffer(base64String) { const binaryString atob(base64String); const bytes new Uint8Array(binaryString.length); for (let i 0; i binaryString.length; i) { bytes[i] binaryString.charCodeAt(i); } return bytes.buffer; }4.2 使用說明上面的代碼中init()方法在頁面加載時調(diào)用一次即可。生成密鑰對之后把公鑰字符串發(fā)給后端后端用它加密返回數(shù)據(jù)。解密時調(diào)用decryptWithPrivateKey傳入你保存的私鑰和密文就能得到明文。需要注意私鑰保存后不要直接塞到localStorage里如果一定要在客戶端保存建議配合IndexedDB加權(quán)限隔離或者用Web Crypto API的crypto.subtle.wrapKey先包裝一層。關于TextEncoder和TextDecoderRSA加密操作的對象是字節(jié)序列不是字符串。直接用JSON.stringify后的字符串去加密是沒問題的但解密后要記得用JSON.parse還原或者統(tǒng)一走TextEncoder/TextDecoder處理避免中文亂碼和特殊字符錯亂。我在實際調(diào)試中遇到過這樣的情況加密正常后端能解密但是解密出來中文是寰堝ソ這種亂碼。排查后發(fā)現(xiàn)問題出在后端把字符串按UTF-8編碼時前端傳過去的密文是Base64字符串后端沒有先解碼成字節(jié)就直接做了解密。這類問題不是RSA本身的問題而是編碼鏈路沒對齊。4.3 填充模式與最大明文長度這一點必須單獨拿出來講因為它經(jīng)常成為生產(chǎn)事故的根源。RSA-OAEP加密時2048位密鑰對應256字節(jié)的密文塊明文長度上限是最大明文長度 密鑰字節(jié)數(shù) - 2 * 哈希長度 - 2當hash選擇SHA-256時哈希長度是32字節(jié)所以計算公式為256 - 2 * 32 - 2 190字節(jié)也就是說在RSA-OAEP SHA-256 2048位密鑰的組合下單次最多只能加密190字節(jié)的明文。如果明文超過這個長度crypto.subtle.encrypt直接會拋DataError異常。這是很多人第一次接觸RSA時最容易忽略的點。RSA本身不是用來加密大體積數(shù)據(jù)的它適合加密對稱密鑰、小字段、短文本。如果你要加密的內(nèi)容超過190字節(jié)常規(guī)做法是走混合加密用RSA加密一個AES對稱密鑰再用AES去加密實際數(shù)據(jù)。后面第6節(jié)我會給出一個完整的混合加密例子那是實際項目中更通用的方案。5. 服務端對接跨語言兼容的實戰(zhàn)要點5.1 和Node.js后端對接最常見的場景是前端調(diào)用后端接口后端返回一個RSA公鑰前端用這個公鑰加密請求體中的某個字段。Node.js端可以使用crypto內(nèi)置模塊完成解密不需要額外安裝東西const crypto require(crypto); function decryptWithPrivateKey(privateKeyPem, encryptedBase64) { // 注意這里默認前端傳入的密文是Base64格式 const buffer Buffer.from(encryptedBase64, base64); const decrypted crypto.privateDecrypt( { key: privateKeyPem, padding: crypto.constants.RSA_PKCS1_OAEP_PADDING, oaepHash: sha256, }, buffer ); return decrypted.toString(utf8); }關鍵點在于oaepHash: sha256必須和前端生成密鑰時指定的hash: SHA-256一致。如果前端用SHA-1后端用SHA-256或者反過來解密必然報錯。5.2 和Java后端對接Java端常見寫法是Cipher cipher Cipher.getInstance(RSA/ECB/OAEPWithSHA-256AndMGF1Padding); cipher.init(Cipher.DECRYPT_MODE, privateKey); byte[] plainBytes cipher.doFinal(Base64.getDecoder().decode(encryptedBase64));這里的OAEPWithSHA-256AndMGF1Padding對應前端的RSA-OAEP SHA-256但Java默認的MGF1摘要可能也是SHA-256有些版本默認MGF1用的SHA-1這會導致前端加密、后端解密時出現(xiàn)javax.crypto.BadPaddingException。遇到這種情況需要顯式指定MGF1參數(shù)或者前端調(diào)整Hash算法。我在實際對接中踩過一個特別典型的坑Java后端返回的公鑰是PKCS#1格式前端importKey時指定了spki結(jié)果直接報錯。后來我把前端的導入格式改成pkcs1但Web Crypto API原生并不支持直接導入PKCS#1格式必須先用node-forge轉(zhuǎn)成SPKI。下面是一段node-forge的轉(zhuǎn)換示例const forge require(node-forge); // 將PKCS#1 PEM轉(zhuǎn)換為SPKI PEM function pkcs1ToSpki(pkcs1Pem) { const publicKey forge.pki.publicKeyFromPem(pkcs1Pem); const asn1 forge.pki.publicKeyToAsn1(publicKey); const spkiPem forge.pki.publicKeyToPem( forge.pki.publicKeyFromAsn1(asn1) ); return spkiPem; }記住一個原則不同語言、不同庫之間互調(diào)密鑰格式和填充模式必須兩邊對齊。上線前先打印日志確認兩邊的密鑰格式字符串和算法參數(shù)能省掉大量排查時間。5.3 常見錯誤速查對接過程中如果報錯可以從這張表快速定位問題報錯信息可能原因解決方向TypeError: Cannot read properties of undefined (reading encrypt)瀏覽器環(huán)境不支持crypto.subtle檢查協(xié)議是否為HTTPS或localhost檢查瀏覽器版本DOMException: The operation is for an incompatible object導入密鑰時指定的算法參數(shù)與密鑰實際生成參數(shù)不一致統(tǒng)一指定相同的hash算法Error: Error during decryption填充模式不匹配確認OAEP與PKCS#1 v1.5的一致性javax.crypto.BadPaddingExceptionJava解密時MGF1摘要算法與前端不一致顯式設置MGF1參數(shù)或調(diào)整前端hashDataError明文長度超過190字節(jié)改用混合加密或分段加密還有一個容易被忽略的問題Base64字符串中如果混入了換行符atob會解析失敗。很多PEM格式的密鑰在傳輸過程中會被自動換行前端拿到的字符串里可能帶了\n最好先做一次replace(/\r?\n/g, )再處理。6. 混合加密實踐RSA加密長文本的通用方案6.1 為什么必須用混合加密前面提到RSA的明文長度上限是190字節(jié)這在真實業(yè)務中遠遠不夠。一個JSON請求體比如{ userId: 10001, timestamp: 1700000000000, data: { name: 張三, phone: 13800138000, remark: 這是一段比較長的備注信息 } }轉(zhuǎn)成字符串后很容易超過190字節(jié)。如果用RSA直接加密分分鐘報錯。解決思路是混合加密用AES加密實際內(nèi)容再用RSA加密AES的密鑰。這個方案在HTTPS中也是這么干的握手時用非對稱算法協(xié)商對稱密鑰之后所有數(shù)據(jù)走對稱加密。6.2 前端混合加密完整代碼// 生成AES密鑰并用RSA公鑰加密 async function hybridEncrypt(rsaPublicKeyBase64, plainText) { // 1. 生成AES-GCM密鑰 const aesKey await crypto.subtle.generateKey( { name: AES-GCM, length: 256, }, true, [encrypt, decrypt] ); // 2. 生成IV const iv crypto.getRandomValues(new Uint8Array(12)); // 3. AES-GCM加密明文 const encodedData new TextEncoder().encode(plainText); const encryptedData await crypto.subtle.encrypt( { name: AES-GCM, iv: iv, }, aesKey, encodedData ); // 4. 導出AES密鑰并使用RSA公鑰加密 const rawAesKey await crypto.subtle.exportKey(raw, aesKey); const publicKey await crypto.subtle.importKey( spki, base64ToArrayBuffer(rsaPublicKeyBase64), { name: RSA-OAEP, hash: SHA-256, }, false, [encrypt] ); const encryptedAesKey await crypto.subtle.encrypt( { name: RSA-OAEP, }, publicKey, rawAesKey ); // 5. 打包返回加密后的AES密鑰 IV 密文 return { encryptedAesKey: arrayBufferToBase64(encryptedAesKey), iv: arrayBufferToBase64(iv.buffer), encryptedData: arrayBufferToBase64(encryptedData), }; }6.3 后端解密對應的Node.js實現(xiàn)const crypto require(crypto); function hybridDecrypt(privateKeyPem, payload) { const { encryptedAesKey, iv, encryptedData } payload; // 1. 用RSA私鑰解密出AES密鑰 const aesKeyBuffer crypto.privateDecrypt( { key: privateKeyPem, padding: crypto.constants.RSA_PKCS1_OAEP_PADDING, oaepHash: sha256, }, Buffer.from(encryptedAesKey, base64) ); // 2. 用AES-GCM解密數(shù)據(jù) const decipher crypto.createDecipheriv( aes-256-gcm, aesKeyBuffer, Buffer.from(iv, base64) ); // 這里注意GCM模式需要處理auth tag const encryptedBuffer Buffer.from(encryptedData, base64); const authTag encryptedBuffer.subarray(encryptedBuffer.length - 16); const dataBuffer encryptedBuffer.subarray(0, encryptedBuffer.length - 16); decipher.setAuthTag(authTag); const decrypted Buffer.concat([ decipher.update(dataBuffer), decipher.final(), ]); return decrypted.toString(utf8); }這段代碼有幾個細節(jié)值得注意。AES-GCM的認證標簽默認是16字節(jié)前端crypto.subtle.encrypt返回的密文中已經(jīng)包含了認證標簽所以后端需要從密文末尾拆出tag再調(diào)用setAuthTag。如果不設置解密時會直接拋錯提示Unsupported state or unable to authenticate data?；旌霞用艿暮锰幰皇侵С秩我忾L度的數(shù)據(jù)二是因為數(shù)據(jù)主體走的是AES對稱加密加解密性能遠高于純RSA。思路和應用層如何實現(xiàn)都建立在這套方案上。6.4 什么時候不需要混合加密如果你的數(shù)據(jù)量很小比如就是加密個驗證碼、手機號、身份證號長度不超過190字節(jié)直接用RSA就夠了不需要引入AES那套復雜度。業(yè)務簡單性也是工程價值的一部分。我見過不少項目為了看起來安全把混合加密寫上去了結(jié)果增加了前后端聯(lián)調(diào)成本卻沒有帶來本質(zhì)收益。密鑰管理、密鑰輪換、審計日志這些沒跟上方案再復雜也是白搭。7. 安全底線與常見坑現(xiàn)場排查實錄7.1 再強調(diào)一遍RSA加密不等于絕對安全分享一段我經(jīng)歷過的真實排查過程。有一個系統(tǒng)前端用RSA公鑰加密登錄密碼后端用私鑰解密看起來沒啥問題。但后來安全團隊測試發(fā)現(xiàn)只要抓包拿到密文直接重放到接口上服務端照樣解密成功登錄照樣通過。問題出在哪缺少防重放機制。RSA加密解決的是數(shù)據(jù)傳輸過程中的不可讀性但密文本身可以被錄制、復制、重放。這就像你寫了一封加密信但信被偷看后小偷可以把信原封不動再交一次。真正安全的接口必須有時間戳、隨機數(shù)、序列號之類的機制結(jié)合驗證。我建議在前端加密時把當前時間戳和隨機字符串拼進明文服務端解密后校驗時間戳的時效性比如允許5分鐘內(nèi)有效同時維護一個已使用隨機數(shù)列表來防重放。7.2 密鑰管理的前端注意事項另一個高頻問題是密鑰的存儲安全。前端瀏覽器環(huán)境中任何保存在localStorage、sessionStorage中的數(shù)據(jù)都面臨XSS攻擊的威脅。如果攻擊者能在頁面注入腳本他就能直接讀取私鑰字符串。我在項目中的做法是前端私鑰只在本次會話中保留在內(nèi)存變量里不寫入localStorage。如果一定要持久化使用IndexedDB并配合CSP內(nèi)容安全策略降低XSS風險。加密私鑰時用crypto.subtle.wrapKey配合另一個密鑰來包裹私鑰。7.3 一次完整的聯(lián)調(diào)排查記錄有一次我負責的項目里前端在Chrome上加密正常但測試同學在某個國產(chǎn)瀏覽器的極速模式下解密失敗。打開控制臺發(fā)現(xiàn)crypto.subtle是undefined說明內(nèi)核比較舊。當時的處理方案是在初始化時做一個特性檢測if (window.crypto window.crypto.subtle) { // 使用Web Crypto API } else { // 降級到node-forge }后來項目組要求兼容的瀏覽器列表里移除了那個老內(nèi)核版本才徹底砍掉了降級邏輯。但這里也說明一個經(jīng)驗產(chǎn)品規(guī)劃階段就要明確兼容目標技術方案要和兼容矩陣對齊。7.4 實用檢查清單我把自己每次上線的自檢項整理成了一張清單供參考[ ] 密鑰長度是否不低于2048位[ ] 前后端hash算法是否完全一致SHA-256[ ] 公鑰導入格式是否與后端導出一致SPKI還是PKCS#1[ ] 加密數(shù)據(jù)的長度是否在190字節(jié)以內(nèi)如果超出是否已走混合加密[ ] Base64字符串是否處理過換行符[ ] 是否加入了時間戳和隨機數(shù)防重放[ ] 私鑰是否未寫入localStorage[ ] 是否做了crypto.subtle特性檢測[ ] 是否處理過中文編碼TextEncoder/TextDecoder[ ] 是否確認服務端日志不會打印私鑰和明文8. 個人實操心得在這個項目的整個過程中我最大的體會是RSA加解密的代碼本身并不復雜真正的復雜度在于格式對齊、參數(shù)對齊和場景判斷。crypto.subtle.generateKey、encrypt、decrypt這些API用起來很快但如果你不去理解SPKI和PKCS#1的區(qū)別不理解為什么RSA-OAEP限制了明文長度不理解為什么Java后端的MGF1參數(shù)會導致解密失敗那么代碼寫得再順手聯(lián)調(diào)時也會被各種詭異的報錯折騰到懷疑人生。最后再分享一個小技巧。在聯(lián)調(diào)階段我習慣在前端和后端各寫一個自測用例前端用公鑰加密一段固定字符串解密后對拍后端用私鑰解密前端生成的密文再對拍明文。兩邊能對上同一個值接口聯(lián)調(diào)才真正有把握。這個習慣幫我節(jié)省了大量時間也避免了上線后才發(fā)現(xiàn)兩邊算法不一致的尷尬。