Ρύθμιση PKCS#11¶

Εγκατάσταση¶

Μπορείτε είτε να λάβετε την ενότητα NetHSM PKCS#11 ως προμεταγλωττισμένο δυαδικό αρχείο είτε να τη μεταγλωττίσετε από τον πηγαίο κώδικα.

Προμεταγλωττισμένα δυαδικά αρχεία¶

Κατεβάστε το αρχείο της ενότητας που αντιστοιχεί στο σύστημά σας από τη σελίδα releases του αποθετηρίου.
Αντιγράψτε το αρχείο της ενότητας στον κατάλογο όπου οι εφαρμογές PKCS#11 περιμένουν να το βρουν.

Μεταγλώττιση από την πηγή¶

Εγκαταστήστε το Rust toolchain.
Κατεβάστε και εξάγετε τον πηγαίο κώδικα από τη σελίδα releases ή κλωνοποιήστε το αποθετήριο ` <https://github.com/Nitrokey/nethsm-pkcs11>`__.
Εκτελέστε το cargo build --release στον κατάλογο πηγής.

Διαμόρφωση¶

Από προεπιλογή, η ενότητα αναζητά αρχεία ρυθμίσεων στο:

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

Αν υπάρχουν πολλά αρχεία, οι ρυθμίσεις θα συγχωνευθούν έτσι ώστε οι θέσεις όλων των αρχείων ρυθμίσεων να χρησιμοποιηθούν από την ενότητα.

Μπορείτε να ορίσετε χειροκίνητα τη θέση του αρχείου ρυθμίσεων (μόνο αυτό θα διαβαστεί) με τη μεταβλητή env P11NETHSM_CONFIG_FILE (π.χ. P11NETHSM_CONFIG_FILE=./p11nethsm.conf).

Μορφή αρχείου διαμόρφωσης¶

Η διαμόρφωση είναι σε μορφή 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

Περιπτώσεις¶

Εάν στην ίδια υποδοχή αναφέρονται πολλές περιπτώσεις NetHSM, οι εν λόγω περιπτώσεις πρέπει να διαμορφωθούν σε συστάδα. Τα διαπιστευτήρια των χρηστών και τα κλειδιά πρέπει να είναι τα ίδια σε όλες τις περιπτώσεις.

Η ενότητα θα χρησιμοποιήσει τις περιπτώσεις με κυκλικό τρόπο, δοκιμάζοντας μια άλλη περίπτωση αν αποτύχει μία.

Αξιοπιστία δικτύου¶

Για να βελτιωθεί η αξιοπιστία της ενότητας PKCS#11, είναι δυνατή η ρύθμιση των χρονικών ορίων, των επαναλήψεων, του πλεονασμού των περιπτώσεων και των παραμέτρων TCP keepalives.

Retries¶

Εάν μια περίπτωση NetHSM δεν είναι προσβάσιμη, η ενότητα PKCS#11 είναι σε θέση να επαναλάβει την αποστολή της αίτησης σε άλλες περιπτώσεις ή στην ίδια περίπτωση (εάν και άλλες περιπτώσεις δεν είναι προσβάσιμες). Είναι δυνατόν να εισαχθεί μια καθυστέρηση μεταξύ των επαναληπτικών προσπαθειών.

Οι περιπτώσεις που αποτυγχάνουν χαρακτηρίζονται ως μη προσβάσιμες και δοκιμάζονται εκ νέου σε ένα νήμα στο παρασκήνιο, οπότε δεν θα δοκιμάζονται, εκτός εάν όλες οι περιπτώσεις είναι μη προσβάσιμες.
Εάν δεν μπορεί να δημιουργηθεί νήμα παρασκηνίου (CKF_LIBRARY_CANT_CREATE_OS_THREADS), οι αποτυχημένες περιπτώσεις θα προσπαθούν να δημιουργηθούν κατά τη διάρκεια των κανονικών λειτουργιών, επιβραδύνοντας τις αιτήσεις. Για να ελαχιστοποιηθεί αυτό, τέτοιοι «inline» έλεγχοι υγείας περιορίζονται σε χρονικά όρια 1 δευτερολέπτου και μόνο 3 έλεγχοι υγείας μπορούν να επιχειρηθούν ανά αίτηση (αυτή είναι η χειρότερη περίπτωση που μπορεί να επιτευχθεί μόνο αν αποτύχει μεγάλος αριθμός περιπτώσεων).

Επομένως:

Ο μέγιστος αριθμός αιτήσεων που αποστέλλονται για μία κλήση API είναι: retries.count + 1 + 3
Η μέγιστη διάρκεια (στη χειρότερη περίπτωση) πριν από την επίτευξη του χρονικού ορίου για μία κλήση API είναι: (retries.count + 1) * timeout_seconds + 3
Το μέγιστο χρονικό όριο για μια κλήση συνάρτησης PKCS#11 ποικίλλει, επειδή ορισμένες λειτουργίες οδηγούν σε πολλαπλές κλήσεις API στο NetHSM.

TCP keepalive¶

Για τη βελτίωση των επιδόσεων, οι συνδέσεις διατηρούνται ανοικτές με τις περιπτώσεις NetHSM, ώστε να αποφεύγεται η ανάγκη επαναλειτουργίας τους. Είναι πιθανό σε ένα δίκτυο με τείχος προστασίας, αυτές οι αδρανείς συνδέσεις να κλείσουν, με αποτέλεσμα η επόμενη προσπάθεια σύνδεσης να έχει χρονικό όριο. Για να αποτρέψετε την αργή χρονοκαθυστέρηση και για να την εντοπίσετε νωρίτερα αν συμβεί, είναι δυνατή η ρύθμιση των παραμέτρων TCP keepalives για αυτές.

Χρήστες¶

Οι χρήστες χειριστής και διαχειριστής είναι προαιρετικοί, αλλά η ενότητα δεν θα ξεκινήσει αν δεν έχει ρυθμιστεί κανένας χρήστης. Αυτό γίνεται για να μπορείτε να ρυθμίσετε τη μονάδα μόνο με χρήστη διαχειριστή, μόνο με χρήστη χειριστή ή και με τους δύο ταυτόχρονα.

Όταν οριστούν οι δύο χρήστες, η ενότητα θα χρησιμοποιεί τον χειριστή από προεπιλογή και θα χρησιμοποιεί τον χρήστη διαχειριστή μόνο όταν το χρειάζεται η ενέργεια.

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

Κωδικοί πρόσβασης¶

Ο κωδικός πρόσβασης μπορεί να παρέχεται με πολλαπλά μέσα:

Σε απλό κείμενο στη ρύθμιση παραμέτρων password: "mypassword"
Σε μια μεταβλητή περιβάλλοντος που διαβάζεται από την ενότητα με το πρόθεμα env:: env:ENV_STORING_THE_PASSWORD
Μέσω της λειτουργίας σύνδεσης του pkcs11, παράδειγμα για το pcks11-tool: pkcs11-tool --module libnethsm_pkcs11.so -p opPassphrase Για να δώσετε τον κωδικό πρόσβασης του διαχειριστή πρέπει να χρησιμοποιήσετε το --so-pin: pkcs11-tool --module libnethsm_pkcs11.so --login --login-type so --so-pin Administrator

Εάν ο κωδικός πρόσβασης ενός χρήστη δεν έχει οριστεί στο αρχείο ρυθμίσεων, θα απαιτηθεί σύνδεση για την παροχή του κωδικού πρόσβασης (3η μέθοδος).

Ένα NetHSM που δεν είναι λειτουργικό θεωρείται ως υποδοχή με το κουπόνι να μην υπάρχει.