Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

nethsm: Update pkcs11 example documentation #215

Merged
merged 2 commits into from
Jan 24, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
102 changes: 68 additions & 34 deletions nethsm/pkcs11-setup.rst
Original file line number Diff line number Diff line change
@@ -43,40 +43,74 @@ The configuration is yaml-formatted:
.. tab:: All platforms
.. code-block:: 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

# You can set the log file location here.
# If no value is set the module will output to stderr.
# If a value is set it will output to the file.
log_file: /tmp/p11nethsm.log
# Optional log level
log_level: Debug

# Each "slot" represents a NetHSM server
slots:
- label: LocalHSM # Name you NetHSM however you want
description: Local HSM (docker) # Optional description

# Users connecting to the NetHSM server
operator:
username: "operator"
password: "env:LOCALHSMPASS"
administrator:
username: "admin"

# List the NetHSM instances
instances:
- url: "https://keyfender:8443/api/v1" # URL to reach the server
# When the NetHSM has a self-signed certificate, it can be verified by a 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.
# However, this should be avoided if possible and certainly not used with a productive NetHSM.
# danger_insecure_cert: true
# 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
# 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


Instances