Impostazione PKCS#11¶

Installazione¶

È possibile ottenere il modulo NetHSM PKCS#11 come binario precompilato o compilarlo dai sorgenti.

Binari precompilati¶

Scaricare il file del modulo corrispondente al proprio sistema dalla pagina releases del repository.
Copiare il file del modulo nella directory in cui le applicazioni PKCS#11 si aspettano di trovarlo.

Compilazione da sorgente¶

Installare la toolchain di Rust.
Scaricare ed estrarre il sorgente dalla pagina dei rilasci di ` <https://github.com/Nitrokey/nethsm-pkcs11/releases>`__ o clonare il repository ` <https://github.com/Nitrokey/nethsm-pkcs11>`__.
Eseguire cargo build --release nella directory dei sorgenti.

Configurazione¶

Per impostazione predefinita, il modulo cerca i file di configurazione in:

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

Se sono presenti più file, le configurazioni saranno unite in modo che gli slot di tutti i file di configurazione siano utilizzati dal modulo.

È possibile impostare manualmente il percorso del file di configurazione (solo questo verrà letto) con la variabile env P11NETHSM_CONFIG_FILE (ad esempio P11NETHSM_CONFIG_FILE=./p11nethsm.conf).

Formato del file di configurazione¶

La configurazione è formattata in 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

Istanze¶

Se più istanze NetHSM sono elencate nello stesso slot, queste istanze devono essere configurate in un cluster. Le credenziali degli utenti e le chiavi devono essere le stesse su tutte le istanze.

Il modulo utilizzerà le istanze in modo round-robin, provando un’altra istanza se una fallisce.

Affidabilità della rete¶

Per migliorare l’affidabilità del modulo PKCS#11, è possibile configurare timeout, retry, ridondanza delle istanze e keepalive TCP.

Retries¶

Se un’istanza di NetHSM non è raggiungibile, il modulo PKCS#11 è in grado di riprovare a inviare la richiesta ad altre istanze o alla stessa istanza (se anche altre istanze non sono raggiungibili). È possibile introdurre un ritardo tra i tentativi.

Le istanze che falliscono sono contrassegnate come irraggiungibili e ritentate in un thread in background, quindi non saranno tentate a meno che tutte le istanze non siano irraggiungibili.
Se non è possibile generare un thread in background (CKF_LIBRARY_CANT_CREATE_OS_THREADS), le istanze non funzionanti saranno tentate durante le normali operazioni, rallentando le richieste. Per ridurre al minimo questo problema, i controlli di salute «in linea» sono limitati a timeout di 1 secondo e possono essere tentati solo 3 controlli di salute per richiesta (questa è la situazione peggiore, che può essere raggiunta solo se un gran numero di istanze fallisce).

Pertanto:

Il numero massimo di richieste inviate per una chiamata API è: retries.count + 1 + 3
La durata massima (nel caso peggiore) prima di raggiungere il timeout per una chiamata API è: (retries.count + 1) * timeout_seconds + 3
Il timeout massimo per una chiamata di funzione PKCS#11 può variare perché alcune funzioni portano a più chiamate API nel NetHSM.

TCP keepalive¶

Per migliorare le prestazioni, le connessioni vengono mantenute aperte con le istanze di NetHSM per evitare di doverle riaprire. È possibile che in una rete con un firewall queste connessioni inattive vengano chiuse, causando il timeout del tentativo di connessione successivo. Per evitare che si verifichino timeout lenti e per rilevarli prima, è possibile configurare dei keepalive TCP per queste connessioni.

Utenti¶

Gli utenti operatore e amministratore sono entrambi opzionali, ma il modulo non si avvia se non è configurato alcun utente. In questo modo è possibile configurare il modulo solo con un utente amministratore, solo con un utente operatore o con entrambi contemporaneamente.

Una volta impostati i due utenti, il modulo utilizzerà l’operatore per impostazione predefinita e utilizzerà l’utente amministratore solo quando l’azione lo richiede.

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

Password¶

La password può essere fornita in diversi modi:

In testo semplice nella configurazione password: "mypassword"
In una variabile d’ambiente letta dal modulo con il prefisso env:: env:ENV_STORING_THE_PASSWORD
Tramite la funzione di login di pkcs11, ad esempio per pcks11-tool: pkcs11-tool --module libnethsm_pkcs11.so -p opPassphrase Per fornire la password di amministrazione è necessario usare --so-pin invece: pkcs11-tool --module libnethsm_pkcs11.so --login --login-type so --so-pin Administrator

Se la password di un utente non è impostata nel file di configurazione, verrà richiesto un login per fornire la password (terzo metodo).

Un NetHSM non operativo è considerato uno slot con il token non presente.