Port existing CodeSafe application to CodeSafe 5

Follow the steps in this chapter if you need to port an existing legacy SEE machine to run on CodeSafe 5.

The porting of legacy CodeSafe application examples in this chapter assumes the perspective of a CodeSafe application developer. CodeSafe users wanting to port legacy third party CodeSafe applications to nShield 5 might need to have the third party issuer of said legacy CodeSafe applications port the applications and sign the ported applications.

CodeSafe users porting third party applications should ensure that the third party CodeSafe developer is a trusted party, and should verify that the ported CodeSafe image has a genuine certificate issued by the trusted developer. After a third party CodeSafe application is ported and signed, the application user can skip to the "Load the signed container" step in the following examples and continue the procedures from there.

Full examples of legacy SEE machines that have been ported with use of the compatibility layer can be found in Build and sign example SEE machines on Linux. These Classic SEE "CSEE" examples are legacy examples that have been modified to run with CodeSafe 5 specifically to demonstrate use of the compatibility layer. In all other ways, these examples are identical to examples provided with previous iterations of nShield HSMs and CodeSafe.

It is assumed that an ASK and developer ID key have already been generated, and that required certificates have already been obtained from Entrust and installed into the target HSM.

The compatibility layer

Legacy CodeSafe transacted data between host application and module SEE machines using SEEJobs. SEEJobs were sent from the host-side application to the nCore API which then passed the jobs on to the SEE machine, and vice versa. CodeSafe 5 removes the need to communicate with SEE machines via the nCore API using SEEJobs.

Instead, CodeSafe 5 allows a network connection to be established directly between a host-side application and an SEE machine. As such, support for transacting SEEJobs, and all related methods has been removed from CodeSafe 5.

The compatibility layer provides support for SEEJobs. All methods that dealt with transacting exist in the compatibility layer, but instead of passing SEEJobs to the nCore API and having the nCore API forward them, the Compatibility layer creates a network connection between the SEE machine and host application.

The methods function similarly, but the mechanism for data transaction has been updated. The compatibility layer is split into two parts: the module-side compatibility layer, and the host-side compatibility layer. Both parts work together to provide support for legacy SEE machines.

The module-side SEE machine and corresponding host-side application must both be ported successfully for them to function on CodeSafe 5. It is not sufficient to port one side but not the other.

Module-side compatibility layer

The module-side compatibility layer provides the methods necessary to connect the SEE machine to the host-side application via network connection.

The module-side compatibility layer comprises the liblegacy_compatibility.a library. Its install location is:

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

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

Host-side compatibility layer

The host-side compatibility layer provides the methods necessary to connect the host-side application to the SEE machine via network connection.

The host-side compatibility layer comprises the following files:

  • legacy-csee-host-side-compatibility.h

  • legacy-csee-host-side-compatibility.c

Their install location is:

  • Linux: /opt/nfast/c/csd5/examples/csee/utils/hostside/

  • Windows: C:\Program Files\nCipher\nfast\c\csd5\examples\csee\utils\hostside\

Required module-side changes for porting

To port a legacy SEE machine to CodeSafe 5, only a single line change is required in code.

Initialize the compatibility layer by calling SEElib_Legacy_Support_Init() after SEElib_Init() is called but before any legacy methods such as SEElib_AwaitJob() are called. This waits for a compatible host-side application to connect before proceeding.

An example SEE machine main() properly initializing the compatibility layer:

int main(void) {

  /* initialize the SEE environment */
  SEElib_init();

  /* initialize legacy SEE support */
  SEElib_Legacy_Support_Init("8888");

  /* The compatibility layer is initialized
     carry on with SEE machine operation */
  Perform_SEE_Machine_Tasks();
  return 0;
}
By default, all provided example SEE machines communicate through port 8888. You can use any port when initializing the compatibility layer, however you must ensure that the host-side application compatibility layer is passed and attempts to connect to the same port number as the one initialized on the module-side.

After the compatibility layer has been initialized, all SEEJob-related methods, such as SEElib_ReturnJob() or SEElib_AwaitJob(), will work. No further changes in code are required for legacy SEE machines to run using CodeSafe 5.

A full list of methods the compatibility layer provides support for can be found in the "SEE Machine Module Side Compatibility Layer" section of SEE API documentation.

Required host-side changes for porting

Porting host-side applications to CodeSafe 5 requires changes to some method calls, in addition to the initialization.

Initialization

Initialize the host-side compatibility layer using the following command:

netsee_initialize_legacy_seejob_support(const char * cseeContainerMachineIPv6, const char * cseeContainerMachinePort)`

It takes two arguments:

  • The SEE machine container IP, which can be found using csadmin list

  • The SEE machine port number

The port number must match the port number passed on to the module-side compatibility layer when the module-side compatibility layer is initialized.

The container IP must be passed to the host-side application. You can pass it in as a command line argument, as in the classic SEE examples described in Build and sign example SEE machines on Linux, however the exact implementation is the decision of the porting developer.

Replacing SEEJob-related method calls

Unlike the module-side compatibility layer, which allows all SEEJob-related method calls to be called without changes, porting the host-side requires certain method calls to be updated.

This is because the compatibility layer’s replacement methods need to replace the role of the nCore API and send SEEJobs to and from the SEE machine’s module-side compatibililty layer.

The methods specific to the nCore API that host-side applications previously used to transact SEEJobs still exist to communicate with the nCore API, but no longer support SEEJobs.

Only nCore API calls for SEEJobs need to be updated. Other unrelated calls to the nCore API do not need to be modified.

Host-side compatibility calls no longer require the NFastApp_Connection and NFast_Call_Context arguments to be passed in, as demonstrated in the following examples.

For more detailed descriptions of these methods, see the "Compatibility layer API Host-side" section of SEE API documentation.

NFastApp_Submit()

Replace SEEJob calls to NFastApp_Submit() with calls to netsee_submit_legacy_seejob().

For example:

NFastApp_Submit(nc, NULL, &cmd, &reply, &tctx);

Becomes:

netsee_submit_legacy_seejob(&cmd, &reply, &tctx);

NFastApp_Wait()

Replace SEEJob calls to NFastApp_Wait() with calls to netsee_wait_legacy_seejob().

For example:

NFastApp_Wait(conn, NULL, &replyp, &tctxp);

Becomes:

netsee_wait_legacy_seejob(&replyp, &tctxp);

NFastApp_Transact()

Replace SEEJob calls to NFastApp_Transact() with calls to netsee_transact_legacy_seejob().

For example:

NFastApp_Transact(conn, NULL, &cmd, &reply, &tctx);

Becomes:

netsee_transact_legacy_seejob(&cmd, &reply, &tctx);

simple_transact()

Replace SEEJob calls to simple_transact() with calls to netsee_simple_transact_legacy_seejob().

For example:

simple_transact(conn, NULL, &cmd, &reply, 1);

Becomes:

netsee_simple_transact_legacy_seejob(&cmd, &reply, 1);

Rebuilding and Recompiling

After the host-side application and module-side SEE machine compatibility layers have been properly initialized, and all host-side SEEJob method replacements have been made in the code, both the host-side application and the module-side SEE machine should be rebuilt with their respective compatibility layers properly linked and included.

The provided Classic SEE examples are practical examples of how the compatibility layer should be implemented, and how the compatibility layer libraries and files should be linked the build chain creating the SEE machine.

Rebuilding host-side

Include legacy-csee-host-side-compatibility.h in host-side application scripts that are being ported. Recompile host-side applications so that legacy-csee-host-side-compatibility.c is included in the source.

Rebuilding Module Side

Link the compatibility layer library liblegacy_compatibility.a to the module-side SEE machine after the changes to the SEE machine source code have been made to initialize the compatibility layer.