Porting existing CodeSafe applications to CodeSafe 5
Follow the steps in this chapter if you need to port an existing SEE machine to run on CodeSafe 5.
This chapter assumes the perspective of a CodeSafe application developer.
CodeSafe users using third-party CodeSafe applications for HSM models prior to nShield 5 should contact the developer of those applications to obtain a CodeSafe 5 version of the application. Ensure that the third-party CodeSafe developer is a trusted party, and can provide a signed CodeSafe 5 application and associated developer ID certificate issued by Entrust.
Examples of Classic SEE "CSEE" machines that have been ported to CodeSafe 5 can be found in Build and sign example SEE machines on Linux. These are examples from previous HSM models that have been modified to run with CodeSafe 5. 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. |
Communication with the host
Legacy CodeSafe transacted data between host application and module SEE machines by sending SEEJobs via the harderver to the HSM’s nCore API service, onto the CodeSafe application, and back again. TCP communication with the host was supported with a networking emulation layer on top of this protocol.
CodeSafe 5 continues to support SEEJobs via the hardserver, but this protocol is now implemented via a securely negotiated SSH tunnel automatically set up between the client hardserver and the CodeSafe application directly without the nCore API service being required to forward the jobs.
Additionally, the TCP network emulation layer (provided by see-sock-serv and related configuration support for BSDSEE/GLIBSEE applications) on top of the SEEJobs protocol has been removed and replaced with a first-class networking implementation which supports TCP and UDP between the host and the CodeSafe application.
| The module-side SEE machine must be rebuilt and re-signed to function on CodeSafe 5 (CodeSafe applications from previous HSM models cannot run on nShield 5). The host-side client application communicating with the SEE machine may or may not require updates depending on how it interacts with the SEE machine, but details for loading and running the CodeSafe application from the client differ from previous HSM models and will need to be changed. |
SEElib library
The module-side SEElib library behaves the same as before for both communication with the nCore API service on the HSM to execute M_Command commands and also for communication with the host via SEEJobs.
Assuming the use of the default port of 8888 for SEEJobs, no source changes should be required, though it will be necessary to include a network-conf.json as per the CSEE examples to permit port 8888 as the ssh_tunnel port (and not to allow incoming plaintext access to this port).
Host-side applications continue to send SEEJobs (i.e. Cmd_SEEJob and Cmd_FastSEEJob commands) via an nCore connection to the hardserver, using the SEE World ID as the identifier for the SEE machine.
Deployment differences
See Automatic Configuration of CodeSafe 5 Applications for information about automatic loading of CodeSafe 5 applications using the [codesafe] section of the config file or using the hsc_codesafe tool.
The [codesafe] section replaces the [load_seemachine] section used by previous HSM models.
The "CodeSafe Direct" feature of loading a SEE machine from the nShield Connect config file is not supported by nShield 5, but the new [codesafe] section can be used to automatically load a SEE machine from a client hardserver config file instead.
If using this with nShield 5, one client of the nShield 5c should have that [codesafe] configuration as only one CodeSafe application may be run at a time.
|
See the examples in Build and sign example SEE machines on Linux for information about running both TCP/UDP applications and CSEE applications with CodeSafe 5.
The NetSEE examples documentation explains how to configure networking; this replaces the network emulation that legacy see-sock-serv and related configuration provided.
The CSEE examples documentation show how to deploy using published objects for the SEE World ID with the SEE machine automatically loaded via the config file, which is the simplest way to deploy, and was also a supported approach for interacting with SEE machines in legacy CodeSafe.
Applications that were using published objects will require the fewest updates.
If the SEE World ID was previously loaded directly by the host-side application using Cmd_CreateSEEWorld within a hardserver connection, that should now be replaced with Cmd_CreateSEEConnection.
If it was loaded using the seeworld_auth_setup() or seeworld_setup() helper functions from the seeworld.h / seeworld.c example utility code, seeworld_connect() should now be used instead.
If using the SEEWorld class to load the SEE World ID in a Java application, SEEWorld5 should now be used instead.
A SEE World ID is required if communicating with the SEE machine via SEEJobs as it is the handle for those jobs, but it may also be required even when not using SEEJobs if the SEE machine talks (locally) to the nCore API service on the HSM (for example to transact cryptographic M_Command commands such as signing or decryption) as the act of doing the Cmd_CreateSEEConnection from the host creates the permission for the CodeSafe application to use the nCore API service.
|