Configuración PKCS#11¶

Instalación¶

Puede obtener el módulo NetHSM PKCS#11 como un binario precompilado o compilarlo desde el código fuente.

Binarios precompilados¶

Descargue el archivo del módulo correspondiente a su sistema desde la página de versiones del repositorio.
Copie el archivo del módulo en el directorio donde sus aplicaciones PKCS#11 esperan encontrarlo.

Compilar desde el código fuente¶

Instale la cadena de herramientas Rust.
Descargue y extraiga el código fuente de la página de versiones o clone el repositorio.
Ejecute cargo build --release en el directorio fuente.

Configuración¶

Por defecto, el módulo busca los archivos de configuración en:

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

Si hay varios archivos, las configuraciones se fusionarán para que el módulo utilice las ranuras de todos los archivos de configuración.

Puede establecer manualmente la ubicación del archivo de configuración (sólo se leerá éste) con la variable env P11NETHSM_CONFIG_FILE (por ejemplo, P11NETHSM_CONFIG_FILE=./p11nethsm.conf).

Formato del archivo de configuración¶

La configuración tiene formato 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

Instancias¶

Si aparecen varias instancias de NetHSM en la misma ranura, estas instancias deben configurarse en un clúster. Las credenciales de los usuarios y las claves deben ser las mismas en todas las instancias.

El módulo utilizará las instancias de forma rotatoria, probando con otra instancia si una falla.

Fiabilidad de la red¶

Para mejorar la fiabilidad del módulo PKCS#11, es posible configurar tiempos de espera, reintentos, redundancia de instancias y keepalives TCP.

Reintentos¶

Si no se puede acceder a una instancia de NetHSM, el módulo PKCS#11 puede reintentar enviar la solicitud a otras instancias o a la misma instancia (si tampoco se puede acceder a otras instancias). Es posible introducir un retardo entre los reintentos.

Las instancias que fallan se marcan como inalcanzables y se vuelven a intentar en un subproceso en segundo plano, por lo que no se intentarán a menos que todas las instancias sean inalcanzables.
Si no se puede generar ningún subproceso en segundo plano (CKF_LIBRARY_CANT_CREATE_OS_THREADS), las instancias fallidas se intentarán durante las operaciones normales, ralentizando las peticiones. Para minimizar esto, estas comprobaciones de estado «en línea» están limitadas a tiempos de espera de 1 segundo, y sólo se pueden intentar 3 comprobaciones de estado por petición (ésta es la peor situación posible que sólo se puede alcanzar si falla un gran número de instancias).

Por lo tanto:

El número máximo de solicitudes enviadas para una llamada a la API es: retries.count + 1 + 3
La duración máxima (en el peor de los casos) antes de alcanzar el tiempo de espera para una llamada a la API es: (retries.count + 1) * timeout_seconds + 3
El tiempo máximo de espera para una llamada a una función PKCS#11 variará porque algunas funciones darán lugar a varias llamadas a la API en NetHSM.

TCP keepalive¶

Para mejorar el rendimiento, las conexiones se mantienen abiertas con las instancias de NetHSM para evitar la necesidad de reabrirlas. Es posible que en una red con cortafuegos, estas conexiones inactivas se cierren, provocando que el siguiente intento de conexión agote el tiempo de espera. Para evitar que se produzcan timeouts lentos, y para detectar antes si se producen, es posible configurar TCP keepalives para estos.

Usuarios¶

Los usuarios operador y administrador son opcionales, pero el módulo no se iniciará si no hay ningún usuario configurado. Esto es para que puedas configurar el módulo sólo con un usuario administrador, sólo con un usuario operador o con ambos a la vez.

Cuando se establecen los dos usuarios el módulo utilizará por defecto el usuario operador y sólo utilizará el usuario administrador cuando la acción lo necesite.

El usuario PKCS#11 normal se asigna al operador de NetHSM y el usuario PKCS#11 SO se asigna al administrador de NetHSM.

Contraseñas¶

La contraseña puede facilitarse por múltiples medios:

En texto plano en la configuración password: "mypassword"
En una variable de entorno leída por el módulo con el prefijo env:: env:ENV_STORING_THE_PASSWORD
A través de la función login de pkcs11, ejemplo para pcks11-tool: pkcs11-tool --module libnethsm_pkcs11.so -p opPassphrase Para proporcionar la contraseña de administrador es necesario utilizar --so-pin en su lugar: pkcs11-tool --module libnethsm_pkcs11.so --login --login-type so --so-pin Administrator

Si la contraseña de un usuario no está establecida en el archivo de configuración, se requerirá un login para proporcionar la contraseña (3er método).

Una NetHSM que no está operativa se considera una ranura con el token no presente.