Bitwarden Server RustSdk 依赖面清单bitwarden-crypto API Surface 与升级破坏性评估实战【免费下载链接】serverBitwarden infrastructure/backend (API, database, Docker, etc).项目地址: https://gitcode.com/GitHub_Trending/ser/server本指南以仓库内.claude/skills/bump-rust-sdk/references/api-surface.mdRustSdk API Surface Inventory为核心系统梳理 Bitwarden Server 中util/RustSdk从bitwarden-crypto导入的全部类型、trait 与对外 FFI 函数并结合源码讲解升级bitwarden-cryptogit rev 时的破坏性风险评估方法、变更检查命令与完整验证流程。读完本文你将能看懂 API Surface 清单的每一张表并具备独立执行一次 RustSdk 依赖升级评审与回归验证的能力。RustSdk 在 Bitwarden Server 中的定位RustSdk 位于util/RustSdk/属于util/工具/测试基础设施而非src/生产代码。它是一层用 Rust 编写的 FFI 垫片shim通过csbindgen把bitwarden-crypto的密码学能力暴露给 C# 侧供Seeder测试数据生成器使用——为集成测试生成密码学上正确的 Protected Data字段级加密的密文。正如 .claude/skills/bump-rust-sdk/SKILL.md 所述RustSdk is Seedertestinfrastructure (util/, notsrc/production): it gives the C# Seeder field-level encryption (encrypt_string/decrypt_string/encrypt_fields) to produce cryptographically correct Protected Data for integration tests.Cargo.toml通过 git rev 固定bitwarden-crypto的版本。当前仓库 util/RustSdk/rust/Cargo.toml 中 pin 的 rev 为c5d5bba159bd222321f3ecfd90f5ae6192c2c8eb对应 bitwarden/clients 的0.2.0-main.841构建依赖固定为base64 0.22.1、serde 1.0.219、serde_json 1.0.141、csbindgen 1.9.3并以cdylibcrate-type 产出原生动态库。references/api-surface.md即为此依赖面的事实清单记录服务器 RustSdk 从bitwarden-crypto导入的每一个类型、trait 和函数用于在升级 rev 时评估破坏性变更影响。文档头部标注其为从真实源码自动生成Auto-generated from actual source files并记录了当时生成的 pinned revabba7fdab687753268b63248ec22639dff35d07c——对比当前Cargo.toml中实际 pin 的c5d5bba…可以发现每次 bump 后该清单都会按规则重新生成详见下文如何保持清单与代码同步。清单的生成方式与同步机制api-surface.md不是手工维护的散文而是从源码抽取的结构化清单。文档的Location字段指明其事实来源util/RustSdk/rust/src/。SKILL.md中给出了再生成规则references/api-surface.mdmust mirror the actual code. After a bump, regenerate it: read every.rsinutil/RustSdk/rust/src/, extract thebitwarden_cryptousestatements, and rewrite the file.仓库还通过.claude/hooks/rust-sdk-surface-check.sh这一 Stop hook 实施强制同步若Cargo.toml发生变更而api-surface.md未同步更新则阻止提交。这意味着清单中每一行都可追溯回对应.rs文件也决定了它天然适合作为升级评审的破坏性变更基线。bitwarden-crypto 类型使用面一lib.rs 中的密钥生成与管理文档将lib.rs中的类型使用归纳为下表完整继承类型用法BitwardenLegacyKeyBytesBitwardenLegacyKeyBytes::from()— 包裹原始密钥字节供SymmetricCryptoKey::try_from()使用HashPurposeHashPurpose::ServerAuthorization枚举变体KdfKdf::PBKDF2 { iterations }枚举变体携带NonZeroU32MasterKeyMasterKey::derive()、.derive_master_key_hash()、.make_user_key()PrivateKeyPrivateKey::from_pem()、.to_public_key()、.to_der()PublicKeyPublicKey::from_der()RsaKeyPair结构体字面量RsaKeyPair { private, public }SpkiPublicKeyBytesSpkiPublicKeyBytes::from()— 包裹公钥 DER 字节SymmetricCryptoKey.make_aes256_cbc_hmac_key()、::try_from()、.to_base64()UnsignedSharedKey::encapsulate_key_unsigned()已废弃以#[allow(deprecated)]包裹UserKeyUserKey::new()、.make_key_pair()、.0字段访问对照 util/RustSdk/rust/src/lib.rs 的use语句实际导入还包含Pkcs8PrivateKeyBytes与SymmetricKeyAlgorithm两个类型用于缓存预解析的私钥 DER 与生成Aes256CbcHmac对称密钥印证了清单以 bitwarden-crypto 导入面为核心的记录口径。各类型在代码中的真实调用点如下Kdf::PBKDF2 { iterations }与MasterKeygenerate_user_keys()先用NonZeroU32::new(kdf_iterations)校验迭代次数为 0 时返回{error:kdf_iterations must be non-zero}随后执行MasterKey::derive(password, email, kdf)派生主密钥再经derive_master_key_hash(password.as_bytes(), HashPurpose::ServerAuthorization)生成主密码哈希——HashPurpose::ServerAuthorization正是服务器认证所需的哈希用途与生产客户端行为保持一致。UserKey/SymmetricCryptoKey/RsaKeyPairmaster_key.make_user_key()产出(user_key, encrypted_user_key)其中user_key.0.to_base64()输出对称密钥encryptedUserKey以 EncString 形式序列化keypair()构造RsaKeyPair { private, public }私钥由池中 DER 字节经encrypt_with_key(key)加密公钥以SpkiPublicKeyBytes包裹后clone().into()。PrivateKey::from_pem()/.to_public_key()/.to_der()RSA_POOL静态缓存LazyLockVecCachedRsaMaterial启动时解析 util/RustSdk/rust/src/rsa_keys.rs 中100 个测试专用的 RSA-2048 PKCS#8 PEM 私钥文件头明确标注TEST-ONLY KEYS — NOT REAL CREDENTIALS仅供本地开发与测试数据生成零安全价值统一转换为Pkcs8PrivateKeyBytes私钥 DER 与SpkiPublicKeyBytes公钥 DER 缓存。keypair()按pool_index % pool.len()取模选取密钥对lib.rs的测试rsa_pool_initializes_all_entries断言恰好 100 项、rsa_pool_keys_are_unique断言公钥互异、keypair_index_wraps_at_pool_boundary断言索引 100 回绕到 0锁定了该池的全部行为。bitwarden-crypto 类型使用面二cipher.rs 中的字段级加密文档将cipher.rs的类型使用归纳为下表完整继承类型用法BitwardenLegacyKeyBytesBitwardenLegacyKeyBytes::from()— 包裹原始密钥字节供SymmetricCryptoKey::try_from()使用EncStringenc_str.parse::EncString()、.to_string()— 按 EncString 格式解析与序列化SymmetricCryptoKey::try_from()、.make_aes256_cbc_hmac_key()、.to_base64()— 密钥构造与测试对照 util/RustSdk/rust/src/cipher.rs实际还导入了KeyEncryptable、KeyDecryptable、SymmetricKeyAlgorithm三个符号。cipher.rs的文件注释明确了设计约束No dependency on bitwarden_vault types — the caller drives which fields to encrypt——加密哪些字段由 C# 调用方决定Rust 层只负责执行这正是 Seeder 中EncryptPropertyAttribute驱动字段加密的底层基础见 util/Seeder/CLAUDE.md 与 util/Seeder/README.md。EncString是文档与源码共同强调的序列化格式形如2.{iv}|{data}|{mac}AES-256-CBC-HMAC-SHA256对称密钥为 64 字节 Base64。解密路径先enc_str.parse()得到EncString再用decrypt_with_key(key)还原明文crypto_util.rs中的wrap_key/unwrap_key还实现了密钥包裹——把待包裹密钥to_encoded()后encrypt_with_key(wrapping_key)供 cipher-key 模式注入key字段。使用到的 traitKeyEncryptable / KeyDecryptable文档的 Traits 表完整继承Trait文件调用的方法KeyEncryptablelib.rs.encrypt_with_key(key)— 加密 DER 字节与字符串KeyEncryptablecipher.rs.encrypt_with_key(key)— 将明文字符串加密为 EncStringKeyDecryptablecipher.rs.decrypt_with_key(key)— 将 EncString 解密回明文从源码看这两个 trait 是对称加密语义的统一抽象KeyEncryptable的encrypt_with_key在 lib.rs 中作用于 RSA 私钥 DER 字节keypair()内material.private_der.encrypt_with_key(key)在 cipher.rs 中作用于任意明文字符串KeyDecryptable的decrypt_with_key则贯穿解密与密钥解包两条路径。它们签名一旦变化如泛型参数或返回类型调整将同时冲击 lib.rs、cipher.rs、crypto_util.rs 三处调用点因此被文档列为Critical编译失败级风险。FFI 函数清单csbindgen 暴露给 C# 的接口文档的 FFI 函数表完整继承函数文件用途generate_user_keyslib.rs由 email/password 派生主密钥、用户密钥与密钥对generate_organization_keyslib.rs生成组织对称密钥 RSA 密钥对generate_user_organization_keylib.rs用用户公钥封装组织密钥unsignedencrypt_stringcipher.rs用对称密钥加密单个明文字符串decrypt_stringcipher.rs用对称密钥解密 EncStringencrypt_fieldscipher.rs按点路径dot-path加密 JSON 对象中指定字段free_c_stringlib.rs释放以上任一函数返回的 C 字符串逐函数结合源码展开generate_user_keys(email, password, kdf_iterations, pool_index)返回 JSON 含masterPasswordHash经HashPurpose::ServerAuthorization派生、key用户对称密钥 Base64、encryptedUserKeyEncString、publicKey/privateKeyRSA 密钥对私钥加密。pool_index决定使用 RSA 池中哪一对测试密钥。generate_organization_keys()SymmetricCryptoKey::make(SymmetricKeyAlgorithm::Aes256CbcHmac)→UserKey::new(key)→key.make_key_pair()返回key/publicKey/privateKey三项 JSON。generate_user_organization_key(user_public_key, organization_key)两个入参均为 Base64。用户公钥经STANDARD.decode后由PublicKey::from_der(SpkiPublicKeyBytes::from(...))还原组织密钥由SymmetricCryptoKey::try_from(BitwardenLegacyKeyBytes::from(...))还原随后调用已废弃的UnsignedSharedKey::encapsulate_key_unsigned(...)。源码中该调用以#[allow(deprecated)]包裹并附注释说明迁移路径When the SDK removes this deprecated API, migrate to signed encapsulation.——这正是文档 Medium 级风险以#[allow(deprecated)]抑制并注明迁移路径的实例。encrypt_string(plaintext, symmetric_key_b64)/decrypt_string(enc_string, symmetric_key_b64)对称密钥为 64 字节 AES-256-CBC-HMAC-SHA256 密钥的 Base64。加密输出2.{iv}|{data}|{mac}格式 EncString解密先parse::EncString()。所有失败路径统一返回{error:...}JSON例如Failed to create symmetric key: invalid key format or length、Failed to decrypt string等。encrypt_fields(json, field_paths_json, symmetric_key_b64)field_paths_json是点路径数组如[name,login.username,login.uris[*].uri]。encrypt_segments递归遍历 JSON 树[*]段对数组元素迭代末段仅加密字符串值缺失字段与null静默跳过非字符串值如type: 1保持不变——cipher.rs的encrypt_at_path_encrypts_array_wildcard、encrypt_at_path_skips_null_values、encrypt_at_path_skips_missing_fields等测试逐一锁定了这些语义。free_c_string(str)接收前述函数返回的裸指针drop(CString::from_raw(str))归还内存。调用约定为谁使用谁释放且释放后指针不得再使用lib.rs中标注了# Safety文档。清单之外的补充源码cipher.rs还暴露了第 8 个 FFI 函数encrypt_fields_with_cipher_key——为单个 cipher 生成独立密钥加密字段并把被 vault key 包裹的 cipher key 注入顶层key字段cipher.rs的encrypt_fields_with_cipher_key_roundtrip测试证明字段必须用 cipher key 而非 vault key 才能解密此外src/下还有attachment.rs、provider.rs两个模块对应附件加密与 provider 场景。评审上游变更时建议一并扫描这些文件因为它们同样消费bitwarden-crypto类型。C# 侧的动态库加载FFI 绑定由csbindgen在构建期生成。仓库中的 util/RustSdk/NativeMethods.cs 负责跨平台加载DllImportResolver根据操作系统Windows/Linux/OSX与进程架构x86/x64/Arm64在runtimes/{win|linux|osx}-{arch}/native/下定位sdk.{dll|so|dylib}。这意味着 bump 后新增/删除/改名任一 FFI 函数都必须同步核对生成的绑定文件——SKILL.md的验证门禁正是git diff ../NativeMethods.g.cs必须为空。升级破坏性风险评估矩阵文档给出了按影响级别划分的评审优先级完整继承。升级bitwarden-cryptorev 时应优先逐一核对以下清单Critical编译失败级上表所列任何类型的重命名或移除EncString解析或序列化格式的变更KeyEncryptable/KeyDecryptabletrait 方法签名变更SymmetricCryptoKey::try_from()或BitwardenLegacyKeyBytes变更High运行时失败级Kdf::PBKDF2枚举变体变更HashPurpose::ServerAuthorization变更MasterKey::derive()或密钥派生行为变更UnsignedSharedKey::encapsulate_key_unsigned()签名变更Medium废弃告警级带#[deprecated]注解的函数——用#[allow(deprecated)]抑制并附注释说明原因与迁移路径Low透明级不影响公共 API 的内部实现变更既有类型新增方法加性变更非破坏性如何检查上游变更文档给出的基线检查命令完整继承cd /path/to/sdk-internal # bitwarden-crypto public API git diff old..new -- crates/bitwarden-crypto/src/lib.rs crates/bitwarden-crypto/src/keys/mod.rs配合SKILL.md的完整流程一次标准 bump 的变更分析应执行cd /path/to/sdk-internal git log --oneline old-rev..new-rev -- crates/bitwarden-crypto git diff old-rev..new-rev -- crates/bitwarden-crypto/src/keys/mod.rs crates/bitwarden-crypto/src/lib.rs将每个提交与上文的 API Surface 清单交叉比对重点关注类型重命名/移除、EncString格式变化、trait 签名变化、废弃 API 增删、Kdf/HashPurpose变体变化等。此外升级目标 rev 的确立遵循npm 版本 → git SHA映射客户端以bitwarden/sdk-internalnpm 包消费同一份源码其package/bitwarden_wasm_internal_bg.wasm中嵌入了构建所用 commit 的短 SHAgrep -ao main ([0-9a-f]\{7\})展开该 SHA 即可得到应 pin 的完整 rev——这正是仓库当前 revc5d5bba…的来源。注意 npm 版本号的.NNN后缀是私有 Azure 发布任务的计数不是GitHub Actions 的 run number不能按时间或序号反推 SHASKILL.md 验证了841→c5d5bba、842→c9f9dba、840→1e45444之间无时间相关性。升级后的构建与验证门禁按SKILL.md修改Cargo.toml的 rev 后应依次执行构建产物为cdylib编译所有依赖并开启opt-level详见Cargo.toml的 profile 配置cd util/RustSdk/rust cargo build cargo test # roundtrip test is the gate: encrypt_string_decrypt_string_roundtrip cargo fmt --check git diff ../NativeMethods.g.cs # must be unchanged dotnet test test/SeederApi.IntegrationTest/cargo test的门禁用例是cipher.rs中的encrypt_string_decrypt_string_roundtrip用同一把密钥加密hello world断言密文以2.开头EncString 格式再解密断言还原为原文decrypt_string_with_wrong_key_fails则证明错误密钥必然失败。这两个用例直接验证了EncString格式与KeyEncryptable/KeyDecryptable语义是否与生产客户端兼容。MSRV 检查对比目标工作区的rust-version与util/RustSdk/rust-toolchain.toml的 channel若 MSRV 高于当前 channel则把 channel 升到 MSRV而非 sdk-internal 的开发工具链否则构建会报 requires rustc X or newer。锁定文件处理使用定向的cargo update -p bitwarden-crypto而非裸cargo update避免锁文件大范围变动reviewCargo.lockdiff 时留意意外引入的传递加密依赖rsa、aes、sha2等。C# 集成回归dotnet test test/SeederApi.IntegrationTest/验证 Seeder 端到端可用此后还需人工human-only不可由 Agent 代跑通过 util/SeederUtility/README.md 或 util/SeederApi/README.md 描述的流程真实播种确认 seeded 用户能用假主密码登录、cipher 能在 Web 客户端中解密且无 Seeder 报错、清理可删除全部跟踪实体。SKILL.md还提供了完整的端到端实战样例作为参照.claude/skills/bump-rust-sdk/references/examples/2026-06-bump.md2026 年 6 月的一次完整 bump 记录。结语把 API Surface 清单当作升级评审的单一事实来源api-surface.md的价值在于把散落在.rs文件中的use语句与调用点收敛为一张可评审的依赖面快照类型表告诉你哪些类型被消费、trait 表告诉你哪些语义接口被依赖、FFI 表告诉你哪些符号跨语言暴露、风险矩阵告诉你评审时按什么优先级核对上游 commit、检查命令则给出可复现的 diff 流程。配合SKILL.md的 npm→git-rev 映射、MSRV 检查、构建与双重验证门禁它足以支撑任何一次bitwarden-crypto升级的破坏性评估同时守住Seeder 产出的 Protected Data 与生产客户端使用相同密码学原语这一核心不变量。【免费下载链接】serverBitwarden infrastructure/backend (API, database, Docker, etc).项目地址: https://gitcode.com/GitHub_Trending/ser/server创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考