区块链【免费下载链接】eosAn open source smart contract platform项目地址https://gitcode.com/gh_mirrors/eo/eos点击查看免费下载导读本指南基于 EOSIO 开源仓库eo/eos中的官方 How-to 文档与wallet_plugin源码系统讲解如何将 YubiHSM 2 硬件安全模块HSM挂载为keosd的硬件钱包。读者将掌握YubiHSM AuthKey 的安全前置配置、keosd通过 Connector 或 USB 直连两种接入方式、--yubihsm-authkey启动参数的正确用法以及解锁后使用cleos wallet时的能力边界与安全注意事项并可深入理解wallet_plugin底层对 YubiHSM SDK 的封装原理。目标与工作原理本指南的目标是将 YubiHSM 附加Attach为 keosd 的硬件钱包。与普通文件钱包不同YubiHSM 钱包的私钥由硬件安全模块物理保管私钥永远不会离开设备keosd只能请求硬件在设备内部完成 ECDSA 签名再取回签名结果。这意味着即使运行keosd的主机被攻破攻击者也无法导出私钥。从源码看该能力由 wallet_plugin 中的yubihsm_wallet类实现它继承自wallet_api接口见 yubihsm_wallet.hpp内部通过 YubiHSM 官方 SDKyubihsm.h与硬件通信。开始之前前置条件在将 YubiHSM 接入 keosd 之前必须依次完成以下准备安装当前受支持的 keosd 版本。keosd 是 EOSIO 的密钥存储守护进程其默认数据目录为~/eosio-wallet启动时注册wallet_plugin、wallet_api_plugin与http_plugin见 keosd/main.cpp。安装 YubiHSM2 软件工具包YubiHSM2 SDK。这是 yubihsm_wallet 编译与运行所依赖的底层库提供yh_*系列 API如yh_init_connector、yh_create_session_derived、yh_util_sign_ecdsa等参见 yubihsm_wallet.cpp。在 YubiHSM 设备上创建一个 AuthKey认证密钥且该 AuthKey 必须具备以下 Capabilities能力sign-ecdsa允许使用硬件执行 ECDSA 签名generate-asymmetric-key允许在设备内部生成非对称密钥对export-wrapped允许以封装wrapped形式导出密钥。其中sign-ecdsa是硬性要求——在解锁流程中keosd 会通过yh_check_capability显式校验该能力缺失时直接抛出 Given authkey cannot perform signing 异常见 yubihsm_wallet.cpp。删除设备上的默认 AuthKey默认认证密钥。[!警告] 安全提示 极其重要在继续后续步骤之前必须创建新的 AuthKey 并删除默认 AuthKey。默认 AuthKey 的密码是公开已知的若保留它任何知情者都可以建立会话、操作设备中的密钥安全性将形同虚设。步骤一配置 keosd 与 YubiHSM 的连接将 keosd 连接到 YubiHSM 有两种方式二者选其一即可。方式一使用 YubiHSM Connector连接器默认情况下keosd 会连接位于默认主机和端口http://127.0.0.1:12345的 YubiHSM Connector。若连接器运行在非默认地址需要通过--yubihsm-url启动选项或在config.ini中设置yubihsm-url来指定正确的 Connector URL# config.ini 示例 yubihsm-url http://127.0.0.1:12345从 wallet_plugin.cpp 可以看到该参数的官方定义Override default URL of http://localhost:12345 for connecting to yubihsm-connector。也就是说默认值就是http://localhost:12345只有连接器部署在其他主机或端口时才需要显式覆盖。方式二通过 USB 直连keosd 也可以直接通过 USB 协议连接 YubiHSM。使用此方式时将 keosd 启动选项设置为--yubihsm-urlysb://ysb://协议前缀告诉 yubihsm_wallet 走 USB 直连路径而非 HTTP Connector。这是本地单机部署、不希望额外运行 Connector 服务时的轻量选择。步骤二以指定 AuthKey 启动 keosd连接方式确定后需要通过--yubihsm-authkey指定用于建立会话的 AuthKey 对象编号Object Numberkeosd --yubihsm-authkey Your_AuthKey_Object_Number该参数的含义在源码中定义为Enables YubiHSM support using given Authkey见 wallet_plugin.cpp。它的触发逻辑如下wallet_plugin.cppif (options.count(yubihsm-authkey)) { uint16_t key options.at(yubihsm-authkey).asuint16_t(); string connector_endpoint http://localhost:12345; if(options.count(yubihsm-url)) connector_endpoint options.at(yubihsm-url).asstring(); wallet_manager_ptr-own_and_use_wallet(YubiHSM, make_uniqueyubihsm_wallet(connector_endpoint, key)); }要点只有显式传入--yubihsm-authkeyYubiHSM 支持才会被启用否则 keosd 仅作为普通文件钱包服务运行钱包在 keosd 中以固定名称YubiHSM注册这正是后续cleos wallet unlock -n YubiHSM中-n参数的来源若同时指定了--yubihsm-url则以其覆盖默认 Connector 地址。如果你使用的是 YubiHSM Connector启动前还应确认连接器服务正常运行可在浏览器或命令行中访问连接器状态接口http://YubiHSM_HOST:YubiHSM_PORT/connector/status默认 HOST 和 Port 为http://127.0.0.1:12345。正常情况下应返回类似如下状态信息statusOK serial* version2.0.0 pid666 addresslocalhost port12345statusOK表示连接器健康serial为设备序列号此处通配version为连接器/固件版本pid为连接器进程号address、port为连接器监听地址与端口应与 keosd 的yubihsm-url保持一致。步骤三用 AuthKey 密码解锁 YubiHSM 钱包keosd 启动后使用cleos以 AuthKey 的密码解锁钱包cleos wallet unlock -n YubiHSM --password YOUR_AUTHKEY_PASSWORD该命令背后对应源码中的解锁流程yubihsm_wallet.cpp依次执行yh_init_connector(endpoint)—— 初始化与 Connector 的连接yh_connect(connector, 0)—— 建立与连接器的 TCP 连接yh_create_session_derived(connector, authkey, password, ...)—— 用 AuthKey 编号与密码派生出会话密钥yh_authenticate_session(session)—— 向硬件完成会话认证yh_util_get_object_info读取 AuthKey 的能力与域capabilities/domains校验sign-ecdsa能力后通过yh_util_list_objects枚举设备中所有YH_ASYMMETRIC_KEY类型、YH_ALGO_EC_P256算法的密钥对象并逐一用yh_util_get_public_key将公钥加载进内存密钥表_keys公钥 → 对象 ID 映射。解锁成功后keosd 还会启动一个 20 秒周期的保活keepalive定时器定期通过YHC_ECHO心跳消息维持与硬件的会话见 yubihsm_wallet.cpp避免会话因空闲超时被硬件端回收。解锁后的日常使用与能力边界解锁完成后你可以像使用普通钱包一样使用cleos wallet系列命令例如cleos wallet list # 查看钱包状态应显示 YubiHSM 已解锁 cleos wallet keys # 仅列出公钥不会输出私钥 cleos wallet create_key -n YubiHSM --key-type R1 # 在硬件内生成新密钥由于 YubiHSM 采用私钥不出设备的安全模型作为安全机制的一部分以下钱包子命令在 YubiHSM 场景下不被支持不支持的操作原因源码依据检索/导出私钥retrieve private keys即wallet keys之外的私钥获取get_private_key与list_keys直接抛出异常Obtaining private key for a key stored in YubiHSM is impossibleyubihsm_wallet.cpp导入密钥import keyIt is not possible to import a key in to the YubiHSM walletyubihsm_wallet.cpp移除密钥remove keyYubiHSM wallet does not currently support removal of keysyubihsm_wallet.cpp设置新密码set passwordYubiHSM wallet cannot have a password set——密码由硬件端 AuthKey 决定yubihsm_wallet.cpp此外YubiHSM 钱包仅支持 R1secp256r1 / prime256v1 P-256密钥create_key在传入非 R1 类型时会抛出unsupported_key_type_exception见 yubihsm_wallet.cpp。这对应 EOS 链上以PUB_R1...为前缀的公钥格式。源码级原理一次交易签名是如何完成的理解了操作步骤后再看一次典型签名的底层链路能更清晰地理解硬件钱包的价值cleos向 keosd 的 wallet API 发起签名请求携带待签摘要digest与公钥yubihsm_wallet::try_sign_digest在内存密钥表_keys中查找公钥对应的硬件对象 IDyubihsm_wallet.cpp调用yh_util_sign_ecdsa(session, key_id, digest, ...)将摘要送入 YubiHSM私钥在硬件内部完成 ECDSA 签名返回 DER 格式签名keosd 将 DER 签名解析为 r、s 分量使用 secp256r1 曲线参数EC_KEY_new_by_curve_name(NID_X9_62_prime256v1)见 yubihsm_wallet.cpp恢复出紧凑签名compact signature并封装为 EOS 标准签名类型返回。整个过程中私钥材料始终没有离开 YubiHSM 芯片即使 keosd 所在主机被完全控制攻击者最多只能借用签名能力而无法窃取密钥本体——这正是硬件钱包的核心安全价值。常见问题与排查建议解锁时报 Failed to create YubiHSM session通常是 AuthKey 编号错误或密码不正确检查--yubihsm-authkey对象号与--password是否与硬件中配置一致。报 Given authkey cannot perform signingAuthKey 缺少sign-ecdsa能力请使用 YubiHSM Manager 工具为 AuthKey 补齐上述三项能力。连接器方式下无法连接先访问http://127.0.0.1:12345/connector/status确认返回statusOK若连接器在其他主机务必通过--yubihsm-url指定完整地址。希望使用 USB 直连确认--yubihsm-urlysb://写法正确且当前用户对 USB 设备有访问权限。相关帮助信息运行keosd --help可查看Config Options for eosio::wallet_plugin一节中--yubihsm-url与--yubihsm-authkey的完整说明亦可参考 keosd 使用文档。延伸阅读原始 How-to 文档How To Attach a YubiHSM Hard Walletkeosd 使用说明Keosd Usage钱包插件参数定义与 YubiHSM 启用逻辑wallet_plugin.cppYubiHSM 钱包实现yubihsm_wallet.cpp、yubihsm_wallet.hppkeosd 主程序入口keosd/main.cpp赞分享区块链【免费下载链接】eosAn open source smart contract platform项目地址https://gitcode.com/gh_mirrors/eo/eos点击查看免费下载相关推荐EOSIO cleos wallet open 命令详解打开本地钱包文件并接入 keosd 钱包服务EOSIO cleos wallet open 命令详解打开本地钱包文件并接入 keosd 钱包服务 cleos wallet open 是 EOSIO 智能区块链EOSIO cleos 连接指定 keosd 钱包服务--wallet-url 参数配置与底层机制详解EOSIO cleos 连接指定 keosd 钱包服务 wallet url 参数配置与底层机制详解 本篇指南聚焦 EOSIO 生态中最常用的钱包连接场景当区块链go-ethereum 智能卡钱包Smartcard Wallet接入指南基于 keycard 的硬件钱包配置与使用go ethereum 智能卡钱包Smartcard Wallet接入指南基于 keycard 的硬件钱包配置与使用 导读 本文以 go ethereum区块链后端上一篇SpacetimeDB C 快速上手5 分钟用 C 编写可编译为 WebAssembly 的服务端模块下一篇Data Science for Beginners 分布可视化实战用 Matplotlib 直方图与 Seaborn 密度图分析明尼苏达鸟类数据集创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
