简介面向 OpenSSL 二次开发者的 C ENGINE 框架模板用于在工程中以自定义引擎替换 OpenSSL 原有的 AES-CBC 与 MD5 算法实现既可对接 CSP、PKCS#11也可直接封装自有算法 API适合具备一定 C/C 与密码学基础、需要在 Linux、Windows、Mac 上验证算法替换方案的开发者。压缩包共 19 个文件、约 95KB以 h 头文件与 cpp 源文件承载接口声明和框架骨架配合 lib 静态库、def 导出定义、vcproj 与 sln 工程、Makefile、ReadMe 说明及 rc 资源脚本源码、工程与构建脚本齐备。Windows 下提供 vc2005、vc2008 可直接打开的工程Linux 侧执行 make 即可并声明兼容 OpenSSL 1.0 与 0.9.8 两个版本。框架把必须实现的接口逐条列出按注释补齐回调即可编译出可加载的 ENGINE省去从零摸索注册流程与算法挂接的环节也便于对照排查接口实现中的问题。已有 1154 人学习。1. 为什么要自己编译一个 OpenSSL Engine硬件密钥接入时绕不开的一层给一套跨平台系统接硬件密码模块上层几十处 EVP_PKEY_CTX 调用散在业务代码里下层只给了一套 C 接口的令牌驱动中间缺一层翻译。想改上层等于把签名和 TLS 握手链路重写一遍。用 C 编译一个 OpenSSL Engine再搭一套可复用的 Engine 框架正好补这个位置往 OpenSSL 里注册一张方法表把 RSA、ECDSA、摘要的实现指针换成自己的业务侧一行不动。代价是这份东西必须按 C 的 ABI 交付实现却想用 C 写类型、异常、内存分配器全在边界上过一遍。下面按入口符号、方法表、后端抽象、构建验证、排错、进阶验证的顺序拆适合手上已经有令牌、又不想动上层代码的人。2. 入口符号与 ABIEngine 被 dlopen 之后到底找什么Engine 在 OpenSSL 里是一个动态库插件加载方不看你的头文件只看两个导出符号。搞不清这两个符号的约定后面写再多方法表都是白搭。2.1 bind_fn 与 v_check加载器只认这两个名字动态引擎的加载路径是ENGINE_by_id→ENGINE_load_dynamic→DSO_load。DSO 把.soWindows 上是.dll映射进来后先找v_check用它确认引擎和当前 OpenSSL 的运行期 ABI 是否兼容再找bind_engine把ENGINE*和一组函数指针表传进去。bind_engine的职责很窄设置 id、name、init/finish/destroy、ctrl 命令表以及各种方法表。它返回 0 表示拒绝接管这个 id返回 1 表示成功。手工写这两个符号容易出错OpenSSL 的engine.h里给了两个宏宏展开出的符号作用IMPLEMENT_DYNAMIC_BIND_FN(fn)bind_engine做静态状态比对、内存函数替换然后回调你的fnIMPLEMENT_DYNAMIC_CHECK_FN()v_check返回版本兼容标记版本对不上直接拒绝加载IMPLEMENT_DYNAMIC_BIND_FN在 C 编译单元里展开时自带extern C所以不要在外面再包一层重复包虽然语法合法但容易让人误以为链接名被改过。真正要注意的是宏内部会调用CRYPTO_set_mem_functions把宿主进程的分配器换进来这意味着引擎里后续所有 OpenSSL 对象都必须用宿主的分配器创建这一条在 5.5 节还会展开。2.2 用 extern C 和可见性把入口钉死C 默认给函数做名字修饰bind_engine会被修饰成_Z11bind_engineP6enginePKcPK12dynamic_fns之类的形式dlsym按裸名字找必然落空。除了宏自带的extern C更稳的做法是在构建层面把符号可见性收紧-fvisibilityhidden让所有符号默认隐藏只对需要导出的入口加__attribute__((visibility(default)))。这样做的副作用是好的——你写的 C 类、模板实例化、内部辅助函数全部不外泄避免和宿主进程里的同名符号撞车。我一般会在头文件里定一个宏// include/export.h #pragma once #if defined(_WIN32) # define ACME_EXPORT __declspec(dllexport) #else # define ACME_EXPORT __attribute__((visibility(default))) #endif然后在构建脚本里打开CXX_VISIBILITY_PRESET hidden。Windows 那边注意__declspec(dllexport)和.def文件二选一不要同时用否则会出现重复导出告警。2.3 一个能编译通过的最小 C Engine 骨架先把能加载、能自检、能打印命令的壳子跑通再往里填算法。下面这份是入口文件后端方法表先留空。// src/engine_entry.cpp #include openssl/engine.h #include cstring #include export.h namespace { constexpr const char* kEngineId acme_p11; constexpr const char* kEngineName ACME P11/CSP bridge engine; } static int eng_init(ENGINE* e); static int eng_finish(ENGINE* e, int); static int eng_destroy(ENGINE* e); static int eng_ctrl(ENGINE* e, int cmd, long i, void* p, void (*f)(void)); // ctrl 命令表给 openssl engine -p / ENGINE_ctrl_cmd_string 用 static const ENGINE_CMD_DEFN kCmds[] { {1, P11_MODULE, path of the PKCS#11 module, ENGINE_CMD_FLAG_STRING}, {2, P11_SLOT, slot index, -1 for first token, ENGINE_CMD_FLAG_NUMERIC}, {3, BACKEND, p11 or csp, ENGINE_CMD_FLAG_STRING}, {0, nullptr, nullptr, 0} // 必须以全零项结尾 }; static int bind_impl(ENGINE* e, const char* id) { if (id ! nullptr std::strcmp(id, kEngineId) ! 0) { return 0; // id 不匹配就放手别抢别人的引擎 } if (!ENGINE_set_id(e, kEngineId)) return 0; if (!ENGINE_set_name(e, kEngineName)) return 0; if (!ENGINE_set_init_function(e, eng_init)) return 0; if (!ENGINE_set_finish_function(e, eng_finish)) return 0; if (!ENGINE_set_destroy_function(e, eng_destroy)) return 0; if (!ENGINE_set_ctrl_function(e, eng_ctrl)) return 0; if (!ENGINE_set_cmd_defns(e, kCmds)) return 0; return 1; } static int eng_ctrl(ENGINE* e, int cmd, long i, void* p, void (*)(void)) { switch (cmd) { case 1: /* P11_MODULE */ break; case 2: /* P11_SLOT */ break; case 3: /* BACKEND */ break; default: return 0; } return 1; } static int eng_init(ENGINE*) { return 1; } static int eng_finish(ENGINE*, int) { return 1; } static int eng_destroy(ENGINE*) { return 1; } IMPLEMENT_DYNAMIC_BIND_FN(bind_impl) IMPLEMENT_DYNAMIC_CHECK_FN()几个参数需要说清楚。ENGINE_set_id里的字符串必须和文件名、ENGINE_by_id的入参三者一致否则命令行会报engine xxx not found。ENGINE_CMD_DEFN结构体是{cmd_num, cmd_name, cmd_desc, cmd_flags}最后一项必须{0, nullptr, nullptr, 0}少了这个哨兵会在遍历命令表时读到野指针是典型的加载期崩溃。bind_impl里的 id 判断不能省——OpenSSL 在ENGINE_by_id找不到时会遍历所有已注册引擎没有这层判断就可能误接管。3. Engine 框架的三层结构方法表、后端抽象与密钥生命周期一个能长期维护的 Engine 框架我习惯拆成三层上层是 OpenSSL 的方法表RSA_METHOD、EVP_PKEY_METHOD、EVP_MD中层是和 OpenSSL 解耦的纯 C 后端接口底层是 P11 和 CSP 两套实现。三层之间只用值类型和裸指针通信谁都不许把异常和智能指针带过界。3.1 RSA_METHOD 与 EVP_PKEY_METHOD 该挂哪个这两张表经常被混用区别在于调用路径。RSA_METHOD挂在RSA对象上管的是老接口RSA_private_encrypt、RSA_public_decrypt、RSA_sign。EVP_PKEY_METHOD挂在EVP_PKEY_CTX上管的是新接口EVP_PKEY_sign、EVP_PKEY_decrypt、EVP_PKEY_derive。现代代码基本走 EVP所以只挂RSA_METHOD往往出现「TLS 握手能用、业务签名不生效」的怪现象。我的做法是两张都挂但共用同一套后端调用方法表挂载函数必填回调典型漏挂的后果RSA_METHODENGINE_set_RSArsa_priv_enc、rsa_priv_dec、rsa_signRSA_*老接口回落软件实现EVP_PKEY_METHODENGINE_set_pkey_methssign、decrypt、ctrlEVP_PKEY_sign走默认软实现EVP_MDENGINE_set_digestsinit、update、final摘要仍在 CPU 上算性能没变化ENGINE_set_pkey_meths的函数签名是int (*)(ENGINE*, EVP_PKEY_METHOD**, const int**, int nid)。调用方先传nid 0拿 nids 数组再逐个 nid 取方法指针所以实现里要先判断 nid 是否为零为零就返回支持列表非零就按 nid 填充。static int pkey_meths(ENGINE*, EVP_PKEY_METHOD** pmeth, const int** nids, int nid) { static int supported[] {EVP_PKEY_RSA, EVP_PKEY_EC}; if (nid 0) { // 查询能力列表 *nids supported; return sizeof(supported) / sizeof(supported[0]); } switch (nid) { case EVP_PKEY_RSA: *pmeth rsa_pkey_method(); return 1; case EVP_PKEY_EC: *pmeth ec_pkey_method(); return 1; default: *pmeth nullptr; return 0; } }注意supported和返回的方法指针都必须是静态存储期OpenSSL 只保存指针不做拷贝用局部数组会在函数返回后变成悬垂指针。3.2 把 P11 会话和 CSP 句柄收敛成一个后端接口P11 的世界里一切操作围绕CK_SESSION_HANDLE和CK_OBJECT_HANDLECSP 的世界里对应的是HCRYPTPROV和HCRYPTKEY。两套句柄类型不能混但上层的方法表不应该知道自己接的是哪一套。所以中间层定义纯虚接口句柄用void*装// include/backend.h #pragma once #include cstddef #include cstdint #include memory #include vector namespace acme { enum class KeyKind { Rsa, Ecdsa }; struct KeyRef { KeyKind kind; std::vectorstd::uint8_t id; // 令牌内密钥的 CKA_ID void* native nullptr; // CK_OBJECT_HANDLE 或 HCRYPTKEY }; class Backend { public: virtual ~Backend() default; virtual bool open(const char* module, long slot) 0; virtual void close() noexcept 0; virtual bool find_key(const std::uint8_t* id, std::size_t id_len, KeyKind kind, KeyRef* out) 0; // digest_is_rawtrue 表示传入的是摘要不需要后端再做 hash virtual bool sign(KeyRef key, bool digest_is_raw, const std::uint8_t* in, std::size_t in_len, std::uint8_t* out, std::size_t* out_len) 0; }; std::unique_ptrBackend make_p11_backend(); std::unique_ptrBackend make_csp_backend(); } // namespace acme接口里所有函数返回bool不抛异常。实现内部可以自由用 C 异常和 RAII 管理会话但必须在sign的边界上catch (...)并转成false。参数digest_is_raw是这套设计里最容易搞错的一个——EVP_PKEY_sign的入参已经是摘要而RSA_sign的入参是原始数据同一张后端表要服务两条路径必须靠这个标志区分否则会出现签名长度对、验签失败的情况。3.3 密钥对象与引用计数load_privkey 什么时候被调用Engine 的密钥来源有两种。一种是从文件读OpenSSL 解析完 PEM 后把EVP_PKEY交给你你从里面掏出RSA*再挂RSA_set_app_data存后端句柄。另一种是密钥根本不出令牌只有个标识这时要挂ENGINE_set_load_privkey_function让 OpenSSL 在遇到特定 URI 前缀时回调你。static EVP_PKEY* load_privkey(ENGINE* e, const char* key_id, UI_METHOD*, void*) { try { auto* be static_castacme::Backend*(ENGINE_get_ex_data(e, kBackendIdx)); if (be nullptr) return nullptr; acme::KeyRef ref; if (!be-find_key(reinterpret_castconst std::uint8_t*(key_id), std::strlen(key_id), acme::KeyKind::Rsa, ref)) { return nullptr; } RSA* rsa RSA_new(); if (rsa nullptr) return nullptr; RSA_set_app_data(rsa, new acme::KeyRef(ref)); // 需要配套的销毁回调 RSA_set_method(rsa, rsa_method()); EVP_PKEY* pk EVP_PKEY_new(); EVP_PKEY_assign_RSA(pk, rsa); // 所有权转移给 pk return pk; } catch (...) { return nullptr; } }这里有两个生命周期坑。RSA_set_app_data只存指针不管释放必须在RSA_METHOD的rsa_finish回调里delete掉否则每加载一次就漏一个KeyRef。EVP_PKEY_assign_RSA会把RSA*的所有权收走之后不要再RSA_free重复释放的崩溃现场通常出现在握手完成后离出错点很远属于典型的黑匣子问题。初始化顺序也值得记一笔ENGINE_init在方法表被真正使用前调用ENGINE_finish在引用计数归零时调用ENGINE_free之后才轮到destroy。后端连接应该在init里建立、在finish里断开而不是在bind_impl里——bind_impl只负责填表可能在没有任何算法被调用的情况下执行提前连令牌会让启动变慢也会在无令牌的机器上留下无谓的告警。4. 把构建跑通CMake 工程、版本探查与产物自检Engine 的构建难点不在语法在链接期。OpenSSL 头文件版本、库版本、编译器 ABI、符号可见性任何一项对不上产物都能编译成功但加载失败或者加载成功但静默不生效。4.1 编译前先确认头文件和库是同一套最常见的翻车是头文件来自系统的/usr/include/openssl库链接到了自编译的/opt/xxx/lib/libcrypto.so两个版本差一个次版本号。ENGINE结构体在 1.1.x 之后是不透明指针跨版本访问内部字段会读到错误偏移表现为 ctrl 命令错乱或者ENGINE_set_id返回成功但ENGINE_get_id读出来是乱码。编译前跑一遍这三条# 头文件里记录的版本 grep -E OPENSSL_VERSION_(TEXT|NUMBER) /usr/include/openssl/opensslv.h # 目标库的 soname 和实际版本 readelf -d /usr/lib/x86_64-linux-gnu/libcrypto.so.3 | grep SONAME strings /usr/lib/x86_64-linux-gnu/libcrypto.so.3 | grep -m1 OpenSSL 3 # 确认 pkg-config 指向的是同一套 pkg-config --cflags --libs openssl三条输出必须能对上。对不上就把OPENSSL_ROOT_DIR显式指到同一棵安装树不要让 CMake 自己猜。另外注意 OpenSSL 3.x 把 Engine 标记为 deprecated编译时会出现大量-Wdeprecated-declarations不要图省事直接-Wno-deprecated-declarations全局关掉——那条告警里混着真正需要处理的 API 迁移提示我一般只在包含engine.h的那几个文件上加#pragma GCC diagnostic ignored。4.2 CMakeLists 逐段拆解引擎是插件不是可执行程序用MODULE而不是SHARED这样在 Linux 上不会生成lib前缀和 soname 链接dlopen直接按文件名找。cmake_minimum_required(VERSION 3.16) project(acme_engine LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) set(CMAKE_POSITION_INDEPENDENT_CODE ON) find_package(OpenSSL 1.1 REQUIRED COMPONENTS Crypto) # 通过缓存变量传入方便交叉编译时换路径 set(P11_MODULE_LIB CACHE FILEPATH path of the token module library) add_library(acme_engine MODULE src/engine_entry.cpp src/rsa_bridge.cpp src/ecdsa_bridge.cpp src/backend_p11.cpp src/backend_csp.cpp src/session_pool.cpp ) target_include_directories(acme_engine PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/include ) target_link_libraries(acme_engine PRIVATE OpenSSL::Crypto ) if(P11_MODULE_LIB) target_link_libraries(acme_engine PRIVATE ${P11_MODULE_LIB}) target_compile_definitions(acme_engine PRIVATE ACME_HAVE_P111) endif() set_target_properties(acme_engine PROPERTIES PREFIX OUTPUT_NAME acme_p11 CXX_VISIBILITY_PRESET hidden VISIBILITY_INLINES_HIDDEN ON )逐段说。find_package(OpenSSL 1.1 REQUIRED COMPONENTS Crypto)只拉libcrypto引擎不需要libssl多链一个库只会在部署时多一个依赖。P11_MODULE_LIB用CACHE FILEPATH而不是硬编码是因为同一份代码要在三个平台上出产物模块库的路径各不相同用缓存变量可以在命令行直接-DP11_MODULE_LIB...覆盖。PREFIX 去掉lib前缀OUTPUT_NAME定成纯小写加下划线和kEngineId保持一致。CXX_VISIBILITY_PRESET hidden配合export.h里的ACME_EXPORT保证最终只有bind_engine和v_check可见。Windows 上还要补一句set_target_properties(acme_engine PROPERTIES WINDOWS_EXPORT_ALL_SYMBOLS OFF)默认的导出全部符号行为会把 C 内部符号也带出去和可见性策略冲突。4.3 产物自检nm、ldd 和 openssl engine编译完先别急着往业务里塞四步自检走一遍# 1. 入口符号必须在且是 T已定义、全局 nm -D --defined-only build/acme_p11.so | grep -E bind_engine|v_check # 2. 除入口外不应有未 demangle 的 C 符号外泄 nm -D --defined-only build/acme_p11.so | grep -v -E bind_engine|v_check # 3. 动态依赖能全部解析不能有 not found ldd -r build/acme_p11.so # 4. 让 openssl 自己加载并跑自检 OPENSSL_ENGINESbuild openssl engine -t -c acme_p11第 4 条的输出会列出引擎支持的算法列表和[ available ]标记。如果显示[ unavailable ]说明init返回了 0通常卡在后端连接上。如果显示engine acme_p11 not found先查OPENSSL_ENGINES环境变量是否被openssl的配置文件覆盖openssl version -d能看到配置目录里面的openssl.cnf可能写死了dynamic_path。ldd -r比ldd多做了符号重定位检查能提前发现「库找到了但符号缺失」的情况比如模块库导出的函数名带了版本后缀编译期用头文件能过运行期找不到。5. 避坑与排查五个让 Engine 静默失效的细节Engine 最折磨人的地方是失败方式特别安静。加载成功、自检通过、业务不报错就是密钥还在软件里算。下面五条都是我在真实联调里踩出来的。5.1 现象openssl engine 显示可用但签名速度没变化原因只挂了RSA_METHOD没有挂EVP_PKEY_METHOD。现代 TLS 栈和大部分业务代码走EVP_DigestSign系列最终落到EVP_PKEY_CTX上根本不碰RSA_METHOD。openssl engine -c显示的 capability 列表是从各个 setter 推导出来的ENGINE_set_RSA也会让它显示RSA所以看起来「支持」实际走的却是默认实现。解决在bind_impl里同时调用ENGINE_set_pkey_meths(e, pkey_meths)并且挂完后用openssl speed -engine acme_p11 rsa2048对比吞吐。如果吞吐和不开引擎一样就是没生效如果吞吐掉一个数量级说明每次签名都在重建会话问题在 5.4。5.2 现象进程在签名完成后随机崩溃调用栈停在 libcrypto 内部原因C 异常穿过了 C 边界。方法表里的回调是 C 函数指针抛异常时栈展开会经过 libcrypto 的 C 帧那里没有对应的清理逻辑表现为资源泄漏或者直接 abort。解决所有挂到 OpenSSL 方法表上的回调函数体第一层就是try { ... } catch (...) { return -1; }。返回值的约定也要对上RSA_METHOD的rsa_priv_enc返回签名长度失败返回 -1EVP_PKEY_METHOD的sign返回 1/0。这两套返回值语义不同混用会导致上层把 -1 当成合法长度。5.3 现象加载时报 version mismatch或者加载成功但 ctrl 命令参数乱码原因头文件与运行库版本不一致或者引擎编译时用的OPENSSL_NO_DEPRECATED打开了而宿主没开。ENGINE在 1.1.0 之后变成不透明结构所有访问必须走 setter/getter但老代码里残留的直接字段访问在编译期不报错因为头文件里结构体定义还在运行期偏移对不上。解决编译时统一加-DOPENSSL_API_COMPAT0x10100000L强制按 1.1.0 的 API 级别检查把直接字段访问变成编译错误而不是运行期玄学。部署前把openssl version -a和ldd的输出一起留档出问题时第一件事是对这两份。5.4 现象单线程正常压测到几十并发就开始报会话冲突或超时原因P11 的会话句柄不是线程安全的很多模块要求一个线程一个会话。如果整个进程共用一个CK_SESSION_HANDLE多线程同时C_SignInit/C_Sign会互相打断操作序列。解决做一个会话池按线程 id 取会话池满时阻塞等待而不是新建。池的容量要和令牌的并发会话上限对齐常见模块限制在 16 到 64 之间超过会返回CKR_SESSION_COUNT。另外C_Login只需要做一次把登录状态记在池对象上每个会话重复登录会把令牌的失败计数打满。5.5 现象进程退出时崩溃在 free或者内存占用缓慢上涨原因内存分配器不一致。IMPLEMENT_DYNAMIC_BIND_FN会把宿主的CRYPTO_set_mem_functions换进来但如果你在引擎里用了全局operator new分配对象、又在 OpenSSL 的销毁回调里用OPENSSL_free释放两套分配器混用必然出问题。CSP 那边更麻烦CryptDestroyKey释放的句柄必须由同一个 provider 上下文创建。解决定一条硬规矩——凡是会交给 OpenSSL 持有的内存一律用OPENSSL_malloc/OPENSSL_free纯内部对象用 RAII 管理在destroy回调里一次性清空。CSP 的 provider 句柄在eng_init里CryptAcquireContext在eng_finish里CryptReleaseContext中间不再二次获取。6. 进阶验证用一条最小链路证明引擎真的接管了框架写完最怕的是自我感觉良好。我习惯用三步验证从命令行到代码逐层收窄。6.1 三步验证链路第一步命令行加载并查看能力OPENSSL_ENGINESbuild openssl engine -t -c -p acme_p11-p会打印所有可设置的 ctrl 命令用来确认命令表注册成功-c列出算法能力-t跑一遍 init/finish 自检。三步都过说明壳子没问题。第二步走一次真实签名OPENSSL_ENGINESbuild openssl dgst -sha256 -engine acme_p11 \ -sign key.pem -out sig.bin data.txt # 用纯软件路径验签证明签名结果合法 openssl dgst -sha256 -verify pub.pem -signature sig.bin data.txt这里的关键是用另一条路径验签。如果引擎自己签、自己验两个错误可能互相抵消。第三步代码里显式设为默认实现确认业务路径也被接管ENGINE_load_dynamic(); ENGINE* e ENGINE_by_id(acme_p11); ENGINE_ctrl_cmd_string(e, P11_SLOT, -1, 0); // 0 表示非必需 ENGINE_init(e); ENGINE_set_default(e, ENGINE_METHOD_RSA | ENGINE_METHOD_EC); // ... 业务代码不做任何修改 ENGINE_finish(e); ENGINE_free(e);ENGINE_set_default的第二个参数是按位或的方法位掩码只写ENGINE_METHOD_ALL会把摘要也接管过去如果摘要方法表没实现完整会出现EVP_DigestInit失败的连锁反应。我一般在调试阶段只开 RSA 和 EC等两块都稳了再考虑摘要。6.2 参数与开关速查项常用取值说明P11_SLOT-1/0..n-1表示取第一个带令牌的槽BACKENDp11/csp同一份产物里按需切换ENGINE_METHOD_*RSA、EC按需组合不建议上来就ALL-DOPENSSL_API_COMPAT0x10100000L强制按 1.1.0 API 检查CXX_VISIBILITY_PRESEThidden配合导出宏收窄符号最后说一个习惯。从那以后我每次改完方法表都强制走一遍「命令行-t -c→ 真实签名 → 软件验签 →nm -D查符号」这四步哪怕只改了一行返回值。Engine 这层东西出错时不报错只在你最不想它出错的时候给你一个验签失败。希望帮到你。本文还有配套的精品资源点击获取