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
# 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.
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.
L’utente PKCS11 regolare è mappato sull’operatore NetHSM e l’SO PKCS11 è mappato sull’amministratore NetHSM.
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.