Debugging CodeSafe 5 applications

CodeSafe application logging

CodeSafe application logs capture any stdout and stderr from the container. This can be used to capture log messages from the IPC daemon or SEElib library, or from the CodeSafe application’s own logging framework.

CodeSafe IPC Daemon logging

The IPC daemon will log to the CodeSafe application log if it encounters a fatal error during startup, if it loses connection to the nCore API service (after previously being connected), or if it encounters other fatal runtime issues. It will also warn if the CodeSafe application has connected to the IPC daemon but the nCore API service connection is not available for an extended period, which may indicate that the host-side startup process is taking a long time to complete or has not been configured correctly.

To enable more verbose logging, edit the ncoreipcdaemon script in the rootfs to set the NFAST_IPCD_LOGLEVEL environment variable (this is present in /opt/nfast/c/csd5/rootfs/bin/ncoreipcdaemon on Linux and C:\Program Files\nCipher\nfast\c\csd5\rootfs\bin\ncoreipcdaemon on Windows). Note that editing this will affect all CodeSafe 5 applications built with this modified rootfs.

If export NFAST_IPCD_LOGLEVEL=1 is set in the environment, INFO-level messages are also emitted (startup, and connections accepted or closed) in addition to ERROR-level messages.

If export NFAST_IPCD_LOGLEVEL=2 is set, logging is further extended with DEBUG-level messages.

Log messages indicate that they are from IPCD, and include a millisecond timestamp for clarity.

nShield 5c Configured for Auto-Loading CodeSafe 5 applications

If the nShield 5c is used with auto-loading of CodeSafe 5 applications via the nShield 5c’s configuration, logging in the CodeSafe application is enabled by default (unless explicitly disabled). Retrieving and clearing the CodeSafe application’s logs can be done via the appliance-cli command:

  • To retrieve the CodeSafe application’s logs:

appliance-cli -m <module number> cs5 getlog

  • To clear the CodeSafe application’s logs:

appliance-cli -m <module number> cs5 clearlog
The csadmin utility, or interactive use of hsc_codesafe, cannot be used with an nShield 5c that’s configured to auto-load CodeSafe 5 applications via the appliance configuration file (instead of the host machine’s configuration file). For debugging purposes, it may be convenient to remove the auto-loading configuration from the nShield 5c and use csadmin or hsc_codesafe to load and start the CodeSafe application remotely from the host machine, to simplify the workflow of testing changes to the application, and only deploy to the 5c configuration file once the application is ready for production deployment.

Host Configured for Automatic CodeSafe 5 Application Loading

If automatic configuration is used, logging in the CodeSafe application is enabled by default (unless explicitly disabled), so this does not need to be configured manually.

The following CodeSafe application logging-related commands are supported by the csadmin utility.

config log set enabled

The config log set enabled command should be issued before the start command. It uses the following format:

/opt/nfast/bin/csadmin config set log enabled -u <UUID> --esn <ESN>

  • <UUID> is the UUID of the CodeSafe application created by the load command.

  • <ESN> is the ESN of the HSM hosting the CodeSafe application.

For example:

/opt/nfast/bin/csadmin config set log enabled -u fedcba09-8765-4321-1234-567890abcdef --esn FEDC-BA09-8765

When successful, the command returns with no error.

config log set disabled

The config log set disabled command should be issued while the CodeSafe application is not running. It uses the following format:

/opt/nfast/bin/csadmin config set log disabled -u <UUID> --esn <ESN>

  • <UUID> is the UUID of the CodeSafe application created by the load command.

  • <ESN> is the ESN of the HSM hosting the CodeSafe application.

For example:

/opt/nfast/bin/csadmin config set log disabled -u fedcba09-8765-4321-1234-567890abcdef --esn FEDC-BA09-8765

When successful, the command returns with no error.

log get

The get command returns the current CodeSafe application log contents, if any. It uses the following format:

/opt/nfast/bin/csadmin log get -u <UUID>

<UUID> is the UUID of the CodeSafe application created by the load command.

For example:

/opt/nfast/bin/csadmin log get -u fedcba09-8765-4321-1234-567890abcdef
FEDC-BA09-8765        SUCCESS
Success: Started application

log clear

The clear command deletes the current CodeSafe application log file if present. It uses the following format:

/opt/nfast/bin/csadmin log clear -u <UUID>

<UUID> is the UUID of the CodeSafe application created by the load command.

For example:

/opt/nfast/bin/csadmin log clear -u fedcba09-8765-4321-1234-567890abcdef
FEDC-BA09-8765        SUCCESS
log: log cleared

Crash Reporter

If the CodeSafe 5 application links against the seelib.a library, an in-process crash reporter will be registered for various termination and crash signals before main().

If the application receives one of the handled signals, a crash report will be written to the CodeSafe application log, as shown below:

SEE MACHINE CRASH: SIGSEGV (Invalid memory reference)
        Sending process PID: 0
        Sending process UID: 0
        Fault address: 0xcafecafecafecafe
        SEGV_MAPERR: Address not mapped to object.
  crashing.c: 298 --  -- some_crashing_function
  main.c: 56 --  -- main
Segmentation fault

In order to obtain a useful crash backtrace, the CodeSafe application should be built with debugging symbols at least at -g1 level and not have the symbols stripped from the binary.