PKCS#11-opsætning

Installation

Du kan enten hente NetHSM PKCS#11-modulet som en præ-kompileret binær fil eller kompilere det fra kildekoden.

Forkompilerede binære filer

  1. Download den modulfil, der passer til dit system, fra releases page i repository’et.

  2. Kopier modulfilen til den mappe, hvor dine PKCS#11-programmer forventer at finde den.

Kompilér fra kilde

  1. Installer Rust toolchain.

  2. Download og udpak kilden fra releases page eller klon repository.

  3. Kør cargo build --release i kildemappen.

Konfiguration

Som standard søger modulet efter konfigurationsfiler i:

  • /etc/nitrokey/p11nethsm.conf

  • /usr/local/etc/nitrokey/p11nethsm.conf

  • $HOME/.config/nitrokey/p11nethsm.conf

Hvis der findes flere filer, vil konfigurationerne blive flettet sammen, så modulet bruger alle slots i konfigurationsfilerne.

Du kan manuelt angive placeringen af konfigurationsfilen (kun denne vil blive læst) med env-variablen P11NETHSM_CONFIG_FILE (f.eks. P11NETHSM_CONFIG_FILE=./p11nethsm.conf).

Format for konfigurationsfil

Konfigurationen er yaml-formateret:

# 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

Forekomster

Hvis der vises flere NetHSM-instanser i samme slot, skal disse instanser konfigureres i en klynge. Brugernes legitimationsoplysninger og nøglerne skal være de samme på alle instanser.

Modulet vil bruge instanserne på en round-robin måde og prøve en anden instans, hvis en fejler.

Netværkets pålidelighed

For at forbedre pålideligheden af PKCS#11-modulet er det muligt at konfigurere timeouts, retries, instance redundancy og TCP keepalives.

Retries

Hvis en NetHSM-instans ikke kan nås, er PKCS#11-modulet i stand til at forsøge at sende anmodningen til andre instanser eller til den samme instans (hvis andre instanser heller ikke kan nås). Det er muligt at indføre en forsinkelse mellem gentagne forsøg.

  • Fejlende instanser markeres som utilgængelige og forsøges igen i en baggrundstråd, så de ikke forsøges, medmindre alle instanser er utilgængelige.

  • Hvis der ikke kan oprettes en baggrundstråd (CKF_LIBRARY_CANT_CREATE_OS_THREADS), vil mislykkede instanser blive forsøgt under normal drift, hvilket gør forespørgslerne langsommere. For at minimere dette er sådanne »inline« sundhedstjek begrænset til timeouts på 1 sekund, og der kan kun forsøges 3 sundhedstjek pr. anmodning (dette er en worst case-situation, som kun kan nås, hvis et stort antal instanser fejler).

Derfor:

  • Det maksimale antal anmodninger, der sendes for et API-kald, er: retries.count + 1 + 3

  • Den maksimale (worst case) varighed, før timeout nås for et API-kald, er: (retries.count + 1) * timeout_seconds + 3

  • Den maksimale timeout for et PKCS#11-funktionskald vil variere, fordi nogle funktioner vil føre til flere API-kald i NetHSM.

TCP keepalive

For at forbedre ydeevnen holdes forbindelser åbne med NetHSM-instanserne for at undgå behovet for at genåbne dem. Det er muligt, at disse inaktive forbindelser i et netværk med en firewall kan blive lukket, hvilket fører til, at det næste forbindelsesforsøg går i stå. For at forhindre langsomme timeouts og for at opdage det tidligere, hvis det sker, er det muligt at konfigurere TCP keepalives for disse.

Brugere

Operatør- og administratorbrugerne er begge valgfrie, men modulet starter ikke, hvis der ikke er konfigureret en bruger. Det er, så du kan konfigurere modulet med kun en administratorbruger, kun en operatørbruger eller begge på samme tid.

Når de to brugere er indstillet, vil modulet som standard bruge operatøren og kun bruge administratorbrugeren, når handlingen har brug for det.

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

Adgangskoder

Adgangskoden kan angives på flere måder:

  • I almindelig tekst i konfigurationen password: "mypassword"

  • I en miljøvariabel læst af modulet med præfikset env:: env:ENV_STORING_THE_PASSWORD

  • Via login-funktionen i pkcs11, eksempel for pcks11-tool: pkcs11-tool --module libnethsm_pkcs11.so -p opPassphrase For at angive administratoradgangskoden skal du bruge --so-pin i stedet: pkcs11-tool --module libnethsm_pkcs11.so --login --login-type so --so-pin Administrator

Hvis en brugers adgangskode ikke er angivet i konfigurationsfilen, kræves der et login for at angive adgangskoden (3. metode).

En NetHSM, der ikke er i drift, betragtes som et slot, hvor tokenet ikke er til stede.