pyauth/python-pkcs11
GitHub: pyauth/python-pkcs11
一个为 Python 提供 PKCS#11 标准高级封装的库，用于简化 HSM 和智能卡设备的加解密操作与密钥管理集成。
Stars: 166 | Forks: 78
.. image:: https://travis-ci.org/danni/python-pkcs11.svg?branch=master
:target: https://travis-ci.org/danni/python-pkcs11
# Python PKCS#11 - 高级封装 API
一个高级的、“更符合 Python 风格”的 PKCS#11 (Cryptoki) 标准接口
旨在支持 Python 中的 HSM 和智能卡设备。
该接口设计遵循 HSM 的逻辑结构，并为文档不清晰的参数提供了有用的默认值。许多 API 可选择性地接受迭代器并像生成器一样运作，允许你流式传输大块数据进行对称加密。
python-pkcs11 还包含许多实用函数，用于在 PKCS#11 数据结构和常见交换格式（包括 PKCS#1 和 X.509）之间进行转换。
python-pkcs11 拥有完整的文档，并且针对所有功能都有完整的集成测试套件。
历史上，该项目曾经针对多个 HSM 平台运行持续集成测试，但随着时间的推移，这种测试设置并未得到维护。目前，GitHub Actions 中的集成测试使用 SoftHSMv2 作为基准。
我们还在 CI 中针对 ``opencryptoki`` 进行测试。如果你愿意贡献包含其他 PKCS#11 实现或真实 HSM 的 CI 设置，欢迎交流！
源码：https://github.com/pyauth/python-pkcs11
文档：http://python-pkcs11.readthedocs.io/en/latest/
## 入门指南
通过 Pip 安装：
::
```
pip install python-pkcs11
```
或从源码构建：
::
```
python -m build .
```
或使用 ``uv``：
::
uv build
假设你的 PKCS#11 库设置为 `PKCS11_MODULE`，并且包含一个名为 `DEMO` 的令牌：
### AES
::
```
import pkcs11
# 初始化我们的 PKCS#11 库
lib = pkcs11.lib(os.environ['PKCS11_MODULE'])
token = lib.get_token(token_label='DEMO')
data = b'INPUT DATA'
# 在我们的 token 上打开一个会话
with token.open(user_pin='1234') as session:
# Generate an AES key in this session
key = session.generate_key(pkcs11.KeyType.AES, 256)
# Get an initialisation vector
iv = session.generate_random(128) # AES blocks are fixed at 128 bits
# Encrypt our data
crypttext = key.encrypt(data, mechanism_param=iv)
```
### 3DES
::
```
import pkcs11
# 初始化我们的 PKCS#11 库
lib = pkcs11.lib(os.environ['PKCS11_MODULE'])
token = lib.get_token(token_label='DEMO')
data = b'INPUT DATA'
# 在我们的 token 上打开一个会话
with token.open(user_pin='1234') as session:
# Generate a DES key in this session
key = session.generate_key(pkcs11.KeyType.DES3)
# Get an initialisation vector
iv = session.generate_random(64) # DES blocks are fixed at 64 bits
# Encrypt our data
crypttext = key.encrypt(data, mechanism_param=iv)
```
### RSA
::
```
import pkcs11
lib = pkcs11.lib(os.environ['PKCS11_MODULE'])
token = lib.get_token(token_label='DEMO')
data = b'INPUT DATA'
# 在我们的 token 上打开一个会话
with token.open(user_pin='1234') as session:
# Generate an RSA keypair in this session
pub, priv = session.generate_keypair(pkcs11.KeyType.RSA, 2048)
# Encrypt as one block
crypttext = pub.encrypt(data)
```
### DSA
::
```
import pkcs11
lib = pkcs11.lib(os.environ['PKCS11_MODULE'])
token = lib.get_token(token_label='DEMO')
data = b'INPUT DATA'
# 在我们的 token 上打开一个会话
with token.open(user_pin='1234') as session:
# Generate an DSA keypair in this session
pub, priv = session.generate_keypair(pkcs11.KeyType.DSA, 1024)
# Sign
signature = priv.sign(data)
```
### ECDSA
::
```
import pkcs11
lib = pkcs11.lib(os.environ['PKCS11_MODULE'])
token = lib.get_token(token_label='DEMO')
data = b'INPUT DATA'
# 在我们的 token 上打开一个会话
with token.open(user_pin='1234') as session:
# Generate an EC keypair in this session from a named curve
ecparams = session.create_domain_parameters(
pkcs11.KeyType.EC, {
pkcs11.Attribute.EC_PARAMS: pkcs11.util.ec.encode_named_curve_parameters('secp256r1'),
}, local=True)
pub, priv = ecparams.generate_keypair()
# Sign
signature = priv.sign(data)
```
### Diffie-Hellman
::
```
import pkcs11
lib = pkcs11.lib(os.environ['PKCS11_MODULE'])
token = lib.get_token(token_label='DEMO')
with token.open() as session:
# Given shared Diffie-Hellman parameters
parameters = session.create_domain_parameters(pkcs11.KeyType.DH, {
pkcs11.Attribute.PRIME: prime, # Diffie-Hellman parameters
pkcs11.Attribute.BASE: base,
})
# Generate a DH key pair from the public parameters
public, private = parameters.generate_keypair()
# Share the public half of it with our other party.
_network_.write(public[Attribute.VALUE])
# And get their shared value
other_value = _network_.read()
# Derive a shared session key with perfect forward secrecy
session_key = private.derive_key(
pkcs11.KeyType.AES, 128,
mechanism_param=other_value)
```
### 椭圆曲线 Diffie-Hellman (ECDH)
::
```
import pkcs11
lib = pkcs11.lib(os.environ['PKCS11_MODULE'])
token = lib.get_token(token_label='DEMO')
with token.open() as session:
# Given DER encocded EC parameters, e.g. from
# openssl ecparam -outform der -name
parameters = session.create_domain_parameters(pkcs11.KeyType.EC, {
pkcs11.Attribute.EC_PARAMS: ecparams,
})
# Generate a DH key pair from the public parameters
public, private = parameters.generate_keypair()
# Share the public half of it with our other party.
_network_.write(public[pkcs11.Attribute.EC_POINT])
# And get their shared value
other_value = _network_.read()
# Derive a shared session key
session_key = private.derive_key(
pkcs11.KeyType.AES, 128,
mechanism_param=(pkcs11.KDF.NULL, None, other_value))
```
## 已测试的兼容性
+------------------------------+--------------+-----------------+--------------+-------------------+
| 功能 | SoftHSMv2 | Thales nCipher | Opencryptoki | OpenSC (Nitrokey) |
+==============================+==============+=================+==============+===================+
| 获取槽/令牌 | 正常 | 正常 | 正常 | 正常 |
+------------------------------+--------------+-----------------+--------------+-------------------+
| 获取机制 | 正常 | 正常 | 正常 | 正常 |
+------------------------------+--------------+-----------------+--------------+-------------------+
| 初始化令牌 | 未实现 |
+------------------------------+-------------------------------------------------------------------+
| 槽事件 | 未实现 |
+------------------------------+-------------------------------------------------------------------+
| 替代认证路径 | 未实现 |
+------------------------------+-------------------------------------------------------------------+
| `始终认证` 密钥 | 未实现 |
+-------------+----------------+--------------+-----------------+--------------+-------------------+
| 创建/复制 | 密钥 | 正常 | 正常 | 错误 | 创建 |
| +----------------+--------------+-----------------+--------------+-------------------+
| | 证书 | 注意事项 [1]_| 注意事项 [1]_ | 注意事项 [1]_| ? |
| +----------------+--------------+-----------------+--------------+-------------------+
| | 域参数 | 注意事项 [1]_| 注意事项 [1]_ | ? | 不适用 |
+-------------+----------------+--------------+-----------------+--------------+-------------------+
| 销毁对象 | 正常 | 不适用 | 正常 | 正常 |
+------------------------------+--------------+-----------------+--------------+-------------------+
| 生成随机数 | 正常 | 正常 | 正常 | 正常 |
+------------------------------+--------------+-----------------+--------------+-------------------+
| 种子随机数 | 正常 | 不适用 | 不适用 | 不适用 |
+------------------------------+--------------+-----------------+--------------+-------------------+
| 摘要 (数据 & 密钥) | 正常 | 注意事项 [2]_ | 正常 | 正常 |
+--------+---------------------+--------------+-----------------+--------------+-------------------+
| AES | 生成密钥 | 正常 | 正常 | 正常 | 不适用 |
| +---------------------+--------------+-----------------+--------------+ |
| | 加密/解密 | 正常 | 正常 | 正常 | |
| +---------------------+--------------+-----------------+--------------+ |
| | 包装/解包 | ? [3]_ | 正常 | 错误 | |
| +---------------------+--------------+-----------------+--------------+ |
| | 签名/验证 | 正常 | 正常 [4]_ | 不适用 | |
+--------+---------------------+--------------+-----------------+--------------+-------------------+
| DES2/ | 生成密钥 | 正常 | 正常 | 正常 | 不适用 |
| DES3 +---------------------+--------------+-----------------+--------------+ |
| | 加密/解密 | 正常 | 正常 | 正常 | |
| +---------------------+--------------+-----------------+--------------+ |
| | 包装/解包 | ? | ? | ? | |
| +---------------------+--------------+-----------------+--------------+ |
| | 签名/验证 | ? | ? | ? | |
+--------+---------------------+--------------+-----------------+--------------+-------------------+
| RSA | 生成密钥对 | 正常 | 正常 | 正常 | 正常 [4]_ [8]_ |
| +---------------------+--------------+-----------------+--------------+-------------------+
| | 加密/解密 | 正常 | 正常 | 正常 | 仅解密 [9]_ |
| +---------------------+--------------+-----------------+--------------+-------------------+
| | 包装/解包 | 正常 | 正常 | 正常 | 不适用 |
| +---------------------+--------------+-----------------+--------------+-------------------+
| | 签名/验证 | 正常 | 正常 | 正常 | 正常 |
+--------+---------------------+--------------+-----------------+--------------+-------------------+
| DSA | 生成参数 | 正常 | 错误 | 不适用 | 不适用 |
| +---------------------+--------------+-----------------+ | |
| | 生成密钥对 | 正常 | 注意事项 [5]_ | | |
| +---------------------+--------------+-----------------+ | |
| | 签名/验证 | 正常 | 正常 [4]_ | | |
+--------+---------------------+--------------+-----------------+--------------+-------------------+
| DH | 生成参数 | 正常 | 不适用 | 不适用 | 不适用 |
| +---------------------+--------------+-----------------+ | |
| | 生成密钥对 | 正常 | 注意事项 [6]_ | | |
| +---------------------+--------------+-----------------+ | |
| | 派生密钥 | 正常 | 注意事项 [7]_ | | |
+--------+---------------------+--------------+-----------------+--------------+-------------------+
| EC | 生成密钥对 | 注意事项 [6]_| ? [3]_ | 不适用 | 正常 |
| +---------------------+--------------+-----------------+ +-------------------+
| | 签名/验证 (ECDSA) | 正常 [4]_ | ? [3]_ | | 仅签名 [9]_ |
| +---------------------+--------------+-----------------+ +-------------------+
| | 派生密钥 (ECDH) | 正常 | ? [3]_ | | ? |
+--------+---------------------+--------------+-----------------+--------------+-------------------+
| 专有扩展 | 不适用 | 未实现 | 不适用 | 不适用 |
+------------------------------+--------------+-----------------+--------------+-------------------+
.. [1] 设备支持的属性集有限。
.. [2] 不支持对密钥进行摘要计算。
.. [3] 未测试：需要设备支持。
.. [4] 不支持默认机制，必须指定机制。
.. [5] 基于现有的域参数。
.. [6] 仅限本地域参数。
.. [7] 生成关于派生密钥的安全警告。
.. [8] `store` 参数被忽略，所有密钥均被存储。
.. [9] 不支持加密/验证，需提取公钥。
Python 版本：
*
PKCS#11 版本：
* 2.11
* 2.20
* 2.40
* 3.1
对于任何未暴露的功能，欢迎发送 pull request。代码设计旨在使其可读性强，并以直观的方式暴露 PKCS#11 规范。
如果你希望你的设备得到支持，请联系我们！
## 更多关于 PKCS#11 的信息
PKCS#11 规范的最新版本可从 OASIS 获取：
http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/pkcs11-base-v2.40.html
你还应查阅你的 PKCS#11 实现的文档。
许多实现暴露了可在你的环境中配置的额外供应商选项，包括替代功能、模式和调试信息。
## 许可证
MIT License
Copyright (c) 2017 Danielle Madeley and contributors
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
标签：AES, Cryptoki, CVE, DNS 反向解析, HSM, PKCS#11, ProjectDiscovery, PyAuth, Python, RSA, SoftHSM, StruQ, X.509, XML 请求, 加密, 安全开发, 密码学, 封装库, 手动系统调用, 数字签名, 数据保护, 无后门, 智能卡, 漏洞扫描器, 硬件安全模块, 逆向工具