PKCS#11-Einrichtung¶

Installation¶

Sie können das NetHSM PKCS#11-Modul entweder als vorkompilierte Binärdatei erhalten oder es aus dem Quellcode kompilieren.

Vorkompilierte Binärdateien¶

Laden Sie die Ihrem System entsprechende Moduldatei von der Seite releases des Repositorys herunter.
Kopieren Sie die Moduldatei in das Verzeichnis, in dem Ihre PKCS#11-Anwendungen sie finden sollen.

Kompilieren aus dem Quelltext¶

Installieren Sie die Rust Toolchain.
Lade den Quellcode von der Seite releases herunter und entpacke ihn oder klone das ` Repository <https://github.com/Nitrokey/nethsm-pkcs11>`__.
Führen Sie cargo build --release im Quellverzeichnis aus.

Konfiguration¶

Standardmäßig sucht das Modul nach Konfigurationsdateien in:

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

Wenn mehrere Dateien vorhanden sind, werden die Konfigurationen zusammengeführt, so dass die Slots aller Konfigurationsdateien vom Modul verwendet werden.

Sie können den Speicherort der Konfigurationsdatei (nur dieser wird gelesen) manuell mit der Umgebungsvariablen P11NETHSM_CONFIG_FILE (z.B. P11NETHSM_CONFIG_FILE=./p11nethsm.conf) festlegen.

Format der Konfigurationsdatei¶

Die Konfiguration ist yaml-formatiert:

# 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

Instanzen¶

Wenn mehrere NetHSM-Instanzen auf demselben Steckplatz aufgeführt sind, müssen diese Instanzen in einem Cluster konfiguriert werden. Die Anmeldeinformationen der Benutzer und die Schlüssel müssen auf allen Instanzen identisch sein.

Das Modul verwendet die Instanzen nach dem Round-Robin-Prinzip und versucht eine andere Instanz, wenn eine ausfällt.

Zuverlässigkeit des Netzwerks¶

Um die Zuverlässigkeit des PKCS#11-Moduls zu verbessern, ist es möglich, Timeouts, Wiederholungen, Instanzredundanz und TCP-Keepalives zu konfigurieren.

Versuche¶

Wenn eine NetHSM-Instanz nicht erreichbar ist, kann das PKCS#11-Modul versuchen, die Anfrage erneut an andere Instanzen oder an dieselbe Instanz zu senden (wenn andere Instanzen ebenfalls nicht erreichbar sind). Es ist möglich, eine Verzögerung zwischen den Wiederholungsversuchen einzuführen.

Fehlgeschlagene Instanzen werden als unerreichbar markiert und in einem Hintergrund-Thread erneut versucht, so dass sie nicht versucht werden, es sei denn, alle Instanzen sind unerreichbar
Wenn kein Hintergrund-Thread erzeugt werden kann (CKF_LIBRARY_CANT_CREATE_OS_THREADS), werden fehlgeschlagene Instanzen während des normalen Betriebs versucht, was die Anfragen verlangsamt. Um dies zu minimieren, sind solche „Inline“-Zustandsprüfungen auf 1 Sekunde Timeout begrenzt, und es können nur 3 Zustandsprüfungen pro Anfrage versucht werden (dies ist eine Worst-Case-Situation, die nur erreicht werden kann, wenn eine große Anzahl von Instanzen fehlschlägt).

Deshalb:

Die maximale Anzahl von Anfragen, die für einen API-Aufruf gesendet werden, beträgt: retries.count + 1 + 3
Die maximale Dauer (im schlimmsten Fall) bis zum Erreichen der Zeitüberschreitung für einen API-Aufruf beträgt: (retries.count + 1) * timeout_seconds + 3
Die maximale Zeitüberschreitung für einen PKCS#11-Funktionsaufruf kann variieren, da einige Funktionen zu mehreren API-Aufrufen im NetHSM führen.

TCP-Keepalive¶

Um die Leistung zu verbessern, werden die Verbindungen mit den NetHSM-Instanzen offen gehalten, damit sie nicht erneut geöffnet werden müssen. Es ist möglich, dass in einem Netzwerk mit einer Firewall diese ungenutzten Verbindungen geschlossen werden, was zu einer Zeitüberschreitung beim nächsten Verbindungsversuch führt. Um langsame Zeitüberschreitungen zu verhindern bzw. diese frühzeitig zu erkennen, können Sie TCP-Keepalives für diese Verbindungen konfigurieren.

Benutzer¶

Die Benutzer „Operator“ und „Administrator“ sind beide optional, aber das Modul wird nicht gestartet, wenn kein Benutzer konfiguriert ist. Auf diese Weise können Sie das Modul nur mit einem Administrator-Benutzer, nur mit einem Bediener-Benutzer oder mit beiden gleichzeitig konfigurieren.

Wenn die beiden Benutzer eingestellt sind, verwendet das Modul standardmäßig den Operator und nur dann den Administrator, wenn die Aktion dies erfordert.

Der reguläre PKCS11-Benutzer wird dem NetHSM-Operator und der PKCS11-SO dem NetHSM-Administrator zugeordnet.

Passwörter¶

Das Passwort kann auf verschiedene Weise übermittelt werden:

Im Klartext in der Konfiguration password: "mypassword"
In einer Umgebungsvariablen, die von dem Modul mit dem Präfix env: gelesen wird: env:ENV_STORING_THE_PASSWORD
Über die Login-Funktion von pkcs11, Beispiel für pcks11-tool: pkcs11-tool --module libnethsm_pkcs11.so -p opPassphrase Um das Admin-Passwort anzugeben, müssen Sie --so-pin verwenden: pkcs11-tool --module libnethsm_pkcs11.so --login --login-type so --so-pin Administrator

Wenn das Passwort eines Benutzers nicht in der Konfigurationsdatei festgelegt ist, ist eine Anmeldung erforderlich, um das Passwort einzugeben (3. Methode).

Ein nicht betriebsbereites NetHSM wird als ein Slot ohne Token betrachtet.