Working with CodeSafe

CodeSafe applications

To run CodeSafe applications on your system, you must have enabled the Secure Execution Engine (SEE) by purchasing and enabling an appropriate SEE activation licence as described in Enabling optional features.

If you want to develop your own CodeSafe applications, you must also purchase the CodeSafe developer kit.

An SEE application is typically a standalone SEE machine that is loaded automatically by the hardserver (for example, a CodeSafe C application).

Check the documentation that your CodeSafe application vendor supplies for information about how to set up and use the application, as well as for any other installation and configuration information.

CodeSafe applications are standalone applications, but each CodeSafe C application can consist of multiple parts, and its installation can include several configuration steps. For instructions on installing and configuring each application, see your application vendor’s documentation.

To use a standalone application:

Ensure that the SEE machine for the application is in the /opt/nfast/custom-seemachines (Linux) or %NFAST_HOME%\custom-seemachines (Windows) directory on the remote file system.

If an SEE machine has previously been loaded on the HSM, press the Clear button on the front of the unit before proceeding to the next step. This clears the current SEE machine from memory.
From the main menu on the front panel of the HSM, select CodeSafe.

To enable the HSM to publish the SEE World for multiple clients, enter the following information when prompted:

The name of the SEE machine file.
The name of the user data file, if required.

The type of custom SEE machine you are using (select SEElib or BSDlib sockserv).

This option is only available if you have provided a valid user data file in step 2. If BSDlib sockserv is selected, worldid_pubname, postload_prog, and postload_args will be passed to load_seemachine.

Log in to a host machine as a user in the nfast group and run the following command (m1 is the Security World’s module number for the HSM whose front panel you used in the previous steps):
```
sudo /opt/nfast/bin/nopclearfail -c -w -m1
```

For detailed descriptions of the options in this section, see load_seemachine.

The ID of the SEE World to create.

This option is only available if you have selected the SEElib option in the previous step.

To use see-sock-serv directly, you must select BSDlib sockserv.

Remotely loading and updating SEE machines

The SEE remote push facility allows the remote deployment of CodeSafe SEE machines to an nShield HSM, negating the need to physically visit the HSM to load or update the SEE machine. This is achieved by editing the configuration file on the RFS for a specific nShield HSM to specify the new SEE machine, then setting a configuration flag in the config file to true.

Before configuring a module to autonomously run an SEE machine and accept updates using the RFS, the module must be configured to accept remotely-pushed configurations. Refer to the nShield Remote Administration User Guide for more information.

For more information about configuring log file storage options, see Configuring log file storage.

To configure an nShield HSM module to autonomously run an SEE machine and accept updates using the RFS:

Copy the existing config file to a new file called config.new.

In the load_seemachine section of the config.new file for the remote module, add or amend the following settings:

pull_rfs=true
machine_file=mymachinename.sar
userdata=myuserdata.sar
worldid_pubname=publ_name

These settings specify the type, name and user data of the SEE machine you wish to load. For more information about each setting, see load_seemachine.

For CodeSafe Direct, the userdata file must be packed as a SAR file.

The remote module will load the new SEE machine in place of any existing SEE machine. If no machine_file value is set, then pushing the config file will remove any existing machines on the unit.

In the sys_log section of the config.new file for the remote module, add or amend the following settings:

behaviour=push
push_interval=1

These settings control how and where log messages are written. Using the example above, messages will be written to the system.log and hardserver.log files of the module, which are accessible using the remote file system. You may wish to revise the push_interval to a higher value once the nShield HSM has successfully loaded the new SEE machine.

Run nopclearfail to clear the module, followed by enquiry to check that the module is ready.
Run cfg-pushnethsm to push the new config file to the module.
Run nopclearfail -c -w.

To load a new SEE machine to multiple nShield HSMs, we recommend scheduling down time for each HSM, upgrading them on a per HSM basis. Each nShield HSM configuration file is specific to an individual HSM and each configuration file should be updated separately to load the new SEE machine.