Inställning av PKCS#11¶

Installation¶

Du kan antingen hämta NetHSM PKCS#11-modulen som en förkompilerad binärfil eller kompilera den från källkoden.

Förkompilerade binära filer¶

Ladda ner den modulfil som motsvarar ditt system från releases page i arkivet.
Kopiera modulfilen till den katalog där dina PKCS#11-program förväntar sig att hitta den.

Kompilera från källa¶

Installera Rust-verktygskedjan.
Ladda ner och extrahera källkoden från sidan releases eller klona repository.
Kör cargo build --release i källkatalogen.

Konfiguration¶

Som standard söker modulen efter konfigurationsfiler i:

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

Om det finns flera filer kommer konfigurationerna att slås samman så att slitsarna i alla konfigurationsfiler används av modulen.

Du kan manuellt ange platsen för konfigurationsfilen (endast denna kommer att läsas) med env-variabeln P11NETHSM_CONFIG_FILE (t.ex. P11NETHSM_CONFIG_FILE=./p11nethsm.conf).

Format för konfigurationsfil¶

Konfigurationen är yaml-formaterad:

# 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

Instanser¶

Om flera NetHSM-instanser anges på samma plats måste dessa instanser konfigureras i ett kluster. Användarnas autentiseringsuppgifter och nycklarna måste vara desamma på alla instanser.

Modulen kommer att använda instanserna i ett round-robin-förfarande och prova en annan instans om en misslyckas.

Nätverkets tillförlitlighet¶

För att förbättra tillförlitligheten hos PKCS#11-modulen är det möjligt att konfigurera timeouts, retries, instance redundancy och TCP keepalives.

Försök på nytt¶

Om en NetHSM-instans inte kan nås kan PKCS#11-modulen försöka skicka begäran på nytt till andra instanser eller till samma instans (om andra instanser inte heller kan nås). Det är möjligt att införa en fördröjning mellan försöken.

Instanser som misslyckas markeras som oåtkomliga och prövas på nytt i en bakgrundstråd, så de kommer inte att prövas om inte alla instanser är oåtkomliga
Om ingen bakgrundstråd kan skapas (CKF_LIBRARY_CANT_CREATE_OS_THREADS), kommer misslyckade instanser att prövas under normal drift, vilket saktar ned förfrågningarna. För att minimera detta begränsas sådana ”inline”-hälsokontroller till timeouts på 1 sekund och endast 3 hälsokontroller kan göras per begäran (detta är en värsta tänkbara situation som endast kan uppnås om ett stort antal instanser misslyckas).

Därför..:

Det maximala antalet förfrågningar som skickas för ett API-anrop är: retries.count + 1 + 3
Den maximala (värsta tänkbara) tiden innan timeout nås för ett API-anrop är: (retries.count + 1) * timeout_seconds + 3
Den maximala tidsgränsen för ett PKCS#11-funktionsanrop varierar eftersom vissa funktioner leder till flera API-anrop i NetHSM.

TCP keepalive¶

För att förbättra prestandan hålls anslutningar öppna med NetHSM-instanserna för att undvika att de behöver öppnas på nytt. I ett nätverk med en brandvägg är det möjligt att dessa lediga anslutningar kan stängas, vilket leder till att nästa anslutningsförsök får en timeout. För att förhindra att långsamma timeouts inträffar, och för att upptäcka tidigare om så sker, är det möjligt att konfigurera TCP keepalives för dessa.

Användare¶

Användarna operatör och administratör är båda valfria men modulen startar inte om ingen användare är konfigurerad. Detta är för att du ska kunna konfigurera modulen med endast en administratörsanvändare, endast en operatörsanvändare eller båda samtidigt.

När de två användarna är inställda kommer modulen att använda operatören som standard och endast använda administratörsanvändaren när åtgärden kräver det.

Den vanliga PKCS#11-användaren är mappad till NetHSM-operatören och PKCS#11 SO är mappad till NetHSM-administratören.

Lösenord¶

Lösenordet kan anges på flera olika sätt:

I klartext i konfigurationen password: "mypassword"
I en miljövariabel som läses av modulen med prefixet env:: env:ENV_STORING_THE_PASSWORD
Via inloggningsfunktionen i pkcs11, exempel för pcks11-tool: pkcs11-tool --module libnethsm_pkcs11.so -p opPassphrase För att ange adminlösenordet måste du använda --so-pin istället: pkcs11-tool --module libnethsm_pkcs11.so --login --login-type so --so-pin Administrator

Om lösenordet för en användare inte har angetts i konfigurationsfilen krävs en inloggning för att ange lösenordet (3:e metoden).

En NetHSM som inte är i drift betraktas som en kortplats där token inte är närvarande.