Create and sign CodeSafe 5 applications with csadmin

Table of Contents

Running csadmin
Developer Identity management
Image creation and signing

The csadmin tool is new to CodeSafe 5. It performs a variety of operations for creating and managing CodeSafe 5 machines. It replaces a number of other utilities such as tct2, elftool and loadmache; these are not needed for CodeSafe 5.

This page describes functionality available in version 13.9.3 or later of the CodeSafe 5 SDK, and version 13.8.4 and later of the nShield 5s firmware. Earlier version of the SDK and firmware do not support all the features described here.

Running csadmin

csadmin itself is included in the main Security World software distribution. Ensure you have completed the steps described at Install the Security World software, and that /opt/nfast/bin (Linux) or C:\Program Files\nCipher\nfast\bin (Windows) is included in your PATH.

A number of csadmin subcommands create or use Security World keys. Your HSM must be enrolled in a Security World (see nShield Security World v13.9.3 Management Guide and sub-pages) to perform these operations.

Subcommands for management of CodeSafe 5 machines on an HSM require access to the launcher service’s SSH client key. You should run these commands as root or Administrator, or as a user in the appropriate group as described in Permissions on SSH keys.

All csadmin subcommands support the -h or --help option for displaying the help text associated with that command.

Developer Identity management

When your company or organization starts to develop CodeSafe 5 applications, you must create a Developer ID key and obtain a certificate provided by Entrust nShield Technical Support, which links that key to the organization’s real-world identity. For a description of Developer ID keys and related topics, see CodeSafe 5 Application Authentication.

Create a Developer ID key and CSR

Developer ID certificates are created with csadmin ids create:

$ csadmin ids create --help
usage: csadmin ids create [-h] --keyname KEYNAME [--appname APP] [-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.
  --appname APP         appname (e.g. simple, seeinteg) of 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

The KEYNAME parameter is the Security World name (ident) for the key. If a key with this name doesn’t exist it is created using the appropriate parameters; if it already exists a new CSR is generated for it.

The X.509 ORGANIZATION and COMMON_NAME fields should match the name and DNS name associated with your organization, as understood by Entrust Technical Support.

Example usage

$ csadmin ids create --keyname developerid --x509cname yourcompany.com --x509org "yourorganization" --x509orgunit "CodeSafe App Development"

Generate key 'developerid' ...

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

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

The output file developerid.csr is a short ASCII text file which can be send via email, or uploaded to the support portal.

The certificate returned will be another short text file; in these examples we use developerid.pem to refer to this file. This contains no secret information so can be made available in source repositories or from file servers.

Upload and view Developer ID certificates

If you use hsc_codesafe automatic configuration utility, you do not need to upload Developer ID certificates manually. You should ensure the certificate file is available at /opt/nfast/kmdata/cscerts for Linux, or C:\ProgramData\nCipher\Key Management Data\cscerts for Windows. The certificate will be uploaded when required by the hsc_codesafe utility.

Developer ID certificates can be uploaded to an HSM using the csadmin ids add subcommand:

$ csadmin ids add developerid.pem
FEDC-BA09-8765        SUCCESS

The list of currently loaded certificates is retrieved using csadmin ids list:

$ csadmin ids list
FEDC-BA09-8765        SUCCESS
Certificates:
{'serialNumber': '705640309799691626348045512084088225642474535983', 'subject': 'Common Name: CodeSafe Development, Organizational Unit: nCipher, Organization: Entrust, Country: GB', 'keyid': '406386a0f3de84618ce0ee4022f67aa86768e6a1', 'authKeyid': 'd81e9f34b89c76b5c20cddd489b6f2d8d66cafd5', 'notBefore': '2023-03-03 09:25:25+00:00', 'notAfter': '2033-03-13 09:25:25+00:00'}
{'serialNumber': '116622002464887670342028053697306624797', 'subject': 'Common Name: yourcompany.com, Organization: yourorganization, Organizational Unit: CodeSafe App Development', 'keyid': 'b6687020bb527f56ef426d174eee61ac16baa16d', 'authKeyid': '406386a0f3de84618ce0ee4022f67aa86768e6a1', 'notBefore': '2025-10-30 16:28:00+00:00', 'notAfter': '2028-10-30 16:27:59+00:00'}

The certificate file you receive back from Entrust Support will contain a chain of certificates, including the Entrust issuing CA’s certificate. Both certificates will be loaded by csadmin ids add, so it is normal to see two or more entries in the above list.

Check a Developer ID certificate

The csadmin ids validate command checks whether a certificate in the HSM’s database can currently be validated. The certificate is identified by its serial number.

$ csadmin ids validate -s 705640309799691626348045512084088225642474535983
FEDC-BA09-8765        SUCCESS

The certificate will be validated when it is first uploaded. If this operation fails the likely reasons are (a) the certificate has expired, or (b) the Entrust Issuing CA certificate has been removed from the database.

Retrieve a Developer ID certificate

A copy of a certificate in the HSM’s database can be retrieved with csadmin ids get. Again, the certificate is identified by its serial number.

$ csadmin ids get -s 705640309799691626348045512084088225642474535983
DE5C-23C7-E473        Certificate: -----BEGIN CERTIFICATE-----
MIIDKDCCAoqg...
-----END CERTIFICATE-----

Remove a Developer ID certificate

This is done with the csadmin ids remove command, specifying the certificate’s serial number:

$ csadmin ids remove -s 116622002464887670342028053697306624797
FEDC-BA09-8765        SUCCESS

Image creation and signing

Create an image file

The csadmin image generate command takes a directory containing a CodeSafe 5 machine image, and packs it into an CodeSafe 5 image file. By convention these have the extension .cs5. The file generated by this command does not contain any signatures; these are added later using csadmin image sign.

$ 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

PACKAGE_NAME is the package name associated with the ASK; it does not need to match either the Security World name (ident) of the ASK, or of the output file, but it is recommended that a consistent naming convention is adopted by the developer.

VERSION_STR can be chosen freely. It can be retrieved using csadmin image inspect (below) but is not otherwise interpreted by the HSM.

ENTRY_POINT, NETWORK_CONF, PACKAGES_CONF and ROOTDIR specify the image contents and control information. They are described in detail at Image creation options.

Example usage

$ 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!

Inspect a CodeSafe 5 image

Use csadmin image inspect to view the information in a .cs5 file header:

$ csadmin image inspect webserver_mod.cs5
Type               codesafe-container
Platform           nShield5
Format             1
PackageName        webserver_mod
Version            1.0
EntryPoint         /usr/bin/entrypoint

Create an Application Signing Key

An Application Signing Key can be created using the generatekey utility. It should use the seeinteg app name, and be an ECDSA key using the NIST P521 curve. It is strongly recommended that this uses OCS ('token') protection. For example:

/opt/nfast/bin/generatekey --batch --module=1 --cardset=some-ocs seeinteg type=ECDSA curve=NISTP521 ident=ask-myapp plainname=ask-myapp protect=token

Sign with an Application Signing Key

A CodeSafe 5 machine must be signed with an ASK before it can be run. This is achieved with the csadmin image sign command:

usage: csadmin image sign [-h] --askeyname ASKEYNAME [--askapp ASKAPP] [--devkeyname DEVKEYNAME] [--devapp DEVAPP]
                          [--devcert DEVCERT] [--startdate STARTDATE] [--expirydate EXPIRYDATE] [--signedask SIGNEDASK] [--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
  --askapp ASKAPP       appname (e.g. simple, seeinteg) of the application signing key
  --devkeyname DEVKEYNAME
                        Name (ident) of the developer signing key
  --devapp DEVAPP       appname (e.g. simple, seeinteg) 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)
  --signedask SIGNEDASK
                        Signed ASK certificate file. Developer key, start, and expiry date params are ignored when present
  --out OUT             Name of the output file. If not specified, the cs5 file is overwritten
  --verbose             Print verbose logs

This must be run in an environment where the ASKEYNAME key is available (i.e. with an attached HSM in the ASK’s Security World). There are two different workflows for signing:

"Online" workflow: if the Developer ID key is also available in this environment, the DEVKEYNAME and DEVAPP parameters identifying this key should be specified. In this case the --startdata and/or --expirydate options may be specified.
"Offline" workflow: this avoids the need to use the Developer ID key when signing an application. In this workflow you use the --signedask option instead of --devapp and --devcert. The offline signing workflow is described here, and the associated commands are documented at Offline signing commands.

The --devcert option must be given, to supply information about the Developer ID key. However, this certificate is not copied into the .cs5 file itself; it is uploaded separately (see Upload and view Developer ID certificates) when the CodeSafe 5 machine is deployed on an HSM.

Add extra signatures to a CodeSafe 5 image

The csadmin image signextra command allows a CodeSafe 5 image to be signed using additional keys which are not ASKs. This enables interoperation with CodeSafe deployments on XC and earlier HSMs, where a existing seeinteg key signs the machine image, and Security World application keys have been bound to that seeinteg key (see Application signatures and ACLs).

$ csadmin image signextra --help
usage: csadmin image signextra [-h] --appname APPNAME --key KEY
                               [--keymech {SHA256Hash,SHA384Hash,SHA3b256Hash,SHA3b384Hash,SHA3b512Hash,SHA512Hash}] [--out OUT]
                               [--verbose]
                               CS5FILE

positional arguments:
  CS5FILE               The cs5 file to be signed

options:
  -h, --help            show this help message and exit
  --appname APPNAME     appname (e.g. simple, seeinteg) of the signing key
  --key KEY             Name (ident) of the signing key
  --keymech {SHA256Hash,SHA384Hash,SHA3b256Hash,SHA3b384Hash,SHA3b512Hash,SHA512Hash}
                        Key hashing mechanism (default SHA512Hash).
  --out OUT             Name of the output file. If not specified, the cs5 file is overwritten
  --verbose             Print verbose logs

The APPNAME and KEY parameters specify the signing key. The current firmware supports RSA, DSA, ECDSA and KCDSA (if enabled) key types here.

Example usage

$ csadmin image signextra --appname seeinteg --key seeintkeyname --keymech SHA512Hash --out ~/hello-signed-extra.cs5 ~/hello.cs5

Offline signing commands

The Developer ID key can be kept in an offline system, or use a different HSM or Security World to the ASK. The offline signing workflow uses two operations described below.

Generate an ASK certificate message

When an ASK is created, it is bound to a CodeSafe 5 application identity (the 'package' name) by a signature using the Developer ID key.

The csadmin image presignask command generates a message to be signed:

$ csadmin image presignask --help
usage: csadmin image presignask [-h] --packagename PACKAGENAME --askeyname ASKEYNAME [--askapp ASKAPP] --devcert DEVCERT
                                [--startdate STARTDATE] [--expirydate EXPIRYDATE] --out OUT [--verbose]

options:
  -h, --help            show this help message and exit
  --packagename PACKAGENAME
                        Name of the package
  --askeyname ASKEYNAME
                        Name (ident) of the application signing key
  --askapp ASKAPP       appname (e.g. simple, seeinteg) of the application 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
  --verbose, -d         Print verbose logs

The ASKAPP and ASKEYNAME specify the key which will be placed in the certificate message. This command must be run in a Security World environment where at least the public key value for this key is available.

PACKAGENAME is the Developer-chosen package name for that key. This must match the PACKAGENAME which will be given to csadmin image create when creating images to be signed with this ASK.

The DEVCERT file must be available (to supply information about the Developer ID key), but the Developer ID key itself is not needed.

Sign an ASK Certificate message

The csadmin image signask command uses the Developer ID key to sign the output from presignask operation above. It creates a file containing an AppKeyCertificate record, suitable for passing as the --signedask parameter to csadmin image sign.

$ csadmin image signask --help
usage: csadmin image signask [-h] --devkeyname DEVKEYNAME [--devapp DEVAPP] --devcert DEVCERT --out OUT [--verbose] ASKFILE

positional arguments:
  ASKFILE               The unsigned ASK message file being signed

options:
  -h, --help            show this help message and exit
  --devkeyname DEVKEYNAME
                        Name (ident) of the developer signing key
  --devapp DEVAPP       appname (e.g. simple, seeinteg) of the developer signing key
  --devcert DEVCERT     The signed developer certificate PEM file
  --out OUT             Name of the signed output ASK cert file
  --verbose, -d         Print verbose logs