使用pkcs11-tool的PKCS#11#
本指南描述了NetHSM的PKCS#11驱动的使用。本指南使用的工具来自`OpenSC<https://github.com/OpenSC/OpenSC>`__。请参考它们的文档,了解如何在你的操作系统上使用它们。
重要
这个驱动仍然是一个早期的概念验证实现,只实现了操作TLS服务器所需的功能。
安装#
安装预编译的库#
从版本库的`版本页面<https://github.com/Nitrokey/nethsm-pkcs11/releases>`__ 下载包含最新版本的存档。使用标题中包含你的操作系统名称的发布档案。
用你选择的归档程序从下载的档案中提取文件。
将提取的库复制到你操作系统中的相应路径。该路径取决于你对OpenSC的安装和配置。
从源代码编译#
重要
这个驱动只能用官方的Go编译器来编译。请不要使用GNU Go编译器(GCC-Go)。请参考他们的`网站<https://go.dev/doc/install>`__,了解如何安装。
从版本库的`版本页面<https://github.com/Nitrokey/nethsm-pkcs11/releases>`__下载最新版本的存档。使用标题中包含 “源代码 “的发布档案。
用你选择的归档程序从下载的档案中提取文件。
在装有提取的源代码的目录中执行以下命令来编译库。
./build.sh
./build.sh
将提取的库复制到你操作系统中的相应路径。该路径取决于你对OpenSC的安装和配置。
配置#
配置文件`p11nethsm.conf`是必需的,用于配置PKCS#11驱动和NetHSM之间的连接。
一个配置文件的例子看起来如下。
YAML 1.1
---
p11nethsm:
logfile: /tmp/p11nethsm.log
maxsessioncount: 5
debug: true
slots:
- label: NetHSM1
description: NetHSM Zone A
url: "https://nethsmdemo.nitrokey.com/api/v1"
# certSHA256:
# - "0C:66:DC:EB:4D:12:C3:24:FC:82:F4:1D:4C:16:44:12:1D:00:79:FF:36:96:65:E2:21:C4:36:94:F7:8E:22:89"
user: "operator"
password: "env:NETHSM_PASS"
根据你的环境,修改配置文件`p11nethsm.conf`。
配置文件可以包括多个槽,在 “槽 “阵列内。这些槽代表多个NetHSM的部署。槽的`label’字段需要包含一个唯一的名字。url”、”user “和 “password “键是必须的。为了安全起见,建议在环境变量中传递密码。为此,`env:NETHSM_PASS`在`password`键中被传递,其中`NETHSM_PASS`是包含密码的环境变量的名称。如果TLS证书不是由操作系统的证书库中的证书颁发机构(CA)签署的,则需要设置`certSHA256`密钥。
配置文件需要保存在以下路径或应用程序执行的目录中。
$HOME/.nitrokey。
/etc/nitrokey/。
关键管理#
信息#
显示关于cryptoki版本的信息,以及PKCS#11驱动。
$ pkcs11-tool --module p11nethsm.so --show-info
Cryptoki version 2.40
Manufacturer Nitrokey GmbH
Library NetHSM PKCS#11 module (ver 0.1)
Using slot 0 with a present token (0x0)
槽位列表#
关于可用插槽的信息。列出的插槽取决于`p11nethsm.conf`配置文件中的插槽阵列的配置。要了解更多关于插槽的配置,请参考`配置<pkcs11_with_pkcs11-tool.html#configuration>`_`一章。
$ pkcs11-tool --module p11nethsm.so --list-slots
Available slots:
Slot 0 (0x0): NetHSM Zone A
token label : NetHSM1
token manufacturer : Nitrokey GmbH
token model : NetHSM
token flags : rng, token initialized, PIN initialized, readonly
hardware version : 0.1
firmware version : 0.1
serial num : 0
pin min/max : 3/256
注解
如果你的配置支持一个以上的插槽,你可能需要在pkcs11-tool命令中添加`–slot <arg>`选项来使用正确的插槽。
生成密钥#
产生一个密钥对并将其存储在NetHSM上。
注解
PKCS#11驱动目前不支持这个功能。一个密钥对可以通过*nitropy* 或REST API请求生成。要了解更多关于如何生成密钥的信息,请参考`生成密钥<../operation.html#generate-key>`_ 章。
列表键#
显示NetHSM上*Key Store* 中的密钥和证书的信息。
$ pkcs11-tool --module p11nethsm.so --list-objects
Using slot 0 with a present token (0x0)
Private Key Object; RSA
label: myFirstKey
ID: 6d7946697273744b6579
Usage: decrypt, sign
Access: sensitive, always sensitive, never extractable
Public Key Object; RSA 0 bits
label: myFirstKey
ID: 6d7946697273744b6579
Usage: none
Access: none
阅读键#
从NetHSM上的*Key Store* 读取密钥和证书。不可能从NetHSM上读取私钥。
一个密钥对的公钥可以读作如下。
$ pkcs11-tool --module p11nethsm.so --read-object --type pubkey --label myFirstKey -o public.key
一个密钥对的证书可以读作以下内容。
$ pkcs11-tool --module p11nethsm.so --read-object --type cert --label myFirstKey -o public.key
返回的证书或公钥是ASN.1编码的。这些数据可以用*dumpasn1* 工具进行解码,因为它包含DER格式的数据。DER格式可以用OpenSSL转换为PEM格式。
写键#
将密钥和证书写入NetHSM上的*Key Store* 。
钥匙对的私钥可以写成如下形式。
$ pkcs11-tool --module p11nethsm.so --write-object secret.key --type privkey --label myFirstKey
一个密钥对的公钥可以写成如下。
$ pkcs11-tool --module p11nethsm.so --write-object public.key --type pubkey --label myFirstKey
一个密钥对的证书可以写成以下样子。
$ pkcs11-tool --module p11nethsm.so --write-object cert.pub --type cert --label myFirstKey
关键业务#
加密#
NetHSM不能用非对称密钥对数据进行加密,但它提供了可用于加密的公开密钥。请参考`显示密钥细节<operation.html#show-key-details>`__一章,或者按照`读取密钥<pkcs11_with_pkcs11.html#read-keys>`一章的描述检索密钥,以了解如何检索公钥。本例假设公钥在`public.pem`文件中。
可以用OpenSSL对数据进行如下加密。
$ echo 'NetHSM rulez!' | openssl pkeyutl -encrypt -pubin \
-inkey public.pem \
-pkeyopt rsa_padding_mode:oaep \
-pkeyopt rsa_oaep_md:sha512 \
-pkeyopt rsa_mgf1_md:sha512 \
-out encrypted.data
解密#
NetHSM可以为存储在NetHSM上的*Key Store* 的私人密钥解密数据。本例使用前一章中的加密信息`加密<pkcs11_with_pkcs11-tool.html#encrypt>`__。
$ pkcs11-tool --module p11nethsm.so --decrypt \
--mechanism RSA-PKCS-OAEP \
--input-file encrypted.data \
--label myFirstKey \
--hash-algorithm SHA512
NetHSM rulez!
签名#
NetHSM可以为存储在NetHSM的*Key Store*中的私钥签署数据。对于使用RSA和ECDSA密钥的签名,必须先计算出摘要。
要计算一个摘要,首先需要数据。一个信息的创建方法如下。
$ echo 'NetHSM rulez!' | pkcs11-tool --module p11nethsm.so \
--sign \
--mechanism SHA512-RSA-PKCS-PSS \
--output-file sig.data \
--label myFirstKey
创建的签名可以用OpenSSL进行验证,方法如下。
$ echo 'NetHSM rulez!' | openssl dgst -keyform PEM \
-verify public.pem \
-sha512 \
-sigopt rsa_padding_mode:pss \
-sigopt rsa_pss_saltlen:-1 \
-signature sig.data