Nastavenie PKCS#11¶

Inštalácia¶

Modul NetHSM PKCS#11 môžete získať buď ako predkompilovaný binárny súbor, alebo ho môžete skompilovať zo zdrojového kódu.

Predkompilované binárne súbory¶

Stiahnite si súbor modulu zodpovedajúci vášmu systému zo stránky releases úložiska.
Skopírujte súbor modulu do adresára, v ktorom ho vaše aplikácie PKCS#11 očakávajú.

Kompilácia zo zdroja¶

Nainštalujte reťazec nástrojov Rust.
Stiahnite a rozbaľte zdrojový kód zo stránky releases alebo klonujte repozitár ` <https://github.com/Nitrokey/nethsm-pkcs11>`__.
Spustite cargo build --release v zdrojovom adresári.

Konfigurácia¶

V predvolenom nastavení modul vyhľadáva konfiguračné súbory v:

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

Ak je prítomných viacero súborov, konfigurácie sa zlúčia tak, aby modul použil sloty všetkých konfiguračných súborov.

Umiestnenie konfiguračného súboru môžete nastaviť ručne (načíta sa len tento súbor) pomocou premennej env P11NETHSM_CONFIG_FILE (napr. P11NETHSM_CONFIG_FILE=./p11nethsm.conf).

Formát konfiguračného súboru¶

Konfigurácia je vo formáte 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

Inštancie¶

Ak je v tom istom slote uvedených viac inštancií NetHSM, tieto inštancie musia byť nakonfigurované v klastri. Prihlasovacie údaje používateľov a kľúče musia byť na všetkých inštanciách rovnaké.

Modul bude používať inštancie okružným spôsobom, pričom v prípade zlyhania jednej inštancie vyskúša inú inštanciu.

Spoľahlivosť siete¶

Na zvýšenie spoľahlivosti modulu PKCS#11 je možné nakonfigurovať časové limity, opakované pokusy, redundanciu inštancií a udržiavacie protokoly TCP.

Retries¶

Ak je inštancia NetHSM nedosiahnuteľná, modul PKCS#11 je schopný opakovať pokus o odoslanie požiadavky iným inštanciám alebo tej istej inštancii (ak sú aj ostatné inštancie nedosiahnuteľné). Je možné zaviesť oneskorenie medzi opakovanými pokusmi.

Neúspešné inštancie sú označené ako nedosiahnuteľné a opätovne sa skúšajú vo vlákne na pozadí, takže sa neskúšajú, pokiaľ nie sú všetky inštancie nedosiahnuteľné.
Ak nie je možné vytvoriť žiadne vlákno na pozadí (CKF_LIBRARY_CANT_CREATE_OS_THREADS), neúspešné inštancie sa budú skúšať počas bežných operácií, čo spomalí požiadavky. Aby sa to minimalizovalo, takéto „inline“ kontroly stavu sú obmedzené na časový limit 1 sekundy a na jednu požiadavku sa môžu pokúsiť iba 3 kontroly stavu (ide o najhoršiu situáciu, ktorá sa môže dosiahnuť iba v prípade veľkého počtu zlyhaných inštancií).

Preto:

Maximálny počet odoslaných požiadaviek na jedno volanie API je: retries.count ` + 1 + 3
Maximálna (najhoršia) doba trvania pred dosiahnutím časového limitu pre jedno volanie API je: (retries.count + 1) * timeout_seconds + 3
Maximálny časový limit pre jedno volanie funkcie PKCS#11 sa bude líšiť, pretože niektoré funkcie vedú k viacerým volaniam API v NetHSM.

Udržiavanie protokolu TCP¶

Na zlepšenie výkonu sa udržiavajú otvorené spojenia s inštanciami NetHSM, aby sa predišlo potrebe ich opätovného otvárania. Je možné, že v sieti s bránou firewall by sa tieto nečinné spojenia mohli uzavrieť, čo by viedlo k tomu, že ďalší pokus o spojenie by vypršal. Aby sa predišlo pomalým timeoutom a aby sa skôr zistilo, ak sa tak stane, je možné pre ne nakonfigurovať keepalives TCP.

Používatelia¶

Používatelia operátor a správca sú voliteľní, ale modul sa nespustí, ak nie je nakonfigurovaný žiadny používateľ. Je to preto, aby ste mohli nakonfigurovať modul len s používateľom administrátora, len s používateľom operátora alebo s oboma súčasne.

Keď sú nastavení dvaja používatelia, modul bude predvolene používať používateľa operátora a používateľa správcu použije len vtedy, keď to akcia vyžaduje.

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

Heslá¶

Heslo možno zadať viacerými spôsobmi:

V jednoduchom texte v konfigurácii password: "mypassword"
V premennej prostredia načítanej modulom s prefixom env:: env:ENV_STORING_THE_PASSWORD
Prostredníctvom prihlasovacej funkcie pkcs11, príklad pre pcks11-tool: pkcs11-tool –module libnethsm_pkcs11.so -p opPassphrase Na zadanie hesla administrátora je potrebné namiesto neho použiť --so-pin: pkcs11-tool --module libnethsm_pkcs11.so --login --login-type so --so-pin Administrator

Ak heslo používateľa nie je nastavené v konfiguračnom súbore, bude sa vyžadovať prihlásenie na zadanie hesla (3. metóda).

NetHSM, ktorý nie je v prevádzke, sa považuje za slot s neprítomným tokenom.