OpenSSL¶

警告

尝试检索私钥将导致 OpenSSL 崩溃。这是正常现象，因为私钥无法从 NetHSM 中提取。您可能需要检索公钥（见下面的示例）。

发动机¶

警告

在使用 0.4.12 或更旧版本的引擎（libp11）时，NetHSM 上的 EdDSA 密钥会导致 OpenSSL 找不到任何密钥。在 0.4.12 及更高版本中，当请求一个密钥时，引擎会列出 NetHSM 上的所有密钥。通过标签或 ID 搜索密钥时，建议使用 0.4.13 或更新版本，或从源代码构建`libp11<https://github.com/OpenSC/libp11>`__。引擎二进制文件将位于``src/.libs/pkcs11.so``。

OpenSSL 引擎接口是为 OpenSSL 实现自定义后端的旧方法，在 OpenSSL 3 中已被弃用。

您需要按照`上的说明设置 PKCS#11 模块<pkcs11-setup.html>`__。

安装发动机：

apt install libengine-pkcs11-openssl

dnf install openssl-pkcs11

pacman -S libp11

接下来需要配置 OpenSSL 以使用该引擎。在``openssl.cnf`` 文件中添加以下几行即可：

openssl_conf = openssl_init

[openssl_init]
engines = engine_section

[engine_section]
pkcs11 = pkcs11_section

[pkcs11_section]
engine_id = pkcs11
dynamic_path = /usr/lib/x86_64-linux-gnu/engines-3/libpkcs11.so
MODULE_PATH = /usr/lib/x86_64-linux-gnu/pkcs11/libnethsm_pkcs11.so
init = 0

备注

您可以使用``OPENSSL_CONF`` 环境变量向 OpenSSL 指定 OpenSSL 配置文件的路径。

警告

如果修改 OpenSSL 主配置文件，使其仅包含这些行，则可能会破坏使用 OpenSSL 的其他程序。因此，你可能需要为引擎创建一个单独的配置文件。

将``/usr/lib/x86_64-linux-gnu/pkcs11/libnethsm_pkcs11.so`` 替换为您之前安装的 PKCS#11 模块的路径。

将``/usr/lib/x86_64-linux-gnu/engines-3/libpkcs11.so`` 替换为您安装的 OpenSSL 引擎的路径。路径因发行版而异。engines-3 中的数字与 OpenSSL 版本相对应。在 Debian 上，OpenSSL 3 引擎的路径是``/usr/lib/x86_64-linux-gnu/engines-3/libpkcs11.so``；在 Fedora 上，路径是``/usr/lib64/engines-3/libpkcs11.so``。

现在，您可以使用`PKCS#11 URIs<https://www.rfc-editor.org/rfc/rfc7512>`___，在 NetHSM 上使用密钥：

engine:pkcs11:pkcs11:object=webserver;type=private

这将使用密钥``webserver``。

备注

你可以使用``p11tool`` 命令从 GnuTLS <https://gnutls.org/> 获取密钥的完整 URI：

p11tool --provider /usr/lib/x86_64-linux-gnu/pkcs11/libnethsm_pkcs11.so --list-all

命令示例¶

读取 NetHSM 上非对称密钥对的公开密钥：

openssl pkey -engine pkcs11 -inform ENGINE -in "pkcs11:object=webserver;type=public" -pubout

提供商¶

OpenSSL 提供者接口是为 OpenSSL 实现自定义后端的新方法。`pkcs11-provider 后端<https://github.com/latchset/pkcs11-provider>`__仍处于早期开发阶段。

您需要按照`上的说明设置 PKCS#11 模块<pkcs11-setup.html>`__。

安装提供程序。Fedora 存在一个名为``pkcs11-provider`` 的软件包。对于其他 Linux 发行版，您需要`从源代码构建它<https://github.com/latchset/pkcs11-provider/blob/main/BUILD.md>`__。

然后，您需要配置 OpenSSL 以使用该提供程序。只需在``openssl.cnf`` 文件中添加以下几行即可：

openssl_conf = openssl_init

[openssl_init]
providers = provider_sect

[provider_sect]
pkcs11 = pkcs11_sect

[pkcs11_sect]
module = /home/sautax/git/pkcs11-provider/src/.libs/pkcs11.so
pkcs11-module-path = /usr/lib/libnethsm_pkcs11.so
activate = 1

将``module`` 设置为已安装的提供程序的路径，将``pkcs11-module-path`` 设置为已安装的 PKCS#11 模块的路径。

如果要将 NetHSM 设置为默认提供程序，可将``default = pkcs11`` 添加到``provider_sect`` 部分。

备注

您可以使用``OPENSSL_CONF`` 环境变量向 OpenSSL 指定 OpenSSL 配置文件的路径。

警告

如果修改 OpenSSL 主配置文件，使其仅包含这些行，则可能会破坏使用 OpenSSL 的其他程序。因此，你可能需要为提供程序创建一个单独的配置文件。

然后，您可以通过`PKCS#11 URIs<https://www.rfc-editor.org/rfc/rfc7512>`__ 在 NetHSM 上使用密钥，例如

openssl pkey -provider pkcs11 -in "pkcs11:object=rsakey" -pubout

如果将 NetHSM 设置为默认提供程序，则可以省略``-provider pkcs11`` 参数。

备注

目前，在 URI 中手动设置密钥类型时，提供程序将无法找到密钥。您可以省略 URI 中的``;type=private`` 或``;type=public`` 部分，使其正常工作。