PKCS#11セットアップ¶

インストール¶

NetHSM PKCS#11モジュールは、コンパイル済みのバイナリとして入手するか、ソースからコンパイルすることができます。

コンパイル済みバイナリ¶

リポジトリの`リリースページ<https://github.com/Nitrokey/nethsm-pkcs11/releases>`__ から、お使いのシステムに対応するモジュールファイルをダウンロードしてください。
モジュール・ファイルを、PKCS#11アプリケーションがそれを見つけることを期待するディレクトリにコピーする。

ソースからコンパイルする¶

`Rust toolchain<https://www.rust-lang.org/tools/install>`__ をインストールする。
`リリースページ<https://github.com/Nitrokey/nethsm-pkcs11/releases>`__ からソースをダウンロードして展開するか、`リポジトリ<https://github.com/Nitrokey/nethsm-pkcs11>`__ をクローンしてください。
cargo build --release をソース・ディレクトリで実行する。

構成¶

デフォルトでは、モジュールは設定ファイルを以下の場所で検索する：

/etc/nitrokey/p11nethsm.conf`
/usr/local/etc/nitrokey/p11nethsm.conf`
$HOME/.config/nitrokey/p11nethsm.conf`

複数のファイルが存在する場合、すべての設定ファイルのスロットがモジュールで使用されるように、設定はマージされます。

env 変数``P11NETHSM_CONFIG_FILE`` (e.g.``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"
      #
      # 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インスタンスが表示されている場合は、これらのインスタンスをクラスタに構成する必要があります。ユーザーとキーの認証情報は、すべてのインスタンスで同じでなければなりません。

モジュールはラウンドロビン方式でインスタンスを使用し、1つが失敗したら別のインスタンスを試す。

ネットワークの信頼性¶

PKCS#11モジュールの信頼性を向上させるために、タイムアウト、再試行、インスタンスの冗長性、およびTCPキープアライブを設定することが可能である。

Retries¶

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).

だから

1回のAPIコールで送信されるリクエストの最大数は以下の通りです：retries.count` + 1 + 3
1回の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キープアライブを設定することができます。

ユーザー¶

オペレータと管理者ユーザはどちらも任意ですが、ユーザが設定されていない場合、モジュールは起動しません。これは、モジュールを管理者ユーザーだけ、オペレーターユーザーだけ、または両方を同時に設定できるようにするためです。

2人のユーザーが設定されると、モジュールはデフォルトでオペレータを使用し、アクションが必要なときだけ管理者ユーザーを使用します。

The regular PKCS#11 user is mapped to the NetHSM operator and the PKCS#11 SO is mapped to the NetHSM administrator.

パスワード¶

パスワードは複数の方法で提供することができる：

コンフィギュレーション``password: "mypassword"`` のプレーンテキストで。
env: のプレフィックスを持つモジュールが読み込む環境変数:env:ENV_STORING_THE_PASSWORD
pcks11-tool の例では、pkcs11 のログイン機能を使ってください：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は、トークンが存在しないスロットとみなされます。