PKCS#11 sąranka#

Įrengimas#

NetHSM PKCS#11 modulį galite gauti kaip iš anksto parengtą dvejetainį paketą arba kompiliuoti jį iš pradinio kodo.

Iš anksto parengtos dvejetainės programos#

  1. Atsisiųskite jūsų sistemą atitinkantį modulio failą iš leidinių puslapio saugyklos.

  2. Nukopijuokite modulio failą į katalogą, kuriame jūsų PKCS#11 programos tikisi jį rasti.

Kompiliuoti iš šaltinio#

  1. Įdiekite Rust įrankių grandinę.

  2. Atsisiųskite ir išskleiskite šaltinį iš leidinių puslapio arba klonuokite saugyklą.

  3. Paleiskite cargo build --release šaltinio kataloge.

Konfigūracija#

Pagal numatytuosius nustatymus modulis ieško konfigūracijos failų:

  • /etc/nitrokey/p11nethsm.conf

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

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

Jei yra keli failai, konfigūracijos bus sujungtos taip, kad modulis naudotų visų konfigūracijos failų lizdus.

Konfigūracijos failo vietą (bus skaitomas tik šis failas) galite nustatyti rankiniu būdu, naudodami env kintamąjį P11NETHSM_CONFIG_FILE (pvz., P11NETHSM_CONFIG_FILE=./p11nethsm.conf).

Konfigūracijos failo formatas#

Konfigūracija yra yaml formato:

# 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

Atvejai#

Jei tame pačiame lizde yra keli NetHSM egzemplioriai, šie egzemplioriai turi būti sukonfigūruoti kaip klasteris. Naudotojų įgaliojimai ir raktai turi būti vienodi visuose egzemplioriuose.

Modulis naudoja egzempliorius rato principu, o nepavykus vienam egzemplioriui, bando naudoti kitą egzempliorių.

Tinklo patikimumas#

Siekiant padidinti PKCS#11 modulio patikimumą, galima konfigūruoti laiko limitus, pakartotinius bandymus, egzempliorių perteklių ir TCP nuolatinį palaikymą.

Retries#

Jei „NetHSM“ egzempliorius nepasiekiamas, PKCS#11 modulis gali pakartotinai siųsti užklausą kitiems egzemplioriams arba tam pačiam egzemplioriui (jei kiti egzemplioriai taip pat nepasiekiami). Galima nustatyti vėlavimą tarp pakartotinių bandymų.

  • Nepavykę egzemplioriai pažymimi kaip nepasiekiami ir pakartotinai bandomi fone, todėl jie nebus bandomi, nebent visi egzemplioriai būtų nepasiekiami.

  • Jei fono gija negali būti sukurta (CKF_LIBRARY_CANT_CREATE_OS_THREADS), nepavykę egzemplioriai bus bandomi įprastinių operacijų metu, o tai sulėtins užklausas. Siekiant tai sumažinti, tokie „inline“ sveikatos patikrinimai yra apriboti iki 1 sekundės laiko, o per vieną užklausą galima bandyti atlikti tik 3 sveikatos patikrinimus (tai blogiausias atvejis, kuris gali būti pasiektas tik tuo atveju, jei nepavyko daug egzempliorių).

Todėl:

  • Didžiausias vienam API skambučiui siunčiamų užklausų skaičius yra: retries.count + 1 + 3

  • Didžiausia (blogiausiu atveju) trukmė iki vieno API skambučio pabaigos yra: (retries.count + 1) * timeout_seconds + 3

  • Maksimalus vienos PKCS#11 funkcijos iškvietimo laikas gali skirtis, nes kai kurios funkcijos sukelia kelis API iškvietimus NetHSM.

TCP keepalive#

Siekiant pagerinti našumą, ryšiai su „NetHSM“ egzemplioriais laikomi atviri, kad nereikėtų jų iš naujo atidarinėti. Gali būti, kad tinkle, kuriame yra ugniasienė, šie neveikiantys ryšiai gali būti uždaryti, dėl to kitas bandymas prisijungti užtruks. Siekiant išvengti lėto išsikrovimo ir anksčiau aptikti, jei taip atsitiktų, galima sukonfigūruoti TCP keepalives (nuolatinį TCP palaikymą).

Vartotojai#

Operatoriaus ir administratoriaus naudotojai yra neprivalomi, tačiau modulis neįsijungs, jei nėra sukonfigūruoto naudotojo. Taip yra todėl, kad modulį galima konfigūruoti tik su administratoriaus naudotoju, tik su operatoriaus naudotoju arba su abiem vienu metu.

Nustačius du naudotojus, modulis pagal nutylėjimą naudos operatoriaus naudotoją, o administratoriaus naudotoją naudos tik tada, kai to reikės veiksmui atlikti.

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

Slaptažodžiai#

Slaptažodį galima nurodyti keliais būdais:

  • Paprastu tekstu konfigūracijoje password: "mypassword"

  • Aplinkos kintamajame, kurį nuskaito modulis su priešdėliu env:: env:ENV_STORING_THE_PASSWORD

  • Per pkcs11 prisijungimo funkciją, pcks11-tool pavyzdys: pkcs11-tool –module libnethsm_pkcs11.so -p opPassphrase ` Norint nurodyti administratoriaus slaptažodį, vietoj jo reikia naudoti --so-pin: pkcs11-tool --module libnethsm_pkcs11.so --login --login-type so --so-pin Administrator

Jei naudotojo slaptažodis nenustatytas konfigūracijos faile, slaptažodžiui nurodyti reikės prisijungti (3-iasis metodas).

Neveikiantis NetHSM laikomas lizdu, kuriame nėra žetono.