使用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