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 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
orRead+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 allRead/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 as a user who is permitted to create privileged connections.
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 thesetup
action, used to add a new configuration or replace an existing configuration -
Specifying the
--remove
option selects theremove
action, used to remove an existing configuration (without replacing it) -
Specifying the
--display
option selects thedisplay
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 theKeyID
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 valuebsdlib
/glibc
to specify use of the providedpostload-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
%NFAST_KMDATA%\config\config
. -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:
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 callshsc_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
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 thesee-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 theKeyID
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
, andsee-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 theHasSEE
flag and theGeneralSEE
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 thesee-stdoe-serv
utility. -r
|--restrict
-
This option only permits userdata and machine-image files from the
nc-seemachines
or thecustom-seemachines
subdirectories of the%NFAST_HOME%
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 SEEJob
s 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.
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 ID
s. 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 |
---|---|
|
This tag holds statistics for the Security World Software commands (jobs) processed by this HSM. |
|
This tag does not apply to nShield Edge HSMs. It holds statistics for the PCI connection between the HSM and the host computer. |
|
This tag is for nShield Edge HSMs only. It holds statistics for the serial connection between the HSM and the host computer. |
|
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. |
|
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 |
|
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. |
|
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. |
|
General statistics for the HSM’s operating environment. |
|
Environmental statistics for the HSM. |
|
Further statistics for the HSM. |
Statistics IDs
ID | Value |
---|---|
|
The length of time (in seconds) since an HSM was last reset, the hardserver was started, or a client connection was made. |
|
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. |
|
The total number of replies returned from server to client, or from HSM to server. |
|
The total length of all the command blocks sent for processing. |
|
The total length of all the reply blocks received after completion. |
|
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. |
|
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. |
|
The number of client connections currently made to the server. This appears in the hardserver statistics. |
|
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. |
|
The number of times the hardserver has declared a device to have failed. The hardserver provides a diagnostic message when this occurs. |
|
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. |
|
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 |
|
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 |
|
The number of |
|
The remote IP address of a client who has this connection. A local client has the address 0.0.0.0. |
|
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. |
|
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. |
|
Not currently reported by the HSM. Attempts to write bad data to the HSM are reflected in |
|
Not currently reported by the HSM.
Write overruns are reflected in |
|
Not currently reported by the HSM.
Write failures due to a lack of memory are reflected in |
|
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 |
|
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. |
|
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 |
|
Not currently reported by the HSM. |
|
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. |
|
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. |
|
The number of |
|
The number of |
|
The number of |
|
The number of |
|
The number of fast channel jobs issued to the HSM.
The fast channel facility is unsupported on current HSMs.
This number should always be |
|
The number of fast channel jobs completed by the HSM.
The fast channel facility is unsupported on current HSMs.
This number should always be |
|
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%. |
|
On PCI HSMs, the total number of interrupts received from the host.
On current HSMs, approximately equal to the total of |
|
The number of low-level (principally data transport) errors encountered while processing fast channel jobs.
Should always be |
|
On PCI HSMs, the number of debug interrupts received.
This is used only for driver testing, and should be |
|
On PCI HSMs, the number of unidentified interrupts from the host. If this is nonzero, a driver or PCI bus problem is likely. |
|
On PCI HSMs, the number of deferred reads that have now completed.
This should be the same as |
|
The number of times a new object has been put into the object store.
This appears under the HSM’s |
|
The number of items in the HSM’s object store that have been deleted and their corresponding memory released. |
|
The current number of objects (keys, logical tokens, buffers, SEE Worlds) in the object store.
This is equal to |
|
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. |
|
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. |
|
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. |
|
The total amount of RAM (both allocated and free) available to the HSM. This is the installed RAM size minus various fixed overheads. |
|
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. |
|
The total amount of RAM allocated for user-mode processes in the HSM ( |
|
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 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 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 theelftool
utility. When creating a SEE user data file, the input format is determined by the SEE machine type. -E
|--encrypt
-
These options 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 aSEEMachine
, it has access to the SEE Confidentiality key and can cause the binary to be decrypted. In this scenario, the Connect works fine with encryptedSEEMachine
binaries. --add-sig
-
This option creates 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 creates 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 displays the key hashes used to sign the SAR file specified by
--infile=<INFILE>
. --unpack-sar-payload
-
This option retrieves 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>
) fortct2
as a string or a number:SEE Machine Type
tct2
machine type parameterPowerPCSXF
PowerPCSXF
or2
PowerPCELF
PowerPCELF
or5
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. Iftct2
cannot determine the appropriate SEE machine type, it returns an error message. In such a case, runtct2
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 typeseeinteg
.
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 passphrase 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 typeseeconf
.
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>