Configurarea PKCS#11¶

Instalare¶

Puteți obține modulul NetHSM PKCS#11 ca un binar precompilat sau îl puteți compila din sursă.

Binare precompilate¶

Descărcați fișierul modul corespunzător sistemului dvs. de pe pagina de versiuni ` <https://github.com/Nitrokey/nethsm-pkcs11/releases>`__ a depozitului.
Copiați fișierul modul în directorul în care aplicațiile PKCS#11 se așteaptă să îl găsească.

Compilați din sursă¶

Instalați lanțul de instrumente Rust.
Descărcați și extrageți sursa de pe pagina de versiuni ` <https://github.com/Nitrokey/nethsm-pkcs11/releases>`__ sau clonați depozitul ` <https://github.com/Nitrokey/nethsm-pkcs11>`__.
Rulați cargo build --release în directorul sursă.

Configurație¶

În mod implicit, modulul caută fișierele de configurare în:

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

În cazul în care există mai multe fișiere, configurațiile vor fi îmbinate astfel încât modulele să utilizeze sloturile din toate fișierele de configurare.

Puteți seta manual locația fișierului de configurare (doar acesta va fi citit) cu ajutorul variabilei ENV P11NETHSM_CONFIG_FILE (de exemplu, P11NETHSM_CONFIG_FILE=./p11nethsm.conf).

Formatul fișierului de configurare¶

Configurația este formatată în 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

Instanțe¶

Dacă mai multe instanțe NetHSM sunt listate în același slot, aceste instanțe trebuie să fie configurate într-un cluster. Datele de identificare ale utilizatorilor și cheile trebuie să fie aceleași pe toate instanțele.

Modulul va utiliza instanțele în mod circular, încercând o altă instanță în cazul în care una dintre ele eșuează.

Fiabilitatea rețelei¶

Pentru a îmbunătăți fiabilitatea modulului PKCS#11, este posibil să se configureze timeout-uri, reintrări, redundanță de instanță și TCP keepalives.

Retries¶

În cazul în care o instanță NetHSM este inaccesibilă, modulul PKCS#11 este capabil să încerce din nou să trimită cererea către alte instanțe sau către aceeași instanță (dacă și alte instanțe sunt inaccesibile). Este posibil să se introducă o întârziere între reintentări.

Instanțele care nu reușesc sunt marcate ca fiind inaccesibile și încercate din nou într-un fir de fundal, astfel încât acestea nu vor fi încercate decât dacă toate instanțele sunt inaccesibile
În cazul în care nu poate fi creat niciun fir de fundal (CKF_LIBRARY_CANT_CREATE_OS_THREADS), instanțele eșuate vor fi încercate în timpul operațiunilor normale, încetinind cererile. Pentru a minimiza acest lucru, astfel de verificări ale stării de sănătate „în linie” sunt limitate la timpi de expirare de 1 secundă și se pot încerca numai 3 verificări ale stării de sănătate pe cerere (aceasta este cea mai nefavorabilă situație care poate fi atinsă numai dacă un număr mare de instanțe eșuează).

Prin urmare:

Numărul maxim de cereri trimise pentru un apel API este: retries.count + 1 + 3
Durata maximă (în cel mai nefavorabil caz) înainte de atingerea timeout-ului pentru un apel API este: (retries.count + 1) * timeout_seconds + 3
Timpul maxim de așteptare pentru un apel de funcție PKCS#11 variază, deoarece unele funcții vor conduce la mai multe apeluri API în NetHSM.

TCP keepalive¶

Pentru a îmbunătăți performanța, conexiunile sunt menținute deschise cu instanțele NetHSM pentru a evita necesitatea redeschiderii acestora. Este posibil ca, într-o rețea cu un firewall, aceste conexiuni inactive să fie închise, ceea ce duce la expirarea timpului de așteptare pentru următoarea încercare de conectare. Pentru a preveni apariția timeout-urilor lente și pentru a detecta mai devreme dacă se întâmplă, este posibil să configurați TCP keepalives pentru acestea.

Utilizatori¶

Utilizatorii operator și administrator sunt opționali, dar modulul nu va porni dacă nu este configurat niciun utilizator. Astfel, puteți configura modulul doar cu un utilizator administrator, doar cu un utilizator operator sau cu ambii în același timp.

Atunci când cei doi utilizatori sunt setați, modulul va utiliza în mod implicit utilizatorul operator și va folosi utilizatorul administrator numai atunci când acțiunea are nevoie de el.

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

Parole¶

Parola poate fi furnizată prin mai multe mijloace:

În text simplu în configurația password: "mypassword"
Într-o variabilă de mediu citită de modulul cu prefixul env:: env:ENV_STORING_THE_PASSWORD
Prin intermediul funcției de conectare a pkcs11, exemplu pentru pcks11-tool: pkcs11-tool --module libnethsm_pkcs11.so -p opPassphrase Pentru a furniza parola de administrator, trebuie să folosiți în schimb --so-pin: pkcs11-tool --module libnethsm_pkcs11.so --login --login-type so --so-pin Administrator

În cazul în care parola unui utilizator nu este setată în fișierul de configurare, va fi necesară o autentificare pentru a furniza parola (a treia metodă).

Un NetHSM care nu este operațional este considerat ca fiind un slot în care simbolul nu este prezent.