PKCS#11 instellen¶

Installatie¶

Je kunt de NetHSM PKCS#11 module als een voorgecompileerde binary krijgen of deze vanaf de broncode compileren.

Voorgecompileerde binaries¶

Download het modulebestand dat overeenkomt met uw systeem van de releases pagina van de repository.
Kopieer het modulebestand naar de map waar uw PKCS#11 toepassingen het verwachten te vinden.

Van bron compileren¶

Installeer de Rust toolchain.
Download en pak de broncode uit van de releases pagina of kloon de repository.
Voer cargo build --release uit in de brondirectory.

Configuratie¶

Standaard zoekt de module naar configuratiebestanden in:

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

Als er meerdere bestanden aanwezig zijn, worden de configuraties samengevoegd zodat de sleuven van alle configuratiebestanden door de module worden gebruikt.

Je kunt de locatie van het configuratiebestand handmatig instellen (alleen deze wordt gelezen) met de env variabele P11NETHSM_CONFIG_FILE (bijvoorbeeld P11NETHSM_CONFIG_FILE=./p11nethsm.conf).

Formaat configuratiebestand¶

De configuratie is yaml-geformatteerd:

# 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

Instanties¶

Als er meerdere NetHSM-instanties in hetzelfde slot staan, moeten deze instanties in een cluster worden geconfigureerd. De referenties van de gebruikers en de sleutels moeten hetzelfde zijn op alle instanties.

De module zal de instanties op een “round-robin” manier gebruiken, waarbij een andere instantie wordt geprobeerd als er één faalt.

Netwerkbetrouwbaarheid¶

Om de betrouwbaarheid van de PKCS#11 module te verbeteren, is het mogelijk om timeouts, retries, instance redundancy en TCP keepalives te configureren.

Retries¶

Als een NetHSM instantie onbereikbaar is, kan de PKCS#11 module opnieuw proberen het verzoek naar andere instanties te sturen, of naar dezelfde instantie (als andere instanties ook onbereikbaar zijn). Het is mogelijk om een vertraging in te voeren tussen de pogingen.

Mislukte instanties worden gemarkeerd als onbereikbaar en opnieuw geprobeerd in een thread op de achtergrond, dus ze worden niet geprobeerd tenzij alle instanties onbereikbaar zijn.
Als er geen achtergrond thread kan worden gespawned (CKF_LIBRARY_CANT_CREATE_OS_THREADS), zullen mislukte instanties worden geprobeerd tijdens normale operaties, wat de aanvragen vertraagt. Om dit te minimaliseren zijn dergelijke “inline” gezondheidscontroles beperkt tot timeouts van 1 seconde en kunnen er slechts 3 gezondheidscontroles per aanvraag worden uitgevoerd (dit is een worst case situatie die alleen kan worden bereikt als een groot aantal instanties faalt).

Daarom:

Het maximum aantal verzonden verzoeken voor één API-aanroep is: retries.count + 1 + 3
De maximale (slechtst denkbare) duur voordat de time-out voor een API-aanroep wordt bereikt is: (retries.count + 1) * timeout_seconds + 3
De maximale time-out voor één PKCS#11 functie-aanroep varieert omdat sommige functies leiden tot meerdere API-aanroepen in de NetHSM.

TCP keepalive¶

Om de prestaties te verbeteren worden verbindingen met de NetHSM instanties open gehouden om te voorkomen dat ze opnieuw geopend moeten worden. Het is mogelijk dat in een netwerk met een firewall deze inactieve verbindingen gesloten worden, waardoor de volgende verbindingspoging een timeout krijgt. Om langzame timeouts te voorkomen, en om ze eerder te detecteren als dat toch gebeurt, is het mogelijk om TCP keepalives hiervoor te configureren.

Gebruikers¶

De operator en administrator gebruikers zijn beide optioneel, maar de module zal niet opstarten als er geen gebruiker is geconfigureerd. Dit is zodat je de module kunt configureren met alleen een administrator gebruiker, alleen een operator gebruiker of beide tegelijk.

Als de twee gebruikers zijn ingesteld, gebruikt de module standaard de operator en alleen de administrator gebruiker als de actie dat nodig heeft.

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

Wachtwoorden¶

Het wachtwoord kan op verschillende manieren worden gegeven:

In platte tekst in de configuratie password: "mypassword"
In een omgevingsvariabele die wordt gelezen door de module met het voorvoegsel env:: env:ENV_STORING_THE_PASSWORD
Via de inlogfunctie van pkcs11, voorbeeld voor pcks11-tool: pkcs11-tool --module libnethsm_pkcs11.so -p opPassphrase Om het beheerderswachtwoord op te geven moet je in plaats daarvan --so-pin gebruiken: pkcs11-tool --module libnethsm_pkcs11.so --login --login-type so --so-pin Administrator

Als het wachtwoord van een gebruiker niet is ingesteld in het configuratiebestand, moet er worden ingelogd om het wachtwoord op te geven (3e methode).

Een NetHSM die niet operationeel is, wordt beschouwd als een slot waarin het token niet aanwezig is.