codeheadsystems/hofmann-elimination

# Hofmann 消除反应 ## 太长不看 本项目实现了 OPRF 和 OPAQUE 安全协议，为通用服务提供了一种减少攻击面（包括凭据被盗后的离线攻击）的方法。可与 Dropwizard 和 Spring Boot 等标准 Java 框架配合使用。 ## 模块结构  ### Java / 服务端 (Maven artifacts) | -- Artifact ID | Version | Description | |----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------| | `hofmann-rfc` | [](https://central.sonatype.com/artifact/com.codeheadsystems/hofmann-rfc) | 所有 RFC 实现：hash-to-curve (RFC 9380)、OPRF (RFC 9497)、OPAQUE (RFC 9807) 以及共享模型 DTOs。 | | `hofmann-client` | [](https://central.sonatype.com/artifact/com.codeheadsystems/hofmann-client) | OPRF/OPAQUE 集成所需的客户端文件。 | | `hofmann-server` | [](https://central.sonatype.com/artifact/com.codeheadsystems/hofmann-server) | OPRF/OPAQUE 集成所需的服务端文件。 | | `hofmann-dropwizard` | [](https://central.sonatype.com/artifact/com.codeheadsystems/hofmann-dropwizard) | 针对 Dropwizard 的特定集成文件。 | | `hofmann-springboot` | [](https://central.sonatype.com/artifact/com.codeheadsystems/hofmann-springboot) | 针对 Spring Boot 的特定集成文件。 | ### TypeScript / 浏览器客户端 | Directory | Description | |------------------------|----------------------------------------------------------------------------------------------------------| | [`hofmann-typescript`](hofmann-typescript/README.md) | 浏览器/Node TypeScript 客户端 — RFC 9497 OPRF + RFC 9807 OPAQUE-3DH。基于 `@noble/curves` 和 `@noble/hashes` 构建。包含 Vite 驱动的交互式演示页面。 | ### 演示环境 | Directory | Description | |------------------------|----------------------------------------------------------------------------------------------------------| | [`hofmann-demo`](hofmann-demo/README.md) | Docker Compose 环境，运行 Dropwizard 服务器和 TypeScript 演示 UI，位于 HAProxy 之后并使用 TLS 1.3。通过 `make certs` 生成自签名 P-256 证书。使用 `make up` 运行。 | ### 示例应用程序 请参阅 [hofmann-elimination-example](https://github.com/codeheadsystems/hofmann-elimination-example) 查看完整的工作应用程序，演示端到端的 OPAQUE 集成。 ### 文档 - **[项目主页](https://codeheadsystems.github.io/hofmann-elimination/)** — 概述、协议图、快速入门指南 - **[迁移指南](MIGRATION.md)** — 如何将现有站点从传统密码认证迁移到 OPAQUE - **[配置指南](USAGE.md)** — 服务器配置、密钥管理、凭据存储实现 - **[账户恢复指南](RECOVERY.md)** — 通过电子邮件、OTP 或自定义机制实现的可插拔账户恢复 - **[交互式 API 文档](https://codeheadsystems.github.io/hofmann-elimination/api-docs.html)** — OPAQUE 和 OPRF 端点的 Swagger UI - **运行时：** 启动您的 Dropwizard 或 Spring Boot 服务器并访问 `/api-docs/` 以查看嵌入式 Swagger UI - **原始 OpenAPI 规范：** [OPRF API](docs/oprf-api.yaml) | [OPAQUE API](docs/opaque-api.yaml) ### 构建 #### Java (需要 Java 21) ``` ./gradlew clean build test ``` #### TypeScript ``` cd hofmann-typescript npm install npm test npm run build ``` ## 目的 本项目提供 OPRF 和 OPAQUE 协议的纯 Java 实现，使服务能够在不存储或传输密码及私钥材料的情况下对用户进行认证。通过使用 OPRF 和 OPAQUE，服务可以显著减少攻击面，即使在服务器遭到入侵的情况下也能保护用户凭据——受损的服务器数据库不会将密码暴露给离线字典攻击，因为服务器从未持有可恢复形式的密码。 本项目还单独提供了 OPRF 原语。这允许客户端通过对敏感材料进行哈希处理来创建标识符，这些标识符在多个客户端之间保持一致且可重用，而无需共享生成它们的密钥材料。结果是服务可以使用该标识符，而无需了解生成了它的数据。当该数据是客户端希望保密的敏感信息时，这非常有用。 ## 协议 本项目实现了三个分层的 RFC： - **Hash-to-Curve** ([详情](hofmann-rfc/HASH_TO_CURVE.md), [rfc 9380](https://www.rfc-editor.org/rfc/rfc9380.html))：使用 Simplified SWU 和 `expand_message_xmd` 将任意输入确定性映射到椭圆曲线点。在内部由 OPRF 使用。 - **OPRF** ([详情](hofmann-rfc/OPRF.md), [rfc 9497](https://www.rfc-editor.org/rfc/rfc9497.html))：不经意伪随机函数。客户端使用服务器的密钥对私有输入计算伪随机函数，而服务器永远无法获知输入。支持 P-256/SHA-256、P-384/SHA-384、P-521/SHA-512 和 Ristretto255/SHA-512。 - **OPAQUE** ([详情](hofmann-rfc/OPAQUE.md), [rfc 9807](https://www.rfc-editor.org/rfc/rfc9807.html))：增强型密码认证密钥交换。基于密码的认证，密码从不传输，且受损的服务器数据库不会将密码暴露给离线字典攻击。 - **账户恢复** ([详情](RECOVERY.md))：可插拔的账户恢复，可与 OPAQUE 并行工作，无需修改协议。用户通过带外机制（电子邮件验证码、短信 OTP、TOTP 等）证明其身份，然后使用新密码重新注册。实现 `RecoveryChallenger` 接口以定义您的恢复方法。 有关协议详情、密码套件、API 参考和有线格式，请参阅上面链接的文档。 ## 安全性 截至 2026 年 2 月，此实现尚未经过正式的安全审计。 有关完整的安全态势、已知设计决策以及如何报告漏洞，请参阅 [SECURITY.md](SECURITY.md)。 最初的 RFC 实现是在 AI 工具的辅助下生成的，并已由人类对照 RFC 规范进行了审查。AI 也被用于搜索直接攻击和侧信道攻击载体，但这不能替代正式的第三方审计。 ## 相关项目 有关所有项目的详细功能比较表，请参阅[项目主页](https://codeheadsystems.github.io/hofmann-elimination/)。 本项目是唯一已知的纯 Java、RFC 兼容（9380 + 9497 + 9807）实现，支持多种密码套件，并可作为标准 Maven artifact 分发且包含框架集成。但我还是链接到了其他项目，以防本项目不能满足您的需求。 ## 许可证 版权所有 2026 Ned Wolpert 根据 Apache 许可证 2.0 版（“许可证”）获得许可； 除非遵守本许可证，否则您不得使用本文件。 您可以在以下位置获取许可证副本： ``` http://www.apache.org/licenses/LICENSE-2.0 ``` 除非适用法律要求或书面同意，否则根据许可证分发的软件 是按“原样”分发的， 没有任何明示或暗示的担保或条件。 请参阅许可证以了解许可证下的特定语言管理权限和 限制。 ## 名称由来 [Hofmann 消除反应](https://en.wikipedia.org/wiki/Hofmann_elimination) 是一种化学反应，涉及胺的消除以生成烯烃。该反应以德国化学家 August Wilhelm von Hofmann 的名字命名，他在 19 世纪首次描述了该反应。Hofmann 消除反应常用于从胺类合成烯烃。它通过用强碱（如氢氧化钠）处理季铵盐来实现，这会导致铵基团的消除并形成烯烃。该反应通常在加热条件下进行，以促进消除过程。 与其他消除反应不同，Hofmann 消除反应生成取代基最少的烯烃作为主要产物，这是由于季铵盐周围的空间位阻造成的。这使其成为合成可能难以通过其他方法获得的特定烯烃的有用反应。 正如 Hofmann 消除反应从分子中去除胺基团，在产物中不留原氮化合物的痕迹一样，该协议从离开客户端的每个值中消除了密码和私钥材料。服务器评估函数、存储凭据并验证认证，而永远不会看到敏感输入。

标签：Dropwizard, Maven, OPAQUE, OPRF, RFC 9497, RFC 9807, Spring Boot, 凭证安全, 后台面板检测, 哈希转曲线, 域名枚举, 密码学, 密钥派生, 手动系统调用, 敏感数据保护, 漏洞验证, 请求拦截, 防离线攻击, 零知识证明