Diem 框架模块解析：SharedEd25519PublicKey 共享 Ed25519 公钥与认证密钥联动轮换机制

Diem 框架模块解析SharedEd25519PublicKey 共享 Ed25519 公钥与认证密钥联动轮换机制【免费下载链接】diemDiem’s mission is to build a trusted and innovative financial network that empowers people and businesses around the world.项目地址: https://gitcode.com/gh_mirrors/di/diem0x1::SharedEd25519PublicKey是 Diem 区块链 Move 框架中的账户密钥管理模块它通过把公钥与账户认证密钥authentication key绑定联动实现可轮换、可共享的 Ed25519 密钥托管能力。本文基于 Diem 框架 1.2.0-rc0 发布工件中的模块文档SharedEd25519PublicKey.md并结合仓库源码完整讲解其资源模型、全部公开函数、密钥派生与轮换的底层原理、错误处理与形式化规范读完你能够理解该模块的完整语义并能直接复用其publish/rotate_key流程设计自己的密钥托管方案。模块定位为什么要共享一把 Ed25519 公钥在 Diem 账户模型中一个账户地址对应一个 32 字节的认证密钥authentication key交易签名校验最终验证的是认证密钥与签名是否匹配。正常情况下认证密钥由账户私钥派生而来用户更换私钥即需轮换认证密钥。SharedEd25519PublicKey模块解决的是一个更具体的托管场景某个地址持有该模块的资源后可以轮换资源中保存的 Ed25519 公钥同时账户的认证密钥会被锁定同步地更新为从新公钥派生的值。用模块文档的原话概括每个持有SharedEd25519PublicKey资源的地址都可以轮换存储在该资源中的公钥但该账户的认证密钥会随之联动更新从而保证两个密钥始终同步。这一机制的实际价值在于账户的私钥可以由密钥托管方持有例如硬件钱包、托管服务或恢复服务而链上账户始终只认从共享公钥派生出的认证密钥任何一次公钥轮换都会同时让链上认证密钥生效杜绝资源里存的公钥与实际使用的认证密钥失配的安全隐患。从源码看该模块位于 language/diem-framework/modules/SharedEd25519PublicKey.move依赖四个内部模块use DiemFramework::Authenticator; use DiemFramework::DiemAccount; use DiemFramework::Signature; use Std::Errors; use Std::Signer;其中DiemAccount提供认证密钥与轮换能力Authenticator负责从公钥派生认证密钥Signature提供 ed25519 公钥合法性校验。资源结构一个公钥 一个轮换能力模块定义了一个具有key能力的资源SharedEd25519PublicKey字段如下字段类型说明keyvectoru832 字节 ed25519 公钥rotation_capDiemAccount::KeyRotationCapability账户的密钥轮换能力其认证密钥始终由key派生struct SharedEd25519PublicKey has key { /// 32 byte ed25519 public key key: vectoru8, /// rotation capability for an account whose authentication key is always derived from key rotation_cap: DiemAccount::KeyRotationCapability, }rotation_cap是整个设计的核心。查看 DiemAccount.move 中的定义/// The holder of KeyRotationCapability for account_address can rotate the authentication key for /// account_address (i.e., write to account_address/DiemAccount/authentication_key). /// There is at most one KeyRotationCapability in existence for a given address. struct KeyRotationCapability has store { /// Address that KeyRotationCapability was associated with when it was created. account_address: address, }KeyRotationCapability只记录创建时绑定的account_address持有该能力即可为该地址轮换认证密钥。每个地址最多同时存在一个这样的能力——这正是SharedEd25519PublicKey可以接管账户密钥控制权的前提资源持有者即资源所在的托管地址通过持有这份能力可以随时把账户认证密钥轮换到任意新公钥派生的值。常量与错误码模块定义了两个u64错误码常量值含义EMALFORMED_PUBLIC_KEY0共享的 ed25519 公钥不是合法的 ed25519 公钥ESHARED_KEY1共享 ed25519 公钥资源未处于所需状态如重复发布或尚未发布const EMALFORMED_PUBLIC_KEY: u64 0; const ESHARED_KEY: u64 1;这些错误码在调用时会与Errors模块的错误类别invalid_argument、already_published、not_published组合成完整的 abort 码下文各函数的错误场景会逐一说明。公开函数逐层解析模块对外暴露 4 个public函数 1 个内部辅助函数构成完整的生命周期publish发布→rotate_key轮换→key/exists_at读取与查询。publish提取轮换能力并发布资源public fun publish(account: signer, key: vectoru8)函数语义分两步执行将发送者的认证密钥轮换为从key派生的值在account地址下发布一个包含 32 字节 ed25519 公钥与发送者轮换能力的资源。实现代码public fun publish(account: signer, key: vectoru8) { let t SharedEd25519PublicKey { key: x, rotation_cap: DiemAccount::extract_key_rotation_capability(account) }; rotate_key_(mut t, key); assert(!exists_at(Signer::address_of(account)), Errors::already_published(ESHARED_KEY)); move_to(account, t); }关键细节先通过DiemAccount::extract_key_rotation_capability(account)把发送者账户的密钥轮换能力提取出来存入资源随后调用内部函数rotate_key_立即把认证密钥轮换到新公钥最后move_to发布资源。两次 abort 条件若发送者地址下已存在SharedEd25519PublicKey资源则以Errors::already_published(ESHARED_KEY)abort若key长度不是 32更准确地说未通过 ed25519 公钥校验则以Errors::invalid_argument(EMALFORMED_PUBLIC_KEY)abort。从 DiemAccount.move 可以看到extract_key_rotation_capability还会在账户已提取过轮换能力时以EKEY_ROTATION_CAPABILITY_ALREADY_EXTRACTEDabort因此一个账户只能发布一次共享公钥资源。rotate_key_内部的公钥轮换核心fun rotate_key_(shared_key: mut SharedEd25519PublicKey, new_public_key: vectoru8)这是模块内部无public修饰仅模块内可见的轮换实现承担全部密码学逻辑fun rotate_key_(shared_key: mut SharedEd25519PublicKey, new_public_key: vectoru8) { // Cryptographic check of public key validity assert( Signature::ed25519_validate_pubkey(copy new_public_key), Errors::invalid_argument(EMALFORMED_PUBLIC_KEY) ); DiemAccount::rotate_authentication_key( shared_key.rotation_cap, Authenticator::ed25519_authentication_key(copy new_public_key) ); shared_key.key new_public_key; }执行顺序很重要它保证了同步性先做密码学校验Signature::ed25519_validate_pubkeynative 函数定义于 Signature.move确认公钥是合法 ed25519 公钥用资源内持有的rotation_cap调用DiemAccount::rotate_authentication_key把账户认证密钥更新为从新公钥派生出的认证密钥最后把新公钥写回shared_key.key。认证密钥派生逻辑在 Authenticator.move/// Compute an authentication key for the ed25519 public key public_key public fun ed25519_authentication_key(public_key: vectoru8): vectoru8 { Vector::push_back(mut public_key, SINGLE_ED25519_SCHEME_ID); Hash::sha3_256(public_key) }即在 32 字节公钥末尾追加单签 ed25519 的 scheme ID再对整体做 SHA3-256得到 32 字节认证密钥。而DiemAccount::rotate_authentication_keyDiemAccount.move会校验认证密钥长度为 32然后写入cap.account_address对应的账户资源。由于rotation_cap内固定记录了被托管账户地址任何轮换都只能作用于该账户符合 DiemAccount.move 中RotateOnlyKeyOfCapAddress规范的访问控制约束。rotate_key公开的轮换入口public fun rotate_key(account: signer, new_public_key: vectoru8) acquires SharedEd25519PublicKey面向外部调用者的轮换接口将account地址下SharedEd25519PublicKey资源中保存的公钥轮换为new_public_key用资源中保存的能力把认证密钥轮换为从new_public_key派生的新值。public fun rotate_key(account: signer, new_public_key: vectoru8) acquires SharedEd25519PublicKey { let addr Signer::address_of(account); assert(exists_at(addr), Errors::not_published(ESHARED_KEY)); rotate_key_(borrow_global_mutSharedEd25519PublicKey(addr), new_public_key); }若account地址下没有该资源则以Errors::not_published(ESHARED_KEY)abort若new_public_key非法长度非 32 或非合法 ed25519 公钥则以Errors::invalid_argument(EMALFORMED_PUBLIC_KEY)abort实现上通过borrow_global_mut拿到资源的可变引用后复用内部rotate_key_保证公开入口与内部逻辑完全一致避免两处实现漂移。key与exists_at读取与查询public fun key(addr: address): vectoru8 acquires SharedEd25519PublicKey public fun exists_at(addr: address): boolkey返回addr地址下资源中保存的公钥若该地址未持有资源以Errors::not_published(ESHARED_KEY)abort。实现为*borrow_globalSharedEd25519PublicKey(addr).key。exists_at返回addr是否持有SharedEd25519PublicKey资源实现为existsSharedEd25519PublicKey(addr)不产生 abort。脚本层封装链上交易的调用入口该模块的能力通过AccountAdministrationScripts中的两个public(script)函数暴露给链上交易使用AccountAdministrationScripts.movepublish_shared_ed25519_public_keypublic(script) fun publish_shared_ed25519_public_key(account: signer, public_key: vectoru8) { SharedEd25519PublicKey::publish(account, public_key) }任何账户都可以发送此交易把发送账户的认证密钥轮换为public_key派生的值并在account下发布共享公钥资源。常见 abort 条件源码第 153-158 行错误类别错误原因说明Errors::INVALID_STATEDiemAccount::EKEY_ROTATION_CAPABILITY_ALREADY_EXTRACTED账户已提取/委托了其KeyRotationCapabilityErrors::ALREADY_PUBLISHEDSharedEd25519PublicKey::ESHARED_KEY资源已发布在该账户下Errors::INVALID_ARGUMENTSharedEd25519PublicKey::EMALFORMED_PUBLIC_KEYpublic_key不是合法 ed25519 公钥rotate_shared_ed25519_public_keypublic(script) fun rotate_shared_ed25519_public_key(account: signer, public_key: vectoru8) { SharedEd25519PublicKey::rotate_key(account, public_key) }任何此前发布过共享公钥资源的账户均可发送此交易轮换密钥。abort 条件源码第 512-516 行错误类别错误原因说明Errors::NOT_PUBLISHEDSharedEd25519PublicKey::ESHARED_KEY账户下未发布共享公钥资源Errors::INVALID_ARGUMENTSharedEd25519PublicKey::EMALFORMED_PUBLIC_KEYpublic_key不是合法 ed25519 公钥形式化规范用 Move Prover 保证的安全性质模块文档为每个函数都附带了 Move Prover 规范spec这些不是注释而是可由验证器证明的安全契约PublishAbortsIf证明publish仅在公钥不合法INVALID_ARGUMENT账户轮换能力不可用资源已存在ALREADY_PUBLISHED时 abortRotateKey_AbortsIf证明rotate_key_在公钥校验失败时以INVALID_ARGUMENTabort并包含DiemAccount::RotateAuthenticationKeyAbortsIf认证密钥长度必须为 32、目标账户必须存在RotateKey_Ensures证明轮换后shared_key.key new_public_key即资源内公钥与传入公钥严格一致模块级Persistence不变式spec module { invariant update forall addr: address where old(existsSharedEd25519PublicKey(addr)): existsSharedEd25519PublicKey(addr); }该全局不变式声明一旦某地址发布了SharedEd25519PublicKey资源该资源将永久存在、不可被销毁。这与资源的key能力而非store能力设计一致从形式化层面保证了托管关系的持久性。使用流程与注意事项总结一个完整的共享公钥托管流程如下发布托管服务以目标账户的signer调用publish(account, key)链上对应publish_shared_ed25519_public_key脚本完成提取轮换能力 轮换认证密钥 发布资源三步此后该账户认证密钥恒等于Authenticator::ed25519_authentication_key(key)轮换需要换钥时调用rotate_key(account, new_public_key)链上对应rotate_shared_ed25519_public_key脚本公钥与认证密钥原子性地同步更新查询通过exists_at(addr)判断托管状态通过key(addr)读取当前公钥。需要牢记的约束每个账户的KeyRotationCapability唯一publish只能成功一次重复发布以ALREADY_PUBLISHED失败公钥必须是合法 ed25519 公钥长度 32否则以EMALFORMED_PUBLIC_KEY失败资源一经发布不可删除Persistence 不变式设计时应把它视为永久的链上托管状态该模块的完整文档与同名实现还同步存在于发布工件 release-1.2.0-rc0 与 current 两套 artifacts 中源码与文档可对照阅读以追踪版本演进。【免费下载链接】diemDiem’s mission is to build a trusted and innovative financial network that empowers people and businesses around the world.项目地址: https://gitcode.com/gh_mirrors/di/diem创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考