企业官网建设流程全解析

• 后端
• 网络
• 通信

导读

libwebsockets（lws）在底层 TLS 库之上提供了一套"通用加密层"（Generic Crypto，即 gencrypto），让同一份业务代码无论是链接 OpenSSL 系还是 mbedtls 系 TLS 库，都能不加修改地完成哈希、HMAC、AES、RSA、椭圆曲线（EC）等密码学操作。在这层之上，lws 还实现了基于 JSON 的 JOSE 体系（JWK / JWS / JWE，对应 RFC 7517 / 7515 / 7516），通过 JSON 对象描述密钥与算法，实现"加密敏捷性"（Crypto Agility）。读完本文，你将掌握：如何通过 CMake 开关启用这两层能力、各层支持的算法清单、密钥在 lws 中的统一表示方式，以及如何结合仓库自带的命令行工具与单元测试快速上手签名、验签、加解密和 X.509 证书处理。

一、架构总览：一层抽象，两层 API

lws 的加密体系采用"底座 + 上层"的分层设计，其整体关系如下：

• 通用加密层（generic layer）：直接封装底层 TLS 库（OpenSSL 及兼容库、mbedtls、GnuTLS、BearSSL、SChannel、OpenHITLS 等）的密码学原语，对外暴露lws_genrsa_、lws_genaes_、lws_genec_、lws_genhash_等一组与后端无关的 API。SSHD 插件（plugins/protocol_lws_ssh_base）等 lws 内部组件就是直接使用这一层的典型例子。
• JOSE 层（JWK / JWS / JWE）：在通用层之上，通过 lws 自带的 lejp JSON 流解析器处理 RFC 7515/7516/7517/7518 定义的 JSON 对象，把"算法 + 密钥 + 载荷"的细节封装进 JSON。所有操作只有一个统一接口，具体算法选择由 JSON 中的字段驱动。

这两层的关系在文档中表述得很清楚：JW系列的 API 内部最终也是调用lws_genrsa_等通用 API 完成的，因此"通用层能做的事，JOSE 层都能做"；两者的主要差异在于：使用通用层时你必须实例化正确的类型并调用类型专属的 API，而使用 JOSE 层时只有一个接口，算法细节隐藏在 API 内部、由 JSON 对象控制。

二、构建开关与 TLS 后端切换

启用这两层能力只需在 CMake 配置阶段打开对应的选项，默认均为OFF（见 CMakeLists.txt）：

cmake -DLWS_WITH_GENCRYPTO=1 -DLWS_WITH_JOSE=1 ..

相关选项说明：

"通用层"之所以能做到代码零改动地跨后端运行，核心就在于它抽象了每个 TLS 库的上下文结构。以哈希为例，include/libwebsockets/lws-genhash.h 中的struct lws_genhash_ctx/struct lws_genhmac_ctx内部就是一大段条件编译：mbedtls 后端使用mbedtls_sha256_context或 PSA 接口（mbedtls v4），SChannel 后端使用BCRYPT_ALG_HANDLE，GnuTLS 使用gnutls_hash_hd_t，BearSSL 使用br_sha256_context等，而 OpenSSL 系则退化为EVP_MD_CTX。对外暴露的 API 签名完全一致，切换后端只需重新cmake -DLWS_WITH_MBEDTLS=1并重新构建。

另外值得注意的是依赖关系：LWS_WITH_MNEMONIC（助记词）功能强制要求LWS_WITH_GENCRYPTO打开，否则 CMake 会直接报错（CMakeLists.txt）。

三、通用层支持的算法清单

3.1 通用哈希（Generic Hash）

• SHA1
• SHA256
• SHA384
• SHA512

对应 include/libwebsockets/lws-genhash.h 中的enum lws_genhash_types。该枚举还包含LWS_GENHASH_TYPE_MD5（一般用于兼容旧协议）和LWS_GENHASH_TYPE_UNKNOWN。LWS_GENHASH_LARGEST定义为 64，即最大哈希（SHA512）的字节数，可作为结果缓冲区的通用尺寸。

3.2 通用 HMAC

• SHA256
• SHA384
• SHA512

对应enum lws_genhmac_types，同样包含 SHA1 变体。除标准的 init/update/destroy 流程外，该头文件还提供了 RFC 5869 HKDF 的三件套：lws_genhkdf_extract()、lws_genhkdf_expand()，以及 TLS 1.3（RFC 8446）专用的lws_genhkdf_expand_label()——后者内部自动构造HkdfLabel结构（uint16 length+"tls13 "前缀 label + context）并调用 expand，QUIC/TLS 1.3 类场景可直接复用。

3.3 通用 AES

include/libwebsockets/lws-genaes.h 中的enum enum_aes_modes定义了全部常用模式：

• CBC
• CFB128
• CFB8
• CTR
• ECB
• OFB
• XTS（注意：需要双倍长度密钥，即 XTS-256 需要 64 字节密钥）
• GCM
• KW（Key Wrap，RFC 3394 密钥包装）

操作方向由enum enum_aes_operation（LWS_GAESO_ENC/LWS_GAESO_DEC）区分，填充策略由enum enum_aes_padding（LWS_GAESP_NO_PADDING/LWS_GAESP_WITH_PADDING）控制。LWS_AES_BLOCKSIZE为 128（位），LWS_AES_CBC_BLOCKLEN为 16（字节）。

3.4 通用 RSA

include/libwebsockets/lws-genrsa.h 中的enum enum_genrsa_mode定义了两种工作模式：

• LGRSAM_PKCS1_1_5：PKCS#1 v1.5 填充
• LGRSAM_PKCS1_OAEP_PSS：OAEP / PSS 填充

源码注释明确指出：PKCS#1 v1.5 虽然被广泛使用，但存在已知弱点，新实现建议使用LGRSAM_PKCS1_OAEP_PSS。OAEP 模式还通过oaep_hashid参数（enum lws_genhash_types）指定 MGF1 使用的哈希（通常为 SHA1）。该模式枚举同时驱动签名/验证与加解密两套能力：RSA 既可以做 PKCS#1 v1.5 / OAEP 数据加解密，也可以做 PKCS#1 1.5 / PSS 签名与验证。

3.5 通用椭圆曲线

include/libwebsockets/lws-genec.h 中的enum enum_genec_alg定义了三种算法：

• LEGENEC_ECDH：椭圆曲线 Diffie-Hellman 密钥协商
• LEGENEC_ECDSA：椭圆曲线数字签名
• LEGENEC_EDDSA：Edwards 曲线数字签名（EdDSA）

支持的曲线：

• P-256 / P-384 / P-521（即文档中的 "P521 (sic)"，JWA 标准中 ES521 对应的正是这条曲线）
• Ed25519 / Ed448

限制：EdDSA 及 Ed25519/Ed448 曲线要求以 OpenSSL（LWS_WITH_OPENSSL）构建；mbedtls 后端不提供这两项能力。曲线的允许集合可通过struct lws_ec_curves数组自定义（.name = NULL结尾），默认启用 P-256/P-384/P-521 三条。

四、通用层 API 速查与头文件地图

所有必要的类型与声明均由 include/libwebsockets.h 统一引入，无需分别 include 各个子头文件。官方文档给出的 API 对应关系如下：

4.1 genhash 典型调用流程

哈希类 API 遵循标准的"初始化 → 喂数据 → 取结果并销毁"三段式：

struct lws_genhash_ctx ctx; uint8_t digest[LWS_GENHASH_LARGEST]; lws_genhash_init(&ctx, LWS_GENHASH_TYPE_SHA256); lws_genhash_update(&ctx, data, len); /* 可多次调用，增量消化 */ lws_genhash_destroy(&ctx, digest); /* 输出摘要并释放后端资源 */

HMAC 版本（lws_genhmac_init）额外需要传入密钥与密钥长度。lws_genhash_destroy()的result参数允许传NULL——这是刻意设计的错误处理路径：即使计算失败也能干净地销毁上下文而不产生悬垂资源。此外还提供lws_genhash_render()（十六进制字符串渲染）与lws_genhash_render_prefixed()（带"SHA256:"之类类型前缀的渲染，供文本协议使用）。

4.2 genrsa 上下文生命周期约定

RSA 与 EC 上下文有一个重要的生命周期约定（源码注释明确说明）：ctx是用户分配的内存，首次传给create()前必须memset清零；一旦create()成功，ctx 会写入一个魔数标记（RSA 为LWS_GENRSA_CTX_CREATED_MARK即"LWGR"，EC 为"LWGE"）。此后若再对仍"存活"的 ctx 调用 create 会失败返回非零，只有先lws_genrsa_destroy()清除标记后才能复用。

密钥对生成使用lws_genrsa_new_keypair(context, ctx, mode, el, bits)，其中bits直接指定模长（例如 2048/4096）。RSA 密文输出恒等于密钥模长（2048 位密钥的加密输出固定为 256 字节），因此out缓冲区必须预留该空间。签名验证类 API 采用"验哈希"模式：lws_genrsa_hash_sig_verify()只针对你传入的哈希值做验证，文档提醒你必须在调用前自行对真实载荷做哈希，并另行确认载荷与哈希的对应关系。

4.3 genec 的 ECDH 用法

ECDH 场景中，lws_genecdh_create()初始化上下文后，用lws_genecdh_set_key()分别设置"我方/他方"（LDHS_OURS/LDHS_THEIRS）的密钥元素，即可计算共享密钥。ECDSA/EdDSA 则通过对应的签名/验证 API 工作。has_private字段标记上下文是否持有私钥部分，用于区分仅公钥场景（如验签）与需要私钥的场景（如签名、解密）。

五、通用层的密钥表示：struct lws_jwk_elements数组

通用层中的密钥不是用某个后端特有的结构保存的，而是统一表示为一个struct lws_jwk_elements（即lws_gencrypto_keyelem，见 include/libwebsockets/lws-gencrypto.h）数组——它是一个极简的"指针 + 长度"组合，用于存放密钥元素二进制表示：

typedef struct lws_gencrypto_keyelem { uint8_t *buf; uint32_t len; } lws_gc_elem_t;

数组的长度由密码学算法决定，各密钥类型对应的元素个数如下：

各元素在数组中的索引由 include/libwebsockets/lws-gencrypto.h 中的枚举精确定义：

• RSA：LWS_GENCRYPTO_RSA_KEYEL_E（公钥指数）、N（模数）、D（私钥指数）、P、Q、DP、DQ、QI，共 8 个；另外还预留了OTHER/RI/DI/TI4 个来自 COSE 但 lws 不主动使用的槽位，因此LWS_GENCRYPTO_MAX_KEYEL_COUNT取 RSA 的完整计数。
• EC：CRV（曲线名）、X、Y（公钥坐标）与D（私钥标量），共 4 个；其中D与 RSA 的D复用同一数组下标。
• OCT / AES：仅K（对称密钥），两者共用一个下标。
• OKP（Octet Key Pair，Ed25519/Ed448）：CRV、X、D。

这种"同名元素必须放在同一索引"的约定是有意设计的（源码注释说明）：当用 JWK 解析输入密钥时，最终密钥类型要到 JSON 解析末尾才能确定，统一索引让中间状态可以安全暂存。

六、JOSE 层：JSON 驱动的加密敏捷性

6.1 什么是 Crypto Agility

JOSE 层（JWK / JWS / JWE）是建立在 gencrypto 之上的 JSON 化加密层。它的核心理念是Crypto Agility（加密敏捷性）：每个 JSON 对象中都自带算法与密码套件信息（如"alg":"ES256"、"enc":"AES_256_GCM"），因此想要升级加密强度或轮换密钥时，只需修改定义密钥和 JWS/JWE 算法的 JSON 即可，代码完全不动。升级期间新旧密钥/算法可以同时有效，天然支持过渡期。当然，哪些算法组合可被接受，需要你自己通过查询解析后的 JW 结构来定义策略。

叠加 lws 的通用层支持，JOSE 体系还获得了独有的TLS 库敏捷性：基于 lws 通用层或 JOSE API 编写的代码，即使底层 TLS 库在 OpenSSL 与 mbedtls 之间切换，也完全无需改动——这意味着服务端与客户端共享加密代码是零成本的。

6.2 JOSE 层头文件地图

include/libwebsockets/lws-jose.h 中的enum lws_jws_jose_hdr_indexes枚举了 JOSE 头可出现的全部字段：LJJHI_ALG（必填）、JKU/JWK/KID/X5U/X5C/X5T/X5T_S256/TYP/CTY/CRIT（可选），以及 JWE 专属的ENC（内容加密算法）、ZIP（"DEF"表示 deflate 压缩）、EPK/APU/APV（ECDH 临时公钥参数）、IV/TAG（AES 参数）、P2S/P2C（PBES2 盐与迭代计数）。

算法名称到内部定义的查表由三个 API 完成：lws_gencrypto_jws_alg_to_definition()、lws_gencrypto_jwe_alg_to_definition()和lws_gencrypto_jwe_enc_to_definition()，查询结果填充struct lws_jose_jwe_alg——该结构携带哈希类型、HMAC 类型、签名/加密算法类型、曲线名、最小/固定密钥位数、IV 位数等信息（表定义在 lib/tls/lws-gencrypto-common.c）。此外lws_jws_parse_jose()/lws_jwe_parse_jose()负责把原始 JOSE 头 JSON 解析进struct lws_jose（支持最多 3 个接收者，见LWS_JWS_MAX_RECIPIENTS）。

七、JOSE 层支持的算法组合

JOSE RFC 为不同算法定义了固定短名，lws 的支持矩阵如下。

7.1 JWS（JSON Web Signatures，RFC 7515）

JWS 测试还覆盖了PS256/PS384/PS512（RSA-PSS）：minimal-examples-lowlevel/api-tests/api-test-gencrypto/README.md 说明，PSS 模式盐随机生成，因此自签自验无法检测"后端对自己一致但在做错事"的实现，测试特意引入了固定 RFC 8017 外部签名向量，并验证 PKCS#1 v1.5 签名会被 PSS 验签正确拒绝。

7.2 JWE（JSON Web Encryption，RFC 7516）

补充说明：OAEP 加解密测试在 lws-genrsa.c 中同时覆盖 SHA-1（JWERSA-OAEP）与 SHA-256（JWERSA-OAEP-256）两个固定向量，并验证"用错误 OAEP 哈希创建的 ctx 必须解密失败"，防止后端忽略传入哈希一律退化为 SHA-1。

八、JOSE 层的密钥结构：struct lws_jwk

JOSE 层的密钥使用 include/libwebsockets/lws-jwk.h 中的struct lws_jwk表示。它包含两个struct lws_gencrypto_keyelem数组，尺寸按最坏情况（目前是 RSA）预分配：

• 一个数组保存密钥元素，与通用层的布局完全一致（oct/RSA/EC/OKP 元素）；
• 另一个数组保存从 JWK JSON 中提取的各种非加密元数据。

元数据索引定义如下：

安全要点：当 jwk 即将超出作用域时，必须调用lws_jwk_destroy()——它负责将 jwk 中所有密钥元素数据清零（zero 掉），防止敏感私钥材料残留在内存中。

九、JWK 导入导出与命令行实践

9.1 JWK API 速览

• lws_jwk_import()/lws_jwk_load()：从 JSON 文本 / 文件导入。支持两种形态：无"keys":[]父数组的单密钥（此时cb/user传NULL），以及带"keys":[]数组的多密钥（通过回调lws_jwk_key_import_callback逐密钥处理，回调返回非零即终止迭代）。
• lws_jwk_export()/lws_jwk_save()：导出到缓冲区 / 文件。LWSJWKF_EXPORT_PRIVATE标志控制是否包含私钥部分（oct 对称密钥只有一份秘密材料，不设此标志导出会失败返回 -1）；LWSJWKF_EXPORT_NOCRLF抑制尾部 CRLF。
• lws_jwk_rfc7638_fingerprint()：计算 RFC 7638 兼容的 SHA-256 指纹——只对 RFC 7638 3.2 节规定的成员（如 RSA 的e/kty/n）做哈希，因此kid、alg等元数据变化不影响指纹。

9.2 命令行工具：生成与格式化 JWK

仓库在 minimal-examples-lowlevel/crypto/minimal-crypto-jwk 提供lws-crypto-jwk工具，可生成任意受支持类型的新随机密钥：

$ ./lws-crypto-jwk -t EC -v P-256 --key-ops "sign verify" --public mykey.pub

常用参数：

工具输出遵循严格 RFC 7638 字典序（部分应用硬性要求）。注意日志走 stderr，密钥数据走 stdout，两者可干净分离。

9.3 命令行工具：JWS 签名与验证

minimal-examples-lowlevel/crypto/minimal-crypto-jws 提供lws-crypto-jws，用于对 stdin 做签名或验证：

$ echo -n "plaintext0123456" | ./lws-crypto-jws -s "ES256" -k ec-p256.private

验证成功时明文输出到 stdout 且退出码为 0，否则无输出、非零退出码。JWS 的紧凑序列化形式为b64u(JOSE 头).b64u(载荷).b64u(签名)，API 测试 minimal-examples-lowlevel/api-tests/api-test-jose/jws.c 中对 RFC 7515 的"none"与 HS256 工作示例做了逐字节断言。

9.4 密钥互操作性

仓库文档明确说明：用 OpenSSL 后端和 mbedtls 后端生成的 JWK / 签名结果完全可互换（"Keys produced with openssl and mbedtls backends are completely interchangeable"）——这正是通用层设计目标的最直观验证。minimal-crypto-jwe 目录还预置了key-rsa-4096.private/key-rsa-4096.pub一对密钥，它们正是用lws-crypto-jwk -t RSA -b 4096生成的。

十、示例与自检：把测试当作最佳实践范本

• 通用层自检：minimal-examples-lowlevel/api-tests/api-test-gencrypto 是 gencrypto API 的单元测试兼用法示例。main.c创建lws_context（LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT）后依次跑test_genaes/test_genec/test_genrsa（mbedtls 后端还会追加密套映射测试）。lws-genrsa.c覆盖密钥对生成、公私钥往返、固定 OAEP 已知答案向量与 PSS 交叉验证；lws-mbedtls-cipherlist.c验证 OpenSSL/IANA/mbedtls 三种拼写的密套名能正确映射到 mbedtls ciphersuite id，且"全部无效"的列表必须导致 vhost 创建失败而不能静默回退。运行：

$ cmake . && make $ ./lws-api-test-gencrypto # 输出 "Completed: PASS"

• JOSE 层自检：minimal-examples-lowlevel/api-tests/api-test-jose 提供jwk.c/jws.c/jwe.c三组测试，直接对应 RFC 7517 / 7515 / 7516 的官方工作示例，在 CI 中持续构建验证。
• X.509 命令行工具：minimal-examples-lowlevel/crypto/minimal-crypto-x509 演示证书加载、解析与证书链验证，以及从 PEM 证书/私钥提取 JWK 的能力。

十一、实践要点与安全建议

1. 新项目优先 OAEP/PSS：RSA 的LGRSAM_PKCS1_1_5模式虽广泛使用但有历史弱点，新实现应选择LGRSAM_PKCS1_OAEP_PSS，并按需指定 OAEP 的 MGF1 哈希。
2. XTS 双倍密钥：AES-XTS 模式需要双倍长度密钥（XTS-256 需 64 字节密钥），include/libwebsockets/lws-genaes.h 与 include/libwebsockets/lws-jose.h 的源码注释均以 "care" 显式提醒。
3. 上下文生命周期：lws_genrsa_ctx/lws_genec_ctx首次使用前必须清零，复用前必须先lws_genrsa_destroy()/lws_genec_destroy()清除 created 标记。
4. 密钥归零：struct lws_jwk出作用域前务必调用lws_jwk_destroy()，它会清零全部密钥元素数据。
5. 算法白名单策略：Crypto Agility 赋予你随时切换算法的便利，但"哪些组合可接受"的策略需要你在业务层通过查询解析后的 JW 结构自行把关，切勿盲目接受任意alg。
6. 依赖提醒：启用LWS_WITH_MNEMONIC前必须确认LWS_WITH_GENCRYPTO=1，否则 CMake 配置阶段即失败。

结语

lws 的加密体系用"通用层 + JOSE 层"两层设计，把"底层 TLS 库差异"和"上层算法选择"双双抽象掉：通用层让你在 OpenSSL 与 mbedtls 之间切换后端而代码零改动，JOSE 层让你仅靠修改 JSON 就能完成算法升级与密钥轮换。配合仓库内置的命令行工具（lws-crypto-jwk/lws-crypto-jws/lws-crypto-jwe/lws-crypto-x509）与 API 自检程序，无论是直接调用 gencrypto 做底层密码学操作，还是走 JWK/JWS/JWE 构建 JSON 化安全协议，你都能获得可运行、可验证的落地路径。

• 后端
• 网络
• 通信