Configuration PKCS#11¶

Installation¶

Vous pouvez obtenir le module PKCS#11 de NetHSM sous la forme d’un binaire précompilé ou le compiler à partir des sources.

Binaires précompilés¶

Téléchargez le fichier du module correspondant à votre système à partir de la page releases du référentiel.
Copiez le fichier du module dans le répertoire où vos applications PKCS#11 s’attendent à le trouver.

Compilation à partir de la source¶

Installer la chaîne d’outils Rust.
Téléchargez et extrayez les sources à partir de la page releases ou clonez le dépôt.
Exécutez cargo build --release dans le répertoire source.

Configuration¶

Par défaut, le module recherche les fichiers de configuration dans :

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

Si plusieurs fichiers sont présents, les configurations seront fusionnées de manière à ce que les emplacements de tous les fichiers de configuration soient utilisés par le module.

Vous pouvez définir manuellement l’emplacement du fichier de configuration (seul celui-ci sera lu) avec la variable env P11NETHSM_CONFIG_FILE (par exemple P11NETHSM_CONFIG_FILE=./p11nethsm.conf).

Format du fichier de configuration¶

La configuration est formatée en 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

Instances¶

Si plusieurs instances NetHSM sont répertoriées dans le même emplacement, ces instances doivent être configurées dans un cluster. Les informations d’identification des utilisateurs et les clés doivent être identiques sur toutes les instances.

Le module utilisera les instances de manière rotative, en essayant une autre instance si l’une d’entre elles échoue.

Fiabilité du réseau¶

Pour améliorer la fiabilité du module PKCS#11, il est possible de configurer des timeouts, des retries, des redondances d’instances et des keepalives TCP.

Retries¶

Si une instance NetHSM est inaccessible, le module PKCS#11 est capable de réessayer d’envoyer la demande à d’autres instances, ou à la même instance (si d’autres instances sont également inaccessibles). Il est possible d’introduire un délai entre les tentatives.

Les instances qui échouent sont marquées comme inaccessibles et relancées dans un thread d’arrière-plan, de sorte qu’elles ne seront pas essayées à moins que toutes les instances ne soient inaccessibles.
Si aucun thread d’arrière-plan ne peut être créé (CKF_LIBRARY_CANT_CREATE_OS_THREADS), les instances défaillantes seront essayées pendant les opérations normales, ce qui ralentira les requêtes. Pour minimiser ce problème, de tels contrôles de santé « en ligne » sont limités à des délais de 1 seconde, et seulement 3 contrôles de santé peuvent être tentés par requête (il s’agit d’une situation de pire cas qui ne peut être atteinte que si un grand nombre d’instances échouent).

C’est pourquoi :

Le nombre maximum de requêtes envoyées pour un appel API est le suivant : retries.count + 1 + 3
La durée maximale (dans le pire des cas) avant d’atteindre le délai d’attente pour un appel à l’API est : (retries.count + 1) * timeout_seconds + 3
Le délai maximum pour un appel de fonction PKCS#11 varie car certaines fonctions conduisent à plusieurs appels d’API dans le NetHSM.

TCP keepalive¶

Pour améliorer les performances, les connexions sont maintenues ouvertes avec les instances de NetHSM afin d’éviter de devoir les rouvrir. Il est possible que, dans un réseau doté d’un pare-feu, ces connexions inactives soient fermées, ce qui entraîne un dépassement du délai de la prochaine tentative de connexion. Afin d’éviter les dépassements de délai et de les détecter plus rapidement, il est possible de configurer des keepalives TCP pour ces connexions.

Utilisateurs¶

Les utilisateurs opérateur et administrateur sont tous deux facultatifs, mais le module ne démarrera pas si aucun utilisateur n’est configuré. Vous pouvez ainsi configurer le module avec un seul utilisateur administrateur, un seul utilisateur opérateur ou les deux à la fois.

Lorsque les deux utilisateurs sont définis, le module utilise l’opérateur par défaut et n’utilise l’administrateur que lorsque l’action le nécessite.

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

Mots de passe¶

Le mot de passe peut être fourni par plusieurs moyens :

En texte clair dans la configuration password: "mypassword"
Dans une variable d’environnement lue par le module avec le préfixe env: : env:ENV_STORING_THE_PASSWORD
Via la fonction login de pkcs11, exemple pour pcks11-tool : pkcs11-tool --module libnethsm_pkcs11.so -p opPassphrase Pour fournir le mot de passe administrateur, vous devez utiliser --so-pin à la place : pkcs11-tool --module libnethsm_pkcs11.so --login --login-type so --so-pin Administrator

Si le mot de passe d’un utilisateur n’est pas défini dans le fichier de configuration, une connexion sera requise pour fournir le mot de passe (3ème méthode).

Un NetHSM qui n’est pas opérationnel est considéré comme un slot dont le jeton n’est pas présent.