Build CodeSafe 5 SDK apps

General SDK use

The CodeSafe 5 SDK provides the tools necessary to build and run SEE machines on nShield 5 HSMs. The CodeSafe 5 SEE machines are containerized. The SDK provides the structure of the container, including a root file system, libraries required for communication with the nCore API, and libraries to enable communication between the SEE machine and the host. The SDK provides headers and libraries for building applications and a root file system for the container containing runtime libraries, binary tools such as touch, cat, grep and optionally a Python distribution.

Prerequisites

GCC 8.x or later.

SDK file structure overview

SDK location

The default installation location of the CodeSafe 5 SDK is:

  • Linux: /opt/nfast/c/csd5/

  • Windows: C:\Program Files\nCipher\nfast\c\csd5\

Some tools required for SEE machine operations might be found elsewhere in the main install. For example, csadmin, which enables loading, starting, and stopping SEE machines, is installed in the following default locations:

  • Linux: /opt/nfast/bin/csadmin

  • Windows: C:\Program Files\nCipher\nfast\bin\csadmin (Windows)

These cases are described in the following sections as required.

Container root file system

The container root file system is located in:

  • Linux: /opt/nfast/c/csd5/rootfs/

  • Windows: C:\Program Files\nCipher\nfast\c\csd5\rootfs\

This root file system contains two main parts: binary files and libraries.

Binaries

rootfs/bin/ (Linux) or rootfs\bin\ (Windows) contains many useful common Linux binaries that you might need within the container such as cat, grep, and touch.

rootfs/sbin/ (Linux) or rootfs\sbin\ (Windows) contains the init script for the container.

Libraries

rootfs/lib/ and rootfs/usr/lib/ (Linux) or rootfs\lib\ and rootfs\usr\lib\ (Windows) contain runtime libraries that may be needed by applications built with the SDK.

CMake

The SDK installs a directory which includes CMake toolchains used for building example SEE machines:

  • Linux: /opt/nfast/c/csd5/cmake

  • Windows: C:\Program Files\nCipher\nfast\c\csd5\cmake

These toolchains can serve as examples themselves for creating custom toolchains.

Include directories

The SDK provides two directories with header files that can be included along with their respective libraries to provide additional functionality in SEE machines. These headers are stored in:

  • Linux:

    • /opt/nfast/c/csd5/gcc/*

    • /opt/nfast/c/csd5/include-see/*

  • Windows:

    • C:\Program Files\nCipher\nfast\c\csd5\gcc\*

    • C:\Program Files\nCipher\nfast\c\csd5\include-see\*

SEE specific libraries

The C libraries which are specific to SEE machines, including seelib.a and librtusr.a, are located in:

  • Linux: /opt/nfast/c/csd5/lib-ppc64-linux-musl/\*

  • Windows: C:\Program Files\nCipher\nfast\c\csd5\lib-ppc64-linux-musl\*

These libraries must be included to enable critical SEE machine functionality such as communication with the nCore API.

The Python module specific to SEE machines is seeapi.py. This module is located under Python site packages in nshield.ipcdaemon.seeapi. This must be imported as SEEAPI to enable critical SEE machine functionality such as communication with the nCore API.

Compatibility

The CodeSafe 5 SDK and nShield 5 HSMs are sufficiently different from previous implementations that applications for HSM models cannot run on the nShield 5.

Applications must be rebuilt using the CodeSafe 5 SDK to run on the nShield 5.

Where possible, APIs such as SEElib and SEEJobs behave as they did with previous HSM models, but signing and deployment details for CodeSafe 5 applications differ.

Building new SEE machines with SEElib

An SEE machine is a container image with a complete filesystem which can be loaded onto an CodeSafe 5-enabled HSM as part of a container. The SEElib library enables SEE machines to interface with the nCore API via the IPC daemon.

Source code is compiled using one of the GCC cross-compilers supplied with the CodeSafe SDK. For details of required compiler options, toolchains, makefiles and so on, see the CMake files supplied with the examples, as well as Build and sign example SEE machines on Linux and Build and sign example SEE machines on Windows.

The container image must be signed using the csadmin utility tool.

Developer authentication

CodeSafe 5 requires a signed CodeSafe image to run SEE machines on the HSM.

The CodeSafe developer needs to request a developer ID certificate by sending a Certificate Signing Request (CSR) to Entrust support. The tool used to create the CSR is integrated into the HSM software as a subcommand of csadmin utility.

For security purposes, a developer keypair must be created and stored within the HSM. In addition, the keypair must be OCS protected to provide authorization control on its use. The developer keypair will be created by csadmin if it does not already exist.

After the certificates are received, they are installed on the HSM and are used to sign CodeSafe application images with the csadmin tool.

The implementation of this is described in more detail in Sign and deploy CodeSafe 5 SDK apps using csadmin.

Deploying SEE machines

After the code has been compiled, built, and signed, the csadmin utility tool is used to deploy the SEE machine. It is used to load the signed CodeSafe application image and then to start the SEE machine. The SEE machine then runs the entrypoint including the main() function.

For more information on the csadmin utility, see Sign and deploy CodeSafe 5 SDK apps using csadmin.

SEE machine initialization requirements

An SEE machine must initialize the SEElib before making use of any of the SEElib functionality. This is done by calling SEElib_init(). It is recommended that this call is made immediately within the main() function of an SEE machine.

By default, SEElib_init() will also enable SEEJobs support for communication from the host via Cmd_SEEJob and Cmd_FastSEEJob sent via a client hardserver. This uses port 8888 within the container, and this port should be set as the ssh_tunnel port in the container configuration as shown in later examples. It is possible to enable a non-default port for SEEJobs by calling SEElib_SetPort(8000) (for example) before SEElib_init(). To disable SEEJobs listening altogether, run SEElib_SetPort(0) before SEElib_init()

SEElib Functions

After initialization, SEElib functions can be used to communicate with the nCore API via the IPC daemon that is included as part of the container image. These functions behave the same as in previous CodeSafe versions although the underlying implementation has changed.

SEElib_Transact()

To send a command to the nCore API and block waiting for a reply:

int SEElib_Transact(struct M_Command *cmd, struct M_Reply *reply)

This sends the cmd command to the nCore API and waits for the reply to be written to reply.

SEElib_Submit() / SEElib_Query()

To send a non-blocking command to the nCore API:

int SEElib_Submit(M_Command *cmd, M_Reply *reply, PEVENT ev, SEElib_ContextHandle tctx)

The cmd command is submitted to the nCore API. The transaction listener thread will call EventSet ev, if ev is non-NULL when the reply returns for this command. The reply is unmarshalled into reply and tctx is returned to the caller with SEElib_Query(M_Reply **replyp, SEElib_ContextHandle *tctx_r).

Before using the SEElib_Submit() method, SEElib_StartTransactListener() must have been called to start the transaction listener.

Unlike SEElib_SubmitCoreJob(), SEElib_Submit() does not block and wait for all other calls to SEElib_Transact() to complete.

SEElib_SubmitCoreJob / SEElib_GetCoreJobEx()

To submit a job to the nCore API:

extern int SEElib_SubmitCoreJob(const unsigned char *data, unsigned int len)

To receive a job from the nCore API:

extern int SEElib_GetCoreJobEx(unsigned char *buf, M_Word *len_io, unsigned flags)

SEElib_SubmitCoreJob() is blocking. It waits for the job to be submitted, which includes waiting for existing calls made to SEElib_Transact() to be completed. The same is true for SEElib_GetCoreJobEx().

For non-blocking calls, consider using SEElib_Submit().

Other SEElib methods

For a comprehensive list of all functionality provided via the SEElib, see: SEE API documentation.

Host/SEE machine communication

Host/SEE machine communication can be done using SEEJobs via the hardserver using an automatically configured SSH tunnel set up by using the [codesafe] configuration section of the client-side config file. Alternatively (or additionally) communication between the host and the SEE machine can be done via TCP and UDP IPv6 networking.

The ncoreapi service can only connect to one CodeSafe container at a time.

Update Connects running in an IPv4 context

The host side of the CodeSafe 5 examples will only be able to communicate over IPv6. Connects running in an IPv4 context will not be able to run examples without changing how CodeSafe 5 is configured on the Connect. See Working with CodeSafe for more information.