wolfSSL/wolfPKCS11
GitHub: wolfSSL/wolfPKCS11
基于 wolfSSL 的轻量级 PKCS#11 加密令牌库，支持 TPM 硬件后端和嵌入式部署。
Stars: 18 | Forks: 23
# wolfPKCS11
使用 wolfSSL 实现加密算法的 PKCS#11 库。
## 项目特性
## 构建
构建 wolfSSL：
```
git clone https://github.com/wolfSSL/wolfssl.git
cd wolfssl
./autogen.sh
./configure --enable-aescfb --enable-rsapss --enable-keygen --enable-pwdbased --enable-scrypt C_EXTRA_FLAGS="-DWOLFSSL_PUBLIC_MP -DWC_RSA_DIRECT -DHAVE_AES_ECB -DHAVE_AES_KEYWRAP"
make
make check
sudo make install
sudo ldconfig
```
autogen.sh 需要：automake 和 libtool：`sudo apt-get install automake libtool`
构建 wolfPKCS11：
```
git clone https://github.com/wolfSSL/wolfPKCS11.git
cd wolfPKCS11
./autogen.sh
./configure
make
make check
```
### 使用 wolfTPM 的 TPM 支持
启用 TPM 用于加密和密钥存储。
已使用 `./configure --enable-singlethreaded --enable-wolftpm --disable-dh CFLAGS="-DWOLFPKCS11_TPM_STORE" && make` 进行测试。
注意：TPM 不支持 DH，因此仅支持 RSA 和 ECC。
### 可选：AES-CCM 支持
要在 wolfPKCS11 中支持 AES-CCM，请在配置 wolfSSL 和 wolfPKCS11 时添加 `--enable-aesccm`。
### 可选：AES-ECB 支持
要在 wolfPKCS11 中支持 AES-ECB，请在定义了 C 宏 `HAVE_AES_ECB` 的情况下配置 wolfSSL。例如，`CFLAGS="-DHAVE_AES_ECB"`。然后在配置步骤中为 wolfPKCS11 添加 `--enable-aesecb` 以启用它。
警告：ECB (Electronic Code Book) 模式的 AES 通常被认为是不安全的。请考虑使用其他 AES 模式。
### 构建选项和定义
#### 定义 WOLFPKCS11_TPM_STORE
使用 `WOLFPKCS11_TPM_STORE` 将对象存储在 TPM NV 中。
#### 定义 WOLFPKCS11_NO_STORE
禁用 token 的存储。
#### 定义 WOLFPKCS11_DEBUG_STORE
为存储启用调试 printf。
#### 定义 WOLFPKCS11_CUSTOM_STORE
移除存储函数的默认实现。
请参阅 wolfpkcs11/store.h 以获取需要实现的函数原型。
#### 定义 WOLFPKCS11_KEYPAIR_GEN_COMMON_LABEL
在生成密钥对时，将私钥的标签设置为公钥的标签。
#### Analog Devices, Inc. MAXQ10xx 安全元件 ([MAXQ1065](https://www.analog.com/en/products/maxq1065.html)/MAXQ1080)
已增加对使用 MAXQ10xx 硬件进行加密操作和证书存储的支持。
使用前：
1. 确保已安装 maxq10xx-sdk，并且它已将正确的头文件安装到 wolfPKCS11 的源代码中。
2. 编辑 `examples/maxq10xx_init.sh` 以确保其指向正确的路径。
3. 执行 `examples/maxq10xx_init.sh` 以确保其已正确初始化。
注意：在代码中，我们嵌入了一个测试密钥。在生产环境中必须更改此密钥！！请联系 Analog Devices 了解如何获取和使用生产密钥。
## 使用 CMake 构建
wolfPKCS11 使用源外构建（out-of-source builds）。它还需要 CMake 3.16 或更高版本（建议 3.22+）。
### 使用 CMake 构建 wolfSSL
wolfPKCS11 依赖于 wolfSSL。请先使用 CMake 构建并安装 wolfSSL：
```
git clone https://github.com/wolfSSL/wolfssl.git
cd wolfssl
mkdir build && cd build
cmake -DCMAKE_INSTALL_PREFIX=/usr/local \
-DWOLFSSL_AES=yes -DWOLFSSL_AESCBC=yes -DWOLFSSL_AESCCM=yes \
-DWOLFSSL_AESCFB=yes -DWOLFSSL_AESECB=yes -DWOLFSSL_AESCTR=yes \
-DWOLFSSL_AESGCM=yes -DWOLFSSL_AESKEYWRAP=yes -DWOLFSSL_AESOFB=yes \
-DWOLFSSL_AESCTS=yes -DWOLFSSL_DH=yes -DWOLFSSL_DH_DEFAULT_PARAMS=yes \
-DWOLFSSL_ECC=yes -DWOLFSSL_HKDF=yes -DWOLFSSL_KEYGEN=yes \
-DWOLFSSL_MD5=yes -DWOLFSSL_RSA=yes -DWOLFSSL_RSA_PSS=yes \
-DWOLFSSL_SHA=yes -DWOLFSSL_SHA224=yes -DWOLFSSL_SHA3=yes \
-DWOLFSSL_SHA384=yes -DWOLFSSL_SHA512=yes \
-DWOLFSSL_SP_MATH_ALL=yes -DWOLFSSL_PUBLIC_MP=yes \
-DWOLFSSL_WC_RSA_DIRECT=yes -DCMAKE_BUILD_TYPE=Release \
..
cmake --build .
sudo cmake --install .
```
若要安装到非系统目录，请设置 `-DCMAKE_INSTALL_PREFIX=`，并在下方构建 wolfPKCS11 时将相同的路径作为 `-DCMAKE_PREFIX_PATH=` 传入。
### 使用 CMake 构建 wolfPKCS11
```
cd wolfPKCS11
mkdir build && cd build
cmake ..
cmake --build .
ctest
```
要启用其他功能，请在配置步骤中传递选项：
```
cmake -DWOLFPKCS11_DEBUG=yes \
-DWOLFPKCS11_AESKEYWRAP=yes \
-DWOLFPKCS11_AESCTR=yes \
-DWOLFPKCS11_AESCCM=yes \
-DWOLFPKCS11_AESECB=yes \
-DWOLFPKCS11_AESCTS=yes \
-DWOLFPKCS11_AESCMAC=yes \
-DWOLFPKCS11_PBKDF2=yes \
..
cmake --build .
ctest
```
如果 wolfSSL 安装在非系统前缀路径下，请向 CMake 指出该路径：
```
cmake -DCMAKE_PREFIX_PATH=/path/to/wolfssl/install ..
```
### CMake 构建选项
| 选项 | 默认值 | 描述 |
|--------|---------|-------------|
| `WOLFPKCS11_DEBUG` | `no` | 启用调试日志 |
| `WOLFPKCS11_SINGLE_THREADED` | `no` | 单线程模式 |
| `WOLFPKCS11_RSA` | `yes` | RSA 支持 |
| `WOLFPKCS11_OAEP` | `yes` | RSA OAEP 支持 |
| `WOLFPKCS11_RSA_PSS` | `yes` | RSA-PSS 支持 |
| `WOLFPKCS11_KEYGEN` | `yes` | 密钥生成支持 |
| `WOLFPKCS11_ECC` | `yes` | ECC 支持 |
| `WOLFPKCS11_DH` | `yes` | DH 支持 |
| `WOLFPKCS11_AES` | `yes` | AES 支持 |
| `WOLFPKCS11_AESCBC` | `yes` | AES-CBC 支持 |
| `WOLFPKCS11_AESGCM` | `yes` | AES-GCM 支持 |
| `WOLFPKCS11_AESKEYWRAP` | `no` | AES Key Wrap 支持 |
| `WOLFPKCS11_AESCTR` | `no` | AES-CTR 支持 |
| `WOLFPKCS11_AESCCM` | `no` | AES-CCM 支持 |
| `WOLFPKCS11_AESECB` | `no` | AES-ECB 支持 |
| `WOLFPKCS11_AESCTS` | `no` | AES-CTS 支持 |
| `WOLFPKCS11_AESCMAC` | `no` | AES-CMAC 支持 |
| `WOLFPKCS11_HMAC` | `yes` | HMAC 支持 |
| `WOLFPKCS11_HKDF` | `yes` | HKDF 支持 |
| `WOLFPKCS11_PBKDF2` | `no` | 用于 PIN 哈希的 PBKDF2 |
| `PBKDF2_ITERATIONS` | `600000` | PBKDF2 迭代次数（当 `WOLFPKCS11_PBKDF2=yes` 时使用） |
| `WOLFPKCS11_MD5` | `yes` | MD5 支持 |
| `WOLFPKCS11_SHA1` | `yes` | SHA-1 支持 |
| `WOLFPKCS11_SHA224` | `yes` | SHA-224 支持 |
| `WOLFPKCS11_SHA256` | `yes` | SHA-256 支持 |
| `WOLFPKCS11_SHA384` | `yes` | SHA-384 支持 |
| `WOLFPKCS11_SHA512` | `yes` | SHA-512 支持 |
| `WOLFPKCS11_SHA3` | `yes` | SHA-3 支持 |
| `WOLFPKCS11_TPM` | `no` | wolfTPM 密钥库支持 |
| `WOLFPKCS11_NSS` | `no` | NSS 特定修改 |
| `WOLFPKCS11_PKCS11_V3_0` | `yes` | PKCS#11 v3.0 支持 |
| `WOLFPKCS11_PKCS11_V3_2` | `no` | PKCS#11 v3.2 支持 |
| `WOLFPKCS11_EXAMPLES` | `yes` | 构建示例 |
| `WOLFPKCS11_TESTS` | `yes` | 构建并注册测试 |
| `WOLFPKCS11_COVERAGE` | `no` | 代码覆盖率支持 |
| `WOLFPKCS11_INSTALL` | `yes` | 创建安装目标 |
| `WOLFPKCS11_DEFAULT_TOKEN_PATH` | `""` | 编译进库的默认 token 存储路径 |
| `WOLFPKCS11_BUILD_OUT_OF_TREE` | `yes` | 在源码树之外生成构建产物 |
| `BUILD_SHARED_LIBS` | `ON` | 构建共享库 (`ON`) 或静态库 (`OFF`) |
注意：wolfSSL 必须在启用了相应功能的情况下构建，上述选项才能生效（例如，启用 `WOLFPKCS11_AESCCM` 需要构建 wolfSSL 时带有 `-DWOLFSSL_AESCCM=yes`）。
## 环境变量
### WOLFPKCS11_TOKEN_PATH
存储包含 token 数据的文件的路径。如果未设置，wolfPKCS11 将按顺序尝试：由 `WOLFPKCS11_TOKEN_PATH` 指定的目录、由 NSS 配置的任何存储目录、用户主目录（POSIX 上为 `~/.wolfPKCS11` 或 Windows 上为 `%APPDIR%\wolfPKCS11`），最后是可选的 `WOLFPKCS11_DEFAULT_TOKEN_PATH` 构建时设置。不会回退到 `/tmp`；部署必须显式提供一个安全的存储位置。
### WOLFPKCS11_NO_STORE
设置为任意值以停止存储 token 数据。
## 发布说明
### wolfPKCS11 Release 2.0 (2025年8月26日)
**概要**
此版本包含许多新功能，使其可以作为 NSS 的 PKCS11 后端。它还包含许多错误修复。
**详情**
* 新增示例
* 为 wolfPKCS11 添加了证书存储
* 添加了新的 AES 算法：
- `AES-CCM`
- `AES-ECB`
- `AES-CTS`
- `AES-CTR`
* 编译器修复
* 对 TPM 存储的巨大改进
* 减少了对象的内存使用
* 增加了对 MAXQ1065 的支持
* 修复了未提供公共指数时的 RSA 问题
* 修复了对 `CKC_X_509` 的 `CKA_CERTIFICATE_TYPE` 搜索
* 修复了未提供模数时的 RSA 问题
* 修复了对证书对象执行 `C_FindObjects` 时的错误内存访问
* 添加了新功能：
- `C_Digest*`
- `C_SignEncryptUpdate`
- `C_DecryptVerifyUpdate`
- `C_GetOperationState` 和 `C_SetOperationState` (仅 Digest)
- `C_SignRecoverInit` 和 `C_VerifyRecover`
- `wolfPKCS11_Debugging_On` 和 `wolfPKCS11_Debugging_Off`
* 添加了新机制：
- `CKM_ECDSA_SHA*`
- `CKM_SHA*_RSA*`
- `CKM_AES_CMAC_GENERAL`
- `CKM_AES_CMAC`
- `CKM_AES_CBC_ENCRYPT_DATA`
- `CKM_HKDF_DATA`
- `CKM_HKDF_KEY_GEN`
- `CKM_TLS12_KEY_AND_MAC_DERIVE`
- `CKM_TLS12_MASTER_KEY_DERIVE`
- `CKM_TLS12_MASTER_KEY_DERIVE_DH`
- `CKM_NSS_TLS_EXTENDED_MASTER_KEY_DERIVE` (仅限 NSS 构建)
- `CKM_NSS_TLS_EXTENDED_MASTER_KEY_DERIVE_DH` (仅限 NSS 构建)
- `CKM_NSS_TLS_PRF_GENERAL_SHA256` (仅限 NSS 构建)
- `CKM_TLS_MAC`
- `CKM_SHA1_RSA_PKCS`
- `CKM_SHA1_RSA_PKCS_PSS`
- `CKM_SHA3*`
- `CKM_MD5`
- `CKM_NSS_PKCS12_PBE_SHA*_HMAC_KEY_GEN` (仅限 NSS 构建)
- `CKM_PKCS5_PBKD2`
* 添加了新类型：
- `CKO_DATA`
- `CKO_NSS_TRUST` (仅限 NSS 构建)
* 添加了新属性：
- `CKA_CERTIFICATE_TYPE`
- `CKA_CERTIFICATE_CATEGORY`
- `CKA_ID`
- `CKA_ISSUER`
- `CKA_SERIAL_NUMBER`
- `CKA_PUBLIC_KEY_INFO`
- `CKA_URL`
- `CKA_HASH_OF_SUBJECT_PUBLIC_KEY`
- `CKA_HASH_OF_ISSUER_PUBLIC_KEY`
- `CKA_NAME_HASH_ALGORITHM`
- `CKA_CHECK_VALUE`
- `CKA_CERT_SHA1_HASH` (仅限 NSS 构建)
- `CKA_CERT_MD5_HASH` (仅限 NSS 构建)
- `CKA_TRUST_SERVER_AUTH` (仅限 NSS 构建)
- `CKA_TRUST_CLIENT_AUTH` (仅限 NSS 构建)
- `CKA_TRUST_EMAIL_PROTECTION` (仅限 NSS 构建)
- `CKA_TRUST_CODE_SIGNING` (仅限 NSS 构建)
- `CKA_TRUST_STEP_UP_APPROVED` (仅限 NSS 构建)
- `CKA_NSS_EMAIL` (仅限 NSS 构建)
- `CKA_NSS_DB` (仅限 NSS 构建，不存储)
* 为 digest 和 HMAC 添加了 SHA3 支持
* 添加了 AES 密钥生成和密钥封装
* 添加了 `--enable-nss` 用于 NSS 特定的 PKCS11 特性
* 修复了 ECC 派生密钥曲线错误
* 修复了对象布尔属性和权限
* 修复了 `C_SetAttributeValue` 有时会擦除密钥的问题
* 修复了 wolfCrypt FIPSv5 和 FIPSv6 支持
* 修复了加载错误时的 token 擦除问题
* 修复了各种内存泄漏
* 完全重写了基于文件的 token 路径处理
* 添加了调试输出
* 修复了可见性问题
* 修复了 ECC 密钥的 x963 用法
* 增加了对旧版 wolfSSL 的支持
* 修复了 token 覆盖先前对象的问题
* 修复了 token 加载错误处理
* 改进了 `C_Login` 的错误处理
* 改进了 Debian 打包
* 修复了 wolfBoot 的构建问题
* 修复了 `malloc(0)` 代码路径
修复了 `C_CopyObject` 未执行深拷贝的问题
* 添加了 `CKM_RSA_PKCS` 以进行封装/解封
* 修复了 FIPSv5 的 ECC 曲线查找
* 修复了密钥的默认属性
* `C_DestroyObject` 现在会删除文件而不是留下截断的文件
* 增加了对 STM32U5 DHUK 封装的支持
* 增加了对 pin 的 PBKDF2 支持
- FIPS 默认启用
- 使用 `--enable-pbkdf2` 或定义 `WOLFPKCS11_PBKDF2` 启用
* 添加了 `--pbkdf2-iterations` 和 `PBKDF2_ITERATIONS` 以设置 pin 处理的 PBKDF2 迭代次数（默认 600,000）。
### wolfPKCS11 Release 1.3 (2024年3月22日)
**概要**
为 wolfPKCS11 添加了 Visual Studio 支持。修复了转换警告和可移植性问题。
**详情**
* 修复了当 data == NULL 时 `C_GetAttributeValue` 错误地报错 `CKR_ATTRIBUTE_VALUE_INVALID` 的问题。`C_GetAttributeValue` 应在数据字段为 NULL 时设置长度。(PR #27)
* 修复了几个转换警告和可能使用未初始化值的问题。(PR #28)
* 修复了 `WOLFPKCS11_USER_SETTINGS` 的可移植性问题。(PR #28)
* 为 wolfPKCS11 添加了 Visual Studio 支持。(PR #28)
- 这包括带有 Windows TBS 接口的 wolfTPM 支持
* 重新设计了共享库版本控制。(PR #29)
### wolfPKCS11 Release 1.2 (2023年12月26日)
**概要**
使用 wolfTPM 添加了对 TPM 2.0 的后端支持。添加了 AES CBC 密钥封装/解封支持。可移植性改进。通过 GitHub Actions 改进了测试。
**详情**
* 针对轻微的转换警告、拼写检查进行清理，并忽略生成的测试文件 (PR #14)
* 添加了对使用 aes_cbc_pad 封装/解封 RSA 的支持。(PR #15)
* 修复了创建后公钥标签的设置问题（在解码前初始化 ECC 对象）(PR #16)
* 刷新密钥存储中的写入。(PR #17)
* 添加了用于嵌入式用途的构建选项 (PR #18)
- `WOLFSSL_USER_SETTINGS` 以避免包含 `wolfssl/options.h`
- `WOLFPKCS11_USER_SETTINGS` 以避免包含 `wolfPKCS11/options.h`
- `WOLFPKCS11_NO_TIME` 使 wc_GetTime() 可选（它禁用了 token 登录时的暴力破解保护）
* 仅在使用 `WOLFPKCS11_NO_TIME` 时重置失败的登录计数器 (PR #18)
* 修复了 `SetMPI`/`GetMPIData` 中的参数传递 (PR #19)
* 修复了释放 PKCS11 对象时的 `NO_DH` ifdef 门控 (PR #20)
* 添加了 GitHub CI action (PR #21)
* 修复了来自 `./autogen.sh` 的警告。更新了 m4 宏。(PR #21)
* 添加了额外的 GitHub CI action 测试。(PR #22)
* 添加了 wolfPKCS11 对使用 TPM 2.0 模块作为后端的支持。使用 wolfTPM 并支持 RSA 和 ECC。需要 https://github.com/wolfSSL/wolfTPM/pull/311 (PR #23)
* 添加了带有 wolfTPM 后端和单线程的 wolfPKCS11 CI 测试。(PR #23)
* 添加了 PKCS11 TPM NV 存储（通过 `WOLFPKCS11_TPM_STORE` 启用）。允许在 TPM 用例中使用 `WOLFPKCS11_NO_STORE`。(PR #23)
* 修复了来自 mingw 的编译器警告。(PR #23)
* 添加了可移植性宏 `WOLFPKCS11_NO_ENV`，用于 setenv/getenv 不可用的情况。(PR #23)
* 修复为仅非静态构建需要 `-ldl`。(PR #23)
* 可移植性修复。添加了 `NO_MAIN_DRIVER`。支持 `SINGLE_THREADED`。为某些全局变量添加了 `static`。(PR #24)
* 修复了 `XREALLOC` 不可用时的可移植性问题。(PR #25)
* 添加了使用 `WOLFPKCS11_USER_ENV` 支持自定义 setenv/getenv。(PR #25)
* 修复了边缘情况 pin 失败后 init 未被调用 final 的问题。(PR #25)
* 添加了使用 SHA2-256 哈希 PIN 的支持。
- PKS11 使用 scrypt，这会使用数 MB 内存，对于嵌入式系统不实用。(PR #25)
### wolfPKCS11 Release 1.1 (2022年5月6日)
* 添加了对 CKM_AES_CBC_PAD 的支持
* 添加了对 token 数据存储的支持。
* 添加了对加密私钥的支持。
* 在 slot 标志中添加了 CKF_LOGIN_REQUIRED。
* 添加了用于签名/验证的 RSA X_509 支持
* 添加了缺失的 `CK_INVALID_SESSION`。
* 添加了一些缺失的 PKCS11 类型。
* 修复了使用 FIPS 140-2 (fipsv2) 的构建。
* 修复了 `WP11_API` 可见性。
* 修复了测试 pin 以满足 FIPS HMAC 要求的至少 14 个字符。
* 修复了获取操作标志的布尔值。
* 修复了误导性的缩进修复。
* 改进了 FIPS 下的 `curve_oid` 查找。
* 从公共 pkcs11.h 头文件中移除了 `config.h`。
* 将存储库转换为 GPLv3。
### wolfPKCS11 Release 1.0 (2021年10月20日)
* 初始 PKCS11 支持
标签：AES, Bash脚本, DNS 反向解析, ECC, PKCS#11, ProjectDiscovery, RSA, SamuraiWTF, TPM支持, wolfSSL, 令牌存储, 加密库, 子域名变形, 安全中间件, 客户端加密, 密码学, 嵌入式安全, 开发库, 开源, 手动系统调用, 数据保护, 硬件安全模块, 网络安全, 隐私保护