簡(jiǎn)介圍繞 OpenSSL ENGINE 二次開(kāi)發(fā)整理的 C 工程模板面向需要在 Linux、Windows、macOS 上替換 OpenSSL 默認(rèn)對(duì)稱加密與 MD5 算法、接入 CSP 或 PKCS#11 的開(kāi)發(fā)者。模板給出 ENGINE 必須實(shí)現(xiàn)的接口與調(diào)用骨架使用者按注釋補(bǔ)齊密碼算法或硬件密碼服務(wù)邏輯即可把自定義實(shí)現(xiàn)掛接到 OpenSSL 中兼容 OpenSSL 1.0 與 0.9.8Windows 下可用 VC2005/VC2008 打開(kāi)解決方案Linux 下執(zhí)行 make 構(gòu)建。壓縮包共 19 個(gè)文件約 95KB包含 h/cpp 源碼、lib/def/exp 導(dǎo)入庫(kù)與符號(hào)定義、vcproj/sln 工程、Makefile 構(gòu)建腳本、rc 資源及 ReadMe 說(shuō)明結(jié)構(gòu)緊湊便于對(duì)照移植和二次開(kāi)發(fā)。已有 1154 人學(xué)習(xí)適合希望理解 ENGINE 框架、驗(yàn)證替換算法流程或?yàn)槊艽a設(shè)備做適配的中高級(jí) C 開(kāi)發(fā)者參考。1. 從一次握手卡殼說(shuō)起OpenSSL Engine 解決的是替換算法實(shí)現(xiàn)這件事前陣子幫一個(gè)做接入網(wǎng)關(guān)的朋友排查握手慢的問(wèn)題抓包發(fā)現(xiàn) RSA 私鑰運(yùn)算全壓在 CPU 上機(jī)器里明明插著一張密碼卡業(yè)務(wù)代碼卻完全不知道該往哪兒轉(zhuǎn)發(fā)。后來(lái)我們把這張卡包成一個(gè) OpenSSL Engine業(yè)務(wù)側(cè)一行代碼沒(méi)改只換了一份配置簽名就整個(gè)跑到卡上去了。這件事讓我對(duì)用 C 編譯 OpenSSL Engine、再搭一套 Engine 框架有了更實(shí)際的理解它真正的價(jià)值在于在 OpenSSL 內(nèi)部把算法實(shí)現(xiàn)的函數(shù)指針換掉不必從零寫(xiě)一個(gè)加密庫(kù)你想的是怎么把后端的 P11 會(huì)話、CSP 句柄塞進(jìn) OpenSSL 已有的調(diào)用鏈里。下面按我自己的落地順序講從一個(gè)能編譯、能加載的最小骨架開(kāi)始一路拆到 P11 與 CSP 兩條后端路線最后落到怎么改、怎么驗(yàn)證。2. Engine 的三層結(jié)構(gòu)與最小可編譯骨架2.1 ENGINE 對(duì)象里掛的是一張張函數(shù)指針表理解 Engine 最快的方式是把它看成一個(gè)算法實(shí)現(xiàn)的注冊(cè)中心。OpenSSL 內(nèi)部維護(hù)一個(gè)全局 ENGINE 鏈表每個(gè) ENGINE 結(jié)構(gòu)體里掛著若干張 method 表ENGINE_set_RSA對(duì)應(yīng)RSA_METHODENGINE_set_DSA對(duì)應(yīng)DSA_METHODENGINE_set_ECDSA對(duì)應(yīng)ECDSA_METHODENGINE_set_digests對(duì)應(yīng)一張EVP_MD數(shù)組ENGINE_set_ciphers對(duì)應(yīng)EVP_CIPHER數(shù)組ENGINE_set_pkey_meths對(duì)應(yīng)一張EVP_PKEY_METHOD表。這些表里全是函數(shù)指針OpenSSL 不關(guān)心你后端是密碼卡、是軟件實(shí)現(xiàn)還是別的庫(kù)只按簽名調(diào)用。調(diào)用鏈?zhǔn)沁@樣走的應(yīng)用層調(diào)用EVP_DigestInit_ex、EVP_PKEY_sign、RSA_private_encrypt時(shí)OpenSSL 先看當(dāng)前EVP_MD_CTX、EVP_PKEY_CTX或RSA對(duì)象上綁沒(méi)綁 Engine綁了就用 Engine 表里的函數(shù)指針沒(méi)綁就走默認(rèn)的軟件 method。所以 Engine 的粒度可以很細(xì)既能整體接管 RSA也能只接管 SM3 摘要剩下的繼續(xù)讓 OpenSSL 自己算。這帶來(lái)一個(gè)很實(shí)用的性質(zhì)Engine 可以只實(shí)現(xiàn)你最想卸載到硬件上的那一部分。我一般先只接管最耗 CPU 的私鑰運(yùn)算和國(guó)密摘要公鑰驗(yàn)簽、對(duì)稱加解密先留著不動(dòng)等壓測(cè)確認(rèn)瓶頸確實(shí)在那一塊再擴(kuò)。這樣改動(dòng)面小、回歸也短不至于一上來(lái)就把整條 TLS 鏈路掀翻。還有一層要分清Engine 本身是實(shí)現(xiàn)層的替換不負(fù)責(zé)策略。要不要用它、用哪個(gè)、哪些算法走它由ENGINE_set_default和配置文件決定。把這兩件事混在一起是后面很多加載成功但不生效的根源。2.2 目錄結(jié)構(gòu)與各文件職責(zé)我習(xí)慣把框架拆成引擎主體 算法適配 后端橋接 驗(yàn)證程序四塊目錄大致如下。這樣拆的好處是后面換后端P11 換 CSP或者換另一家卡只動(dòng) bridge 層bind_engine和算法表都不用碰。openssl-engine-demo/ ├── CMakeLists.txt ├── include/ │ └── demo_engine.h # 對(duì)外導(dǎo)出的 bind_engine / v_check 聲明 ├── src/ │ ├── demo_engine.cpp # ENGINE 主體id、init/finish/ctrl、cmd 定義 │ ├── demo_rsa.cpp # RSA_METHOD 實(shí)現(xiàn)私鑰運(yùn)算轉(zhuǎn)發(fā) │ ├── demo_digest.cpp # EVP_MD 表摘要算法注冊(cè) │ ├── demo_pkey.cpp # EVP_PKEY_METHODPSS/ECDSA 這類需要 ctx 的算法 │ └── demo_p11_bridge.cpp # 后端橋接會(huì)話管理、句柄映射、機(jī)制轉(zhuǎn)換 ├── test/ │ ├── engine_smoke.c # 獨(dú)立于 openssl 命令行的冒煙程序 │ └── openssl-demo.cnf # 加載配置 └── build/ # 編譯輸出最終產(chǎn)物是 demo_p11.so幾個(gè)文件職責(zé)要?jiǎng)澢?。demo_engine.cpp只做注冊(cè)和生命周期管理不寫(xiě)任何算法邏輯demo_rsa.cpp、demo_digest.cpp只做OpenSSL 參數(shù) → 后端調(diào)用的翻譯不直接碰dlopendemo_p11_bridge.cpp才是唯一知道 P11 函數(shù)列表的地方。這條邊界守住了后端一旦出問(wèn)題排查范圍立刻收斂到一個(gè)文件。2.3 編譯命令與幾個(gè)容易踩的參數(shù)最小可用的編譯命令就是一行g(shù) -shared -fPIC但參數(shù)順序和頭文件路徑很講究尤其是機(jī)器上同時(shí)裝了系統(tǒng)自帶 OpenSSL 和你自己編的 OpenSSL 時(shí)。# 關(guān)鍵點(diǎn)-I 和 -L 必須指向同一個(gè) OpenSSL 安裝前綴 g -stdc17 -O2 -g -fPIC -shared \ -I/usr/local/openssl/include \ src/demo_engine.cpp src/demo_rsa.cpp src/demo_digest.cpp \ src/demo_pkey.cpp src/demo_p11_bridge.cpp \ -L/usr/local/openssl/lib -lcrypto -ldl \ -Wl,-rpath,/usr/local/openssl/lib \ -o demo_p11.so參數(shù)含義逐條說(shuō)-fPIC -shared是動(dòng)態(tài)引擎的硬性要求產(chǎn)物必須能被dlopen-I和-L指向同一前綴否則會(huì)出現(xiàn)頭文件是 1.1.1、鏈接庫(kù)是 3.0 的錯(cuò)配癥狀是加載時(shí)符號(hào)找不到-ldl是給 bridge 層動(dòng)態(tài)加載 PKCS#11 模塊用的如果你的后端是編譯期靜態(tài)鏈接的可以去掉-Wl,-rpath把運(yùn)行時(shí)庫(kù)路徑寫(xiě)進(jìn)產(chǎn)物省得后面還要設(shè)LD_LIBRARY_PATH。版本差異要提前想清楚。OpenSSL 1.1.1 里ENGINE_*系列是完整可用的主路徑文檔也齊3.0 起這套 API 被標(biāo)成 deprecated默認(rèn)編譯配置下還能用但如果你的 OpenSSL 是用no-deprecated編的ENGINE_set_RSA這些符號(hào)直接不存在編譯就過(guò)不去。我一般先確認(rèn)目標(biāo)環(huán)境的 OpenSSL 配置openssl version -a看版本再翻include/openssl/opensslconf.h里有沒(méi)有OPENSSL_NO_DEPRECATED。如果已經(jīng)有 3.0 的強(qiáng)制要求那就得考慮走 provider 路線Engine 只能當(dāng)過(guò)渡方案。產(chǎn)物命名也有約定。OpenSSL 加載動(dòng)態(tài)引擎時(shí)默認(rèn)會(huì)在OPENSSL_ENGINES環(huán)境變量指向的目錄、以及編譯期寫(xiě)死的 engines 目錄里按引擎ID.so找文件所以產(chǎn)物名最好和ENGINE_set_id里的 id 保持一致比如 id 是demo_p11產(chǎn)物就叫demo_p11.so。名字對(duì)不上時(shí)ENGINE_by_id會(huì)返回空但報(bào)錯(cuò)信息非常含糊這個(gè)坑后面單獨(dú)說(shuō)。3. 核心代碼拆解從 bind_engine 到 RSA_METHOD 與 EVP_MD3.1 bind_engine 是整個(gè)框架唯一的加載入口動(dòng)態(tài)引擎被dlopen之后OpenSSL 會(huì)dlsym兩個(gè)符號(hào)bind_engine和v_check。前者是注冊(cè)回調(diào)后者是 ABI 版本協(xié)商。v_check返回 1 表示接受當(dāng)前 OpenSSL 的 ABI 版本返回 0 就直接放棄加載。這兩個(gè)函數(shù)必須用extern C導(dǎo)出C 編譯器默認(rèn)會(huì)做名字修飾導(dǎo)出的符號(hào)名會(huì)變成_Z11bind_engineP6enginePKcPKS2_這種dlsym按bind_engine找不到。/* demo_engine.cpp —— 框架注冊(cè)入口 */ static const char *DEMO_ENGINE_ID demo_p11; static const char *DEMO_ENGINE_NAME Demo PKCS#11 Engine; /* 生命周期回調(diào)前面先聲明實(shí)現(xiàn)在文件后半段 */ static int demo_init(ENGINE *e); static int demo_finish(ENGINE *e); static int demo_destroy(ENGINE *e); static int demo_ctrl(ENGINE *e, int cmd, long i, void *p, void (*f)(void)); extern C int bind_engine(ENGINE *e, const char *id, const char *const *list) { /* id 為空表示由 ENGINE_by_id 加載此時(shí)不做強(qiáng)校驗(yàn) * id 非空時(shí)必須和注冊(cè) id 一致防止配置寫(xiě)錯(cuò)卻靜默成功 */ if (id ! NULL strcmp(id, DEMO_ENGINE_ID) ! 0) { return 0; } if (!ENGINE_set_id(e, DEMO_ENGINE_ID)) return 0; if (!ENGINE_set_name(e, DEMO_ENGINE_NAME)) return 0; if (!ENGINE_set_RSA(e, demo_rsa_method())) return 0; if (!ENGINE_set_pkey_meths(e, demo_pkey_meths)) return 0; if (!ENGINE_set_digests(e, demo_digest_table)) return 0; if (!ENGINE_set_init_function(e, demo_init)) return 0; if (!ENGINE_set_finish_function(e, demo_finish)) return 0; if (!ENGINE_set_destroy_function(e, demo_destroy)) return 0; if (!ENGINE_set_ctrl_function(e, demo_ctrl)) return 0; if (!ENGINE_set_cmd_defns(e, demo_cmd_defns)) return 0; return 1; /* 必須返回 1返回 0 會(huì)被當(dāng)成加載失敗 */ } extern C int v_check(unsigned long v) { /* 0x10001 是 OpenSSL 1.0.1 起的 ABI 版本號(hào)低于它直接拒絕 */ return (v 0x10001UL) ? 1 : 0; }邏輯上這段代碼只做一件事把散落在各個(gè)文件里的 method 表收集起來(lái)掛到傳進(jìn)來(lái)的ENGINE *e上。任何一個(gè)ENGINE_set_*失敗都要立刻返回 0因?yàn)榘胱?cè)的狀態(tài)最麻煩看起來(lái)加載成功實(shí)際只有部分算法生效。參數(shù)說(shuō)明e是 OpenSSL 分配的 ENGINE 對(duì)象不要自己ENGINE_newid是配置里寫(xiě)的 engine_id可能為空l(shuí)ist是配置文件里default_algorithms之外的附加參數(shù)列表一般用不上。ENGINE_set_init_function注冊(cè)的回調(diào)只在第一次ENGINE_init時(shí)執(zhí)行適合放后端庫(kù)加載、全局會(huì)話池初始化這類只跑一次的動(dòng)作。3.2 把 RSA 私鑰運(yùn)算接到后端RSA_METHOD 的寫(xiě)法RSA_METHOD是一張函數(shù)指針表最常被調(diào)用的是rsa_priv_enc、rsa_priv_dec、rsa_pub_enc、rsa_pub_dec。以簽名為例rsa_priv_enc的職責(zé)是接收待簽名數(shù)據(jù)、按 padding 規(guī)則處理、輸出簽名值返回值是簽名長(zhǎng)度。這里有個(gè)容易翻車(chē)的點(diǎn)返回值必須是實(shí)際輸出字節(jié)數(shù)返回 0 或負(fù)數(shù)會(huì)被 OpenSSL 當(dāng)成失敗而且上層報(bào)錯(cuò)信息完全看不出是你這邊的問(wèn)題。/* demo_rsa.cpp —— 私鑰運(yùn)算轉(zhuǎn)發(fā) */ static int demo_rsa_priv_enc(int flen, const unsigned char *from, unsigned char *to, RSA *rsa, int padding) { /* 后端會(huì)話掛在 RSA 對(duì)象的 ex_data 上索引在 init 階段申請(qǐng)一次 */ DEMO_SESSION *s (DEMO_SESSION *)RSA_get_ex_data(rsa, g_rsa_ex_idx); if (s NULL) { /* 沒(méi)綁定會(huì)話時(shí)回落到默認(rèn)實(shí)現(xiàn)避免上層直接失敗 */ const RSA_METHOD *def RSA_PKCS1_OpenSSL(); return def-rsa_priv_enc(flen, from, to, rsa, padding); } CK_MECHANISM mech; switch (padding) { case RSA_PKCS1_PADDING: mech.mechanism CKM_RSA_PKCS; break; case RSA_NO_PADDING: mech.mechanism CKM_RSA_X_509; /* 底層模冪padding 由上層做 */ break; default: return -1; /* 未支持的 padding 明確失敗比靜默降級(jí)好排查得多 */ } mech.pParameter NULL; mech.ulParameterLen 0; CK_ULONG siglen (CK_ULONG)RSA_size(rsa); CK_RV rv s-funcs-C_SignInit(s-session, mech, s-priv_key); if (rv ! CKR_OK) { return -1; } rv s-funcs-C_Sign(s-session, (CK_BYTE_PTR)from, (CK_ULONG)flen, to, siglen); if (rv ! CKR_OK) { return -1; } return (int)siglen; /* 必須返回真實(shí)長(zhǎng)度 */ }幾個(gè)參數(shù)再解釋一下flen/from是輸入數(shù)據(jù)加了RSA_PKCS1_PADDING時(shí)這里傳的已經(jīng)是 DigestInfo 結(jié)構(gòu)不要自己再拼一遍to是輸出緩沖區(qū)長(zhǎng)度至少RSA_size(rsa)padding決定機(jī)制映射PSS 這類帶參數(shù)的 padding 不適合在這個(gè)函數(shù)里做要轉(zhuǎn)到EVP_PKEY_METHOD的sign回調(diào)那里能拿到EVP_PKEY_CTX上的 PSS salt 長(zhǎng)度等參數(shù)。方法表本身用RSA_meth_new/RSA_meth_set_*構(gòu)造1.1.1 和 3.0 都能用static RSA_METHOD *demo_rsa_method(void) { static RSA_METHOD *meth NULL; if (meth ! NULL) { return meth; /* 進(jìn)程內(nèi)只構(gòu)造一次重復(fù)構(gòu)造會(huì)泄漏 */ } meth RSA_meth_new(Demo PKCS#11 RSA method, 0); if (meth NULL) return NULL; RSA_meth_set_priv_enc(meth, demo_rsa_priv_enc); RSA_meth_set_priv_dec(meth, demo_rsa_priv_dec); /* 公鑰運(yùn)算通常留在軟件側(cè)硬件不擅長(zhǎng)也沒(méi)必要 */ return meth; }RSA_meth_new的第二個(gè)參數(shù)是 flags一般傳 0。這里我特意不設(shè)pub_enc/pub_decOpenSSL 在沒(méi)設(shè)時(shí)會(huì)自動(dòng)回落到默認(rèn)實(shí)現(xiàn)公鑰運(yùn)算繼續(xù)走軟件省一次硬件往返。3.3 摘要算法用 EVP_MD 表注冊(cè)摘要這塊比 RSA 簡(jiǎn)單因?yàn)镋VP_MD的回調(diào)是固定的四個(gè)init、update、final、cleanup。上下文數(shù)據(jù)放在EVP_MD_CTX_md_data(ctx)返回的那塊內(nèi)存里EVP_MD_meth_set_*時(shí)不用自己管分配。/* demo_digest.cpp —— 以國(guó)密摘要為例注冊(cè)一張 EVP_MD */ static EVP_MD *demo_make_digest(void) { EVP_MD *md EVP_MD_meth_new(NID_sm3, NID_undef); if (md NULL) return NULL; EVP_MD_meth_set_result_size(md, 32); /* 摘要輸出長(zhǎng)度 */ EVP_MD_meth_set_input_blocksize(md, 64); /* 分組長(zhǎng)度影響 EVP 層緩沖 */ EVP_MD_meth_set_flags(md, 0); EVP_MD_meth_set_init(md, demo_md_init); EVP_MD_meth_set_update(md, demo_md_update); EVP_MD_meth_set_final(md, demo_md_final); EVP_MD_meth_set_cleanup(md, demo_md_cleanup); EVP_MD_meth_set_copy(md, demo_md_copy); return md; } /* 注冊(cè)表以 NID 為索引最后一項(xiàng)用 NID_undef 結(jié)尾 */ static int demo_digest_table(ENGINE *e, const EVP_MD **md_table, int *nids, int nid) { static const int supported[] { NID_sm3, NID_undef }; if (md_table NULL) { *nids 1; return 1; } if (nid NID_undef) { md_table[0] demo_make_digest(); return 1; } return 0; }demo_digest_table這個(gè)回調(diào)的調(diào)用約定值得單獨(dú)記一下OpenSSL 會(huì)先用md_table NULL調(diào)一次問(wèn)你支持幾個(gè)算法你填*nids再用nid NID_undef調(diào)一次讓你把EVP_MD*指針填進(jìn)數(shù)組最后按具體 nid 逐個(gè)查詢。三次調(diào)用的返回值含義不同寫(xiě)錯(cuò)的話癥狀是openssl engine -c列出來(lái)的算法列表缺項(xiàng)。result_size和input_blocksize必須和算法真實(shí)參數(shù)一致。填小了EVP_DigestFinal會(huì)截?cái)噍敵鎏畲罅藭?huì)多寫(xiě)內(nèi)存input_blocksize影響 OpenSSL 內(nèi)部的緩沖和EVP_MD_CTX_copy行為填錯(cuò)不一定立刻崩但在長(zhǎng)數(shù)據(jù)流上會(huì)出詭異結(jié)果。3.4 配置文件加載與第一次冒煙代碼編出來(lái)只是第一步能不能被 OpenSSL 認(rèn)出來(lái)要靠配置。最省事的方式是給一個(gè)獨(dú)立的 cnf用OPENSSL_CONF指過(guò)去不污染系統(tǒng)默認(rèn)配置。openssl_conf openssl_init [openssl_init] engines engine_section [engine_section] demo_p11 demo_p11_section [demo_p11_section] engine_id demo_p11 dynamic_path /usr/local/lib/engines-1.1/demo_p11.so MODULE_PATH /usr/lib64/libpkcs11.so SLOT_ID 0 init 1 default_algorithms ALLdynamic_path指向產(chǎn)物MODULE_PATH、SLOT_ID是自定義 ctrl 命令的參數(shù)由demo_ctrl解析名字隨便起但要和demo_cmd_defns對(duì)上init 1表示加載后立刻ENGINE_initdefault_algorithms ALL表示把這個(gè)引擎設(shè)成所有算法的默認(rèn)實(shí)現(xiàn)。這一行是加載成功但不生效的高發(fā)區(qū)后面單獨(dú)講。冒煙驗(yàn)證用官方命令行就夠export OPENSSL_CONF./test/openssl-demo.cnf openssl engine -t -c demo_p11 # 期望輸出類似 # (demo_p11) Demo PKCS#11 Engine # [RSA, SM3] # [ available ]-t測(cè)的是ENGINE_init能不能成功-c列出這個(gè)引擎支持的算法。兩行都正常說(shuō)明注冊(cè)鏈路通了只有第一行沒(méi)有算法列表問(wèn)題在 method 注冊(cè)available變成unavailable問(wèn)題在init回調(diào)里的后端連接。4. 后端對(duì)接P11 與 CSP 兩條路線的落地差異4.1 PKCS#11 的會(huì)話模型與對(duì)象映射P11 是跨平臺(tái)的標(biāo)準(zhǔn)接口密碼卡、軟件模擬器、云上的密鑰服務(wù)基本都支持所以 Engine 框架對(duì)接的第一優(yōu)先級(jí)一般是它。核心概念就三個(gè)slot、session、object。C_Initialize之后C_GetSlotList拿槽位C_OpenSession開(kāi)會(huì)話C_Login登錄之后所有運(yùn)算都在會(huì)話里發(fā)起。對(duì)象映射是這里最需要想清楚的一層。P11 里的私鑰是CKO_PRIVATE_KEY類型的對(duì)象用C_FindObjects按CKA_ID或CKA_LABEL找出來(lái)拿到句柄OpenSSL 側(cè)的RSA對(duì)象只填n和e就夠d不填私鑰運(yùn)算全部轉(zhuǎn)發(fā)到句柄上。這樣私鑰永遠(yuǎn)不出硬件符合大多數(shù)合規(guī)場(chǎng)景的要求。會(huì)話的生命周期要單獨(dú)設(shè)計(jì)。我一般做成每個(gè)線程一個(gè)會(huì)話的池子ENGINE_init時(shí)建池ENGINE_finish時(shí)銷毀中間用CRYPTO_THREAD_lock保護(hù)。共享一個(gè)會(huì)話看著省資源實(shí)際在并發(fā)簽名時(shí)會(huì)被 P11 實(shí)現(xiàn)內(nèi)部的鎖串行化壓測(cè)直接掉到單核水平。機(jī)制轉(zhuǎn)換要建一張表把 OpenSSL 的 padding/算法組合映射成 P11 的CKM_*。RSA_PKCS1_PADDING對(duì)應(yīng)CKM_RSA_PKCSRSA_NO_PADDING對(duì)應(yīng)CKM_RSA_X_509PSS 對(duì)應(yīng)CKM_RSA_PKCS_PSS且要填CK_RSA_PKCS_PSS_PARAMSECDSA 對(duì)應(yīng)CKM_ECDSA且輸入必須是定長(zhǎng)的 r||s 而不是 DER。最后這條最容易翻車(chē)OpenSSL 期望 DER 編碼的簽名P11 吐的是裸 r||s中間得自己轉(zhuǎn)一次。4.2 CSP 的句柄包裝與算法標(biāo)識(shí)映射Windows 上的密碼設(shè)備大多還是走 CSP接口老是老但驅(qū)動(dòng)覆蓋確實(shí)廣。CSP 的模型和 P11 差別不小CryptAcquireContext拿HCRYPTPROVCryptGetUserKey或CryptImportKey拿HCRYPTKEY簽名走CryptSignHash而且它的哈希對(duì)象是獨(dú)立創(chuàng)建的CryptCreateHash→CryptHashData→CryptSignHash三步走。在 Engine 里包裝 CSP關(guān)鍵是別把HCRYPTKEY直接塞進(jìn)RSA對(duì)象的字段里。正確做法還是走 ex_dataRSA_set_ex_data(rsa, idx, wrapper)wrapper 里放 prov、key、以及一個(gè)引用計(jì)數(shù)。原因是RSA對(duì)象可能被RSA_dup或者跨線程復(fù)制裸句柄的釋放時(shí)機(jī)根本對(duì)不上最后不是泄漏就是重復(fù)釋放。算法標(biāo)識(shí)映射是另一張表。CALG_RSA_SIGN對(duì)應(yīng) PKCS#1 v1.5 簽名CALG_RSA_KEYX對(duì)應(yīng)加密CALG_SHA1、CALG_SHA_256對(duì)應(yīng)摘要。這里有個(gè)歷史包袱CSP 里摘要和簽名是綁在一起的CryptSignHash的dwFlags決定簽名時(shí)用什么哈希而 OpenSSL 的模型里摘要和簽名是分開(kāi)的兩步。對(duì)接時(shí)要么在EVP_PKEY_METHOD的 sign 回調(diào)里把已經(jīng)算好的 DigestInfo 原樣傳進(jìn)去用CALG_RSA_SIGN要么在 RSA_METHOD 層接受已經(jīng)帶 padding 的數(shù)據(jù)。選哪條取決于你的 CSP 驅(qū)動(dòng)對(duì) raw 簽名的支持程度有的驅(qū)動(dòng)只認(rèn)CryptSignHash那就只能走前者。4.3 什么時(shí)候選 P11什么時(shí)候繞不開(kāi) CSP判斷標(biāo)準(zhǔn)其實(shí)很樸素目標(biāo)平臺(tái)是不是只有 Windows以及設(shè)備廠商提供的驅(qū)動(dòng)形態(tài)?？缙脚_(tái)、要接多家的卡、后續(xù)可能上云上的密鑰服務(wù)一律優(yōu)先 P11因?yàn)榻涌跇?biāo)準(zhǔn)、行為一致、調(diào)試工具也多。只有在 Windows 上對(duì)接的是純 CSP 驅(qū)動(dòng)、廠商明確不提供 P11 模塊時(shí)才單獨(dú)做一條 CSP 分支。我的做法是在 bridge 層抽一個(gè)demo_backend_ops結(jié)構(gòu)體里面全是函數(shù)指針open_session、close_session、sign、digest、find_key。P11 和 CSP 各實(shí)現(xiàn)一份demo_engine.cpp只依賴這個(gè)結(jié)構(gòu)體。這樣 Engine 主體和算法適配層完全不用改切換后端只是換一個(gè) ops 實(shí)現(xiàn)配置文件里加個(gè)BACKEND p11或BACKEND csp就行。成本上也要有預(yù)期。P11 路線前期要處理機(jī)制映射和簽名格式轉(zhuǎn)換大概兩三天能跑通CSP 路線因?yàn)楣?duì)象的模型差異往往要在EVP_PKEY_METHOD層多寫(xiě)一層適配時(shí)間差不多但調(diào)試更煩因?yàn)?Windows 上的錯(cuò)誤碼不像 P11 的CKR_*那么直觀。兩邊都做的話bridge 層的抽象一定要先定好否則后面就是兩份代碼互相抄。5. 避坑與排查Engine 加載不上、加載上又不生效的幾種典型5.1 先建立一條固定的定位順序Engine 出問(wèn)題時(shí)的報(bào)錯(cuò)信息普遍很含糊ENGINE_by_id返回空既不告訴你找不到文件也不告訴你符號(hào)沒(méi)導(dǎo)出。所以我一般按固定順序走一遍先確認(rèn)產(chǎn)物存在且架構(gòu)匹配file demo_p11.so再確認(rèn)OPENSSL_ENGINES或dynamic_path指對(duì)了接著用nm -D demo_p11.so | grep -E bind_engine|v_check看符號(hào)有沒(méi)有正確導(dǎo)出然后用LD_DEBUGlibs看dlopen到底加載了哪個(gè)路徑的庫(kù)最后才進(jìn) gdb 斷bind_engine看返回值。這條順序的價(jià)值在于把配置文件問(wèn)題符號(hào)導(dǎo)出問(wèn)題依賴庫(kù)問(wèn)題代碼邏輯問(wèn)題四類原因分開(kāi)不至于一上來(lái)就改代碼。5.2 五條踩過(guò)的坑現(xiàn)象一openssl engine demo_p11報(bào)cannot load engine但文件明明存在。原因通常是 OpenSSL 按引擎ID.so的規(guī)則去 engines 目錄找而你配的是dynamic_path卻寫(xiě)錯(cuò)了絕對(duì)路徑或者目錄權(quán)限不對(duì)導(dǎo)致dlopen失敗。解決是把dynamic_path寫(xiě)成絕對(duì)路徑并用ls -l確認(rèn)可讀同時(shí)用LD_DEBUGlibs openssl engine demo_p11 21 | grep demo看實(shí)際嘗試加載的路徑?，F(xiàn)象二openssl engine -t顯示 available但openssl speed -evp sm3還是軟件速度。原因是配置里沒(méi)寫(xiě)default_algorithms引擎只是被加載沒(méi)有被設(shè)成默認(rèn)實(shí)現(xiàn)。解決是在引擎配置段加default_algorithms ALL或者在代碼里ENGINE_init之后顯式調(diào)ENGINE_set_default(e, ENGINE_METHOD_ALL)。要注意ALL會(huì)把 RAND 也接管如果你的引擎沒(méi)實(shí)現(xiàn) RAND啟動(dòng)時(shí)可能直接失敗更穩(wěn)的寫(xiě)法是ENGINE_METHOD_ALL ~ENGINE_METHOD_RAND?，F(xiàn)象三ENGINE_init階段段錯(cuò)誤。我遇到過(guò)一次是demo_ctrl里解析MODULE_PATH時(shí)沒(méi)判p為空——OpenSSL 在查詢命令定義時(shí)也會(huì)調(diào) ctrl此時(shí)p是 NULL。解決是所有 ctrl 回調(diào)開(kāi)頭先按cmd分支只在真正設(shè)置參數(shù)的分支里解引用p并且ENGINE_CMD_BASE之后的命令號(hào)才做業(yè)務(wù)處理?，F(xiàn)象四單線程跑得好好的壓測(cè)時(shí)偶發(fā)簽名失敗。原因有兩個(gè)常見(jiàn)來(lái)源一是C_Initialize時(shí)沒(méi)傳CK_C_INITIALIZE_ARGS并置CKF_OS_LOCKING_OK多線程下 P11 模塊內(nèi)部沒(méi)加鎖二是 ex_data 索引在每個(gè)bind_engine調(diào)用里都RSA_get_ex_new_index一次索引值越用越大最后超出上限。解決是把C_Initialize的參數(shù)補(bǔ)全并且把 ex_data 索引申請(qǐng)放進(jìn)demo_init、用靜態(tài)變量緩存?，F(xiàn)象五換到 OpenSSL 3.0 環(huán)境后編譯報(bào)ENGINE_set_RSA未聲明。原因是那套 OpenSSL 用了no-deprecated編譯。解決有兩條路要么換一個(gè)保留 deprecated API 的 OpenSSL 構(gòu)建要么在編譯時(shí)定義OPENSSL_API_COMPAT0x10101000L把 deprecated 聲明放出來(lái)前提是庫(kù)本身編進(jìn)去了。長(zhǎng)遠(yuǎn)看還是得規(guī)劃往 provider 遷移Engine 在 3.x 上屬于能用但不建議新寫(xiě)的東西。5.3 一份可以照著走的排查清單把上面幾條壓成一張表出問(wèn)題時(shí)從上往下過(guò)一遍基本能定位到層。檢查項(xiàng)命令典型異常含義產(chǎn)物架構(gòu)file demo_p11.so架構(gòu)不匹配加載必失敗符號(hào)導(dǎo)出nm -D demo_p11.so | grep bind_engine沒(méi)加extern C名字被修飾依賴庫(kù)ldd demo_p11.solibcrypto指向了系統(tǒng)舊版本加載路徑LD_DEBUGlibs openssl engine demo_p11dynamic_path寫(xiě)錯(cuò)或權(quán)限不足注冊(cè)結(jié)果openssl engine -c demo_p11算法列表缺項(xiàng)method 沒(méi)掛上是否生效openssl speed -evp sm3速度沒(méi)變default_algorithms沒(méi)設(shè)這份清單我一般貼在項(xiàng)目 README 里新同事接手時(shí)少走很多彎路。6. 二次開(kāi)發(fā)換成自研算法后怎么改、怎么驗(yàn)真正需要改框架的場(chǎng)景通常是往里面加一個(gè)自研算法或者把某一段轉(zhuǎn)發(fā)邏輯換掉。以加一個(gè)自研摘要為例改動(dòng)面其實(shí)很固定在demo_digest.cpp里新增一組init/update/final/cleanup/copy回調(diào)用EVP_MD_meth_new構(gòu)造result_size和input_blocksize按算法真實(shí)參數(shù)填然后把 NID 加進(jìn)demo_digest_table的支持列表和nids計(jì)數(shù)里。如果這個(gè)算法沒(méi)有現(xiàn)成 NID用OBJ_create注冊(cè)一個(gè)自定義 OID或者直接用NID_undef加EVP_MD_meth_set_flags(md, EVP_MD_FLAG_DIGALGID_ABSENT)繞過(guò)參數(shù)編碼。別忘了在openssl.cnf的default_algorithms里確認(rèn)這個(gè)算法類型被包含否則還是老問(wèn)題——加載了但不生效。驗(yàn)證我堅(jiān)持三步走。第一步openssl engine -t -c看注冊(cè)第二步用openssl dgst -engine demo_p11 -sm3 somefile.bin和純軟件結(jié)果做cmp第三步寫(xiě)個(gè)獨(dú)立的小程序直接調(diào)EVP_DigestInit_ex并顯式綁引擎繞開(kāi)配置文件驗(yàn)證代碼路徑。第三步最有價(jià)值因?yàn)榕渲媚苎谏w很多問(wèn)題獨(dú)立程序里ENGINE_by_id返回空就是空沒(méi)有第二層兜底。對(duì)簽名類算法還要補(bǔ)一組邊界用例空數(shù)據(jù)、剛好一個(gè)分組長(zhǎng)度的數(shù)據(jù)、超過(guò) 64KB 的數(shù)據(jù)以及一個(gè)刻意構(gòu)造的錯(cuò)誤 padding看失敗路徑是否返回負(fù)值而不是 0。調(diào)試技巧上我最常用的是在bind_engine開(kāi)頭和每個(gè) method 回調(diào)里各打一行fprintf(stderr, ...)不要用printf因?yàn)?Engine 可能被加載進(jìn)守護(hù)進(jìn)程stdout 早被重定向了。配合gdb -p附著到openssl進(jìn)程在demo_rsa_priv_enc上下斷點(diǎn)能直接看到padding傳進(jìn)來(lái)的是什么值比自己猜映射表快得多。還有一個(gè)小習(xí)慣所有 P11 調(diào)用的返回值都用CKR_*名字打出來(lái)不要只打數(shù)字CKR_KEY_HANDLE_INVALID和CKR_MECHANISM_INVALID光看數(shù)字根本分不清。順帶說(shuō)一個(gè)容易被忽略的改造點(diǎn)ENGINE_set_default的粒度。整體接管用ENGINE_METHOD_ALL只接管特定算法用按位與組合比如只接管 RSA 和摘要就是ENGINE_METHOD_RSA | ENGINE_METHOD_DIGESTS。粒度選錯(cuò)的影響不是功能出錯(cuò)而是性能反而下降——把對(duì)稱加解密也轉(zhuǎn)到硬件上小包場(chǎng)景光往返開(kāi)銷就吃掉了收益。最后一條教訓(xùn)是我自己踩出來(lái)的。早些年改完 Engine 只跑了openssl engine -t就認(rèn)為完事結(jié)果上線后才發(fā)現(xiàn)某個(gè) TLS 套件走的 ECDSA 路徑根本沒(méi)接管全部悄悄回落到了軟件實(shí)現(xiàn)壓測(cè)數(shù)據(jù)和預(yù)期差了整整一個(gè)數(shù)量級(jí)。從那以后我每次改完 Engine都強(qiáng)制走一遍完整鏈路驗(yàn)證加載、算法列表、單算法對(duì)比、真實(shí)握手抓包看密鑰交換用的哪條路徑四步缺一不可。希望這些能幫到你少在那些報(bào)錯(cuò)含糊的地方耗時(shí)間。本文還有配套的精品資源點(diǎn)擊獲取