Utilities

Entrust supplies the following SEE-specific nShield command-line utilities, described in this appendix:

  • 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

  • stattree

For a list of all supplied nShield utilities, see the User Guide.

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 tell elftool to dump (display) all fields in the input file infile as they are read.

-q|--quiet

These options tell elftool to suppress informative messages.

--single-section

This option tells elftool to check 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 tells elftool to generate an output file outfile in nonexecutable AIF output (ARM only, deprecated).

--bin

This option tells elftool to generate an output file outfile in raw binary format.

--sxf

This option tells elftool to generate an output file outfile in nShield SEE Executable Format (SXF).

-n|--no-output

These options tell elftool to 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 root or as a user in the group nfast.

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 the User Guide 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 the User Guide 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 the User Guide 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.

For details about the configuration files, see the User Guide.

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.

‑f|‑‑force

Setting this option allows the command to make configuration changes without prompting you.

‑‑no‑reset

This option tells the command not to reset 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:

  1. Loads an SEE machine into each HSM configured.

  2. 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-2 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

see-*-serv utilities

This section describes the usage and available options for the host-side utilities that Entrust supplies to enable standard IO and socket connections for SEE machines using the bsdlib/glibc architecture:

  • see-sock-serv, for SEE machines that require only sockets.

  • see-stdoe-serv, for SEE machines that require only standard output and error streams.

  • see-stdioe-serv, for SEE machines that require standard input, output, and error streams.

    If you are using a nShield Connect, you must set the --no-feature-check option when running the see-stdoe-serv utility.

  • see-stdioesock-serv, for SEE machines that require sockets in addition to standard input, output, and error streams.

Each of the 4 supplied utilities has the capability to:

  • Load the SAR file for the SEE machine

  • Load the mandatory userdata file

  • Provide a selection of socket and I/O streams

SEE machines that require the standard I/O streams or INET domain sockets must be serviced by one of the described host-side utilities. Without an appropriate host-side utility, SEE machine operations requiring any of these streams are blocked until the appropriate service becomes available.

Ensure that you select the appropriate utility for your SEE machine, because running a host-side utility with more provisions than the SEE machine was linked against causes the SEE machine to abort.

Usage

All the see-*-serv host-side utilities take the same arguments:

see-sock-serv -p <PUBL-NAME> | -o <KEYID> | -M <MACHINE>.sar
see-stdoe-serv -p <PUBL-NAME> | -o <KEYID> | -M <MACHINE>.sar
see-stdioe-serv -p <PUBL-NAME> | -o <KEYID> | -M <MACHINE>.sar
see-stdioesock-serv -p <PUBL-NAME> | -o <KEYID> | -M <MACHINE>.sar
-M|--machine=<MACHINE>.sar

This option specifies SEE machine file (packed as a SAR). If you do not specify this option, the SEE machine must have been loaded previously by, for example, running the loadmache command-line utility. (See loadmache.)

--userdata-sar <USERDATA>.sar

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

--userdata-raw <USERDATAFILE>

This option specifies the name of an unpacked userdata file to be passed to SEE machine.

The raw file is internally made into an unsigned SAR file.
-p|--published-object=<NAME>

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

-o|--object-id=<NAME>

This option specifies the KeyID of the started SEE machine.

-m|--module=<MODULE>

This option specifies an HSM onto which the SEE machine is to be loaded.

Use the enquiry command-line utility to get information about an HSM. For more information, see the User Guide.
--job-prefix <PREFIX>

This option is for debugging. For the host-side utilities that provide a single service (that is, see-sock-serv, see-stdoe-serv, and see-stdioe-serv), specifying this option forces the service to use the job prefix specified by <PREFIX>.

--trace

Specifying this option polls the Security World’s trace buffer. The contents are printed to stderr in dark red.

If the configuration of the Security World requires it, you must supply authorization to poll the trace buffer when specifying this option. The see-*-serv host-utility prompts you to supply authorization if it is required.
--plain-trace

This option functions like the --trace option to poll the Security World’s trace buffer, but the output from --plain-trace is not surrounded by terminal escape codes.

-f|--no-feature-check

Specifying this option suppresses the default behavior of the see-*-serv host-side utilities to ensure that the HSM specified by the -m|--module=<MODULE> option has the HasSEE flag and the GeneralSEE feature before the utility tries to load an SEE machine.

If you are using a nShield Connect, you must set the --no-feature-check option when running the see-stdoe-serv utility.
-r|--restrict

This option only permits userdata and machine-image files from the nc-seemachines or the custom-seemachines subdirectories of the /opt/nfast directory to be loaded. When userdata is loaded automatically by a privileged account, this option should be specified, for extra security.

Error output from SEE machine with SEElib architecture

You cannot use the see-*-serv host-side utilities to load SEE machines built with the SEElib architecture. If you try to do so, the utility returns a message similar to

FATAL: SeeHostCallProvision_Init (prefix `nC/HC/sock/INET ') failed:
SeeHostcallProvisionFailed

This is the expected behavior caused by the host utility sending SEEJobs that the SEE machine cannot understand or to which it cannot respond correctly.

You can use the loadmache command-line utility to manually load SEE machines built with the SEElib architecture.

stattree

The stattree utility returns the statistics gathered by the hardserver and HSMs.

Usage

stattree [<node> [<node> [...]]]

Output

Running the stattree utility displays a snapshot of statistics currently available on the host machine. Statistics are gathered both by the hardserver (relating to the server itself, and its current clients) and by each attached HSM.

Times are listed in seconds. Other numbers are integers, which are either real numbers, IP addresses, or counters. For example, a result ‑CmdCount 74897 means that there have been 74,897 commands submitted.

A typical fragment of output from stattree looks like this:

+PerModule:
   +#1:
      +ModuleObjStats:
         -ObjectCount          5
         -ObjectsCreated       5
         -ObjectsDestroyed     0
      +ModuleEnvStats:
         -MemTotal             15327232
         -MemAllocKernel       126976
         -MemAllocUser         0
      +ModuleJobStats:
         -CmdCount             169780
         -ReplyCount           169778
         -CmdBytes             3538812
         -ReplyBytes           4492764
         -HostWriteCount       169772
         -HostWriteErrors      0
         -HostReadCount        437472
         -HostReadErrors       0
         -HostReadEmpty        100128
         -HostReadDeferred     167578
         -HostReadTerminated   0
         -PFNIssued            102578
         -PFNRejected          1
         -PFNCompleted         102577
         -ANIssued             1
         -CPULoadPercent       0
      +ModuleSerialStats:
         -HostReadCount        437476
         -HostReadDeferred     167580
         -HostReadReconnect    167579
         -HostReadErrors       0
         -HostWriteCount       169774
         -HostWriteErrors      0

PerModule, ModuleObjStats, and ModuleEnvStats are node tags that identify classes of statistics. 1 identifies an instance node.

ObjectCount, MemTotal, and the remaining items at the same level are statistics IDs. Each has a corresponding value.

If <node> is provided, stattree uses the value given as the starting point of the tree and displays only information at or below that node in the tree. Values for <node> can be numeric or textual. For example, to view the object counts for local HSM number 3:

$ stattree PerModule 3 ModuleObjStats
+#PerModule:
   +#3:
      +#ModuleObjStats:
         -ObjectCount          6
         -ObjectsCreated       334
         -ObjectsDestroyed     328

The value of <node> must be a node tag; it must identify a node in the tree and not an individual statistic. Thus, the following command does not work:

$ stattree PerModule 3 ModuleObjStats ObjectCount
+#PerModule:
   +#3:
      +#ModuleObjStats:
Unable to convert 'ObjectCount' to number or tag name.

Node tags

These hold statistics for each HSM:

Category Contains

ModuleJobStats

This tag holds statistics for the Security World Software commands (jobs) processed by this HSM.

ModulePCIStats

This tag holds statistics for the PCI connection between the HSM and the host computer.

ServerGlobals

Aggregate statistics for all commands processed by the hardserver since it started.

The standard statistics (as described below) apply to the commands sent from the hardserver to HSMs. Commands processed internally by the server are not included here. The Uptime statistic gives the total running time of the server so far.

Connections

Statistics for connections between clients and the hardserver. There is one node for each currently active connection. Each node has an instance number that matches the log message generated by the server when that client connected. For example, when the hardserver message is Information: New client #24 connected, the client’s statistics appear under node #24 in the stattree output.

PerModule

Statistics kept by the HSMs. There is one instance node for each HSM, numbered using the standard HSM numbering. The statistics provided by each HSM depend on the HSM type and firmware version.

ModuleObjStats

Statistics for the HSM’s Object Store, which contains keys and other resources. These statistics may be useful in debugging applications that leak key handles, for example.

ModuleEnvStats

General statistics for the HSM’s operating environment.

HostEnvStats

Environmental statistics for the HSM.

HostSysInfo

Further statistics for the HSM.

Statistics IDs

ID Value

Uptime

The length of time (in seconds) since an HSM was last reset, the hardserver was started, or a client connection was made.

CmdCount

The total number of commands sent for processing from a client to the server, or from the server to an HSM. Contains the number of commands currently being processed.

ReplyCount

The total number of replies returned from server to client, or from HSM to server.

CmdBytes

The total length of all the command blocks sent for processing.

ReplyBytes

The total length of all the reply blocks received after completion.

CmdMarshalErrors

The number of times a command block was not understood when it was received. A nonzero value indicates either that the parties at each end of a connection have mismatched version numbers (for example, a more recent hardserver has sent a command to a less recent HSM that the HSM does not understand), or that the data transfer mechanism is faulty.

ReplyMarshalErrors

The number of times a reply was not understood when it was received. A nonzero value indicates either that the parties at each end of a connection have mismatched version numbers (for example, a more recent hardserver has sent a command to a less recent HSM that the HSM does not understand), or that the data transfer mechanism is faulty.

ClientCount

The number of client connections currently made to the server. This appears in the hardserver statistics.

MaxClients

The maximum number of client connections ever in use simultaneously to the hardserver.

This gives an indication of the peak load experienced so far by the server.

DeviceFails

The number of times the hardserver has declared a device to have failed. The hardserver provides a diagnostic message when this occurs.

DeviceRestarts

The number of times the hardserver has attempted to restart an HSM after it has failed. The hardserver provides a Notice message when this occurs. The message does not indicate that the attempt was successful.

QOutstanding

The number of commands waiting for an HSM to become available on the specified client connection. When an HSM accepts a command from a client, this number decreases by 1 and DevOutstanding increases by 1. Commands that are processed purely by the server are never included in this count.

DevOutstanding

The number of commands sent by the specified client that are currently executing on one or more HSMs. When an HSM accepts a command from a client, this number decreases by 1 and QOutstanding increases by 1. Commands that are processed purely by the server are never included in this count.

LongOutstanding

The number of LongJobs sent by the specified client that are currently executing on one or more HSMs. When an HSM accepts a LongJobs command from a client, this number increases by 1 and QOutstanding decreases by 1. Commands that are processed purely by the server are never included in this count.

RemoteIPAddress

The remote IP address of a client who has this connection. A local client has the address 0.0.0.0.

HostWriteCount

The number of write operations (used to submit new commands) that have been received by the HSM from the host machine. One write operation may contain more than one command block. The operation is most efficient when this is the case.

HostWriteErrors

The number of times the HSM rejected the write data from the host. A nonzero value may indicate that data is being corrupted in transfer, or that the hardserver/device driver has got out of sync with the HSM’s interface.

HostWriteBadData

Not currently reported by the HSM.

Attempts to write bad data to the HSM are reflected in HostWriteErrors.

HostWriteOverruns

Not currently reported by the HSM. Write overruns are reflected in HostWriteErrors.

HostWriteNoMemory

Not currently reported by the HSM. Write failures due to a lack of memory are reflected in HostWriteErrors.

HostReadCount

The number of times a read operation to the HSM was attempted. The HSM can defer a read if it has no replies at the time, but expects some to be available later. Typically the HSM reports HostReadCount in two places: the number under ModuleJobStats counts a deferred read twice, once when it is initially deferred, and once when it finally returns some data. The number under ModulePCIStats counts this as one operation.

HostReadErrors

The number of times a read to an HSM failed because the parameters supplied with the read were incorrect. A nonzero value here typically indicates some problem with the host interface or device driver.

HostReadEmpty

The number of times a read from the HSM returned no data because there were no commands waiting for completion. In general, this only happens infrequently during HSM startup or reset. It can also happen if PauseForNotifications is disabled.

HostReadUnderruns

Not currently reported by the HSM.

HostReadDeferred

The number of times a read operation to the HSM was suspended because it was waiting for more replies to become available. When the HSM is working at full capacity, a sizeable proportion of the total reads are likely to be deferred.

HostReadTerminated

The number of times an HSM had to cancel a read operation which has been deferred. This normally happens only if the clear key is pressed while the HSM is executing commands. Otherwise it might indicate a device driver, interface, or firmware problem.

PFNIssued

The number of PauseForNotifications commands accepted by the HSM from the hardserver. This normally increases at a rate of roughly one every two seconds. If the hardserver has this facility disabled (or a very early version), this does not occur.

PFNRejected

The number of PauseForNotifications commands rejected by the HSM when received from the hardserver. This can happen during HSM startup or reset, but not in normal use. It indicates a hardserver bug or configuration problem.

PFNCompleted

The number of PauseForNotifications commands that have been completed by the HSM. Normally, this is one less than the PFNIssued figure because there is normally one such command outstanding.

ANIssued

The number of Asynchronous Notification messages issued by the HSM to the hardserver. These messages indicate such things as the clear key being pressed and the HSM being reset. In later firmware revisions inserting or removing the smartcard or changing the non-volatile memory also generate asynchronous notifications.

ChanJobsIssued

The number of fast channel jobs issued to the HSM. The fast channel facility is unsupported on current HSMs. This number should always be 0.

ChanJobsCompleted

The number of fast channel jobs completed by the HSM. The fast channel facility is unsupported on current HSMs. This number should always be 0.

CPULoadPercent

The current processing load on the HSM, represented as a number between 0 and 100. Because an HSM typically contains a number of different types of processing resources (for example, main CPU, and RSA acceleration), this figure is hard to interpret precisely. In general, HSMs report 100% CPU load when all RSA processing capacity is occupied; when performing non-RSA tasks the main CPU or another resource (such as the random number generator) can be saturated without this statistic reaching 100%.

HostIRQs

On PCI HSMs, the total number of interrupts received from the host. On current HSMs, approximately equal to the total of HostReadCount and HostWriteCount.

ChanJobErrors

The number of low-level (principally data transport) errors encountered while processing fast channel jobs. Should always be 0 on current HSMs.

HostDebugIRQs

On PCI HSMs, the number of debug interrupts received. This is used only for driver testing, and should be 0 in any production environment.

HostUnhandledIRQs

On PCI HSMs, the number of unidentified interrupts from the host. If this is nonzero, a driver or PCI bus problem is likely.

HostReadReconnect

On PCI HSMs, the number of deferred reads that have now completed. This should be the same as HostReadDeferred, or one less if a read is currently deferred.

ObjectsCreated

The number of times a new object has been put into the object store. This appears under the HSM’s ModuleObjStats node.

ObjectsDestroyed

The number of items in the HSM’s object store that have been deleted and their corresponding memory released.

ObjectCount

The current number of objects (keys, logical tokens, buffers, SEE Worlds) in the object store. This is equal to ObjectsCreated minus ObjectsDestroyed. An empty HSM contains a small number of objects that are always present.

CurrentTempC

The current temperature (in degrees Celsius) of the HSM main circuit board. First-generation HSMs do not have a temperature sensor and do not return temperature statistics.

MaxTempC

The maximum temperature recorded by the HSM’s temperature sensor. This is stored in non-volatile memory, which is cleared only when the HSM is initialized. First-generation HSMs do not have a temperature sensor and do not return temperature statistics.

MinTempC

The minimum temperature recorded by the HSM’s temperature sensor. This is stored in non-volatile memory, which is cleared only when the HSM is initialized. First-generation HSMs do not have a temperature sensor and do not return temperature statistics.

MemTotal

The total amount of RAM (both allocated and free) available to the HSM. This is the installed RAM size minus various fixed overheads.

MemAllocKernel

The total amount of RAM allocated for kernel (that is, non-SEE) use in an HSM. This is principally used for the object store (keys, logical tokens, and similar) and for big-number buffers.

MemAllocUser

The total amount of RAM allocated for user-mode processes in the HSM (0 for non-SEE use). This includes the size of the SEE Machine image, and the total heap space available to it. The HSM’s kernel does not know (and does not report in the statistics) how much of the user-mode’s heap is currently free, and how much is in use.

SystemFans

The fan speed (RPM) for each fan in the HSM.

tct2

The tct2 command-line utility (also referred to as the Trusted Code Tool) enables users to sign, pack, and encrypt file archives so that they can be loaded onto an SEE-Ready nShield HSM. tct2 creates SAR files.

tct2 uses keys that are protected by a Security World or an OCS.

Examples of how tct2 can be used are provided in Example SEE machines.
Encrypted SEE machines are not currently supported for use with nShield Connect HSMs. 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.
Check the documentation supplied by the application vendor to see if you need to use tct2 to set up and use the application.

Usage

tct2 [[‑S|‑‑sign] | [‑P|‑‑pack] | [‑E|‑‑encrypt] | [‑‑add‑sig] | [‑‑sign‑and‑pack] | [‑‑print‑sigs] | [‑‑unpack‑skycert] | [‑‑unpack‑sar‑payload]] [‑‑sigfile=<NAME> ] [‑k|‑‑key=<IDENT>] [[‑‑is‑machine] |[‑‑machine‑key=<HASH>]| [‑‑machinekey‑ident=<IDENT> ] [‑T|‑‑machine‑type=<TYPE>]] [‑m|‑‑module=<MODULE> ] [‑o|‑‑outfile=<OUTFILE>] [‑‑non‑interactive] [‑‑show‑metadata] [‑v|‑‑verbose] [‑q|‑‑quiet] [[‑i|‑‑infile=]<INFILE>]

Help options

-h|--help

These options display help for tct2.

-V|--version

These options display the version number of tct2.

-u|--usage

These options display a brief usage summary for tct2.

Program options

-S|--sign

These options tells tct2 to create a signature on the file specified by ‑‑infile=<INFILE>. You must specify ‑‑key=<IDENT> and one of ‑‑is‑machine, ‑‑machine‑key=<HASH>, ‑‑machine‑key‑ident=<IDENT>.

-P|--pack

These options tell tct2 to pack the file specified by ‑‑infile=<INFILE> and any signatures specified by ‑‑sigfile=<NAME> into a SAR file specified by ‑‑outfile=<OUTFILE>. When creating an SEE machine image, the input file is a .SXF file produced by the elftool utility. When creating a SEE user data file, the input format is determined by the SEE machine type.

-E|--encrypt

These options tell tct2 to encrypt the packed SAR file specified by ‑‑infile=<INFILE>. ‑‑key=<IDENT> must be specified.

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.
--add-sig

This option tells tct2 to create a signed SAR file specified by ‑‑outfile=<OUTFILE> from the unsigned SAR file specified by ‑‑infile=<INFILE> and the key specified by ‑‑key=<IDENT>.

--sign-and-pack

This option tells tct2 to create a signature on the file specified by ‑‑infile=<INFILE> using ‑‑key=<IDENT> and one of ‑‑is‑machine, ‑‑machine‑key=<HASH>, or ‑‑machine‑key‑ident=<IDENT>, then to pack it in the file specified by ‑‑outfile=<OUTFILE>.

--print-sigs

This option tells tct2 to display the key hashes used to sign the SAR file specified by ‑‑infile=<INFILE>.

--unpack-sar-payload

This option tells tct2 to retrieve the payload of the SAR file specified by ‑‑infile=<INFILE>.

Packing and signing options

--sigfile=<NAME>

This option specifies the file that contains the signature. This option can be repeated to specify multiple signatures.

Machine key specification options for signing operations

--is-machine

This option specifies SEE machine signing mode.

--machine-key=<HASH>

This option specifies the key hash of the SEE machine for which this signature is good.

--machine-key-ident=<IDENT>

This option retrieves the hash of key <IDENT> then behaves like ‑‑machine‑key=<HASH>. Only one machine key specification option can be specified.

-T|--machine-type=<TYPE>

These options specify the SEE machine type. You can specify the appropriate machine type parameter (<TYPE>) for tct2 as a string or a number:

SEE Machine Type tct2 machine type parameter

PowerPCSXF

PowerPCSXF or 2

PowerPCELF

PowerPCELF or 5

If you are not sure which SEE machine type is appropriate for your HSM, run the enquiry command-line utility, and check the SEE Machine Type output.

If you do not specify an SEE machine type with this option, tct2 tries to determine the appropriate type by reading the format of the code to be signed. If tct2 cannot determine the appropriate SEE machine type, it returns an error message. In such a case, run tct2 again, explicitly setting the SEE machine type with this option.

Other options

-m|--module=<MODULE>

These options specify the HSM to use (where MODULE is an HSM number). The default is 1.

-i, --infile=<INFILE>.

These options specify the name of the input .sxf file. You can also specify the input file without the using ‑‑infile option by including the file name at the end of the command.

-o, --outfile=<OUTFILE>

These options specify the name of the output .sar file to create. This option is valid only with the program options that create an output file, as described in Program options.

--non-interactive

This option sets non‑interactive mode. This means that, if you have not already loaded any required card sets, tct2 fails (instead of prompting you to load any required card sets).

--show-metadata

This option shows image metadata before signing.

-v|--verbose

These options increase the verbosity level. These options can be repeated.

-q|--quiet

These options decrease the verbosity level. These options can be repeated.

Signing

Use one of the following methods to create a signing key:

  • During the KeySafe key-generation process, ensure you select the SEE Code Integrity option.

  • When generating the key with the generatekey command-line utility, ensure you select the application type seeinteg.

Signing keys can be DSA or RSA. You can sign a file any number of times using different signing keys.

For information about key application types, see Key application type (APPNAME).
For information about generating keys, see the User Guide.

To create a signature, give a command of the form:

tct2 ‑S|‑‑sign [‑m|‑‑module=<MODULE>] ‑k|‑‑key=<IDENT> [‑‑machine‑key=<HASH>| ‑‑machine‑key‑ident=<IDENT> | ‑‑is‑machine] ‑o|‑‑outfile=<OUTFILE> [‑i|‑‑infile=<INFILE>]

If the signing key is protected by an OCS, tct2 prompts you for the pass phrase for the inserted card.

Packing

All files must be packed even if you are not adding signatures. The packing operation must be performed once and only once. Your application vendor may have supplied a pre‑packed SAR file.

Packing a file creates a new SAR file. The packed file contains:

  • The original file

  • Specified signatures, if any.

To pack a file and any signatures, give a command of the form:

tct2 ‑P|‑‑pack ‑o|‑‑outfile=<OUTFILE> [‑i|‑‑infile=]<INFILE> [sigfile...]

Encryption

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.

Use one of the following methods to create an encryption key:

  • During the KeySafe key-generation process, ensure you select the SEE Code Confidentiality option.

  • When generating the key with the generatekey command-line utility, ensure you select the application type seeconf.

Encryption keys can be either Triple DES or AES keys. Encryption keys can be protected by the Security World or by a 1/N OCS.

For information about key application types, see Key application type (APPNAME).
For information about generating keys, see the User Guide.

A .sar file can be encrypted only once. To encrypt a .sar file, use the command:

tct2 ‑E|‑‑encrypt ‑k|‑‑key=<IDENT> [‑m|‑‑module=<MODULE>] ‑o|‑‑outfile=<OUTFILE> [‑i|‑‑infile=]<INFILE>