Sign and deploy CodeSafe 5 SDK apps using csadmin

Signing CodeSafe images

All CodeSafe images must be signed before they can be loaded on to an HSM. Entrust recommends that you have two signing keys: one that you use to sign CodeSafe images that are still under development, and one that you only use for signing tested CodeSafe images that are ready for deployment. In this guide, the two recommended keys are referred to as the development signing key and the production signing key, however you can name these keys as required by your particular development organisation.

Signed CodeSafe images can be loaded to an HSM if the certificate associated with the signing key is also loaded to that HSM. Therefore you must ensure that the certificates associated with development signing keys are never distributed outside of your development organisation. If you develop CodeSafe images for customers who are not part of your development organisation, you should only send them CodeSafe images that have been signed by, and certificates that are associated with, a production signing key.

You can create as many signing keys as you require. This allows you to use different signing keys to group your CodeSafe images based on whatever criteria you require. For example, you could use different signing keys based on the intended customer or on the functionality of the CodeSafe image.

You must keep track of which key has been used to sign which image and ensure that the end user receives the correct matching certificate and does not receive certificates that they do not require.

The following sections describe the commands used to create the signing keys and certificates followed by a worked example showing the entire process of building, signing, loading, and running a CodeSafe image.

The csadmin utility tool

The following examples use a Linux machine for the deployment of CodeSafe applications. The same commands can be applied to a Windows machine.

The csadmin tool is used to manage CodeSafe images throughout the development and deployment process. It is available as part of the Security World ISO. It must be installed as instructed in Install the CodeSafe 5 SDK on Linux and Install the CodeSafe 5 SDK on Windows.

You must be logged in as an Administrator or a user with local administrator rights to execute csadmin commands.

You must have /opt/nfast/bin in your PATH environment variable to use csadmin.

Executing csadmin displays the available subcommands:

To view the help text included here while using csadmin, run a command or sub-command with the -h|--help option.

The csadmin tool covers CodeSafe application deployment from both the perspective of a CodeSafe application developer and a CodeSafe application user. The help text displays the complete set of commands available. This document details the commands that are specific to CodeSafe developers. See the User Guide for your HSM to see an overview of the csadmin tool and details of the other commands available.

Generate loadable images

CS5 images are generated with csadmin image generate. Before generating an image, the CodeSafe 5 SDK must be previously installed. This includes an installation of Python and nfpython suitable to run on the HSM. To display the generate operation’s usage, execute it with the --help option :

$ csadmin image generate --help
usage: csadmin image generate [-h] --package-name PACKAGE_NAME --version-str VERSION_STR --entry-point ENTRY_POINT --network-conf NETWORK_CONF
--packages-conf PACKAGES_CONF --rootdir ROOTDIR [--verbose] CS5FILE

positional arguments:
  CS5FILE               The cs5 file to be handled

optional arguments:
  -h, --help            show this help message and exit
  --package-name PACKAGE_NAME
                        Short name describing the product contents
  --version-str VERSION_STR
                        Version number of this package contents
  --entry-point ENTRY_POINT
                        Full path, within the container, to the entry point application to be executed upon start
  --network-conf NETWORK_CONF
                        Full path, outside the container, to the network config file to be copied into the container meta data
  --packages-conf PACKAGES_CONF
                        Full path, outside the container, to the extra packages config file used to copy additional packages into container rootfs
  --rootdir ROOTDIR     Directory where the contents of the new container are located
  --verbose             Print verbose logs

Generating an image requires the name of the CS5 file and the use of the following mandatory command-line arguments:

--package-name
--version-str
--entry-point
--network-conf
--packages-conf
--rootdir

The following items are also required:

A container directory (not necessarily named "container") that points to what would be the SEE machine’s root directory.

This directory must include any files used by the application, including the entry point program, for example:
```
container/
├── home
└── usr
    └── bin
        └── entrypoint
```
The container directory can be located anywhere in the host file system. Ensure you pass the full path to the generate command via the --rootdir argument, as specified in the command usage.
An entry point program.

This is the program that runs when the SEE container is started (on launcher start). It must be made executable so it can be launched accordingly. In the previous example, the entry point program is in container/usr/bin/entrypoint.
A network configuration file. (See Example network-conf.json file.)

The valid range for container_port is 1024 - 65535.
A file with extra packages information. (See Example extra-packages-conf.json file)

Example csadmin image generate operation

$ csadmin image generate --package-name "MyCodeSafeApp" --entry-point /usr/bin/entrypoint --network-conf network-conf.json --packages-conf extra-packages-conf.json --version-str 1.0  --rootdir container/ myapp.cs5
INFO: creating content package
INFO: Creating content tar ball
INFO: Creating copy of source file: network-conf.json into dest: cs5_build/meta/network-conf.json
INFO: Creating copy of source file: extra-packages-conf.json into dest: cs5_build/meta/extra-packages-conf.json
INFO: Creating compressed tar ball cs5_build/extra-packages.tar.gz out of cs5_build/extra-packages
INFO: Creating compressed tar ball cs5_build/container.tar.gz out of container/
INFO: Creating uncompressed tar ball content.tar out of cs5_build
INFO: creating cs5 file myapp.cs5
INFO: adding content hash to the package

INFO: File myapp.cs5 was created successfully!

--entry-point points to the full path of the executable program relative to the container’s root.

Example extra-packages-conf.json file

{
    "packages": [{
            "package": "python",
            "description": "python 3.8 binaries",
            "host_path": "python3/csd5/ppc64/usr/bin",
            "machine_path": "usr/bin",
            "exclude": ""
        },
        {
            "package": "python",
            "description": "python 3.8 libraries",
            "host_path": "python3/csd5/ppc64/usr/lib/python3.8",
            "machine_path": "python3",
            "exclude": ""
        },
        {
            "package": "binaries",
            "description": "binaries for script support 1.0.0",
            "host_path": "c/csd5/rootfs/bin",
            "machine_path": "bin",
            "exclude": ""
        }
    ]
}

Example network-conf.json file

{
    "incoming" : {
        "tcp" : {
            "protos" : [ "ipv6" ], "ports" : [ 8000, 8001, 8888 ]
        }
    },
    "outgoing" : {
        "udp" : {
            "protos" : [ "ipv4" ], "ports" : [ 53 ]
        }
    },
    "ssh_tunnel" : {
             "container_port" : 8000
    }
}

Example entry point script

#!/bin/sh
export PYTHONHOME=/usr/bin
export PYTHONPATH=/usr/lib/python3.8/:/usr/lib/python3.8/lib-dynload:/usr/lib/python3.8/site-packages
python -m http.server --directory / --bind :: 8888

Sign images

CodeSafe images are signed with csadmin image sign. A signing key must be created before the CS5 file is signed, because signing must be done using HSM-protected keys.

csadmin image sign --help
usage: csadmin image sign [-h] --askeyname ASKEYNAME --devkeyname DEVKEYNAME --devcert DEVCERT [--startdate STARTDATE] [--expirydate EXPIRYDATE]
                          [--out OUT] [--verbose]
                          CS5FILE

positional arguments:
  CS5FILE               The cs5 file to be signed

options:
  -h, --help            show this help message and exit
  --askeyname ASKEYNAME
                        Name (ident) of the application signing key
  --devkeyname DEVKEYNAME
                        Name (ident) of the developer signing key
  --devcert DEVCERT     The signed developer certificate PEM file
  --startdate STARTDATE
                        Start of validity period for the signed ASK cert in Unix time (default: no start date)
  --expirydate EXPIRYDATE
                        End of validity period for the signed ASK cert in Unix time (default: no expiration date)
  --out OUT             Name of the output file. If not specified, the cs5 file is overwritten.
  --verbose             Print verbose logs

For more information, see Signing CodeSafe images.

Create a developer ID certificate

Developer ID certificates are created with csadmin ids create. This command generates a developer ID key with the given name (if it doesn’t exist already) and a certificate signing request so a certificate can be generated (see Signing CodeSafe images):

$ csadmin ids create --help
usage: csadmin ids create [-h] --keyname KEYNAME [-m MODULE] --x509cname COMMON_NAME [--x509country COUNTRY]
                          [--x509province STATE_OR_PROVINCE] [--x509locality LOCALITY] --x509org ORGANIZATION [--x509orgunit ORGANIZATIONAL_UNIT] [--verbose]

options:
  -h, --help            show this help message and exit
  --keyname KEYNAME     Name for the certificate's key.
  -m MODULE, --module MODULE
                        Module to generate the key with.
  --x509cname COMMON_NAME
                        The CN part of the key's DN.
  --x509country COUNTRY
                        The C part of the key's DN.
  --x509province STATE_OR_PROVINCE
                        The ST part of the key's DN.
  --x509locality LOCALITY
                        The L part of the key's DN.
  --x509org ORGANIZATION
                        The O part of the key's DN.
  --x509orgunit ORGANIZATIONAL_UNIT
                        The OU part of the key's DN.
  --verbose             Print verbose logs

Example CodeSafe developer process

The examples in this chapter show how various csadmin commands can be used to create a signed CodeSafe image for deployment. For details of the csadmin tool (See The csadmin utility tool)

Create developer ID keys

To sign CodeSafe images, you must create a developer ID for your development organisation and obtain a matching certificate from Entrust. You can obtain a certificate by creating a Certificate Signing Request (CSR) file and sending it to Entrust Support who will process the CSR and return a signed certificate to you.

Entrust strongly recommend that you create at least two developer IDs: a 'development' ID for signing CodeSafe images that are still in development, and a 'production' ID for signing images that are ready to be deployed.

The csadmin ids create command provides the functionality to generate a developer ID key if it does not already exist, as well as the CSR file in a single step.

Keep track of which certificate matches each developer ID key. When you send a signed CodeSafe image to a customer you will need to also send them the matching certificate for them to be able to load the image on their HSM.

The developer ID keys only need to be created once. The certificates matching them have a limited validity period and will need to be refreshed before they expire.

When you refresh a certificate you must send it to anyone who received a copy of a SEE machine that is signed by the key matching that certificate. Users of SEE machines require a valid certificate every time they start the SEE machine.

To refresh a certificate, use the csadmin ids create command with an existing key. This creates a CSR file for the existing key, which should be sent to Entrust Support who will process the CSR and return a new signed certificate.

The integrity of the signing process relies on the procedural steps being followed to secure a CodeSafe application image.

For this reason, developer ID keys are OCS protected and therefore to sign a CodeSafe application a quorum of OCS cards and associated passphrases must be available for the signing.

Only use your 'production' developer ID key to sign fully tested CodeSafe images that you know to be ready for deployment.

Generate an HSM-protected developer ID key and CSR

csadmin ids create --keyname developerid --x509cname developer.entrust.com --x509country US --x509province Minnesota --x509locality Shakopee --x509org "CodeSafe App Development" --x509orgunit "Entrust CodeSafe"

Generate key 'testdeveloperkey' ...

Loading `TestOCS':
 Module 1: 0 cards of 1 read
 Module 1 slot 0: empty
Card reading complete.

OK
Generate a CSR in 'testdeveloperkey.csr' ...
OK
Created CSR file 'testdeveloperkey.csr'. Please send it to Entrust Support

This creates the CSR file in the location where the command was run.

keyname must conform with character set restrictions. For more information, see the ident entry in the Key properties table in the Key generation options and parameters chapter of the User Guide for your nShield 5 HSM.

This developer ID creation was done with TestOCS, quorum of 1/1. Exact output might vary slightly with different OCS quorums.

Send the resulting CSR to customer support to be signed by Entrust.

Load your certificate

When you receive your signed certificate chain back from Entrust Support, load the developer ID certificate chain in the HSM using csadmin ids add.

You can use csadmin ids list to view the loaded certificate.

$ csadmin ids add entrust_developerid_cert_chain.pem
FEDC-BA09-8765        SUCCESS
$ csadmin ids list
FEDC-BA09-8765        SUCCESS
Certificates:
{'serialNumber': '1', 'subject': 'Common Name: developer.entrust.com, Organizational Unit: Entrust CodeSafe, Organization: Entrust, Locality: Shakopee, State/Province: Minnesota, Country: US', 'keyid': 'abcdef12345678900987654321fedcbaabcdef12', 'authKeyid': '0987654321fedcbaabcdef123456789009876543', 'notBefore': '2023-01-01 12:34:56+00:00', 'notAfter': '2024-01-01 12:34:56+00:00'}
{'serialNumber': '2', 'subject': 'Common Name: developer.entrust.com, Organizational Unit: Entrust CodeSafe, Organization: Entrust, Locality: Shakopee, State/Province: Minnesota, Country: US', 'keyid': '1234567890abcdeffedcba098765432112345678', 'authKeyid': 'fedcba09876543211234567890abcdeffedca098', 'notBefore': '2023-01-01 12:34:56+00:00', 'notAfter': '2024-01-01 12:34:56+00:00'}

Generate an Application Signing Key (ASK) with generatekey

This generates a simple ECDSA NIST521P key.

The following example specifies the key to be protected with an OCS.

/opt/nfast/bin/generatekey --batch --module=1 simple type=ECDSA curve=NISTP521 ident=ask plainname=ask protect=token

Sign the CodeSafe image

This example signs a CodeSafe application called hello.cs5:

csadmin image sign --askeyname ask --devkeyname developerid --devcert ~/ca/developerid_cert.pem --out ~/hello-signed.cs5 ~/hello.cs5