Building CodeSafe 5 applications

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.

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.

This example shows how to specify extra packages to be included in the container image, which will be copied from the host into the container at build time.

The binaries package is required for most applications, as it includes the IPC daemon which is required to mediate between the CodeSafe application and the nCore API service.

The other packages are needed for all applications: * The python packages can be omitted if Python is not being used. * The kmlocal and cardlist packages support use of the NFKM library as they pull in Security World files to their usual /opt/nfast/kmdata locations within the container.

It is also possible to specify custom packages here, which can be copied from the host into the container at build time, and then used by the application. These may be relative paths to the nShield installation location, like the python and binaries packages in the example; absolute paths to any location on the host file system; or paths referenced via environment variables, as in the kmlocal and cardlist examples.

This example shows port 8888 (the default port for the nShield SEEJobs protocol) accessible securely through the SSH tunnel. TCP ports 8000 and 8001 are exposed directly on the HSM network interface for other application services, and no outgoing ports are allowed.

The nShield-specific C libraries are located in:

Applications that wish to communicate with the nCore API service, or expose the SEEJobs protocol, from a C or C++ application, must link against either of two main groups of libraries:

The traditional CodeSafe SEElib library exists as the stand-alone library seelib.a. This static library is not compatible with libnfstub.a or libnfkm.a.

As a convenience for users combining use of SEElib (SEElib_* functions) with the NFastApp_* functions in the C Generic Stub and/or the NFKM APIs, the C Generic stub static library libnfstub.a in CodeSafe 5 includes the full SEElib API.

If the goal is to migrate use of SEElib_Transact to NFastApp_Transact for consistency with client-side application code whilst still retaining support for SEEJobs, or if SEElib is being used primarily but NFKM library must also be used in the same application, then libnfstub.a must be used instead. This provides all the SEElib symbols in a form compatible with libnfstub.a and libnfkm.a. seelib.a must not be linked against in this case. The usual seelib.h header should continue to be used to obtain the declarations, but if also including C Generic Stub (such as nfastapp.h) or NFKM headers (such as nfkm.h), they should be included before seelib.h.

If SEElib_init() is called in the libnfstub.a implementation, it will initialize an NFast_AppHandle internally which is configured to marshal M_Bignum objects in the form defined by struct NFast_Bignum in the seelib.h header, which is an M_ByteBlock containing a little-endian representation of the value. This makes the default marshalling behaviour and struct representation of objects when migrating existing SEElib code from seelib.a to libnfstub.a identical.

In order to support inter-operation with other NFastApp use-cases, new APIs SEElib_init_NFastApp() and SEElib_init_NFastApp_default() have been added in seelib.h that can be called instead of SEElib_init() if required. These new functions are declared if nfastapp.h is included before seelib.h. SEElib_init_NFastApp() allows initialization of SEElib with the caller’s own NFast_AppHandle, allowing the caller to precisely control the NFastApp initialization. SEElib_init_NFastApp_default() initializes the SEElib library with the default NFastApp Bignum implementation defined in nfastapp-bignum.h. This provides maximum compatibility with typical default NFastApp initialization that would be used in most client-side application code that is being migrated to CodeSafe 5. If nfastapp-bignum.h is being used, it should be included before seelib.h.

If "manual" marshalling or unmarshalling of nCore types is being performed using functions like NF_Marshal_CertificateList or NF_Unmarshal_CertificateList, the struct NF_UserData * context set in the NF_Marshal_Context.u or NF_Unmarshal_Context.u field was set to NULL in traditional seelib.a applications. If using marshalling or unmarshalling functions when linking against libnfstub.a, the struct NF_UserData * u; field must now be set to a valid Generic Stub object. This should either be obtained in the usual manner using the NFastApp APIs, or if using the SEElib initialization extensions, it can be obtained using the new SEElib_GetUserData() function. When using seelib.a, SEElib_GetUserData() will always return NULL as it is not applicable for the implementation of the marshalling and unmarshalling functions in that version of the library.

The nShield-specific Python modules are nfpython (for nCore interfaces) and nfkm (for NFKM interfaces, which is a superset of the nfpython module and so can be used instead of nfpython if using both APIs).

If using the Python runtime from the extra packages (see Example extra-packages-conf.json file), these modules are available as import nfpython or import nfkm without any additional configuration, and behave in the same way as they do on the host side, except that they communicate with the nCore API service via the IPC daemon within the container instead of communicating via the hardserver service.

As with the C libnfkm.a API, effective use of the Python nfkm API for Security World functionality will usually require the kmlocal and (if interacting with smartcards) cardlist packages to be included in the image as described in Example extra-packages-conf.json file.

The Python webserver example in the SDK (/opt/nfast/python3/csd5/examples/webserver on Linux and C:\Program Files\nCipher\nfast\python3\csd5\examples\webserver on Windows) demonstrates use of the nfpython and nfkm modules in a CodeSafe application, and can be used as a reference for this use-case. It can be used in conjunction with the supplied hostside client, or from a web browser.

CodeSafe 5 supports C++17.

You can link the seelib.a or the libnfstub.a and libnfkm.a libraries with C++ applications to use the nShield APIs. The relevant header files contain extern "C" guards so that they can be included in C++ code.

The helloplus example in the SDK (/opt/nfast/c/csd5/examples/netsee/helloplus on Linux and C:\Program Files\nCipher\nfast\c\csd5\examples\netsee\helloplus on Windows) shows how to build a simple CodeSafe 5 application with C++ 17 and demonstrates various C++ language and library features working with the cross-compiler. It doesn’t have a client-side component, and the example’s output is simply written to the application log.

If not using CMake to build your CodeSafe 5 application, the C++ compiler and linker flags defined in the SDK’s codesafe-toolchain-nshield5-csee.cmake file should be consulted to obtain the correct flags for your own build files. Note that the -static linker flag is required to statically link the C and C++ runtime libraries in this case.

The reserved C++ keyword export is used as a field name in M_Command.args.export and M_Reply.reply.export (defined in both seelib.h and nfastapp.h headers). By default, the field is renamed using the pre-processor to exportcmd when compiling with a C++ compiler. If an application has already worked around this issue by defining export before including relevant nShield headers, the pre-processor renaming will not be applied, and the user’s existing work-around will continue to behave as before. If STDMARSHAL_KEEP_EXPORT_RENAME is defined before including relevant headers, export will not be #undef-ed after the affected headers, so that code can still reference M_Command.args.export and M_Reply.reply.export for backwards-compatibility with code migrated from C to C++; this should only be done if export is not otherwise being used in the codebase. To completely disable these workarounds, define the STDMARSHAL_NO_EXPORT_RENAME macro before including relevant headers.

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

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

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

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.

To submit a job to the nCore API:

To receive a job from the nCore API:

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().

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

The 5s HSM itself only exposes an IPv6 network interface, so only IPv6 can be used for direct TCP or UDP communication between the host and the CodeSafe application. However, if using a 5c (Connect form factor), then the communication is relayed automatically to the 5c’s network interface, which supports both IPv4 and IPv6, so the host can communicate with the CodeSafe application via IPv4 if desired in that case. See Working with CodeSafe for more information regarding configuration of CodeSafe on the 5c.