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 格式：

# 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"
    administrator:
      username: "admin"

    # 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 parrallelism 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 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 模块可重试向其他实例或同一实例（如果其他实例也无法访问）发送请求。可以在重试之间引入延迟。

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

  • 如果无法生成后台线程（CKF_LIBRARY_CANT_CREATE_OS_THREADS），则会在正常运行期间尝试失败的实例，从而降低请求速度。为了尽量减少这种情况，此类 "内联 "健康检查的超时时间限制为 1 秒，并且每次请求只能尝试 3 次健康检查（这是最糟糕的情况，只有在大量实例失败时才能达到）。

因此

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

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

  • 一次 PKCS#11 函数调用的最大超时时间会有所不同，因为有些函数会导致 NetHSM 中的多个 API 调用。

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 被视为不存在令牌的插槽。