Skip to main content

Configuration

The Primus PKCS#11 API provider has two main configuration files:

  • primus.cfg: Contains public settings, such as connectivity details (hostname, port) and partition names.
  • .secrets.cfg: Contains secret values, such as the permanent secret used to authenticate to the HSM.

To fully configure the Primus PKCS#11 API provider:

  1. First, adapt the configuration file primus.cfg as described below.
  2. When using a CloudHSM: configure the service proxy credentials.
  3. After that, establish HSM connectivity, fetching the HSM permanent secret using the ppin command line tool. This will write to the .secrets.cfg file.

Configuration File Locations​

primus.cfg (Unix)​

Possible configuration locations:

  1. /etc/primus/primus.cfg

    The primary location lookup when initializing the PKCS#11 library. The configuration file name is labeled 'primus.cfg', in lower case. When not found, the configuration initialization falls back to the fallback location. Initially the directory and files don't exist. Add the directory and copy the files from the fallback location and adjust the access rights. It is recommended to use the primary location.

  2. /usr/local/primus/etc/primus.cfg

    The fallback location1 lookup when initializing the PKCS#11 library. The configuration file name is labeled 'primus.cfg', in lower case. Note, that a provider update will overwrite the file!

  3. SECUROSYS_PKCS11_CONF

    The environment variable pointing to the fully qualified configuration file name. When set, the environment variable supersedes the primary and fallback configuration locations.

If the file cannot be located, the initialization fails and returns an initialization error.

.secrets.cfg (Unix)​

Possible configuration locations:

  1. /etc/primus/.secrets.cfg

    The primary location lookup when accessing the permanent secrets information. The file name is labelled '.secrets.cfg', in lower case. When not found, the initialization falls back to the fallback location.

    Initially the directory and file don't exist. Add the directory and copy the files from the fallback location and adjust the access rights. It is recommended to use the primary location.

  2. /usr/local/primus/etc/.secrets.cfg

    The fallback1 location lookup when accessing the permanent secrets information. The file name is labeled '.secrets.cfg', in lower case. Note, that a provider update will overwrite the file!

  3. SECUROSYS_SECRETS_CONF

    The environment variable pointing to the fully qualified permanent secrets file name. When set, the environment variable supersedes the primary and fallback configuration locations.

If the file cannot be located, the initialization fails and returns an initialization error.

"primus.cfg" Configuration File Parameters​

Configure your specific HSM connection details within the configuration file primus.cfg. Adapt the colored parameters according to your HSM setup (cluster configuration). Default HSM connection details (hostnames, ports) can be found at the bottom, if not provided by your security officer. For scenarios involving redundant HSMs, consult the section Clustered HSM Connection and Failover Mechanisms.

#-----------------------------
# Primus PKCS#11 configuration
#-----------------------------
version = "1.0";

/* This example configuration template contains 1 slot:                    */
/* hsm0: standalone hsm with one partition (slot id 0)                     */ 

/*--- GLOBAL CONFIGURATION SECTION ----------------------------------------*/
primus:
{
  wait_delay = 250; /* in ms*/
  wait_max_tries = 5;
  connect_on_init = true;

  /*--- HSM CONFIGURATION SECTION -----------------------------------------*/
  hsms:
  {
     /*--- HSM0, e.g. standalone hsm with one partition, slot id 0 */
     hsm0:
     {
        host = "HSM0_HostnameOrIpOrProxyURL";
        port = "2310";
        priority = 0; /* Optional priority. Default 0, which is highest priority */
        slots:
        {
           slot0:
           {
              client_id = "Client_ID0";
              user_name = "PARTITION_NAME0";
              id = 0;
           }; /* end slot0 */
        }; /* end slots */
     }; /* end hsm0 */
  }; /* end hsms */

  /*--- LOG CONFIGURATION SECTION -----------------------------------------*/
  log:
  {
#    file = "/tmp/primus.log";    /* optional for unix, logs to LOCAL1 syslog */
#    file = "%PUBLIC%\Securosys\Primus P11\primus.log";  /* for windows */
    write_log_file      = true;     /* write to log-file */
    write_syslog        = true;     /* write to syslog */
    trace_linenumber    = false;    /* true or false */
    trace_timestamp     = true;     /* true or false */
    trace_function      = true;     /* true or false */
    trace_inout         = false;    /* true or false */
    trace_pid           = true;     /* true or false */
    trace_filename      = false;    /* true or false */
    trace_mask          = 0x00;
    trace_level         = 4;        /* 0-7 log level details */
  }; /* end log */

}; /* end primus */

The version = "1.0"; line indicates the configuration file version. 3

The top-level primus:{ ... }; block contains the fields:

AttributesContent description
wait_delayDuration to wait when incomplete data received [ms]. (default: wait_delay = 250;)
wait_max_triesNumber of retry attempts when waiting for data completion and fallback3 to next cluster HSM (default: wait_max_tries = 5;).
net.ipv4.tcp_syn_retries is reduced (=2) via socket options to reduce failover times
connect_on_inittrue: Connection(s) to HSM(s) for a given slot is initiated on library initialization to minimize setup delays.
false: Establishes a connection to the HSM(s) upon opening the first session for a given slot. The connection is terminated once all sessions for that slot are closed.
(default: connect_on_init = true;)
For details see section Clustered HSM Connection and Failover Mechanisms.
hsmsList of HSMs, in hsms:{ ... }; block.

Section 'hsms'​

The hsmx:{ ... }; block contains the HSM connection and partition definitions, where x is indexed from 0..n.

AttributesContent description
hostThe hostname or IP address of the HSM or the service proxy, as a string.
e.g. host = "grimsel.securosys.ch"; or host = "82.197.162.10";
portThe port of the PKCS#11 API on the HSM or service proxy, as a string.
e.g. port = "2310";
priority4Optional setting that defines the selection priority among redundant HSMs. Lower values indicate higher priority. Random selection for equal priority.
Values: 0-127 (numerical), default: priority = 0; (highest priority).
For details see section Clustered HSM Connection and Failover Mechanisms.
pinOptional, not recommended: The setup password for the connection with the HSM. If present, the PKCS#11 Provider will use it to connect to the HSM partition. This setup password has a limited time validity. Use the 'ppin' utility to fetch the partition permanent secret.
slotsList of enumerated slots of the HSM.

Section slots5​

The slots:{ ... }; block contains sub-blocks slotx:{ ... }; which each define a slot (partition) with the following fields:

AttributesContent description
user_nameThe name of the HSM user (partition). It is assumed that identical user_names on same or different HSMs refer to a redundant partition (cluster), assigning automatically the same user credentials. Therefore not redundant partitions must have different partition names!
client_idAn ID string chosen by the client to identify itself or the application within the HSM logs. It is a part of the complete user Id received and logged on the HSM (partially hashed): client_id@hash(machine_name@ipd_address@mac_address)
e.g. client_id = "myApplication"; results in the HSM logs as myApplication@d1172dac ...
proxy_userCloudHSM only: the name of the service user (proxy), as provided by Securosys.
proxy_passwordCloudHSM only, optional (not recommended): the password for the service user (proxy). Use the ppin tool instead to store this in .secrets.cfg.
idPKCS#11 Slot ID assigned to the HSM partition (numerical), e.g. id = 0;
Assign same id for redundant partitions (HSM cluster).
Assign different id for non-redundant different partitions(s).

Section log​

The log info is written to the syslog channel for Unix and to the debug channel on Windows. The log:{ ... }; block contains the fields:

AttributesContent description
fileComplete pathname to an optional file where a copy of the log information is written.

On Unix: optionally write log information to 'file' in addition to syslog, default: file = "/tmp/primus.log".
On Windows: write log information to 'file'; default: file = "%PUBLIC%\Securosys\Primus P11\primus.log"; 6
Please check, that the user or application has read/write access to the log-file.
write_log_file7Write log messages to the log file <false|true>
write_syslog7Write log messages to syslog <false|true>
trace_linenumberAdd the source line number to the message <false|true>
trace_timestampAdd a timestamp to the message8 <false|true>
trace_functionAdd the function name to the message <false|true>
trace_inoutAdd function's entry/exit messages <false|true>
trace_pidAdd process name/id to the message <false|true>
trace_filenameAdd source filename to the message <false|true>
trace_maskAllow trace messages:
0x00 None
0x01 log input of each p11 function
0x02 log protocol serialization information
0x04 log received TCP data information (avail. Bytes, bytes read)
trace_levelThe maximum level of detail allowed in messages (0-7)

The trace_level have the following meaning:

trace_levelLabelSeverityDescription
0LOG_EMERGEmergencysystem is unusable
1LOG_ALERTAlertaction must be taken immediately
2LOG_CRITCriticalcritical conditions
3LOG_ERRErrorerror conditions
4LOG_WARNINGWarningwarning conditions
5LOG_NOTICENoticenormal but significant condition
6LOG_INFOInformationalinformational messages
7LOG_DEBUGDebugdebug-level messages
Productive Systems

Logging can negatively impact system performance. For optimal performance in production environments, it is strongly recommended not to exceed the following trace_mask and trace_level values:

 trace_mask = 0x00;
 trace_level = 4;

Configure syslog (Unix)​

By default, the Primus PKCS#11 API provider writes its logs to /tmp/primus.log (because /tmp is guaranteed to be writable) and to journald (specifically, the local1 facility). This is configured in the logs section of the primus.cfg.

As a syslog tag (SYSLOG_IDENTIFIER), the name of the binary using the PKCS#11 API provider is used. For example, to show the syslog entries from the ppin tool:

journalctl -t ppin

If in addition to journald you want the events written to a file in /var/log/, add the following to /etc/rsyslog.d/50-ppin.conf:

# Log ppin messages to file (in addition to journald)
:syslogtag, contains, "ppin" /var/log/ppin.log

# Stop processing the message further
& stop

Additionally, to have logrotate manage the size of this new file, add the following to /etc/logrotate.d/ppin:

/var/log/ppin.log {
  missingok
}

Then restart the rsyslog daemon: sudo service rsyslog restart.

Repeat this for any other program for which you want to have the logs in a dedicated file.

Clustered HSM Connections and Failover Mechanisms​

For an HSM cluster, redundancy and connection management are handled by the provider internally. No changes are required on the application side. The following rules apply:

  • A connected HSM partition corresponds to a PKCS#11 slot with an inserted token, both having the name of the partition.

  • The provider assumes that partitions with the same user_name on two HSMs contain the same credentials (that is, they are redundant, cloned partitions).

  • Redundant partitions of an HSM cluster are configured using the same PKCS#11 Slot ID (see id in section slots). Therefore:

    • Assign the same PKCS#11 Slot ID to redundant partitions. Cluster redundancy is not visible to applications. The partition name and serial number are identical on all redundant partitions.

    • Assign different PKCS#11 Slot IDs to different partitions on the same or multiple HSMs.

In CloudHSM, the service proxy distributes new connections across the redundant HSMs within the cluster.

The priority setting in the hsm section allows adapting the preferred hsm selection and failover, for example, to optimize latency in geo-redundant HSM clusters.

Upon loading of a PKCS#11 library instance (per process), the initial HSM connection attempt for a given slot is made randomly from the highest priority pool (i.e. the one with the lowest numerical value). If no HSM in that priority pool is reachable, the process continues with the next lower priority pool, following the same logic. If all priority pools are exhausted without a successful connection, the provider returns a CKR_TOKEN_NOT_PRESENT error.

Once a successful HSM connection is established, the process continues to reuse it. The following situations trigger a connection reassessment:

  • the current connection fails and a failover is required
  • cryptographic rekeying is due (typically every 2 to 4 hours, done in the background) 9
  • the PKCS#11 library is re-initialized by the process

In case of connect_on_init = false; a connection is established upon opening the first session for a given slot, and the connection is terminated once all sessions for that slot are closed.

Load distribution across multiple redundant HSMs can be achieved either by launching multiple processes (each with its own library instance) or by deploying multiple clients, or by accessing the same partition via multiple PKCS#11 slots (having different PKCS#11 Slot IDs).

To reduce latency impact on performance, multi-threaded access is recommended - ideally with around 64 threads.

Default Connection Parameters of the PKCS#11 API​

The table below shows the default configuration values, if not specified differently by your Security Officer (SO):

Hostname or IP AddressPort NumberUsing Proxy
Standard HSMas setup by your SO2310no
Developer programgrimsel.securosys.ch2410no
nufenen.securosys.ch2411no
oberalp.securosys.ch2412yes

For CloudHSM access see CloudHSM Connectivity Details.

Footnotes​

  1. Versions prior to v1.5 have primary and fallback configuration location swapped. ↩ ↩2

  2. Environment variable support and default file location fallback were introduced with v1.8.4+ ↩ ↩2 ↩3 ↩4

  3. In version 0.9.xxx the fallback mechanism is disabled. ↩ ↩2

  4. Introduced with v1.7 ↩

  5. Version prior to v1.0.3 use a different notation for slots block and slot id. ↩

  6. For productive systems, set the trace_level = 4; and consider Linux log-file rotation. ↩

  7. Introduced with v2.2.2 ↩ ↩2

  8. Versions prior to v1.5 do not support timestamp on Linux nor environment variable on Windows ↩

  9. Introduced with v2.3.7 ↩

Get started withCloudHSM for free.
Other questions?Ask Sales.
Last updated on
Feedback
Need help?