PKCS#11 设置

安装

您可以获取 NetHSM PKCS#11 模块的预编译二进制文件，也可以从源代码中编译它。

预编译二进制文件

1. 从`版本库页面<https://github.com/Nitrokey/nethsm-pkcs11/releases>`__下载与你的系统相对应的模块文件。

2. 将模块文件复制到 PKCS#11 应用程序希望找到它的目录。

从源代码编译

1. 安装`Rust 工具链<https://www.rust-lang.org/tools/install>`__。

2. 从`发行版页面<https://github.com/Nitrokey/nethsm-pkcs11/releases>`__下载并提取源代码，或克隆`资源库<https://github.com/Nitrokey/nethsm-pkcs11>`__。

3. 在源代码目录下运行``cargo build --release``。

配置

默认情况下，模块会在以下位置搜索配置文件：

• /etc/nitrokey/p11nethsm.conf

• /usr/local/etc/nitrokey/p11nethsm.conf

• $HOME/.config/nitrokey/p11nethsm.conf

如果存在多个文件，配置将被合并，以便模块使用所有配置文件的插槽。

您可以使用环境变量``P11NETHSM_CONFIG_FILE``（例如``P11NETHSM_CONFIG_FILE=./p11nethsm.conf``）手动设置配置文件的位置（只读取该文件）。

配置文件格式

配置采用 yaml 格式：

All platforms

# Set this option to true to enable the compatibility option for the C_SetAttributeValue() function.
# This allows the applications using the Java Sun PKCS11 module (like EJBCA) to generate keys.
# When using this, the names given to the keys will be ignored and the keys will have random names.
# Under the hood it will store in memory the name given to the key when calling C_SetAttributeValue(). When a certificate is uploaded it will check if the name was previously passed to C_SetAttributeValue() and translate it to the real name on the NetHSM.
enable_set_attribute_value: false

# Optional log level, acceptable  values are Trace, Debug, Info, Warn and Error
log_level: Debug

# By default, the module logs to both syslog and stderr, trying the sockets /dev/log, /var/run/syslog and finally /var/run/log
# A custom socket can be configured:
syslog_socket: /var/nethsm/log
# Instead of a socket, a custom UDP or TCP syslog can be configured:
# syslog_udp:
#    to_addr: 127.0.0:1:514
#    from_addr: 127.0.0:1:4789
# syslog_tcp: 127.0.0.1:601
# Only one option among "syslog_socket", "syslog_udp", "syslog_tcp" can be configured at the same time

# You can configure the syslog facility ( "kern", "user", "mail", "daemon", "auth", "syslog", "lpr", "news", "uucp", "cron", "authpriv", "ftp", "local0", "local1", "local2", "local3", "local4", "local5", "local6" or "local7"):
syslog_facility: "user"
# You can set the hostname (for use only with syslog_udp or syslog_tcp)
# syslog_hostname: "localhsm-pkcs11"
# You can set the process name (defaults to the process name obtained from the OS)
# syslog_process: "NetHSM Pkcs11"
# You can set the pid used in logs (defaults to the process id obtained from the OS)
# syslog_pid: 0
# You can also configure a custom file, or "-" for stderr.
# log_file: /tmp/p11nethsm.log

# Each "slot" represents a HSM cluster of server that share the same user and keys.
slots:
  - label: LocalHSM                        # Name your NetHSM however you want
    description: Local HSM (docker)        # Optional description

    # Users connecting to the NetHSM server
    operator:
      username: "operator"
      # If the password starts with `env:`, it will obtain the password from an environment variable:
      # password: "env:LOCALHSMPASS"
      # password: "localpass"
      #
      # If the field is not provided, it is expected to be given through `C_Login` function with the
      # `CKU_USER` userType
    administrator:
      username: "admin"
      # If the password starts with `env:`, it will obtain the password from an environment variable:
      # password: "env:LOCALADMINHSMPASS"
      # password: "adminpass"
      #
      # If the field is not provided, it is expected to be given through `C_Login` function with the
      # `CKU_SO` userType

    # List the NetHSM instances
    instances:
      - url: "https://keyfender:8443/api/v1"   # URL to reach the server
        # To avoid having to re-open connections on each requests, the module keeps a connection pool to each instance. If the module is used by a multithreaded application, multiple connections can be opened at the same time.
        # This configures the maximum number of connections in the pool at the same time.
        # Note that this does not limit the total number of open connections.
        # Having a degree of parallelism that is higher than the max number of idle connection can lead overhead as those connections will be closed an re-opened frenquently
        max_idle_connections: 10
        # By default, the certificate of the HSM will be validated using the system's root certificate authority.
        # When the NetHSM uses a self-signed certificate, it can be verified against an allowed list of sha256 fingerprint of the NetHSM's certificate:
        sha256_fingerprints:
          - "31:92:8E:A4:5E:16:5C:A7:33:44:E8:E9:8E:64:C4:AE:7B:2A:57:E5:77:43:49:F3:69:C9:8F:C4:2F:3A:3B:6E"
        # Alternatively certificate checks can be skipped entirely with danger_insecure_cert option.
        # This should be avoided if possible and certainly not used with a productive NetHSM.
        # danger_insecure_cert: true
    # Configure whether the certificates stored in the nethsm are stored in PEM or DER
    # The nethsm itself supports both, but some tooling may only support one of the encodings.
    # Valid values are PEM or DER. Defaults to PEM
    #
    # Values exchanged over the PKCS#11 interface will always be DER encoded.
    # This config only changes the format they are stored in on the Nethsm itself for compatibility with other tooling.
    certificate_format: PEM
    # Configure the network retry mechanism. If absent, no retries are attempted on a network error
    retries:
      # The number of retries after a network error
      count: 3
      # The delay between retries, in integer seconds
      delay_seconds: 1
    # it is possible to configure idle connections to make use of TCP keepalives, preventing the closing of connections by a firewall or detecting such cases
    tcp_keepalive:
      # the number of seconds before keepalives packets start being sent
      # Corresponds to `TCP_KEEPIDLE` on Linux, `TCP_KEEPALIVE` on macOS, and the field keepalivetime of tcp_keepalive on Windows
      time_seconds: 600
      # the number of seconds between each keepalive packet
      # Corresponds to `TCP_KEEPINTVL` on Linux and macOS, and the field keepaliveinterval of tcp_keepalive on Windows
      interval_seconds: 60
      # the number of keepalive packets being sent without a response before the connection
      # is considered closed
      # Corresponds to `TCP_KEEPCNT` on Linux and macOS, and is not used on Windows
      retries: 3
    # Time a connection can spend idle before being closed
    connections_max_idle_duration: 1800

    # Configurable timeout for network operations. If a network operation takes more than, `timeout_seconds`, consider it failed. If `retries` is configured, it will be retried.
    # Defaults to infinite
    timeout_seconds: 10

实例

如果同一插槽中列出多个 NetHSM 实例，则必须将这些实例配置为一个群集。所有实例上的用户证书和密钥必须相同。

模块将以循环方式使用实例，如果一个实例失败，就会尝试另一个实例。

网络可靠性

为提高 PKCS#11 模块的可靠性，可以配置超时、重试、实例冗余和 TCP 保持。

重试

如果 NetHSM 实例无法访问，PKCS#11 模块可重试向其他实例或同一实例（如果其他实例也无法访问）发送请求。可以在重试之间引入延迟。

• 失败的实例会被标记为不可达，并在后台线程中重试，因此除非所有实例都不可达，否则不会对它们进行尝试

• If no background thread can be spawned (CKF_LIBRARY_CANT_CREATE_OS_THREADS), failed instances will be tried during normal operations, slowing down the requests. To minimise this, such "inline" health checks are limited to one second timeouts, and only three health checks can be attempted per request (this is a worst case situation that can only be reached if a large number of instances failed).

因此

• 一次 API 调用发送的最大请求数为`retries.count`` + 1 + 3

• 一次 API 调用超时前的最长（最差）持续时间为： (retries.count + 1) *timeout_seconds + 3

• The maximum timeout for one PKCS#11 function call will vary because some functions will lead to multiple API calls in the NetHSM.

TCP 保持

为了提高性能，NetHSM 实例会保持连接畅通，以避免重新打开连接。在有防火墙的网络中，这些空闲连接有可能被关闭，导致下一次连接尝试超时。为了防止慢速超时的发生，并在发生超时时提前检测，可以为这些连接配置 TCP keepalives。

用户

操作员和管理员用户都是可选的，但如果没有配置用户，模块将无法启动。因此，您可以只配置管理员用户、操作员用户或同时配置这两个用户。

设置两个用户后，模块将默认使用操作员用户，只有在操作需要时才使用管理员用户。

常规 PKCS#11 用户映射为 NetHSM 操作员，PKCS#11 SO 映射为 NetHSM 管理员。

密码

密码可以通过多种方式提供：

• 在配置``password: "mypassword"`` 中以纯文本形式出现。

• 在模块读取的环境变量中，以``env:`` 为前缀：env:ENV_STORING_THE_PASSWORD

• 通过 pkcs11 的登录功能，以 pcks11-tool 为例：pkcs11-tool --module libnethsm_pkcs11.so -p opPassphrase 要提供管理员密码，需要使用``--so-pin`` 代替：pkcs11-tool --module libnethsm_pkcs11.so --login --login-type so --so-pin Administrator

如果配置文件中未设置用户密码，则需要登录以提供密码（第 3 种方法）。

未运行的 NetHSM 被视为不存在令牌的插槽。