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

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

ネットワークの信頼性¶

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

Retries¶

NetHSMインスタンスに到達できない場合、PKCS#11モジュールは他のインスタンス、または同じインスタンス（他のインスタンスも到達できない場合）にリクエストの送信を再試行することができる。リトライの間に遅延を設けることも可能である。

失敗したインスタンスは到達不能とマークされ、バックグラウンドのスレッドで再試行されるため、すべてのインスタンスが到達不能にならない限り試行されない。
バックグラウンドスレッドが生成できない場合(CKF_LIBRARY_CANT_CREATE_OS_THREADS)、失敗したインスタンスは通常の操作中に試行され、リクエストの処理速度が遅くなります。これを最小にするために、このような "インライン "ヘルスチェックは1秒間のタイムアウトに制限され、リクエストごとに3つのヘルスチェックしか試行できません(これは、多数のインスタンスが失敗した場合にのみ到達できる最悪のケースです)。

だから

1回のAPIコールで送信されるリクエストの最大数は以下の通りです：retries.count` + 1 + 3
1回のAPIコールでタイムアウトに達するまでの最大（ワーストケース）時間は以下の通り： (retries.count + 1) *timeout_seconds + 3
いくつかの関数は NetHSM 内で複数の API 呼び出しにつながるため、1 つの PKCS#11 関数呼び出しの最大タイムアウトは異なります。

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は、トークンが存在しないスロットとみなされます。