Skip to main content

Configuration

Configuration Files​

primus.cfg​

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​

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​

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.

#-----------------------------
# 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 = false;

  /*--- HSM CONFIGURATION SECTION -----------------------------------------*/
  hsms:
  {
     /*--- HSM0, e.g. standalone hsm with one partition, slot id 0 */
     hsm0:
     {
        host = "HSM0_HostnameOrIpOrProxyURL";
        port = "2310";
        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: 250 [ms])
wait_max_triesNumber of tries when waiting for data completion and fallback3 to next cluster HSM (default: 5) net.ipv4.tcp_syn_retries is reduced (=2) via socket options to reduce failover times
connect_on_initConnect to configured HSM(s) on library initialization resulting in shorter connection setup times (default: false)
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.
portThe port of the PKCS#11 API on the HSM or service proxy, as a string.
priority4Optional: Priority in selecting a redundant HSM. The smaller the value, the higher priority. Round-robin for equal priority. Values: 0-127, default priority value is 0 (=highest priority).
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.

Clustered HSMs (having the same PKCS#11 Slot ID, see id in Section slots) are redundant. The first connection is selected randomly from the highest priority pool (=lowest value) and after that round-robin from the same pool. If no HSM of this priority pool is reachable, the next lower priority pool is considered in the same manner until all pools are exhausted. In this case the provider returns a CKR_TOKEN_NOT_PRESENT error.

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. It is a part of the complete user Id received and logged on the HSM (partially hashed): myApplication@hash(machine_name@ipd_adress@mac_address) Example: myApplication@d1172dac ...
proxy_userCloudHSM only: the name of the service user (proxy), as provided by Securosys.
proxy_passwordCloudHSM only: the password for the service user (proxy)
idPKCS#11 Slot ID assigned to the HSM partition, e.g. id=0

A network HSM differs slightly compared to a card reader (=slot) with an inserted card (=token):

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

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

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

  • A partition may be addressed via multiple slots (using different PKCS#11 Slot IDs) to parallelize access (performance optimization).

  • The provider assumes that partitions with the same user_name are redundant and use the same credentials.

  • A service proxy (CloudHSM) autonomously distributes new connections to different redundant HSMs in the cluster.

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.
write_log_file6Write log messages to the log file <false|true>
write_syslog6Write log messages to syslog <false|true>
trace_linenumberAdd the source line number to the message <false|true>
trace_timestampAdd a timestamp to the message7 <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

On Unix: optionally write log information to 'file' in addition to syslog, default /tmp/primus.log.

On Windows: write log information to 'file'; default %PUBLIC%\Securosys\Primus P11\primus.log8

Please check, that the user has read/write access to this log-file.

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
CloudHSM CHa-api.cloudshsm.com2310yes
b-api.cloudshsm.com2310yes

For other CloudHSM clusters see the application note 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. Introduced with v2.2.2 ↩ ↩2

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

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