Utilities

Entrust supplies the following SEE-specific nShield command-line utilities:

elftool.
loadmache.
loadsee-setup.
hsc_loadseemachine
The see-*-serv host-side utilities:
- see-sock-serv.
- see-stdoe-serv.
- see-stdioe-serv.
- see-stdioesock-serv.
seessl-migrate.py.
tct2 (the Trusted Code Tool)

This appendix also describes the following general nShield command-line utilities:

nfkmverify

For a list of all supplied nShield utilities, see nShield v13.6.5 Utilities Reference.

cpioc

The cpioc command-line utility takes a collection of files and packs them up into a userdata archive file that the SEE machine can use.

Usage

cpioc userdata.cpio <MyFile1> <MyFile2> <MyFile3> <[...]>

In this command, <MyFile1>, <MyFile2>, and <MyFile3> represent the files being packed into the userdata.cpio file that is generated by the command. You can specify as many files as appropriate.

You can also specify one or more directories; the command automatically packs their contents (including any subdirectories) into the generated userdata.cpio file.

elftool

The elftool command-line utility lets you convert ELF format executables into a format suitable for loading as an SEE machine.

Usage

elftool [<options>] <infile> [<outfile>]

This utility has the following options:

-d|--dump-fields: These options dumps (display) all fields in the input file infile as they are read.
-q|--quiet: These options suppresses informative messages.
--single-section: This option checks that exactly one of each section type is present in the input file infile. If more than one section of a type is present, an error is displayed.
--aif: This option generates an output file outfile in nonexecutable AIF output (ARM only, deprecated).
--bin: This option generates an output file outfile in raw binary format.
--sxf: This option generates an output file outfile in nShield SEE Executable Format (SXF).
-n|--no-output: These options check the input file infile without generating any output.

To view the loadable sections of an ELF file, use the following command:

elftool --dump-fields <infile>

This command displays details of the sections of the file under one of the following categories:

Read Only: This category includes program code and constant data (either Read or Read+Execute permissions).
Read/Write: This category includes non-constant data initialized to particular values (Read+Write permissions).
Zero Init: This category includes non-constant data initialized to zero.

To generate an AIF or SXF format output file correctly, the ELF input file must have the following characteristics:

The address range for one category of data (for example, Read Only) must not overlap with the address range for another (for example, Read/Write).
All Zero Init data must come after all Read/Write data in memory (that is, Zero Init data must occupy a higher memory address).

The default options for most linkers ensure that ELF files meet these requirements.

To convert a ELF file into SXF, a format specifically for SEE machines, use the following command:

elftool --sxf <infile> <outfile>

SXF format files can be loaded on all existing SEE-enabled HSMs. This is the preferred format.

To convert a ELF file into binary format, use the following command:

elftool --bin <infile> <outfile>

The output file consists of the Read Only data immediately followed by the Read/Write data, without a header. This may be useful in applications other than SEE Machine images.

loadmache

The loadmache command-line utility supplied with the Secure Execution Engine (SEE) loads an SEE machine into an SEE-enabled HSM. The hardserver can automatically use this utility to load an SEE machines.

To use this command, you must be logged in to the host computer as a user in the group nfast (Linux) or as a user who is permitted to create privileged connections (Windows).

SEE machines that require support from a host-side see-*-serv utility

If your SEE machine requires support from a host-side see-*-serv utility, you must run one of those utilities as appropriate to serve the SEE machine before its networking or stdioe provisions can work.

Usage

loadmache [-m|--module=<MODULE>] [-s|--slot=<SLOT>] [-U|--unencrypted] [-e|--encryptionkey=<IDENT>] [-a|--sighash=<HASH>] [-n|--noprompt] <machine-filename>

In this command, the machine-filename parameter specifies the path of the SEE machine. If machine-filename is not specified, loadmache tries to select a machine from the location specified by the `NFAST_SEE_MACHINEIMAGE_`* environment variables. See Environment variables for more information about environment variables.

HSM options

-m|--module=<MODULE>: These options specify the hardware security module to use.
-s|--slot=<SLOT>: These options specify the slot from which to load cards.

SEE machine loading options

-a|--sighash=<HASH>: These options specify that the SEE machine is to be signed with a key whose hash is HASH.
-n|--noprompt: These options specify that you are never prompted for missing smart cards.
-U|--unencrypted: These options specify that the SEE machine is to be unencrypted. This is the default. If set, these options override any previously specified `NFAST_SEE_MACHINEENCKEY_`* variable. See Environment variables for more information about environment variables.
-e|--encryptionkey=<IDENT>: These options specify that the SEE machine is to be encrypted with the key identified by IDENT. If set, these options override the -U|--unencrypted options.

If neither the -e|--encryptionkey nor the -U|--unencrypted options are specified, a decryption key is used only if the name of a suitable one is found in the location specified by the NFAST_SEE_MACHINEENCKEY_DEFAULT environment variable. See Environment variables for more information about environment variables.

loadsee-setup

The loadsee-setup command-line utility helps you set up, display, or remove settings in the hardserver configuration file that control the automatic loading of SEE machines.

You can use loadsee-setup for one of three types of action by specifying the appropriate option:

Specifying the --setup option selects the setup action, used to add a new configuration or replace an existing configuration
Specifying the --remove option selects the remove action, used to remove an existing configuration (without replacing it)
Specifying the --display option selects the display action, used to display the configuration of one or all HSMs

Usage

loadsee-setup -s|--setup -m <MODULE>
loadsee-setup -r|--remove -m <MODULE>
loadsee-setup -d|--display [-m <MODULE>]

Action selection

-s|--setup: This option selects the setup action, enabling you to set up the hardware configuration file for the HSM specified by -m|--module=<MODULE> to provide automatic loading for the SEE machine specified by -M|--machine=<MACHINE>.sar.

You must always specify the -m|--module=<MODULE> and -M|--machine=<MACHINE>.sar options when using the --setup option. See the comments in the hardserver configuration file for information about the effects of specifying or omitting other options.

-r|--remove: This option selects the remove action, enabling you to remove settings that control automatic SEE machine loading from the hardware configuration file for the HSM specified by -m|--module=<MODULE>
-d|--display: This option selects the display action, enabling you to display the current configuration of automatic SEE machine loading for the HSM specified by -m|--module=<MODULE> or, if no HSM is specified, all HSMs in the Security World.

Setup options

-M|--machine=<MACHINE>.sar

This option specifies the SEE machine file (packed as a SAR). You must supply a value for this option when using setup mode.

-U|--userdata=<USERDATA>.sar

This option specifies the name of the userdata file (packed as a SAR) to be passed to SEE machine.

-k|--key=<IDENT>

This option identifies the seeconf key protecting the SEE machine. You must supply this option is the SEE machine is encrypted. Only HSM-protected keys are supported.

-S|--sighash=<HASH>

This option identifies the hash of the key that the SEE machine is signed with. You only need to supply this option if the SEE machine is encrypted and you are using a dynamic SEE feature. This option is not required if the SEE machine is not encrypted or if you have the GeneralSEE static feature.

-p|--published-object=<NAME>

This option specifies the PublishedObject name to use for publishing the KeyID of the started SEE machine.

-P|--postload-prog=<PROGRAM>

This option specifies the post-load program to be run after the SEE machine is loaded.

In most cases, SEE machines using the bsdlib/glibc architecture should supply the value bsdlib/glibc to specify use of the provided postload-bsdlib program.

-A|--postload-args="<ARGUMENTS>"

This option specifies an argument string to pass to the post-load program specified by the --postload-prog option. Supply the individual arguments within the double quotation marks, each argument separated from the next by a single space.

General options

-m|--module=<MODULE>: This option specifies the HSM with the hardware configuration file that is to be acted upon by the command. You must supply a value for this option in either setup or remove mode.
-c|--configfile=<FILENAME>: This option specifies name of (or path to) the hardserver configuration file to be acted upon by the command. The default is /opt/nfast/kmdata/config/config (Linux) or %NFAST_KMDATA%\config\config (Windows).
-f|--force: Setting this option allows the command to make configuration changes without prompting you.
--no-reset: This option prevents resetting HSMs with changed configurations.

Output

loadsee-setup --setup

This section provides an example of loadsee-setup used in --setup mode.

When --setup mode is specified, the only other required options are -m|--module=<MODULE> and -M|--machine=<MACHINE>.sar. However, if you supply the -A|--postload-args="<ARGUMENTS>" option, you must also supply the -P|--postload-prog=<PROGRAM> option.

To set up a hardware configuration file to provide automatic loading for an SEE machine, run a command similar to the following Solo XC example:

loadsee-setup --setup -m1 --machine /tmp/test.sar --postload-prog=glibc --postload-args="--provision stdoe --userdata-sar /tmp/userdata.sar --trace"

If automatic SEE machine loading has already been configured for the specified HSM, loadsee-setup warns you before it is overwritten:

Module #1 new SEE configuration saved, new configuration follows:
Module #1:
  Machine file:                 /tmp/test-helloworld.sar
  Userdata file:
  WorldID published object:
  Postload helper:              glibc
  Postload args:                --provision stdoe --userdata-sar /tmp/test.cpio.sar
--trace
Clear modules now to reload new configuration? (yes/no): yes

You can use the -f|--force option to bypass this warning and overwrite the existing configuration.

After setting up the configuration, loadsee-setup resets the affected HSM (unless you specified the --no-reset option).

loadsee-setup --remove

This section provides an example of loadsee-setup used in --remove mode.

When --remove mode is specified, the only other required option is -m|--module=<MODULE>. This specifies the HSM with the hardserver configuration file that needs the settings for automatic SEE machine loading removed.

To remove settings for automatic SEE machine loading from an HSM’s hardware configuration file, run a command similar to the following example:

loadsee-setup --remove -m1

If the HSM specified by -m|--module=<MODULE> does not exist or is not currently configured to automatic SEE machine loading configured, an error is displayed. Otherwise, the current configuration is displayed and loadsee-setup prompts you to continue:

Module #1:
  Machine file:                 /tmp/test-helloworld.sar
  Userdata file:
  WorldID published object:
  Postload helper:              glibc
  Postload args:                --provision stdoe --userdata-sar /tmp/test.cpio.sar
--trace
Erase this configuration? (yes/no): yes
Module #1 SEE auto-loading configuration removed.
Clear modules now to reload new configuration? (yes/no): yes

You can use the -f|--force option to bypass warnings and remove the existing configuration without being prompted.

After removing the configuration, loadsee-setup resets any HSM with a configuration that has changed (unless you specified the --no-reset option). After running loadsee-setup command in --remove mode, no SEE machines are automatically loaded onto the specified HSM.

loadsee-setup --display

This section provides an example of loadsee-setup used in --display mode.

You are not required to specify any additional options with --remove mode. You can specify the -m|--module=<MODULE> option to display the settings for automatic SEE machine loading in a particular HSM’s hardserver configuration file; without specifying this option, loadsee-setup displays the settings for automatic SEE machine loading in the hardserver configuration files for any HSM in the Security World for which these settings exist.

To display settings for automatic SEE machine loading for all HSMs, run a command similar to the following example:

$ loadsee-setup --display

This command produces output similar to the following:

Module #1:
  Machine file:                 /tmp/test-helloworld.sar
  Userdata file:
  WorldID published object:
  Postload helper:              glibc
  Postload args:                --provision stdoe --userdata-sar /tmp/test

hsc_loadseemachine

The hsc_loadseemachine utility enables you to publish an SEE machine. The utility:

Loads an SEE machine into each HSM configured.
Publishes a newly created SEE world, if appropriate.

Usage

hsc_loadseemachine [<options>]

Options

-m|--module: This option specifies the HSM number into which the configuration data must be read. The default value is 0.

The SEE machine can be loaded only if you specify this option. If you do not specify this option, the utility examines the configuration file to check the changes that are made to the load_seemachine section and then reset any HSM that has had its entry modified. The hardserver loading script then calls hsc_loadseemachine -m MODULE for each HSM that has been reset.
-c|--configfile=<FILENAME>: This option specifies the name of the configuration file that must be read.

nfkmverify

The nfkmverify command-line utility verifies key generation certificates. You can use nfkmverify to confirm how a particular Security World and key are protected. It also returns some information about the Security World and key.

The nfkmverify utility compares the details in the ACL of the key and those of the card set that currently protects the key.

A key that has been recovered to a different card set shows a discrepancy for every respect that the new card set differs from the old one. For example, a key recovered from a 2-of-1 card set to a 1-of-1 card set has a different card-set hash and a different number of cards, so two discrepancies are reported. The discrepancy is between the card set mentioned in the ACL of the key and the card set by which the key is currently protected (that is, the card set mentioned in the key blobs).

A key that has been transferred from another Security World shows discrepancies and fails to be verified. We recommend that you verify keys in their original Security World at their time of generation.

If you must replace your Security World or card set, we recommend that you generate new keys whenever possible. If you must transfer a key, perform key verification immediately before transferring the key; it is not always possible to verify a key after transferring it to a new Security World or changing the card set that protects it.

Usage

nfkmverify [-f|--force] [-v|--verbose] [-U|--unverifiable] [-m|--module=<MODULE>] [appname ident [appname ident [...]]]

Help options

-h|--help: This option displays help for nfkmverify.
-V|--version: This option displays the version number for nfkmverify.
-u|--usage: This option displays a brief usage summary for nfkmverify.

Program options

-m|--module=<MODULE>

This option performs checks with module MODULE.

-f|--force

This option forces display of an output report that might be wrong.

-U|--unverifiable

This option permits operations to proceed even if the Security World is unverifiable.

If you need the -U|--unverifiable option, there may be some serious problems with your Security World.

-v|--verbose

This option prints full public keys and generation parameters.

-C|--certificate

This option checks the original ACL for the key using the key generation certificate. This is the default.

-L|--loaded

These options check the ACL of a loaded key instead of the generation certificate.

-R|--recov

This option checks the ACL of the key loaded from the recovery blob.

--allow-dh-unknown-sg-group

This option allows an operation to proceed even if a Diffie-Hellman key is using an unrecognized Sophie-Germain group.

Output

Output returned from nfkmverify can take a variety of forms, depending on the parameters of the given key generation certificate, Security World, and key concerned. Examples of possible output resulting from several different situations are provided below.

Under normal circumstances, issuing a command of the form:

nfkmverify --verbose --unverifiable myapp o20010621a13h25m02

returns output of the form:

** [Security world] **
   1 Administrator Cards
         (Currently in Module #1 Slot #0: Card #1)
        Cardset recovery ENABLED
        Passphrase recovery disabled
        Strict FIPS 140 level 3 (does not improve security) disabled
        SEE application nonvolatile storage disabled
        real time clock setting disabled
        SEE debugging disabled
        Generating module ESN 0A42-E645-7A75 currently #1 (in same incarnation)
** [Application key myapp o20010621a13h25m02] **
    [Named 'test Thu, 21 Jun 2001 13:25:02 +0100']
         Useable by HOST applications.
         Recovery ENABLED.
         MODULE-ONLY protection
         Type RSAPrivate 1024 bits keygenparams.type= RSAPrivate 2
                .params.rsaprivate.flags= none 0x00000000
                                                        .lenbits= 0x00000400 1024
                                                        .given_e absent
                                                        .nchecks absent

    Generating module ESN 0A42-E645-7A75 currently #1 (in same incarnation)
         nCore hash 23a901f3329aa9e29cd79d3bb7b32d549b725fc3
         public_half.type= RSAPublic 1
                    .data.rsapublic.e= 4 bytes
                                                        00010001

                                                        .n= 128 bytes
         8a6ab219 183de558 48c8379e 840895ff 0ba64bae 392848c6 c0aeb7f9 d10b046d
         4a214b70 4878b518 8e599c69 1cd61db0 bab4f852 425c70f5 b9c000e5 4ceda15f
         c062b5dd 01852380 f70275a1 870a6947 68ef59f0 db5d2e84 d6ae8dc1 7542e94d
         adedece8 cb3c9fb6 98fab8af 52c94137 a76ab7dd 38648134 0df55ca8 2f45e8b7

Verification successful, check details above.

Output of the form shown above indicates successful verification of the relevant key generation certificate.

The following examples indicate forms of output that could be returned if you try to verify the generation certificate of a key generated in a Security World that was created with an insufficiently up-to-date version of Security World for nShield.

In such a case, issuing a command of the form:

nfkmverify --verbose myapp spong

returns output of the form:

PROBLEM: no world generation certificates
PROBLEM: application key myapp spong: no key generation signature
 2 issues found, NOT VERIFIED

Adding the --unverifiable option to the same command:

nfkmverify --verbose --unverifiable myapp spong

returns output of the form:

PROBLEM: application key myapp spong: no key generation signature
1 issues found, NOT VERIFIED

Then, also adding the --force option to this same command:

nfkmverify --force --verbose --unverifiable myapp spong

returns output of the form:

PROBLEM: application key myapp spong: no key generation signature
PROBLEMS BUT FORCING POSSIBLY-WRONG OUTPUT
 ** [Security world] **
     UNVERIFIED SECURITY WORLD !
          proceeding anyway as requested
 ** [Application key myapp spong] **
    [Not named]
         Useable by HOST applications.
         Recovery ENABLED.
         MODULE-ONLY protection

 1 issues found, NOT VERIFIED