CodeSafe v13.4.5 Developer Guide

Introduction

CodeSafe is a runtime on the Entrust nShield HSM that allows third-party developers to run their own code within the secure boundary of the module. Using the CodeSafe Developer Kit, developers write their own CodeSafe Apps, cross-compile them and package them to run on the HSM. While on the HSM, the CodeSafe App is segregated from the actual keys loaded onto the module: even the keys the App uses. This means that CodeSafe can be used without affecting the FIPS 140 validation of the module it runs on.

Where the HSMs provide security controls on key usage, CodeSafe provides control over application code. Depending on the runtime used, you’re either sending nCore commands to the HSM, or designing your own protocol to send data and commands back and forth.

The CodeSafe™ Developer Kit includes the Secure Execution Engine (SEE) technology. The CodeSafe product comprises a suite of cross-compilers and support tools that allow you to develop SEE machines.

With CodeSafe, you can build and deploy Trusted Agents to perform application-specific security functions on your behalf on unattended servers, or in unprotected environments where the operation of the system is outside of your direct control. Examples of Trusted Agents include digital meters, authentication agents, time-stamps, audit loggers, digital signature agents and custom encryption processes.

Traditionally, HSMs have protected cryptographic keys within a defined security boundary; SEE allows you to extend that security boundary to include code that utilizes those protected keys. The code itself can be signed and encrypted to provide additional protection.

This manual applies to both the nShield Solo XC and to the nShield Solo PCIe.

Read this guide if …​

Read this guide if you are writing and running SEE applications in C with a SEE-Ready HSM.

This guide:

  • Introduces the concept of the Secure Execution Engine (SEE)

  • Explains how to use the example SEE machines provided on the installation media

  • Describes how to write your own SEE applications in C using the CodeSafe Developer Kit

  • Describes how to run your secure SEE applications using a SEE-Ready HSM

  • Describes how to obtain export certificates for SEE applications, if required

This guide assumes that you are familiar with the concept of Security World, as described in the User Guide. It also assumes that you are familiar with the following documentation:

  • The Cryptographic API Integration Guide, which describes the use of hardware security modules with third-party software products

  • The nCore Developer Tutorial, which explains how to write applications using a hardware security module

  • The nCore API Documentation (supplied as HTML), which describes the nCore C API.

Concepts and terminology introduced in the Cryptographic API Integration Guide, nCore Developer Tutorial, and nCore API Documentation are not explained in this guide.

Conventions

Model numbers

Model numbering conventions are used to distinguish different nShield hardware security devices. In the table below, n represents any single digit integer.

Model number Used for

NH2047

nShield Connect 6000

NH2040

nShield Connect 1500

NH2033

nShield Connect 500

NH2068

nShield Connect 6000+

NH2061

nShield Connect 1500+

NH2054

nShield Connect 500+

NH2075-B

nShield Connect XC Base

NH2075-M

nShield Connect XC Medium

NH2075-H

nShield Connect XC High

NH2079-B

nShield 5c Base

NH2079-M

nShield 5c Medium

NH2079-H

nShield 5c High

NH2082

nShield Connect XC SCAP

NH2089-B

nShield Connect XC Base - Serial Console

NH2089-M

nShield Connect XC Mid - Serial Console

NH2089-H

nShield Connect XC High - Serial Console

NH3003-B

nShield Connect CLX Base - Serial Console

NH3003-M

nShield Connect CLX Mid - Serial Console

NH3003-H

nShield Connect CLX High - Serial Console

nC3nnnE-nnn, nC4nnnE-nnn

nShield Solo PCIe

nC30n5E-nnn, nC40n5E-nnn

nShield Solo XC PCIe

nC30nnU-10, nC40nnU-10

nShield Edge

NC5536E-B

nShield 5s Base

NC5536E-M

nShield 5s Medium

NC5536E-H

nShield 5s High

Security World Software

The default locations for Security World Software and program data directories on English-language systems are summarized in the following table:

Directory name Linux default path Windows environment variable Windows Server 2016 or later

nShield Installation

/opt/nfast/

NFAST_HOME

C:\Program Files\nCipher\nfast

Key Management Data

/opt/nfast/kmdata/

NFAST_KMDATA

C:\ProgramData\nCipher\Key Management Data

Dynamic Feature Certificates

/opt/nfast/femcerts/

NFAST_CERTDIR

C:\ProgramData\nCipher\Feature Certificates

Static Feature Certificates

/opt/nfast/kmdata/hsm-ESN/features

%NFAST_KMDATA%\hsm-esn\features

C:\ProgramData\nCipher\Key Management Data

Log Files

/opt/nfast/log

NFAST_LOGDIR

C:\ProgramData\nCipher\Log Files

User Log Files

/home/<user>/nshieldlogs

NFAST_USER_LOGDIR

C:\Users\<user>\nshieldlogs

Remote Static Feature Certificates

%NFAST_KMDATA%\hsm-ESN\features

Remote Static Feature Certificates

%NFAST_KMDATA%\hsm-ESN\features
Dynamic feature certificates must be stored in the directory stated above. The directory shown for static feature certificates is an example location. You can store those certificates in any directory and provide the appropriate path when using the Feature Enable Tool. However, you must not store static feature certificates in the dynamic features certificates directory.

The instructions in this guide refer to the locations of the software installation and program data directories as follows:

  • By name (for example, Key Management Data).

  • Linux: By absolute path (for example, /opt/nfast/kmdata).

  • Windows: By nShield environment variable names enclosed with percent signs (for example, %NFAST_KMDATA%).

NFAST_KMDATA cannot be a symbolic link.

If the software has been installed into a non-default location:

  • Linux: Create a symbolic link from /opt/nfast/ to the directory where the software is actually installed.

  • Windows: Ensure that the associated nShield environment variables are re-set with the correct paths for your installation. For more information about creating symbolic links, see your operating system’s documentation.

Windows only

By default, the Windows C:\ProgramData\ directory is a hidden directory. To see this directory and its contents, you must enable the display of hidden files and directories in the view settings of the Folder Options.

The absolute paths to the Security World Software installation directory and program data directories are stored in the indicated nShield environment variables at the time of installation If you are unsure of the location of any of these directories, check the path set in the environment variable.

With previous versions of Security World Software, the Key Management Data directory was located by default in C:\nfast\kmdata. The Feature Certificates directory was located by default in C:\nfast\fem, and the Log Files directory was located by default in C:\nfast|log.
Utility help options

Unless noted, all the executable utilities provided in the bin subdirectory of your nShield installation have the following standard help options:

  • -h|--help displays help for the utility

  • -v|--version displays the version number of the utility

  • -u|--usage displays a brief usage summary for the utility.

Requirements

To write and run a SEE C application on the HSM, you need:

  • A SEE-Ready hardware security module

    To determine whether your HSM is SEE-Ready, refer to the product data sheet for your HSM.
    Encrypted SEE machines are not currently supported for use with nShield Connects. When the SEEMachine binary is installed on the Connect itself for automated loading at boot, the SEE Confidentiality key is not available. However, when a client host loads a SEEMachine, it has access to the SEE Confidentiality key and can cause the binary to be decrypted. In this scenario, the Connect works fine with encrypted SEEMachine binaries.

  • A Feature Enable smart card for activating the SEE capabilities of your HSM

  • The CodeSafe Developer Kit (supplied on this installation media)

  • An appropriate GCC compiler (supplied on this installation media) for the target HSM.

You must have installed your SEE-Ready HSM (as instructed in the Installation Guide) and the necessary Security World for nShield for the CodeSafe Developer Kit (as instructed in the User Guide). You must install at least the following software component bundles included on the installation media:

  • hwsp Hardware Support

  • ctls Core Tools

  • csd CodeSafe Developer

  • gccsrc Prebuilt PowerPC GCC for CodeSafe/C

When you have installed and configured your SEE-Ready HSM, to make full use of SEE, you must create a Security World by using one of the following tools:

  • The new-world utility

  • KeySafe

  • The front panel (nShield Connects only).

For detailed information about creating Security Worlds, see the User Guide.

Further information

This guide forms one part of the information and support provided by Entrust.

The nCore API Documentation is supplied as HTML files installed in the following locations:

  • API reference for host:

    • Linux: /opt/nfast/document/ncore/html/index.html

    • Windows: %NFAST_HOME%\document\ncore\html\index.html

  • API reference for SEE:

    • Linux: /opt/nfast/document/csddoc/html/index.html

    • Windows: %NFAST_HOME%\document\csddoc\html\index.html

We recommend that you monitor the Announcements & Security Notices section on Entrust nShield Support, https://nshieldsupport.entrust.com, where any announcement of Security advisories will be made.

Security advisories

If Entrust becomes aware of a security issue affecting nShield HSMs, Entrust will publish a security advisory to customers. The security advisory will describe the issue and provide recommended actions. In some circumstances the advisory may recommend you upgrade the nShield firmware and or image file. In this situation you will need to re-present a quorum of administrator smart cards to the HSM to reload a Security World. As such, deployment and maintenance of your HSMs should consider the procedures and actions required to upgrade devices in the field.

The Remote Administration feature supports remote firmware upgrade of nShield HSMs, and remote ACS card presentation.

We recommend that you monitor the Announcements & Security Notices section on Entrust nShield, https://nshieldsupport.entrust.com, where any announcement of nShield Security Advisories will be made.

Contacting Entrust nShield Support

To obtain support for your product, contact Entrust nShield Support, https://nshieldsupport.entrust.com.