Create and sign CodeSafe 5 applications with csadmin

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

This page describes functionality available in version 13.9.3 or later of the CodeSafe 5 SDK, and nShield 5s firmware version 13.8.4 and later. Earlier versions 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.6 Management Guide and sub-pages) to perform these operations.

Subcommands for management of CodeSafe 5 applications 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 keys, and their associated certificate requests (CSRs), 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

In this command:

KEYNAME 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, otherwise this command generates a fresh CSR for the existing key. The Developer ID key should be OCS-protected.
ORGANIZATION and COMMON_NAME 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 sent 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

Manage Developer ID certificates on an nShield 5c appliance

When CodeSafe 5 applications are auto-loaded from the [codesafe] section of the nShield 5c (Connect) appliance’s own config file, the required Developer ID certificates are loaded automatically (see the tip under Upload and view Developer ID certificates), and no client has direct access to the csadmin utility on the appliance. In that case, use the appliance-cli cs5 commands to list or remove the loaded certificates on the appliance if required (replace -m1 with the module number of the 5c):

appliance-cli -m1 cs5 certlist lists the certificates currently loaded on the appliance.
appliance-cli -m1 cs5 certremove <serial-number> removes the certificate with the given serial number.

In the current release these commands are refused while auto-load is enabled (enabled=yes in the [codesafe] section), reporting Command '<name>' unavailable as Codesafe 5 autoload currently configured on Connect 5c. To list or remove certificates, temporarily set enabled=no in the [codesafe] section and apply the configuration, then run the command. A CodeSafe 5 application that is already running is not stopped by this change.

See Auto-Load Configuration of CodeSafe 5 Applications via the nShield 5c for appliance auto-load configuration.

Image creation and signing

Create an image file

The csadmin image generate command takes a directory containing a CodeSafe 5 application container contents, and packs it into a 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

In this command:

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

After an image has been signed, and optionally encrypted, csadmin image inspect reports additional fields, including Signed, SigningKeys, SHA512Hash, and (for an encrypted image) Encrypted and EncryptKey. See Encrypt a CodeSafe 5 image for an example.

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 image 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]
                          [--enckey ENCKEY] [--encapp ENCAPP]
                          [--encauthkey ENCAUTHKEY] [--encauthapp ENCAUTHAPP]
                          [--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
  --enckey ENCKEY       Optional name (ident) of key for image encryption
  --encapp ENCAPP       Appname for ENCKEY (default 'seeconf')
  --encauthkey ENCAUTHKEY
                        Optional name (ident) of the key to authorize use of
                        ENCKEY. If --enckey is but --encauthkey is not
                        specified, the ASK is used for authorization.
  --encauthapp ENCAUTHAPP
                        Optional appname for ENCAUTHKEY (default 'simple';
                        ignored if --encauthkey is not specified)
  --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 (that is, 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, you can use the DEVKEYNAME and DEVAPP parameters to identify this key should be specified. In this case the --startdate 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.

You must specify the --devcert option to supply information about the Developer ID key. However, the Developer ID certificate is not copied into the .cs5 file itself; it is uploaded separately (see Upload and view Developer ID certificates) when the CodeSafe 5 application is deployed on an HSM. This allows the certificate to be renewed without requiring a new .cs5 file.

The csadmin image sign command can also encrypt the image in the same step, using the --enckey, --encapp, --encauthkey and --encauthapp options. See Encrypt a CodeSafe 5 image.

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 an existing seeinteg key signs the application 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

If a CodeSafe 5 machine has already been loaded on the HSM, adding an extra signature to its image using csadmin image signextra does not automatically cause the machine to be reloaded.

If the machine continues to run with the previously loaded image, verification of the newly added signature will fail, and VerifyFailed messages may be reported in the logs.

To ensure that the updated image is used, configure the hardserver to force a reload of the CodeSafe 5 machine when the image changes. This can be done by enabling the force_reload setting in the hardserver configuration.

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

In this command:

ASKAPP and ASKEYNAME specify the key which will be placed in the certificate message. You should run this command 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 application. This must match the PACKAGENAME which will be given later to csadmin image generate, when creating images to be signed with this ASK.
You should ensure the DEVCERT file is 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 the 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

Encrypt a CodeSafe 5 image

CodeSafe 5 images can optionally be encrypted so that the image contents are confidential at rest. An encrypted image is decrypted only inside the HSM, at load time; the plaintext image is never exposed on the host.

Encryption uses AES-256-GCM. The image signatures are computed over the plaintext content, whose hashes are stored separately in the image. Because of this:

An image can be signed first and encrypted afterwards, or signed and encrypted in a single csadmin image sign command (see Sign and encrypt in a single command).
Additional signatures can still be added with csadmin image signextra after the image has been encrypted.

Signing and encryption are separate operations, so they can be performed in different Security Worlds. When you run csadmin image encrypt as its own step, the seeconf encryption key (and the seeinteg key that certifies it) can belong to a different Security World from the Application Signing Key (ASK) and the Developer ID key. The only requirement is that the seeconf key and its certifying seeinteg key belong to the same Security World, so that they can be loaded together during encryption. Signing and encryption can only be combined in one csadmin image sign command when all the keys involved are in the same Security World.

Encrypting an image raises its file format version to 2. An encrypted image can only be loaded on an HSM whose firmware supports CodeSafe 5 image encryption. On older firmware, loading fails with an error such as File version was 2; this tool only supports up to version 1.

Create an image encryption key

The encryption key is an AES-256 seeconf key created with the generatekey utility. It should be generated module-protected to support automatic loading. The seeintegname parameter must be specified to designate an existing seeinteg key that must be presented to authorize use of the encryption key for the encrypt operation. This certifier key must belong to the same Security World as the seeconf encryption key, because the two keys are loaded together when the image is encrypted. We recommend using the Application Signing Key (ASK) as the certifier if you intend to sign and encrypt in one command (see Sign and encrypt in a single command), although this is not mandatory. Using the ASK as the certifier in that case avoids the need to create another seeinteg key. If encryption is done as a separate step from signing, any other seeinteg key may be used as the certifier. The certifying seeinteg key does not need to be the ASK or Developer ID key. If encryption is performed as a separate step, the key does not even need to belong to the same Security World. The certifier key (and its protection credential) must be loaded when encrypting, but not when loading the encrypted application, as the HSM protects the decryption operation internally (the ACL on the seeconf key generated by the generatekey utility does not allow general decryption by a client-side application).

$ generatekey seeconf
module: Module to use? (1, 2) [1] > 2
protect: Protected by? (token, module) [module] >
size: Key size? (bits, 128-256) [256] >
logkeyusage: Log key usage? (yes/no) [no] > yes
plainname: Key name? [] > aes256seeconf
OPTIONAL: seeintegname: SEE integrity key(s)? (devidseeinteg) []
> devidseeinteg
nvram: Blob in NVRAM (needs ACS)? (yes/no) [no] >
OPTIONAL: trusted-certifier: implicitly trusted seeinteg key hashes? [] >
key generation parameters:
 operation          Operation to perform                    generate
 application        Application                             seeconf
 module             Module to use                           2
 protect            Protected by                            module
 verify             Verify security of key                  yes
 type               Key type                                AES
 size               Key size                                256
 logkeyusage        Log key usage                           yes
 plainname          Key name                                aes256seeconf
 seeintegname       SEE integrity key(s)                    devidseeinteg
 nvram              Blob in NVRAM (needs ACS)               no
 trusted-certifier  implicitly trusted seeinteg key hashes
Key successfully generated.
Path to key: /opt/nfast/kmdata/local/key_seeconf_aes256seeconf

Encrypt an image with csadmin image encrypt

The csadmin image encrypt command encrypts an existing .cs5 image:

$ csadmin image encrypt --help
usage: csadmin image encrypt [-h] [--out OUT] --enckey ENCKEY
                             [--encapp ENCAPP] --encauthkey ENCAUTHKEY
                             [--encauthapp ENCAUTHAPP] [--verbose]
                             CS5FILE

positional arguments:
  CS5FILE               The cs5 file to be encrypted

options:
  -h, --help            show this help message and exit
  --out OUT             Name of the output file. If not specified, the cs5
                        file is overwritten
  --enckey ENCKEY       Name (ident) of the encryption key
  --encapp ENCAPP       Appname for ENCKEY (default 'seeconf')
  --encauthkey ENCAUTHKEY
                        Name (ident) of the key to authorize use of ENCKEY
  --encauthapp ENCAUTHAPP
                        Appname for ENCAUTHKEY (default 'simple')
  --verbose             Print verbose logs

In this command:

--enckey (and --encapp, default seeconf) identify the image encryption key created above.
--encauthkey (and --encauthapp) identify the seeinteg key that authorizes use of the encryption key. This must be the key named as seeintegname when the encryption key was generated.

The following example encrypts a previously signed image. Here the encryption key is protected by an Operator Card Set (OCS), so the card is requested when the key is loaded:

$ csadmin image encrypt --enckey aes256seeconf --encauthapp seeinteg --encauthkey devidseeinteg --out encrypted-echo.cs5 ./echo.cs5

Loading `exampleocs':
 Module 2 slot 2: `exampleocs' #1
 Module 2 slot 2:- passphrase supplied - reading card
Card reading complete.

* Wrote CS5 file encrypted-echo.cs5

Sign and encrypt in a single command

csadmin image sign accepts the same --enckey, --encapp, --encauthkey and --encauthapp options as csadmin image encrypt, so an image can be signed and encrypted in one command. When --enckey is given but --encauthkey is not, the Application Signing Key (ASK) is used to authorize the encryption.

Such a command uses several keys: the Developer ID key (OCS-protected), the ASK (OCS- or softcard-protected, and may be the same key as the Developer ID key), the key that authorizes the encryption (by default the same key as the ASK), and the seeconf encryption key (module-protected). Where the same card-protected or softcard-protected key is used for more than one of these operations, you may be prompted to present its credentials several times.

To avoid this, run the command under the preload utility, which loads the required credentials once, up front, and makes them available for the whole operation. Naming a module with --module also confines credential loading to that one module, which avoids the extra work of loading an OCS on every module of a multi-module system, which is the preload default. The same benefit applies to single-operation commands such as csadmin image signextra and csadmin image encrypt. preload can also present credentials out of band, for example in an automated build where a shared preload session is set up in advance. See preload for details.

You do not need preload for correctness. The csadmin image commands automatically load keys that must reside on the same module together, so the seeconf encryption key is loaded on the same module as the key that certifies its use. Where a key is OCS- or softcard-protected, any usable module can be selected. preload is a convenience for caching credentials and for choosing the module up front.

The following example signs (with an ASK and a Developer ID key) and encrypts in a single command. Here the same seeinteg key is used as the ASK, as the Developer ID key, and as the key that authorizes the encryption, so one key makes both signatures and certifies use of the encryption key; in general these can be different keys.

$ preload --module=2 --cardset=exampleocs csadmin image sign --askapp seeinteg --askeyname devidseeinteg --devapp seeinteg --devkeyname devidseeinteg --devcert developerid_cert.pem --enckey aes256seeconf --out signed-encrypted-echo.cs5 ./echo.cs5
...
INFO: Loading complete. Executing subprocess csadmin image sign --askapp seeinteg --askeyname devidseeinteg --devapp seeinteg --devkeyname devidseeinteg --devcert developerid_cert.pem --enckey aes256seeconf --out signed-encrypted-echo.cs5 ./echo.cs5
* Wrote CS5 file signed-encrypted-echo.cs5

Stand-alone signing with the ASK (with the Developer ID key delegated up front, as described in CodeSafe 5 Application Authentication) and stand-alone encryption with csadmin image encrypt remain fully supported; this combined command is a convenience.

csadmin image inspect reports whether an image is encrypted, and the name of the encryption key:

$ csadmin image inspect signed-encrypted-echo.cs5
Type               codesafe-container
Platform           nShield5
Format             1
PackageName        echo
Version            1.0
EntryPoint         /usr/bin/entrypoint
Signed             True
SigningKeys        seeinteg-devidseeinteg
SHA512Hash         8deeb5fa1294ab70c278977e5665bce7c68d5fe71b14251b1d64d128ed02869a83833f68e93dcd08f96a92d105e46e60734c1174fbeff3e70003b47e7d69181a
Encrypted          True
EncryptKey         aes256seeconf

Load an encrypted CodeSafe 5 image

To load an encrypted image, the HSM must have the image encryption key installed as a SEE Loader key. The image is then decrypted inside the HSM. The seeconf encryption key must therefore be present in the Security World in which the HSM is enrolled when the image is loaded, even if the image was encrypted in a different Security World. Only the encryption key itself is needed at load time; the seeinteg key that certified it during encryption is not needed to load the image. The decrypted form is retained (including across reboots) so the application can be restarted without presenting the key again, unless the machine is destroyed and reloaded. The signatures are verified over the plaintext image every time the application starts, exactly as for an unencrypted image.

If the encryption key has not been installed, loading fails with an error such as Required decryption key '<keyname>' has not been installed.

There are three ways to load an encrypted image; each installs the encryption key for you when you identify it:

Manual load with csadmin load

Pass the encryption key with --enckey (and --encapp, default seeconf):

$ csadmin load --esn E866-0C27-CF25 --enckey aes256seeconf signed-encrypted-echo.cs5
E866-0C27-CF25        UUID: de131c2a-0da7-483b-9ccd-26233fe4d600

Interactive load with hsc_codesafe

Specify encryption_key=<key ident>. The hsc_codesafe name=value arguments correspond to the [codesafe] configuration fields.

$ hsc_codesafe -m2 image_file=signed-encrypted-echo.cs5 worldid_pubname=echosee encryption_key=aes256seeconf -- pause
hsc_codesafe:INFO: Installing SEE Loader key: aes256seeconf
...
hsc_codesafe:INFO: READY: signed-encrypted-echo.cs5 running on E866-0C27-CF25 (#2); SEE World ID published as echosee

Automatic load from the [codesafe] configuration section

Set the encryption_key field in the [codesafe] section of the config file. See Automatic Configuration of CodeSafe 5 Applications via the Host Machine and Auto-Load Configuration of CodeSafe 5 Applications via the nShield 5c.

Errors when loading an encrypted image

Loading an encrypted image fails in two common cases. The following example uses csadmin load without an encryption key against two modules: one whose firmware does not support image encryption, and one that supports it but does not yet have the encryption key installed:

$ csadmin load signed-encrypted-echo.cs5
8ED1-2C9A-9331        ERROR: Failed to create machine: launcher create: File version was 2; this tool only supports up to version 1.
E866-0C27-CF25        ERROR: Failed to create machine: launcher create: LXCError Required decryption key 'aes256seeconf' has not been installed
Failed to load the machine for module(s): ['E866-0C27-CF25', '8ED1-2C9A-9331']

File version was 2; this tool only supports up to version 1: The target module’s firmware does not support CodeSafe 5 image encryption. Load the image on a module whose firmware supports image encryption, or upgrade the module firmware.
Required decryption key '<keyname>' has not been installed: The module supports image encryption but the encryption key was not supplied, so it could not be installed. Re-run the load, identifying the encryption key: pass --enckey to csadmin load, encryption_key= to hsc_codesafe, or set the encryption_key field in the [codesafe] configuration section. The same error appears in the client or 5c hardserver log if an encrypted image is auto-loaded from the [codesafe] section without encryption_key set.