Konfiguracja PKCS#11¶

Instalacja¶

Moduł NetHSM PKCS#11 można pobrać jako wstępnie skompilowany plik binarny lub skompilować go ze źródła.

Wstępnie skompilowane pliki binarne¶

Pobierz plik modułu odpowiadający Twojemu systemowi ze strony releases repozytorium.
Skopiuj plik modułu do katalogu, w którym aplikacje PKCS#11 spodziewają się go znaleźć.

Kompilacja ze źródła¶

Zainstaluj Rust toolchain.
Pobierz i wyodrębnij źródło ze strony wydań ` <https://github.com/Nitrokey/nethsm-pkcs11/releases>`__ lub sklonuj repozytorium ` <https://github.com/Nitrokey/nethsm-pkcs11>`__.
Uruchom cargo build --release w katalogu źródłowym.

Konfiguracja¶

Domyślnie moduł wyszukuje pliki konfiguracyjne w:

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

Jeśli istnieje wiele plików, konfiguracje zostaną połączone, tak aby sloty wszystkich plików konfiguracyjnych były używane przez moduł.

Możesz ręcznie ustawić lokalizację pliku konfiguracyjnego (tylko ten zostanie odczytany) za pomocą zmiennej env P11NETHSM_CONFIG_FILE (np. P11NETHSM_CONFIG_FILE=./p11nethsm.conf).

Format pliku konfiguracyjnego¶

Konfiguracja ma format 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

Wystąpienia¶

Jeśli na liście znajduje się wiele instancji NetHSM w tym samym slocie, instancje te muszą być skonfigurowane w klastrze. Poświadczenia użytkowników i klucze muszą być takie same we wszystkich instancjach.

Moduł będzie korzystał z instancji w trybie round-robin, wypróbowując kolejną instancję, jeśli jedna zawiedzie.

Niezawodność sieci¶

Aby poprawić niezawodność modułu PKCS#11, możliwe jest skonfigurowanie limitów czasu, ponawiania prób, redundancji instancji i utrzymywania TCP.

Próby¶

Jeśli instancja NetHSM jest nieosiągalna, moduł PKCS#11 może ponowić próbę wysłania żądania do innych instancji lub do tej samej instancji (jeśli inne instancje są również nieosiągalne). Możliwe jest wprowadzenie opóźnienia pomiędzy kolejnymi próbami.

Nieudane instancje są oznaczane jako nieosiągalne i ponawiane w wątku w tle, więc nie będą próbowane, chyba że wszystkie instancje są nieosiągalne.
Jeśli nie można utworzyć wątku w tle (CKF_LIBRARY_CANT_CREATE_OS_THREADS), nieudane instancje będą próbowane podczas normalnych operacji, spowalniając żądania. Aby to zminimalizować, takie „wbudowane” kontrole kondycji są ograniczone do 1-sekundowych limitów czasu i tylko 3 kontrole kondycji mogą być próbowane na żądanie (jest to najgorsza sytuacja, która może zostać osiągnięta tylko w przypadku awarii dużej liczby instancji).

Dlatego:

Maksymalna liczba żądań wysłanych dla jednego wywołania API wynosi: retries.count + 1 + 3
Maksymalny (najgorszy przypadek) czas przed osiągnięciem limitu czasu dla jednego wywołania API wynosi: (retries.count + 1) * timeout_seconds + 3
Maksymalny limit czasu dla jednego wywołania funkcji PKCS#11 będzie różny, ponieważ niektóre funkcje prowadzą do wielu wywołań API w NetHSM.

TCP keepalive¶

Aby poprawić wydajność, połączenia są utrzymywane otwarte z instancjami NetHSM, aby uniknąć konieczności ich ponownego otwierania. Możliwe jest, że w sieci z zaporą ogniową te bezczynne połączenia mogą zostać zamknięte, co doprowadzi do przekroczenia limitu czasu następnej próby połączenia. Aby zapobiec wystąpieniu powolnych timeoutów i wykryć je wcześniej, można skonfigurować dla nich keepalives TCP.

Użytkownicy¶

Użytkownicy operator i administrator są opcjonalni, ale moduł nie uruchomi się, jeśli nie zostanie skonfigurowany żaden użytkownik. Dzięki temu można skonfigurować moduł tylko z użytkownikiem administratora, tylko z użytkownikiem operatora lub z obydwoma użytkownikami jednocześnie.

Po ustawieniu dwóch użytkowników moduł będzie domyślnie korzystał z operatora i używał użytkownika administratora tylko wtedy, gdy akcja tego wymaga.

Zwykły użytkownik PKCS#11 jest mapowany na operatora NetHSM, a PKCS#11 SO jest mapowany na administratora NetHSM.

Hasła¶

Hasło można podać na wiele sposobów:

W postaci zwykłego tekstu w konfiguracji password: "mypassword"
W zmiennej środowiskowej odczytywanej przez moduł z prefiksem env:: env:ENV_STORING_THE_PASSWORD
Poprzez funkcję logowania pkcs11, przykład dla pcks11-tool: pkcs11-tool --module libnethsm_pkcs11.so -p opPassphrase Aby podać hasło administratora należy użyć --so-pin zamiast: pkcs11-tool --module libnethsm_pkcs11.so --login --login-type so --so-pin Administrator

Jeśli hasło użytkownika nie jest ustawione w pliku konfiguracyjnym, wymagane będzie zalogowanie się w celu podania hasła (trzecia metoda).

NetHSM, który nie działa, jest uważany za slot z nieobecnym tokenem.