CodeSafe 5 v13.9.5 Developer Guide

Introduction

CodeSafe 5 evolves Entrust’s established Secure Execution Engine (SEE) technology, which allows third-party code to run within the HSM. The CodeSafe 5 product comprises an SDK for application development, and tooling for managing the deployment of those applications on HSMs.

CodeSafe 5 is available on the 5s, 5c, and 5c 10G HSM models. Running a CodeSafe 5 application is a licensable feature.

CodeSafe basic concepts

A CodeSafe 5 application is built using the SDK and assembled into a CodeSafe 5 image (.cs5) file. The developer then applies one or more signatures to the image binary, typically using keys held in a Security World, and the resulting signed image is loaded onto one or more nShield HSMs. These signatures are verified before application execution begins.

The application runs and receives commands (in some application-specific form) from an external client. It may perform its own computations, and has access to the nCore API for cryptographic operations. The keys which signed the application can be referenced in nCore command certificates, which in turn allows the creation of Security World keys which can only be used by that application.

All commands, replies, temporary keys and other nCore API objects created by a running CodeSafe 5 application are private to that instance. A running instance is sometimes referred to as a CodeSafe machine, and its data is not visible outside the HSM or to other nCore API clients.

The CodeSafe 5 machine runs in a protected, logically separate environment to the nCore API service; this means that the FIPS 140 validation of the HSM is not affected by the use of a CodeSafe application. Key data held by the nCore API is still subject to the restrictions expressed in its ACL; this remains true even if a CodeSafe machine itself is compromised.

So, CodeSafe applications can implement functionality such as:

  • decrypting messages with one key then re-encrypting with another

  • adding business-specific validation of message data before it is signed

  • securely generating personalisation data for injection into embedded devices

  • implementing custom cryptographic algorithms, communication protocols, etc.

New features in CodeSafe 5

The CodeSafe 5 execution environment is shown below:

CodeSafe 5 Architecture overview

The CodeSafe 5 architecture provides significant enhancements not available on CodeSafe for older Solo+ and XC HSMs, taking advantage of the capabilities of the HSM’s Linux kernel. These include:

  • The application is now a container image, rather than a single executable. It may include multiple executables, and has its own private nonvolatile storage.

  • The container has access to native IPv4 and IPv6 networking. It may accept incoming network connections and make outgoing ones.

  • An SSH server is provided for use by the application, to allow end-to-end secure transport of application data between the HSM and a client.

  • Most commonly-used Linux system calls are supported natively, allowing a wider range of languages to be supported.

  • Each CodeSafe 5 application is linked to the identity of its developer, which is verified by Entrust. The administrator can select which developer identities are permissible on each HSM.

CodeSafe 5 features gives more details.

Management of CodeSafe 5

CodeSafe 5 is managed by a new launcher service, which has its own network port, SSH server, and client credentials. Unlike earlier HSMs, administrators do not install or configure of CodeSafe machines using nCore API commands. This allows separation of the user role for managing CodeSafe 5 machines from the role(s) used for regular cryptographic operations.

Three options are currently supported as launcher service clients:

  • The csadmin tool. This allows the user to issue individual commands to load, start and stop CodeSafe 5 machines from the command line, or from user-written scripts.

  • The hsc_codesafe utility. This provides a more automated way of running and configuring CodeSafe 5 machines, driven from a configuration file and triggered when the state of an HSM changes.

  • KeySafe 5. This is described in the KeySafe 5 User Guide.

Compatibility with CodeSafe on Solo+ and Solo XC

A CodeSafe application for earlier HSMs will need to be recompiled in order to run on a CodeSafe 5 system. The SDK’s seelib library provides a compatible set of API calls to allow dispatch of nCore API commands, and processing of requests from the client. This allows existing sources to be rebuilt with minimal changes.

Also, the SDK now offers a Generic Stub ( nfstub ) library, which is API compatible with the host-side Generic Stub.

Note that the Cmd_SEEJob nCore API command is no longer implemented by the ncoreapi service. Instead, the client sends SEEJob commands directly to the CodeSafe 5 machine via its dedicated SSH tunnel. A client can establish its own SSH connection to send commands directly to the HSM; alternatively the hardserver process can manage the SSH connection, and the client can send SEEJob commands to that hardserver. This is achieved using hsc_codesafe configuration.

It is no longer required that communication with a client application is framed into SEEJob commands. The SSH service (and other network connections) provides a general-purpose pipe which can be used for other protocols. If the CodeSafe 5 application does not start up the compatibility code, it can use other arrangements to accept network connections.