簡介圍繞 OpenSSL ENGINE 二次開發(fā)整理的 C 工程模板面向需要在 Linux、Windows、macOS 上替換 OpenSSL 默認(rèn)對(duì)稱加密與 MD5 算法、接入 CSP 或 PKCS#11 的開發(fā)者。模板給出 ENGINE 必須實(shí)現(xiàn)的接口與調(diào)用骨架使用者按注釋補(bǔ)齊密碼算法或硬件密碼服務(wù)邏輯即可把自定義實(shí)現(xiàn)掛接到 OpenSSL 中兼容 OpenSSL 1.0 與 0.9.8Windows 下可用 VC2005/VC2008 打開解決方案Linux 下執(zhí)行 make 構(gòu)建。壓縮包共 19 個(gè)文件約 95KB包含 h/cpp 源碼、lib/def/exp 導(dǎo)入庫與符號(hào)定義、vcproj/sln 工程、Makefile 構(gòu)建腳本、rc 資源及 ReadMe 說明結(jié)構(gòu)緊湊便于對(duì)照移植和二次開發(fā)。已有 1154 人學(xué)習(xí)適合希望理解 ENGINE 框架、驗(yàn)證替換算法流程或?yàn)槊艽a設(shè)備做適配的中高級(jí) C 開發(fā)者參考。1. 從一次握手卡殼說起OpenSSL Engine 解決的是替換算法實(shí)現(xiàn)這件事前陣子幫一個(gè)做接入網(wǎng)關(guān)的朋友排查握手慢的問題抓包發(fā)現(xiàn) RSA 私鑰運(yùn)算全壓在 CPU 上機(jī)器里明明插著一張密碼卡業(yè)務(wù)代碼卻完全不知道該往哪兒轉(zhuǎn)發(fā)。后來我們把這張卡包成一個(gè) OpenSSL Engine業(yè)務(wù)側(cè)一行代碼沒改只換了一份配置簽名就整個(gè)跑到卡上去了。這件事讓我對(duì)用 C 編譯 OpenSSL Engine、再搭一套 Engine 框架有了更實(shí)際的理解它真正的價(jià)值在于在 OpenSSL 內(nèi)部把算法實(shí)現(xiàn)的函數(shù)指針換掉不必從零寫一個(gè)加密庫你想的是怎么把后端的 P11 會(huì)話、CSP 句柄塞進(jìn) OpenSSL 已有的調(diào)用鏈里。下面按我自己的落地順序講從一個(gè)能編譯、能加載的最小骨架開始一路拆到 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)還是別的庫只按簽名調(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ì)象上綁沒綁 Engine綁了就用 Engine 表里的函數(shù)指針沒綁就走默認(rèn)的軟件 method。所以 Engine 的粒度可以很細(xì)既能整體接管 RSA也能只接管 SM3 摘要剩下的繼續(xù)讓 OpenSSL 自己算。這帶來一個(gè)很實(shí)用的性質(zhì)Engine 可以只實(shí)現(xiàn)你最想卸載到硬件上的那一部分。我一般先只接管最耗 CPU 的私鑰運(yùn)算和國密摘要公鑰驗(yàn)簽、對(duì)稱加解密先留著不動(dòng)等壓測確認(rèn)瓶頸確實(shí)在那一塊再擴(kuò)。這樣改動(dòng)面小、回歸也短不至于一上來就把整條 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è)和生命周期管理不寫任何算法邏輯demo_rsa.cpp、demo_digest.cpp只做OpenSSL 參數(shù) → 后端調(diào)用的翻譯不直接碰dlopendemo_p11_bridge.cpp才是唯一知道 P11 函數(shù)列表的地方。這條邊界守住了后端一旦出問題排查范圍立刻收斂到一個(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ù)含義逐條說-fPIC -shared是動(dòng)態(tài)引擎的硬性要求產(chǎn)物必須能被dlopen-I和-L指向同一前綴否則會(huì)出現(xiàn)頭文件是 1.1.1、鏈接庫是 3.0 的錯(cuò)配癥狀是加載時(shí)符號(hào)找不到-ldl是給 bridge 層動(dòng)態(tài)加載 PKCS#11 模塊用的如果你的后端是編譯期靜態(tài)鏈接的可以去掉-Wl,-rpath把運(yùn)行時(shí)庫路徑寫進(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)直接不存在編譯就過不去。我一般先確認(rèn)目標(biāo)環(huán)境的 OpenSSL 配置openssl version -a看版本再翻include/openssl/opensslconf.h里有沒有OPENSSL_NO_DEPRECATED。如果已經(jīng)有 3.0 的強(qiáng)制要求那就得考慮走 provider 路線Engine 只能當(dāng)過渡方案。產(chǎn)物命名也有約定。OpenSSL 加載動(dòng)態(tài)引擎時(shí)默認(rèn)會(huì)在OPENSSL_ENGINES環(huán)境變量指向的目錄、以及編譯期寫死的 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ú)說。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 一致防止配置寫錯(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 表收集起來掛到傳進(jìn)來的ENGINE *e上。任何一個(gè)ENGINE_set_*失敗都要立刻返回 0因?yàn)榘胱?cè)的狀態(tài)最麻煩看起來加載成功實(shí)際只有部分算法生效。參數(shù)說明e是 OpenSSL 分配的 ENGINE 對(duì)象不要自己ENGINE_newid是配置里寫的 engine_id可能為空list是配置文件里default_algorithms之外的附加參數(shù)列表一般用不上。ENGINE_set_init_function注冊(cè)的回調(diào)只在第一次ENGINE_init時(shí)執(zhí)行適合放后端庫加載、全局會(huì)話池初始化這類只跑一次的動(dòng)作。3.2 把 RSA 私鑰運(yùn)算接到后端RSA_METHOD 的寫法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ī)則處理、輸出簽名值返回值是簽名長度。這里有個(gè)容易翻車的點(diǎn)返回值必須是實(shí)際輸出字節(jié)數(shù)返回 0 或負(fù)數(shù)會(huì)被 OpenSSL 當(dāng)成失敗而且上層報(bào)錯(cuò)信息完全看不出是你這邊的問題。/* 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) { /* 沒綁定會(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í)長度 */ }幾個(gè)參數(shù)再解釋一下flen/from是輸入數(shù)據(jù)加了RSA_PKCS1_PADDING時(shí)這里傳的已經(jīng)是 DigestInfo 結(jié)構(gòu)不要自己再拼一遍to是輸出緩沖區(qū)長度至少RSA_size(rsa)padding決定機(jī)制映射PSS 這類帶參數(shù)的 padding 不適合在這個(gè)函數(shù)里做要轉(zhuǎn)到EVP_PKEY_METHOD的sign回調(diào)那里能拿到EVP_PKEY_CTX上的 PSS salt 長度等參數(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è)硬件不擅長也沒必要 */ return meth; }RSA_meth_new的第二個(gè)參數(shù)是 flags一般傳 0。這里我特意不設(shè)pub_enc/pub_decOpenSSL 在沒設(shè)時(shí)會(huì)自動(dòng)回落到默認(rèn)實(shí)現(xiàn)公鑰運(yùn)算繼續(xù)走軟件省一次硬件往返。3.3 摘要算法用 EVP_MD 表注冊(cè)摘要這塊比 RSA 簡單因?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 —— 以國密摘要為例注冊(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); /* 摘要輸出長度 */ EVP_MD_meth_set_input_blocksize(md, 64); /* 分組長度影響 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)一次問你支持幾個(gè)算法你填*nids再用nid NID_undef調(diào)一次讓你把EVP_MD*指針填進(jìn)數(shù)組最后按具體 nid 逐個(gè)查詢。三次調(diào)用的返回值含義不同寫錯(cuò)的話癥狀是openssl engine -c列出來的算法列表缺項(xiàng)。result_size和input_blocksize必須和算法真實(shí)參數(shù)一致。填小了EVP_DigestFinal會(huì)截?cái)噍敵鎏畲罅藭?huì)多寫內(nèi)存input_blocksize影響 OpenSSL 內(nèi)部的緩沖和EVP_MD_CTX_copy行為填錯(cuò)不一定立刻崩但在長數(shù)據(jù)流上會(huì)出詭異結(jié)果。3.4 配置文件加載與第一次冒煙代碼編出來只是第一步能不能被 OpenSSL 認(rèn)出來要靠配置。最省事的方式是給一個(gè)獨(dú)立的 cnf用OPENSSL_CONF指過去不污染系統(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測的是ENGINE_init能不能成功-c列出這個(gè)引擎支持的算法。兩行都正常說明注冊(cè)鏈路通了只有第一行沒有算法列表問題在 method 注冊(cè)available變成unavailable問題在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開會(huì)話C_Login登錄之后所有運(yùn)算都在會(huì)話里發(fā)起。對(duì)象映射是這里最需要想清楚的一層。P11 里的私鑰是CKO_PRIVATE_KEY類型的對(duì)象用C_FindObjects按CKA_ID或CKA_LABEL找出來拿到句柄OpenSSL 側(cè)的RSA對(duì)象只填n和e就夠d不填私鑰運(yùn)算全部轉(zhuǎn)發(fā)到句柄上。這樣私鑰永遠(yuǎn)不出硬件符合大多數(shù)合規(guī)場景的要求。會(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)部的鎖串行化壓測直接掉到單核水平。機(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且輸入必須是定長的 r||s 而不是 DER。最后這條最容易翻車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 的模型里摘要和簽名是分開的兩步。對(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í)候繞不開 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層多寫一層適配時(shí)間差不多但調(diào)試更煩因?yàn)?Windows 上的錯(cuò)誤碼不像 P11 的CKR_*那么直觀。兩邊都做的話bridge 層的抽象一定要先定好否則后面就是兩份代碼互相抄。5. 避坑與排查Engine 加載不上、加載上又不生效的幾種典型5.1 先建立一條固定的定位順序Engine 出問題時(shí)的報(bào)錯(cuò)信息普遍很含糊ENGINE_by_id返回空既不告訴你找不到文件也不告訴你符號(hào)沒導(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)有沒有正確導(dǎo)出然后用LD_DEBUGlibs看dlopen到底加載了哪個(gè)路徑的庫最后才進(jìn) gdb 斷bind_engine看返回值。這條順序的價(jià)值在于把配置文件問題符號(hào)導(dǎo)出問題依賴庫問題代碼邏輯問題四類原因分開不至于一上來就改代碼。5.2 五條踩過的坑現(xiàn)象一openssl engine demo_p11報(bào)cannot load engine但文件明明存在。原因通常是 OpenSSL 按引擎ID.so的規(guī)則去 engines 目錄找而你配的是dynamic_path卻寫錯(cuò)了絕對(duì)路徑或者目錄權(quán)限不對(duì)導(dǎo)致dlopen失敗。解決是把dynamic_path寫成絕對(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還是軟件速度。原因是配置里沒寫default_algorithms引擎只是被加載沒有被設(shè)成默認(rèn)實(shí)現(xiàn)。解決是在引擎配置段加default_algorithms ALL或者在代碼里ENGINE_init之后顯式調(diào)ENGINE_set_default(e, ENGINE_METHOD_ALL)。要注意ALL會(huì)把 RAND 也接管如果你的引擎沒實(shí)現(xiàn) RAND啟動(dòng)時(shí)可能直接失敗更穩(wěn)的寫法是ENGINE_METHOD_ALL ~ENGINE_METHOD_RAND。現(xiàn)象三ENGINE_init階段段錯(cuò)誤。我遇到過一次是demo_ctrl里解析MODULE_PATH時(shí)沒判p為空——OpenSSL 在查詢命令定義時(shí)也會(huì)調(diào) ctrl此時(shí)p是 NULL。解決是所有 ctrl 回調(diào)開頭先按cmd分支只在真正設(shè)置參數(shù)的分支里解引用p并且ENGINE_CMD_BASE之后的命令號(hào)才做業(yè)務(wù)處理?，F(xiàn)象四單線程跑得好好的壓測時(shí)偶發(fā)簽名失敗。原因有兩個(gè)常見來源一是C_Initialize時(shí)沒傳CK_C_INITIALIZE_ARGS并置CKF_OS_LOCKING_OK多線程下 P11 模塊內(nè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 聲明放出來前提是庫本身編進(jìn)去了。長遠(yuǎn)看還是得規(guī)劃往 provider 遷移Engine 在 3.x 上屬于能用但不建議新寫的東西。5.3 一份可以照著走的排查清單把上面幾條壓成一張表出問題時(shí)從上往下過一遍基本能定位到層。檢查項(xiàng)命令典型異常含義產(chǎn)物架構(gòu)file demo_p11.so架構(gòu)不匹配加載必失敗符號(hào)導(dǎo)出nm -D demo_p11.so | grep bind_engine沒加extern C名字被修飾依賴庫ldd demo_p11.solibcrypto指向了系統(tǒng)舊版本加載路徑LD_DEBUGlibs openssl engine demo_p11dynamic_path寫錯(cuò)或權(quán)限不足注冊(cè)結(jié)果openssl engine -c demo_p11算法列表缺項(xiàng)method 沒掛上是否生效openssl speed -evp sm3速度沒變default_algorithms沒設(shè)這份清單我一般貼在項(xiàng)目 README 里新同事接手時(shí)少走很多彎路。6. 二次開發(fā)換成自研算法后怎么改、怎么驗(yàn)真正需要改框架的場景通常是往里面加一個(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è)算法沒有現(xiàn)成 NID用OBJ_create注冊(cè)一個(gè)自定義 OID或者直接用NID_undef加EVP_MD_meth_set_flags(md, EVP_MD_FLAG_DIGALGID_ABSENT)繞過參數(shù)編碼。別忘了在openssl.cnf的default_algorithms里確認(rèn)這個(gè)算法類型被包含否則還是老問題——加載了但不生效。驗(yàn)證我堅(jiān)持三步走。第一步openssl engine -t -c看注冊(cè)第二步用openssl dgst -engine demo_p11 -sm3 somefile.bin和純軟件結(jié)果做cmp第三步寫個(gè)獨(dú)立的小程序直接調(diào)EVP_DigestInit_ex并顯式綁引擎繞開配置文件驗(yàn)證代碼路徑。第三步最有價(jià)值因?yàn)榕渲媚苎谏w很多問題獨(dú)立程序里ENGINE_by_id返回空就是空沒有第二層兜底。對(duì)簽名類算法還要補(bǔ)一組邊界用例空數(shù)據(jù)、剛好一個(gè)分組長度的數(shù)據(jù)、超過 64KB 的數(shù)據(jù)以及一個(gè)刻意構(gòu)造的錯(cuò)誤 padding看失敗路徑是否返回負(fù)值而不是 0。調(diào)試技巧上我最常用的是在bind_engine開頭和每個(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)來的是什么值比自己猜映射表快得多。還有一個(gè)小習(xí)慣所有 P11 調(diào)用的返回值都用CKR_*名字打出來不要只打數(shù)字CKR_KEY_HANDLE_INVALID和CKR_MECHANISM_INVALID光看數(shù)字根本分不清。順帶說一個(gè)容易被忽略的改造點(diǎn)ENGINE_set_default的粒度。整體接管用ENGINE_METHOD_ALL只接管特定算法用按位與組合比如只接管 RSA 和摘要就是ENGINE_METHOD_RSA | ENGINE_METHOD_DIGESTS。粒度選錯(cuò)的影響不是功能出錯(cuò)而是性能反而下降——把對(duì)稱加解密也轉(zhuǎn)到硬件上小包場景光往返開銷就吃掉了收益。最后一條教訓(xùn)是我自己踩出來的。早些年改完 Engine 只跑了openssl engine -t就認(rèn)為完事結(jié)果上線后才發(fā)現(xiàn)某個(gè) TLS 套件走的 ECDSA 路徑根本沒接管全部悄悄回落到了軟件實(shí)現(xiàn)壓測數(shù)據(jù)和預(yù)期差了整整一個(gè)數(shù)量級(jí)。從那以后我每次改完 Engine都強(qiáng)制走一遍完整鏈路驗(yàn)證加載、算法列表、單算法對(duì)比、真實(shí)握手抓包看密鑰交換用的哪條路徑四步缺一不可。希望這些能幫到你少在那些報(bào)錯(cuò)含糊的地方耗時(shí)間。本文還有配套的精品資源點(diǎn)擊獲取