Automatic Configuration of CodeSafe 5 Applications

CodeSafe 5 Configuration Section

The configuration section [codesafe] is supported in the client-side hardserver config file which allows specification of:

  • the esn of the nShield 5s or nShield 5c module onto which to load the application

  • the CodeSafe 5 image_file to load and run; this must be readable by the nfast user, which is a member of nfast group and nfastadmin group by default (the /opt/nfast/custom-seemachines (Linux) or C:\Program Files\nCipher\nfast\custom-seemachines (Windows) is a recommended location)

  • the worldid_pubname to assign the published object that the SEE world ID is registered with

Run cfg-mkdefault -f config.example to create a new example config file showing this section with documentation of all its fields.

You can manually add it to your existing config file before the [load_seemachine] section if it is not already present.

CodeSafe 5 configuration section documentation:

[codesafe]
# Start of the codesafe section
# The CodeSafe 5 applications to load and start on an nShield 5. Use
# [load_seemachine] for previous HSM types.
# Each entry has the following fields:
#
# ESN of the module to load the CodeSafe application onto
#  esn=ESN
#
# Whether this configuration entry is enabled (default="yes"). This is a
# convenience for disabling CodeSafe auto-loading on a given module
# temporarily without removing the configuration.
#  enabled=ENUM
#
# The filename of the CodeSafe application for this module to host.
#  image_file=STRING
#
# Port in the CodeSafe application that is configured for SEEJobs
# communication. An SSH tunnel is automatically created for SEEJobs
# communication between the hardserver and this port. Set to 0 to explicitly
# disable. (default=8888)
#  seejobs_port=PORT
#
# Enable ncoreapi access for the CodeSafe application with
# Cmd_CreateSEEConnection. The identities in the image_file are passed
# automatically. (default="yes")
#  enable_ncoreapi=ENUM
#
# The PublishedObject name to use for publishing the KeyID of the started
# CodeSafe application.
#  worldid_pubname=STRING
#
# Enable auto-enrollment of the client with an nShield 5c. Auto-enrollment is
# enabled by default. This setting is ignored if the HSM is an nShield 5s or
# if this machine is an unprivileged client of a 5c.
#  auto_enroll=ENUM
#
# Unless set to "no", logging will be enabled for the CodeSafe application
# (default="yes"). Logs can be retrieved with csadmin log get -u UUID
#  logging=ENUM
#
# If set to "yes", the CodeSafe application is forcibly re-loaded even if a
# matching image appears to be loaded already (default="no")
#  force_reload=ENUM
#
# Key names of identities of CodeSafe application to pass to
# Cmd_CreateSEEConnection. This is only applicable if enable_ncoreapi has not
# been disabled. If only signed with the ASK, this is passed, if signed with
# the ASK and one extra signature (csadmin image signextra) then the default
# is to pass only the extra identity, and if there are more signers than this
# then all the identities are supplied. To override the defaults (e.g. to
# supply both the ASK and signextra identies) specify the key names as a
# space-separated list. Note, this controls what is reported by
# Cmd_GetWorldSigners instead of the CodeSafe application.
#  identities=STRING
bash

Entries for additional modules may be added separated by ---- lines.

A new or modified configuration or CodeSafe app can be applied to a module dynamically by running nopclearfail -c -m MODULE_NO. The new configuration or changed application will be loaded automatically after the module returns from the clear operation.

Automatic Startup

The configuration-helper program hsc_codesafe is run automatically by the hardserver during module startup (or after clear) to process the [codesafe] configuration, including the following steps:

  • Automatically configures CodeSafe 5 on the 5c and enrolls it with the local system (requires 13.7 or later Connect image, and will be skipped if the client is not privileged, in which case it will have to be configured up-front manually as per nShield 5c Codesafe 5 Configuration to allow access to the unprivileged client).

  • Stops all existing CodeSafe applications on the module.

  • Destroys any existing CodeSafe applications on the module if they do not match the hash of the one specified in configuration.

  • Loads any required developer ID certificates from the /opt/nfast/kmdata/cscerts (Linux) or C:\ProgramData\nCipher\Key Management Data\cscerts (Windows) if not already loaded.

  • Loads the CodeSafe application specified in config (if not already loaded).

  • Enables CodeSafe logging in the application configuration.

  • Enables the SSHD in the application configuration, gets the SSHD server public key, generates an ephemeral client key and registers it with the SSHD server (This is done for SEEJobs support unless seelibs_port is explicitly disabled).

  • Starts the CodeSafe application.

  • Runs the internal nShield ncssh tool to set up a mutually authenticated tunnel between a local UNIX domain socket that is accessible to the hardserver and the port (by default 8888) for the SEEJobs protocol in the CodeSafe application.

  • Runs Cmd_CreateSEEConnection with the identity information for the CodeSafe application (unless enable_ncoreapi is disabled).

  • If worldid_pubname is set, runs Cmd_SetPublishedObject to register the SEE World ID returned by Cmd_CreateSEEConection so that applications can make use of the CodeSafe application (this ID should be used with calls to Cmd_SEEJob / Cmd_FastSEEJob).

hsc_codesafe will run until the module is cleared or the hardserver is shut down.

If the module is cleared, hsc_codesafe will be re-run automatically when the module returns from clear to negotiate a fresh mutually authenticated SSH tunnel and start the CodeSafe application again.

It takes a couple of minutes for the CodeSafe application to be available after the module is cleared. Loading performance will be improved in a future firmware release.

Interactive hsc_codesafe execution

In order to support build, run, debug cycles when the user is developing the CodeSafe 5 application, hsc_codesafe can also be run interactively without configuration in config and without needing to clear the module.

It can be passed the same name-value pairs of config entries on the command-line as would normally be read from the config file.

For example, to load a CSEE (SEEJobs) CodeSafe application, and then when it is ready, run a host-side command which uses the application:

hsc_codesafe -m1 image_file=/opt/nfast/custom-seemachines/echo.cs5 worldid_pubname=echosee -- perfcheck "misc:SEEJob" -s -t 10
bash

To load a non-SEEJobs application pass seejobs_port=0, and to prevent Cmd_CreateSEEConnection being run automatically pass enable_ncoreapi=no. The example below shows this, and just runs csadmin list to fetch the container address when loading has completed instead of running an application directly. In this example, the module to use is specified via ESN rather than via module number (either option is supported regardless of other parameters passed).

hsc_codesafe esn=8ED1-2C9A-9331 image_file=/opt/nfast/custom-seemachines/seetickets_netsee.cs5 seejobs_port=0 enable_ncoreapi=no -- csadmin list
bash

Monitoring Connection Status

The log messages from hsc_codesafe are currently included in the hardserver log /opt/nfast/log/hardserver.log (or Event Log on Windows, can be retrieved on the command-line using nshieldeventlog -c 10 for the last 10 lines, for example).

A "pseudo-module" is registered in the hardserver for the CodeSafe application SEE Jobs endpoint and is visible when running enquiry -m 1001 as the counterpart for module 1, enquiry -m 1002 as the counterpart for module 2, and so on. This will return InvalidModule if the hsc_codesafe processing has not run to completion and is only visible when the SSH tunnel is set up and Cmd_CreateSEEConnection has been run successfully to trigger the enrollment of the CodeSafe application for SEEJobs via the hardserver. The version details reported by the pseudo-module reflect the version of the CodeSafe SDK whose SEELib library code the CodeSafe application is linked against (not the HSM firmware version).

CodeSafe 5 pseudo-module enquiry example:

$ enquiry -m1001
Module #1001:
 enquiry reply flags  none
 enquiry reply level  Five
 serial number
 mode                 operational
 version              13.7.2
 speed index          20000
 rec. queue           120..250
 level one flags      none
 version string       13.7.2-85-90e580d1
 checked in           0000000067ca1f41 Thu Mar  6 22:18:41 2025
 level two flags      none
 max. write size      262152
 level three flags    none
 level four flags     ServerHasPollCmds HasLongJobs ServerHasLongJobs ServerHasCreateClient
 module type code     17
 module type          nShield CodeSafe 5 on nShield 5
 product name         CodeSafe 5
 device name          #1001 CodeSafe 5 SEE Jobs Endpoint for 8ED1-2C9A-9331
 hardware status      OK
bash

Apart from running enquiry for the status reporting of SEEJobs communication, the pseudo-module should not currently be used for any other client operations.

The information reported by this "pseudo-module" is from the SEE machine itself, and reflects the version number of the CodeSafe SDK that the seelib.a it is linked against is from. This is distinct from the the HSM firmware version and status information that is reported in the enquiry output for the "normal" module like module 1.

Troubleshooting

You can monitor the progress in loading the CodeSafe application with tail -f /opt/nfast/log/hardserver.log (or monitoring the Event Log on Windows)

Output from CodeSafe 5 loading will appear as log lines containing Module #1 Startup (or whichever module number), so grep can be used to filter to just these messages.

When the CodeSafe application has been loaded successfully a log line like the below will be reported, meaning that the application is now available for client communication (and the message provides some example commands for further diagnostics information):

2025-03-13 12:33:24 t00e774076f7f0000: Hardserver [FP]: Notice: Module #1 Startup: hsc_codesafe:INFO: READY: /opt/nfast/custom-seemachines/echo.cs5 running on 8ED1-2C9A-9331 (#1); SEE World ID published as echosee; csadmin log get -u da5c30a8-a302-4dff-bda6-d424d5749273 to retrieve logs; enquiry -m 1001 to check SEEJobs endpoint status
bash

If loading fails, retry can be attempted by clearing the module (that is the main module, not the pseudo-module in the 1001+ range) or by restarting the client hardserver (nFast Server service on Windows).