Nastavení PKCS#11

Instalace

Modul NetHSM PKCS#11 můžete získat buď jako předkompilovanou binární sadu, nebo jej můžete zkompilovat ze zdrojových kódů.

Předkompilované binární soubory

  1. Stáhněte si soubor modulu odpovídající vašemu systému ze stránky releases úložiště.

  2. Zkopírujte soubor modulu do adresáře, kde jej aplikace PKCS#11 očekávají.

Kompilace ze zdrojového kódu

  1. Nainstalujte řetězec nástrojů Rust.

  2. Stáhněte a rozbalte zdrojový kód ze stránky releases nebo naklonujte repozitář ` <https://github.com/Nitrokey/nethsm-pkcs11>`__.

  3. Spusťte cargo build --release ve zdrojovém adresáři.

Konfigurace

Ve výchozím nastavení modul hledá konfigurační soubory v:

  • /etc/nitrokey/p11nethsm.conf

  • /usr/local/etc/nitrokey/p11nethsm.conf

  • $HOME/.config/nitrokey/p11nethsm.conf

Pokud je k dispozici více souborů, budou konfigurace sloučeny tak, aby modul používal sloty všech konfiguračních souborů.

Umístění konfiguračního souboru můžete nastavit ručně (načten bude pouze tento soubor) pomocí proměnné env P11NETHSM_CONFIG_FILE (např. P11NETHSM_CONFIG_FILE=./p11nethsm.conf).

Formát konfiguračního souboru

Konfigurace je ve formátu 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

Instance

Pokud je ve stejném slotu uvedeno více instancí NetHSM, musí být tyto instance nakonfigurovány v clusteru. Pověření uživatelů a klíče musí být ve všech instancích stejné.

Modul bude instance používat obousměrně a v případě selhání jedné instance vyzkouší jinou.

Spolehlivost sítě

Pro zvýšení spolehlivosti modulu PKCS#11 je možné konfigurovat časové limity, opakování, redundanci instancí a udržovací protokoly TCP.

Retries

Pokud je instance NetHSM nedosažitelná, modul PKCS#11 je schopen zopakovat odeslání požadavku jiným instancím nebo stejné instanci (pokud jsou ostatní instance rovněž nedosažitelné). Mezi opakovanými pokusy je možné zavést prodlevu.

  • Instance, které selžou, jsou označeny jako nedosažitelné a jsou znovu zkoušeny ve vlákně na pozadí, takže nebudou zkoušeny, pokud nejsou všechny instance nedosažitelné.

  • Pokud nelze vytvořit žádné vlákno na pozadí (CKF_LIBRARY_CANT_CREATE_OS_THREADS), budou se neúspěšné instance zkoušet během běžných operací, což zpomalí požadavky. Aby se to minimalizovalo, jsou takové „inline“ kontroly stavu omezeny na 1sekundový timeout a na jeden požadavek se lze pokusit provést pouze 3 kontroly stavu (to je nejhorší případ, kterého lze dosáhnout pouze v případě velkého počtu selhání instancí).

Proto:

  • Maximální počet odeslaných požadavků pro jedno volání API je: retries.count + 1 + 3

  • Maximální (nejhorší) doba trvání před dosažením časového limitu pro jedno volání API je: (retries.count + 1) * timeout_seconds + 3.

  • Maximální časový limit pro jedno volání funkce PKCS#11 se bude lišit, protože některé funkce povedou k více voláním API v NetHSM.

Zachovávání protokolu TCP

V zájmu zvýšení výkonu jsou spojení s instancemi NetHSM udržována otevřená, aby nebylo nutné je znovu otevírat. Je možné, že v síti s bránou firewall by tato nečinná spojení mohla být uzavřena, což by vedlo k vypršení časového limitu dalšího pokusu o připojení. Aby k pomalému vypršení času nedocházelo a aby bylo možné dříve zjistit, pokud k němu dojde, je možné pro ně nakonfigurovat udržovací protokoly TCP.

Uživatelé

Uživatelé operátor a správce jsou volitelní, ale modul se nespustí, pokud není nakonfigurován žádný uživatel. To proto, abyste mohli modul nakonfigurovat pouze s uživatelem správce, pouze s uživatelem operátora nebo s oběma uživateli současně.

Pokud jsou nastaveni dva uživatelé, modul ve výchozím nastavení použije uživatele operátora a uživatele správce použije pouze tehdy, když to akce vyžaduje.

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

Hesla

Heslo lze zadat více způsoby:

  • V prostém textu v konfiguraci password: "mypassword"

  • V proměnné prostředí načtené modulem s předponou env:: env:ENV_STORING_THE_PASSWORD

  • Prostřednictvím přihlašovací funkce pkcs11, příklad pro pcks11-tool: pkcs11-tool –module libnethsm_pkcs11.so -p opPassphrase Pro zadání hesla správce je třeba místo něj použít --so-pin: pkcs11-tool --module libnethsm_pkcs11.so --login --login-type so --so-pin Administrator

Pokud není heslo uživatele nastaveno v konfiguračním souboru, bude vyžadováno přihlášení za účelem zadání hesla (3. metoda).

NetHSM, který není v provozu, je považován za slot s nepřítomným tokenem.