Skip to main content

Configuration

Configuration Files​

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.

syslog (Unix)​

Configure 'rsyslog.conf' and 'logrotate' to log the Primus PKCS#11 events. Add the lines in /etc/rsyslog.conf:

# Save primus messages also to primus.log
syslog.* /var/log/primus.log

And add the line in /etc/logrotate.d/syslog:

/var/log/primus

Restart the syslog daemon.

"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 setting up your CloudHSM, have a look at the example on how to configure the CloudHSM access. 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)
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

Clustered HSM Connection and Failover Mechanisms​

For an HSM cluster, redundancy and connections management are handled provider internally, requiring no changes on the application side. The following rules apply:

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

  • The provider assumes that partitions with the same user_name use the same credentials (redundant partitions).

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

    • Same PKCS#11 Slot ID has to be assigned for redundant partitions (cluster). Cluster redundancy is not visible for the applications; partition name and serial number are identical on all redundant partitions.

    • Different PKCS#11 Slot IDs have to be assigned for different partitions on same and multiple HSMs.

  • Note that in CloudHSM environments, a service proxy autonomously distributes new connections across the redundant HSMs within the cluster.

The optional connection priority setting (see priority in section hsm) allows to adapt to preferred hsm selection and failover, e.g. 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, except in the following situations, which trigger a reassessment of the connection:

  • 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 ↩

Last updated on