Nshield Admin PDF

nShield/payShield Administrator
Guide Windows
Version:
Date:
5.5
03 November 2005
Copyright 2005 nCipher Corporation Limited, Cambridge, United Kingdom.
Neither the whole nor any part of the information contained in this document may be adapted or
reproduced in any material or electronic form without the prior written consent of the copyright holder.
nCipher, nForce, nShield, payShield, nCore, nToken, nFast Ultra, nForce Ultra,
netHSM, KeySafe, CipherTools, CodeSafe, keyAuthority, SEE, and the SEE logo are
trademarks of nCipher Corporation Limited.
nFast and the nCipher logo are registered trademarks of nCipher Corporation Limited.
All other trademarks are the property of the respective trademark holders.
Information in this document is subject to change without notice.
nCipher Corporation Limited makes no warranty of any kind with regard to this information, including,
but not limited to, the implied warranties of merchantability and fitness for a particular purpose. nCipher
Corporation Limited shall not be liable for errors contained herein or for incidental or consequential
damages concerned with the furnishing, performance or use of this material.
Commercial Computer Software - proprietary

This computer software and documentation is Commercial Computer Software and Computer Software
Documentation, as defined in sub-paragraphs (a)(1) and (a)(5) of DFAR 252.227-7014, "Rights in
Noncommercial Computer Software and Noncommercial Computer Software Documentation". Use,
duplication or disclosure by the Government is subject to nCipher's standard US Terms And Conditions
for the Product.
Patents
UK Patent GB9714757.3. Corresponding patents/applications in USA, Canada, South Africa, Japan and
International Patent Application PCT/GB98/00142.
nShield/payShield Administrator Guide Windows v5.5
Contents
Chapter 1:
Chapter 2:
Chapter 3:
Introduction
10
General information
10
Audience
11
Contents of this guide
11
Conventions
13
Additional Documentation
16
Further information
16
nCipher security worlds
18
Security
20
Application independence
24
Platform independence
25
Flexibility
25
Robustness
31
Scalability
34
KeySafe and security worlds
35
Applications and the security world
37
The nCipher PKCS #11 library and security worlds
37
Risks
38
Getting the module working
39
Determining module requirements
39
Chapter 4:
Chapter 5:
Chapter 6:
Chapter 7:
Prerequisites to software installation
40
Software installation procedure
43
After software installation
46
Configuring the module
51
Creating and configuring a security world
56
Creating and configuring a payShield installation
64
Creating the Operator Card Set
71
Changing the module state
76
Entering the pre-maintenance state
76
Entering the pre-initialization state
78
Entering the operational state
79
Uninstalling
82
Uninstalling the nCipher support software
82
Configuring the hardserver
83
Remote module connections
83
Hardserver settings
84
Hardserver start-up settings
84
Remote slots
84
SEE machines
85
Hardserver configuration file
85
Payments configuration file
96
Using multiple modules
98
Identifying modules
98
Multiple modules and Remote Operator
99
Adding a module
100
Chapter 8:
Chapter 9:
Chapter 10:
Chapter 11:
Module fail over
100
Feature Enabling nCipher Modules
101
Available Features
101
payShield features
103
Ordering features for your module
104
Enabling features
105
Using CodeSafe Applications
108
CodeSafe/C applications
108
Using KeySafe
109
Starting KeySafe
109
The KeySafe window
111
Errors
120
Managing security worlds
123
Security world files
123
Security world options
125
Creating a security world
129
After you have created a security world
154
Adding or restoring a module to the security world
155
Erasing a module from a security world
162
Deleting the security world
165
Displaying information about your security world
166
Windows Cryptographic Services Provider (CSP)
179
Transferring keys between security worlds
185
Chapter 12:
Chapter 13:
Chapter 14:
Chapter 15:
About payShield installations
187
About payShield Card Sets
187
Supported payShield Key Types
190
payShield security world properties
191
Remote Operator Card Sets
193
About Remote Operator
193
Configuring Remote Operator
194
Administration tasks with cards and softcards
200
Replacing an Operator Cards pass phrase
200
Replacing Operator Card Sets
202
Changing pass phrases with cardpp
218
Changing pass phrases with ppmk
220
Replacing the Administrator Card Set
221
nShield Administrator Utilities
226
Help options
226
anonkneti
227
cfg-reread
228
enquiry
229
floodtest
238
hardserver
242
initunit
244
loadkeys
246
key-xfer-im
250
loadrom
253
mk-reprogram
255
Appendix A:
ncversions
257
new-world
259
nvram-backup
266
nvram-sw
272
payshield-config
278
payshield-info
280
payshield-install
283
postrocs
286
ppmk
287
preload
290
racs
301
rfs-setup
302
rfs-sync
304
rtc
307
slotinfo
310
sppupgradekeys
312
stattree
314
Upgrading module firmware
323
Version Security Number
323
Firmware on the CD-ROM
324
What must I do?
325
Key data
325
Firmware installation overview
326
PCI modules
327
After firmware installation
329
Appendix B:
Components on nCipher CD-ROMs
330
nCipher component bundles
330
nCSS User CD-ROM
335
CipherTools CD-ROM
335
CodeSafe CD-ROM
336
Components Required for Particular Functionality
337
PKCS #11 applications
338
Cryptographic Hardware Interface Library applications
338
nCipherKM JCA/JCE cryptographic service provider
338
nCipher SNMP monitoring agent
339
Appendix C:
Environment variables
340
Appendix D:
Logging and debugging
343
Environment variables to control logging
343
Logging from the nCipher CSP
348
Logging and debugging information for PKCS #11
349
Hardserver debugging
350
Debugging information for payShield
350
Debugging information for Java
352
Appendix E:
Installed Utilities
354
Appendix F:
The nCipher SNMP monitoring agent
361
Activating the nCipher SNMP agent
362
Default settings
363
Do you already have an SNMP agent running?
363
Activation of the SNMP agent
363
Further Information
364
Using the nCipher SNMP agent with a manager application 367

Useful nCipher SNMP agent command-line switches
382
Using the SNMP command line tools
385
Chapter 1: Introduction
General information
This guide describes how to use an nShield, payShield or payShield
Ultra hardware security module (or HSM) to protect and accelerate
the performance of the longterm cryptographic keys that are used by
your applications, including payment and related applications on
payShield modules.
In this guide, the term nShield refers to any of the nShield, payShield
or payShield Ultra modules. Information specific to the payShield and
payShield Ultra modules is clearly marked.
nCipher modules use the security world paradigm to provide a secure
environment with both application independence and platform
independence for all your module and key management operations.
Security worlds have the flexibility and scalability to suit your needs,
while also providing the robustness that is needed for every day
operation as a key component in your IT infrastructure.
Standard nCipher security worlds need to be prepared for use with
payShield applications. Although it is possible to convert an existing
security world for use with payShield, nCipher recommends that you
create a new security world and then follow the instructions in
payShield security world properties on page 191. Be sure to create
back up copies of any existing data in your kmdata directory before
creating a new security world, or attempting to convert an existing
security world.
All nCipher modules support standard cryptography frameworks and
can be quickly integrated with many standards based products.
10
1 Introduction
Audience
Audience
Read this guide if you need to configure or administer an nShield or
payShield module, and you use or require an nCipher security world
to protect your keys.
This guide assumes that you are familiar with the basic concepts of
cryptography and Public Key Infrastructure (PKI).
This guide assumes that you have read the Hardware Installation
Guide and that you have installed your nShield or payShield module.

Chapter 1: Introduction, this chapter, describes the purpose and
intended audience of this guide.
Chapter 2: nCipher security worlds describes the concept of security
worlds.
Chapter 3: Getting the module working describes the steps involved
in getting the module working.
Chapter 4: Changing the module state describes how to change the
state of the module.
Chapter 5: Uninstalling describes how to uninstall nCipher software.
Chapter 6: Configuring the hardserver describes how to configure the
hardserver software, which controls communication between
applications and nCipher modules.
Chapter 7: Using multiple modules describes how to install additional
modules on a system where at least one module and the server
software have already been installed.
Chapter 8: Feature Enabling nCipher Modules describes how to order
and enable new features purchased from nCipher.
11
1 Introduction
Chapter 9: Using CodeSafe Applications describes CodeSafe

applications.
Chapter 10: Using KeySafe introduces KeySafe, nCiphers security
world management tool.
Chapter 11: Managing security worlds contains detailed information
about working with security worlds, including adding a module to an
existing security world.
Chapter 12: About payShield installations describes how to configure
a payShield installation.
Chapter 13: Remote Operator Card Sets describes the use of Remote
Operator card sets.
Chapter 14: Administration tasks with cards and softcards describes
how to perform card-management tasks that require an Administrator
Card Set.
Chapter 15: nShield Administrator Utilities describes the utilities that
are used in this manual.
Appendix B: Components on nCipher CD-ROMs lists the contents
of the standard bundles and the additional software supplied on your
nCipher CD-ROM.
Appendix A: Upgrading module firmware describes how to upgrade
your nCipher module if nCipher has supplied updated firmware.
Appendix E: Installed Utilities lists all the utilities installed with the
nCipher software.
Appendix F: The nCipher SNMP monitoring agent describes how to
use the supplied Simple Network Management Protocol (SNMP)
agent with your nCipher module.
12
1 Introduction
Conventions
Conventions
nCipher modules
The following terms are used to distinguish different module versions:
Term
Model number
Used for
nCipher PCI module
nCnnnnP-nnn
Any nCipher module with

a PCI interface.
nCipher nToken module
nC2022p-000 or
nC2023p-000
an nCipher nToken
module (PCI interface).
nCipher netHSM module
nHnnnn
Any nCipher netHSM

module (netHSM
300/800/1600, payShield
net, or payShield Ultra
net).
acceleration-only module
nC10nnX-nnn
Any nCipher module that

does not support key
management (nFast
module).
key-management module
nC30nnX-nnn,
nC40nnX-nnn, or
nHnnnn
Any nCipher module that

supports key management
(nForce, nShield,
payShield, netHSM
300/800/1600, payShield
net, or payShield Ultra
net).
OEM PCI 1600

key-management module
nC3033P-1600
The OEM PCI 1600

modules are supplied to
OEM customers only.
In this table, n is any integer.
13
1 Introduction
Conventions
Version numbers
The version number shown on the copyright page and at the bottom
of each page in this guide is the version number of this document.
Please quote this version number if you contact Support at nCipher
with queries about nCipher documentation.
nCipher software
The hardserver software controls communication between
applications and nCipher modules, which may be installed locally or
remotely. It runs as a service on the host computer.
The nCipher support software is a collection of programs and utilities,
including the hardserver, supplied by nCipher to install and maintain
your nCipher security system.
Default directory
By default, nCipher software is installed in the /opt/nfast/ (Unix) or
C:\nfast (Windows) directory, referred to as the nCipher directory.
Instructions in this guide are given on the assumption that nCipher
software was installed in this location. If you install the software in
another directory, you must set the environment variable
NFAST_HOME to point to the directory where the software is
installed. You can choose to install nCipher software in another
location, in which case you must substitute your location accordingly.
An environment variable, NFAST_HOME, is used to specify the
default location for nCipher software. For further information on
setting environment variables, refer to Setting the environment
variables on page 49.
14
1 Introduction
Conventions
Typographical conventions
Note
The word Note in the margin indicates the appearance of important

supplemental information.
If there is a danger of static damage, this is indicated by the reaching
hand symbol in the margin.
If there is a danger of loss or exposure of key material (or any other
security risk), this is indicated by a security triangle in the margin.
If there is a danger of damage to the hardware, this is indicated by a
caution triangle in the margin. If you see this symbol on the product
itself, please refer to the Hardware Installation Guide.
If there is a danger of electric shock to the user, this is indicated by a
warning triangle in the margin.
Examples of onscreen terminal display, both of data returned and of
your input, are represented in a form like this:
install
Keyboard keys that you must type are represented like this: Enter ,
Ctrl - C .
15
1 Introduction
This guide forms one part of the information and support provided by
nCipher. The following documents are produced to support nCipher
products, and the guides for your product can be found in the
document directory of the CD-ROM for that product:
Guide
PDF file
Hardware Installation Guide, for information on

hardware installation and troubleshooting; a
printed copy is also supplied with nCipher
modules (part number N-001027).
Hardware_Installation.pdf
nShield/payShield Operator Guide, for

information on managing keys and other tasks
with an nShield/payShield module that do not
require an Administrator Card.
nShield_Operator.pdf
CodeSafe/C Developers Guide, for reference

material about developing in C for the Secure
Execution Environment.
CodeSafe_C_Developer.pdf
Integration Guide, for information on developing

applications with an nCipher module using
industry standard interfaces.
Integration_Guide.pdf
nCore Developers Guide, for information on

developing applications with an nCipher module
using the nCipher API and NFKM library.
nCore_Developer_Guide.pdf
nCore Developers Reference, for reference

material covering nCipher API, C generic stub,
and NFKM libraries.
nCore_Developer_Ref.pdf
payShield Developer Reference, for payShield

developer reference material
payShield_Developer_Ref.pdf
Key-loading Solution Guide, for information

about nCiphers key-loading solution.
Key-loading_Solution.pdf
Further information
Release notes containing the latest information about the nCipher
products are available in the release directory of the CD-ROM.
16
1 Introduction
Further information
The Java Generic Stub classes, nCipher KM JCA/JCE provider

classes, and Java Key Management classes are supplied with HTML
documentation in standard Javadoc format, which is installed in the
appropriate nfast/java directory when you install these classes.
nCipher also supplies a performance tool that you can use to test Web
server performance both with and without an nCipher module in order
to confirm performance. This tool is supplied separately. If you
require a copy, contact your nCipher sales representative.
All nCipher product documentation, including a range of guides that
describe how to configure popular third-party applications, is
available from the nCipher web site:
http://active.ncipher.com/documentation/.
If you would like to receive security advisories from nCipher, please
subscribe to the low volume nCipher security-announce mailing list.
To do this, send a mail with the single word subscribe in the message
body to security-announce-request@ncipher.com.
If you cannot find the information you need or you are unable to solve
a problem with your nCipher module, contact Support at nCipher by
sending E-mail to support@ncipher.com.
17
Chapter 2: nCipher security worlds

Key management is the hardest part of cryptography. Although
designing secure cryptographic algorithms and protocols is not easy,
there is a large body of academic research upon which to rely.
Keeping the keys secret is much harder. nCipher has developed its
security world technology to provide an infrastructure for secure lifecycle management of keys.
Key management involves the procedures and protocols, both manual
and automated, that are used throughout the entire life cycle of
cryptographic keys. These procedures and protocols include the
generation, distribution, use, storage, destruction, and optional
archiving and disaster recovery of cryptographic keys.
The security world concept and its infrastructure enable nCipher to
offer several important features in a simple and intuitive, yet secure,
way, where all keys can be made available to all modules in the
security world.
These features include:
security
application independence
platform independence
flexibility
robustness
scalability.
The security world infrastructure lets you perform and control all
these activities under your chosen security policy.
A security world consists of:
one or more nCipher payShield, nForce, nShield, or netHSM

modules
18
2 nCipher security worlds
nCipher security worlds
a set of Administrator smart cards used to control access to

security world configuration and recovery operations. (Security
worlds compliant with the Federal Information Processing
Standards (FIPS) 140-2 at level 3 require the use of smart cards
to authorize most operations; see FIPS 140-2 compliance on page
23 for more information about nCipher and FIPS.)
an optional set or sets of Operator smart cards used to control

access to application keys. (Security worlds compliant with the
Federal Information Processing Standards (FIPS) 140-2 at level
3 require the use of smart cards to authorize most operations; see
FIPS 140-2 compliance on page 23 for more information about
nCipher and FIPS.)
some cryptographic key and certificate data that is encrypted

using the security world key and stored on a host computer or
computers.
Figure 1 shows how these components are related to one another.

Cards, keys, and even modules can be added or removed at any time.
These elements are linked by the security world key, which is unique
to each world.
Distributing the keys used for different tasks within the security world
over different storage media means that a security world can recover
from the loss of any one element. It also increases the difficulties
faced by an attacker, who needs to obtain all the elements before
gaining any information.
19
Figure 1
Security
The security world
Security
Most importantly, a key-management system must store keys
securely. Security must be designed into the system from the start; it
cannot be added later.
The nCipher security world has been designed to ensure that keys
remain secure throughout their life cycle. The security world uses
multiple interlocking keys, and because of this, each key is always
protected by another key, even during recovery operations.
20
Security
Because the security world is built around nCipher key-management

modules, keys are only ever available in plain text in secure hardware.
The security world uses smart cards for two different purposes:
Note
one set of cards forms an Administrator Card Set that is used to

control access to recovery functions
one or more sets of cards referred to as Operator Card Sets that

are used to control access to application keys.
In strict FIPS 140-2 Level 3 security worlds, the Administrator Card

Set or an Operator Card Set is needed to authorize most operations,
including the creation of keys and Operator Card Sets.
Each card set consists of a number of smart cards, N, of which a
smaller number, K, is required to authorize an action. The required
number is sometimes referred to as the threshold.
Note
The value for K is intended to be less than N. Although it is possible

for K to equal N, this is not recommended because an error on one
card renders the whole card set unusable. If this happens with your
Administrator Card Set, you are forced to replace your security world
and generate new keys.
An Administrator Card Set is used to authorize several different
actions, and each of these can have a different value for K. All the card
sets are distinct; an individual smart card can only belong to the
Administrator Card Set or to one Operator Card Set.
Each user can access the keys protected by the security world and the
keys protected by their Operator Card Set. They cannot access keys
that are protected by other Operator Card Sets.
The smart cards that are used as Operator Cards employ the security
world key to perform a challenge-response protocol with the module.
This means that Operator Cards can only be used by a module
belonging to the same security world that they do.
Note
An individual smart card can be used as either a part of the

Administrator Card Set or as part of an Operator Card Set, but not as
part of both.
21
Security
Security worlds and Remote Operator

The Remote Operator feature makes it possible for the contents of a
smart card inserted into the slot of one module, the attended module,
to be securely transmitted and loaded onto another module, the
unattended module. Only Operator Cards can be loaded to remote
slots in this way. Both the attended module and the unattended
module must be in the same security world.
The Remote Operator feature is useful such circumstances as when
you need to load a key protected by an Operator Card Set onto a
machine to which you do not have physical access (for example,
because it is in secure area).
Secure communication channels between the attended and unattended
modules are achieved using an impath (an abbreviation of
intermodule path), which is the secure protocol that nCipher modules
use for communication over IP networks. An impath is a
cryptographically secure channel between two nCipher nC-series
hardware security modules. Data sent through such a channel is
secure against both eavesdroppers and active adversaries. The channel
can carry arbitrary user data as well as module-protected secrets, such
as share data, to be passed directly between modules.
Security worlds shared with netHSM modules

Previously, in order to maintain data consistency in security worlds
that included both netHSMs/payShield net modules and other types of
nCipher modules, you had to copy files manually between the
netHSM remote file systems and non-netHSM client machines.
However, the client cooperation mechanism now allows client
computers for non-netHSM module types to automatically update the
security world and key data stored on the remote file system. See
Setting up client cooperation on page 53 for more information.
22
Security
FIPS 140-2 compliance

All nCipher security worlds are compliant with the Federal
Information Processing Standards 140-2. The default setting for
nCipher security worlds is FIPS 140-2 at level 2.
A security world that complies with the roles and services section of
FIPS 140-2 level 2 does not require any authorization to create an
Operator Card Set or an application key. All security worlds rely on
the security features of your operating system to control which users
can write data to the host.
FIPS 140-2 level 3 compliance

When you create a security world, you can choose whether you want
the security world to comply with the roles and services section of
FIPS 140-2 at level 2 or level 3. The FIPS 140-2 level 3 option is
included for those customers who have a regulatory requirement for
compliance with FIPS 140-2 at level 3.
A security world that complies with FIPS 140-2 level 3 requires
authorization from any smart card that is part of the security worlds
Administrator Card Set, or an Operator Card Set, before you can
create or erase an Operator Card Set.
Note
A security world only provides a complete level 3 compliant system

when used with nShield and payShield modules, which have the
additional physical security coating required by the FIPS 140-2 level
3.
If you choose to create a security world that complies with FIPS 1402 level 3, the module initializes in strict FIPS mode. This option
ensures that the module complies with the roles and services, key
management, and self-test sections of FIPS 140-2 at level 3, as
described in its validation certificate.
For more details of the nShield/Payshield FIPS 140-2 validation see
http://csrc.nist.gov/cryptval/140-2.htm
23
A security world can protect keys for any nCipher-aware software.
Each key belongs to a specific application and is only ever used by
that application. However, within a single security world, every key
can belong to a different application. Keys are stored along with any
additional data that is required by the application.
You do not need to specify which applications you will use. You can
add a key for any supported application at any time.
The security world requires no knowledge of how the key will be used
by an application. A security world controls the protection for the key;
the application determines how it is used.
Although keys belong to a specific application, Operator Card Sets do
not. If a user requires keys for different applications, they can all be
protected under the same Operator Card Set.
Figure 2 illustrates this.
Figure 2
Operator Card Sets, keys, and applications
24
Card Set 1 protects keys for use with Application 1 and

Application 2.
Card Set 2 protects a single key for use with Application 2.
Card Set 3 protects keys for use with Application 2 and

Application 3.
The security world protects a key for use with Application 3.
A security world is completely platform independent. All key
information is stored in nCipher's proprietary format. This format can
be read by any computer supported by nCipher, regardless of the
native format used by that computer. This means that you can safely
move a security world between platforms, even between platforms
with differing native formats. For example, you can move a security
world between Windows and UNIX platforms. You can also include
hosts running different operating systems in the same security world.
Note
When copying host data between computers using different Operating

Systems or disk formats, use a mechanism that preserves the original
data format and line endings (such as .tar file archives).
Flexibility
Within a security world, you can choose the relevant level of
protection for each application key that you create.
When you create a security world, a cryptographic key is generated
that protects the application keys and Operator Card Sets in the
created security world. You can choose to make this security world
key can be a Triple DES (Data Encryption Standard) or an AES
(Advanced Encryption Standard) key.
25
Flexibility
Using the security world key: module-protected keys

If you have an application key that must be available to all your users
at all times, it can be protected by the security world key. This is called
a module-protected key. Application keys protected by the security
world key have no pass phrase. Module-protected keys can be used by
any instance of the application for which they were created, provided
that it is running on a server fitted with a module belonging to the
correct security world.
This level of protection is suitable for high-availability Web servers
that you want to recover immediately if the computer resets.
Using Operator Card Sets: card-set protected keys

If you want to restrict key access to a particular user, you can create a
set of smart cards known as an Operator Card Set. There is no limit to
the number of Operator Card Sets that you can create within a security
world.
An Operator Card Set belongs to a specific security world. It cannot
be read, erased, or even formatted except in a module from its security
world.
An Operator Card Set stores a number of symmetric keys that are used
to protect the working keys. These keys are Triple DES keys.
Each card in an Operator Card Set stores only a fragment of the
Operator Card Set keys. These keys can only be re-created if you have
access to enough of their fragments. Because cards sometimes fail or
are lost, the number of fragments required to re-create the key (K)
should usually be less than the total number of fragments (N).
26
Flexibility
Using card sets for extra security

If you want to create a card set for extra security, you need to make K
large and N less than twice K (for example 3 of 5, or 5 of 9). This
practice ensures that if you have a set of K cards that can be used to
recreate the key, you can be certain that there is no other such set in
existence.
Note
Some applications restrict K to 1.
Using card sets to share keys

You can use card sets that enable the same keys to be used in a number
of different modules at any one time, but you must leave one of the
cards in each module.
If you want to use keys protected by the card set across multiple
modules, you may want to make K equal to 1 and N equal to the
number of modules. You can then insert a card into each module.
If you want to issue the same key to a set of users, again you would
want to make K equal to 1 and N equal to the number of users, giving
one card to each user.
If a card becomes damaged, the cardset can be recovered using the
Administrator Card Set.
Note
You can only recover card sets that were created with the recovery
option explicitly set.
Using card sets for high availability

You may have some keys to which you must have access at all times
and with which you cannot afford to risk the failure of a smart card.
In such a case, you can create a 1-of-2 card set. Use the first card as
the working card and store the spare second card in a safe. If the
27
Flexibility
working card fails, retrieve the spare card from the safe and use it until
you re-create a new set of two cards, as described in Replacing an
Operator Card Set or recovering keys to softcards on page 32.
Note
You can only recover card sets that were created with the recovery
option explicitly set.
Using pass phrases

Each Operator Card can be given a pass phrase. The pass phrases are
independent. You can choose to give only some cards in a card set
pass phrases.
You can change the pass phrase on a card at any time. For information
on changing pass phrases, see Changing pass phrases with cardpp on
page 218 or the appropriate Operator Guide for your module. This
requires the card, the existing pass phrase, and a module that belongs
to the security world.
Note
Some applications do not support the use of pass phrases.

There is no absolute limit on the length of pass phrases. However,
some applications may not accept pass phrases longer than 255
characters. Likewise, the security world does not impose restrictions
on which characters you can use, although some applications may not
accept certain characters.
Using persistent Operator Card Sets

If you create a standard Operator Card Set, the keys protected by a
card can only be used while that card, or the last card loaded in the
case of card sets, is in the nCipher modules smart card reader. The
keys protected by this card are removed from the memory of the
module as soon as the card is removed from the smart card reader.
Although this feature provides added security, it means that only one
user can load keys at any time because there is only one smart card
reader on the module.
28
Flexibility
Keys that are protected by a given Operator Card Set cannot be shared
simultaneously between a large pool of modules.
Therefore, the security world architecture gives you the option of
making an Operator Card Set persistent. This means that the keys
protected by a card persist after the card has been removed. This
enables you to use the same smart card in several modules
simultaneously. It also means that several users can load keys onto the
same module at the same time. The nCipher support software
maintains strict separation between the keys loaded by each user, and
each user only has access to the keys protected by their Operator Card
Set.
Keys protected by a persistent card are automatically removed from
the module:
Note
when the application that loaded the Operator Card Set closes the
connection to the module.
after a time limit that may be specified when the card set is
created.
when an application chooses to remove a key.
Some applications automatically remove a key after each use,

reloading it only when required. Such applications do not benefit from
persistent Operator Cards. The only way of sharing keys between
modules for these applications is by having multiple smart cards in an
Operator Card Set.
Although the module stores the key, the key is only available to the
application that loaded it. If you want to use keys protected by this
card in another application, you must re-insert the card, and enter its
pass phrase if it has one. Certain applications are designed to allow
only one user to be logged in at a time, in which case they remove any
previously loaded persistent Operator Card Set used in that
application before allowing the user to log into with a new Operator
Card Set.
29
Flexibility
You can manually remove all keys protected by persistent cards by

pressing the modules Clear button or by turning off power to the
module. Either process removes all keys protected by Operator Card
Sets from the module, including the card in the reader. In such cases,
all users of any applications using the module must log in again.
You are offered a choice as to whether or not to make an Operator
Card Set persistent when you create the card set. Once you have made
the decision, you cannot change it. Persistence is a property of the
card set.
A security world can contain a mix of persistent and non-persistent
card sets.
Using softcard-protected keys

If you want to use pass phrases to restrict key access but avoid using
physical tokens (as required by smart-card protection), you can create
a softcard-protected key. A softcard is a file containing a logical token
that cannot be loaded without a pass phrase; its logical token must be
loaded in order to authorize the loading of any key that is protected by
the softcard. Softcard files are stored in the kmdata directory and have
names of the form softcard_hash (where hash is the hash of the logical
token share).
Softcard-protected keys offer greater security than module-protected
keys and also have greater availability than keys protected by operator
card sets (albeit without the greater security obtained through the
requirement of physical tokens to authorize key-loading).
A softcard's pass phrase is set when you generate it, and you can use
a single softcard to protect multiple keys. Softcards function as
persistent 1-of-1 logical tokens, and after a softcard is loaded, it
remains valid for loading its keys until its KeyID is destroyed.
30
Robustness
Robustness
If you are using cryptography in a production environment, you need
to know that it will work 24 hours a day, 7 days a week. If something
goes wrong, you must be able to recover without compromising your
security. An nCipher security world offers all of these features.
Backup and recovery

The nCipher security world data stored on the host is encrypted using
your choice of either Triple DES or AES encryption.
You should regularly back up the data stored in the kmdata directory
safely with your normal backup procedures.
It would not matter if an attacker were to obtain this data because it is
worthless without the encryption keys, stored in your module, and the
Administrator cards for that security world.
When you create a security world, it automatically creates recovery
data for the security world key. As with all host data, this is encrypted
with Triple DES. The cryptographic keys that protect this data are
stored on a set of smart cards called the Administrator Card Set. The
keys are split among the cards in the Administrator Card Set using the
same K-of-N mechanism as for an Operator Card Set. The
Administrator Card Set protects several keys that are used for
different operations.
The cards in the Administrator Card Set are only used for recovery
operations and adding extra modules to a security world. At all other
times, these cards should be stored in a safe.
Note
In strict FIPS 140-2 Level 3 security worlds, the Administrator Card

Set or an Operator Card Set is needed to control many operations,
including the creation of keys and Operator Card Sets.
31
Robustness
Replacing a module
If you have a problem with a module, you can replace it with a new
module by using the Administrator Card Set and the recovery data to
load the security world key securely. Use the same mechanism to
reload the security world key if you need to upgrade the firmware in
the module or if you need to add extra modules to the security world.

If you lose one of the smart cards from the Administrator Card Set, or
if the card fails, you must immediately create a replacement set using
the KeySafe Replace Administrator Card Set option or the racs utility.
The module does not store recovery data for the Administrator Card
Set. It relies on the fact that K is less than N; therefore, it can re-create
all the keys on the module even if the information from one of the
cards is missing.
You cannot replace the Administrator Card Set unless you have the
required number of current cards and access to their pass phrases.
Therefore, as soon as you lose one card, or as soon as one card fails,
you should replace the set.
Although replacing the Administrator Card Set deletes the copy of the
recovery data on your host, the old Administrator Card Set can still
be used with the old host data, which may be on backup tapes and
other hosts. To protect against this risk, you must immediately erase
the old Administrator Cards after you create a new Administrator
Card Set.
Replacing an Operator Card Set or recovering keys to softcards

If you lose an Operator Card, you lose all the keys that are protected
by that card. In order to prevent this, a security world can optionally
store a second copy of the working key that is protected by a recovery
key.
32
Robustness
Similarly, you can recover keys protected by one softcard to another

softcard.
Note
The ability to recover an Operator Card Set is an option that is

enabled by default during security world creation. To disable
recoverability, you must explicitly choose to do so during the security
world creation process. Once set during security world creation, the
ability (or inability) to recover an Operator Card Set can never be
altered.
Note
Keys protected by an Operator Card Set can only be recovered to

another Operator Card Set, and not to a softcard. Likewise, softcardprotected keys can only be recovered to another softcard, and not to
an Operator Card Set.
You can use the rocs command-line utility or KeySafe to create new
working copies of your keys protected by the key on a given card set.
To recover keys protected by one softcard to another softcard, you
must use the rocs command-line utility.
Replacing Operator Card Sets and softcards requires authorization.
Otherwise, an attacker could simply duplicate a set or softcard
without your knowledge. Therefore, the recovery keys are protected
by the Administrator Card Set.
Storing any key recovery data introduces some extra risk, because an
attacker with the Administrator Card Set and a copy of the recovery
data could re-create your security world. You may have some keys
that you consider to be especially sensitive. In this case, if you lose the
Operator Card Set that protects the key, you may choose to issue a new
key. Therefore, you can turn off the key recovery feature for the
security world or for a specific key.
Recovery data can only be generated when you create the security
world or key. If you choose not to create recovery data when you
generate the security world or key, it cannot be added later. If you have
not selected the recovery feature for the security world, it cannot be
enabled for any key in the security world.
33
Scalability
Similarly, if you choose to create recovery data when you generate the
security world or key, it cannot be removed later in a secure manner.
The recovery data for application keys is kept separate from the
recovery data for the security world key. The security world always
creates recovery data for the security world key. It is only the recovery
of application keys that is optional.
Scalability
A security world is scalable. You can add multiple modules to a server
and share a security world across multiple servers. You can also add
Operator Card Sets and application keys at any time. You do not need
to make any decisions about the size of the security world when you
create it.
To share a security world across multiple servers:
ensure each server has at least one module fitted
copy the host data to each server or make it available on a shared

disk
use the recovery data and the Administrator Card Set to load the
required cryptographic keys securely onto every module.
If you want to have access to the same keys on every server, you must
ensure that all changes to the data are propagated to the remaining
servers. If your are part of a cluster, then the tools provided by the
cluster should synchronize the data. If the servers are connected by a
network, then they could all access the same copy of the data. There
is no risk of an attacker obtaining information by snooping on the
network, as the data is only ever decrypted inside a module.
Alternatively, you can maintain copies of the data on different servers.
It is now possible to allow non-netHSM modules to automatically
access the remote file system (RFS) used by netHSM and payShield
NET modules and to share security world and key data stored in the
34
kmdata directory. Client modules that access data in this way are
described as cooperating clients. See Setting up client cooperation on

page 53 for more information.
Load sharing
If you have more than one module on your system and you load the
same key onto each module, your nCipher-aware applications can
make use of the load sharing features in the nCipher server to share
the cryptography between them.
Note
It is up to the application to implement load sharing. Some

applications may not be able to make use of this feature.

KeySafe provides an intuitive and easy-to-use graphical interface for
managing security worlds. KeySafe manages the security world and
the keys protected by it. See the Operator Guide for full information
about KeySafe.
Note
Most applications store only their long-term keys in the security

world. Session keys are short term keys generated by the application
which are not normally loaded into the security world.
Although you use KeySafe to generate keys, it is your chosen
application that actually uses them. You do not need KeySafe to make
use of the keys that are protected by the security world. For example,
if you share a security world across several host computers, you do not
need to install KeySafe on every computer. If you want to manage the
security world from a single computer, you can install KeySafe on just
that one computer even though you are using the security world data
on other machines.
KeySafe enables you to:
35
Note
create a security world and its Administrator Card Set, either

FIPS 140-2 level 2 or level 3
This option provides compliance with the roles and services of the
FIPS 140- 2 level 3 standard. It is included for those customers who
have a regulatory requirement for compliance.
add a module to a security world
remove a module from a security world
replace an Administrator Card Set
create Operator Card Sets
list the Operator Card Sets in the current security world
change the pass phrase on an Operator Card
remove a lost Operator Card Set from a security world
replace Operator Card Sets
erase an Operator Card
add a new key to a security world
import a key into a security world
list the keys in the current security world
delete a key from a security world.
KeySafe does not provide tools to back up and restore the host data or
update module firmware, nor does KeySafe provide tools to
synchronize host data between servers. These functions can be
performed with your standard system utilities.
In addition to KeySafe, nCipher also supplies command-line utilities
to manage the security world. Current versions of these tools can be
used interchangeably with the current version of KeySafe.
36

The security world can protect keys for a range of industry standard
applications. See the nCipher web site (http://www.ncipher.com) for
details of applications that are currently supported.
nCipher has produced Application Guides for many supported
applications. These Application Guides contain information about
installing and configuring the application to work with nCipher
modules and security worlds.
For information on the range of Application Guides available, either
visit the nCipher web site (http://www.ncipher.com) or contact
Support at nCipher (support@ncipher.com).
The nCipher PKCS #11 library and security worlds

Many applications use a PKCS (Public Key Cryptography Standard)
#11 library to generate and manage cryptographic keys. nCipher has
produced a version of the PKCS #11 library that uses the security
world to protect keys.
Enabling a PKCS #11 based application to use nCipher hardware key
protection involves configuring the application to use the nCipher
PKCS #11 library.
A PKCS #11 token created by the nCipher PKCS #11 library is a
security world Operator Card Set.
The current PKCS #11 standard only supports tokens that are part of
a 1-of-N card set.
A security world does not make any distinction between different
applications that use the nCipher PKCS #11 library. Therefore, you
can create a key in one PKCS #11 compliant application and make use
of it in a different PKCS #11 compliant application.
37
Risks
Risks
Even the best-designed tools cannot offer security against every risk.
Although a security world can control which user has access to which
keys, it cannot prevent a user from using a key fraudulently. For
example, a security world can only determine whether a user is
authorized to use a particular key; it cannot determine whether the
message being sent with that key is accurate.
A security world can only manage keys that were created inside the
security world; keys created outside a security world, even if imported
into the security world, may remain exposed to a security risk.
Most failures of security systems are not the result of inherent flaws
in the system, but result from carelessness on the part of the users. The
following basic rules apply to any security system:
Note
Keep your smart cards safe.
Always obtain smart cards from a trusted source: from nCipher

or directly from Gemplus.
Never insert a smart card used with nCipher key management

into an untrusted smart card reader.
Never insert any untrusted smart card into your module.
Never tell anyone your pass phrase.
Never write down your pass phrase.
Never use a pass phrase that is easy to guess.
Only use the Administrator Card Set in modules connected to

trusted hosts.
If you have any doubts about the security of a key and/or security
world, you should replace that key and/or security world with a newly
generated one.
38
Chapter 3: Getting the module working

This chapter describes the steps involved in setting up the nCipher
software to work with the module for the first time. These steps must
be performed in the following order:
1.
Determine the requirements for the module, as described in

Determining module requirements on page 39.
2.
Complete any prerequisites to installing nCipher support

software, as described in Prerequisites to software installation on
page 40.
3.
Install the software, as described in Software installation

procedure on page 43.
4.
Perform post-installation tests and software environment

configurations, as described in After software installation on
page 46.
5.
Configure the hardserver, as described in Configuring the

hardserver on page 51. Also, if necessary, set up client
configuration, as described in Setting up client cooperation on
page 53
6.
Create and configure the security world, as described in Creating

and configuring a security world on page 56.
7.
Configure the payShield installation, as described in Creating

and configuring a payShield installation on page 64.
8.
Create the Operator Card Set, as described in Creating the

Operator Card Set on page 71.
Determining module requirements

Before you start to set up the module, you must identify the specific
requirements of your installation. You (or your security policy officer)
should have determined the following:
39
3 Getting the module working
which optional components of the nCipher software you need to

install. To do this you need to know:
-
the applications that are to use the module.
any constraints on installing software on your computer.
the security requirements for the security world (see Determining

module requirements on page 39 for details of these options).
if you want to use payShield, the requirements for the payShield

installation, including the functions to be enabled (see About
payShield Card Sets on page 187 for details of these options).
Do not start the installation procedure until you have this information.

This section describes various steps you may need to take before
installing the nCipher support software. These are:
Installing and connecting the module on page 40
Removing existing installations on page 41
Installing Java patches on page 41
Identifying which components to install on page 42.
Installing and connecting the module

Before you install the nCipher support software on the host, the
module must be connected as described in the Hardware Installation
Guide.
40
Removing existing installations

nCipher recommends that you uninstall older versions of support
software before you install new support software. If the installer
detects an existing nCipher installation, it asks you if you want to
install the new components. These components replace your existing
installation.
Instructions for uninstalling nCipher support software are provided in
Chapter 5: Uninstalling.
The automated nCipher installers do not delete other components or
any key data and security world data that you have created.
Note
Because the nCipher server is installed as a service, it is only possible

to have one nCipher installation on any given computer.
Installing Java patches

nCipher currently supports JRE/JDK version 1.4.x.
If you intend to use KeySafe, Suns Java run-time environment
version 1.4.x or the equivalent developer kit must be installed. It is
recommended that you install Java before you install the nCipher
components. The Java executable must be on your path.
The DSE200s Web-based interface requires JRE/JDK version 1.3.x,
which is installed with the DSE200 support software.
Java software is available from http://java.sun.com/products/. If your
security policy does not allow the use of downloaded software, these
components can be obtained on CD-ROM from Sun or your operating
system vendor.
In order to use nCipher Java components, you may need to install
patches supplied by your operating system manufacturer. Refer to the
Sun documentation supplied with your Java installation.
41
The nCipher Windows install wizard determines whether you have a

Java Runtime Environment (JRE) installed by examining the registry.
Any warnings displayed by the installer apply to this JRE. If you
intend to use a JRE not defined in the registry (for example, if you
have multiple JREs installed), check that this JRE version is
compatible with nCipher support software.
Identifying which components to install

nCipher supplies standard component bundles that contain many of
the necessary components for your installation and, in addition,
individual components for use with supported applications. To be sure
that all component dependencies are satisfied, you can install all the
software components supplied, or you can choose to install only those
you need.
During the installation process, you are asked to choose which
bundles and components to install. Your choice depends on a number
of considerations, among them the following:
the types of application that will be using the module
the amount of disk space available for the installation
your companys policy on installing software. For example,

although it may be simpler to choose all software components,
your company might have a policy of not installing any software
that is not required.
You must install the hwsp Hardware Support bundle. If the hwsp
Hardware Support bundle is not installed, your module cannot
function.
Note
The nfdrv Windows device drivers component, required if you are using
an nCipher PCI card, is installed as part of the hwsp Hardware Support
bundle.
42
Additionally, nCipher recommends that you always install the ctls

Core Tools bundle, which contains all the nCipher command-line
utilities, including generatekey, low level utilities, and test programs.
Note
The Core Tools bundle includes the tclsrc Tcl run time component that
installs a run-time Tcl installation within the nCipher directories.
This is used by nCiphers tools for creating the security world, by
KeySafe, and by the new-world utility. This does not affect any other
installation of Tcl on your computer.
See Appendix B: Components on nCipher CD-ROMs for details of
the optional components. Ensure that you have identified those that
you require before you start the installation.

You should have removed any nCipher installation on the computer
before starting this installation. See Chapter 5: Uninstalling for more
information on uninstalling your software. If the installer detects an
existing nCipher installation, it asks you if you want to install the new
components. These components replace your existing installation, but
the installer does not delete other components that you have created.
Note
Because the nCipher server is installed as a service, it is only possible

to have one nCipher installation on any given computer.
nCipher supplies the nCipher client software as bundles of standard
packages that provide much of the required software for your
installation. In addition to the standard bundles, nCipher provides
individual packages for use with specific applications and features
supported by the module. Ensure you have determined which bundles
or packages you require before beginning the installation. (See
Identifying which components to install on page 42; further details
about the contents of bundles and packages are provided in Appendix
B: Components on nCipher CD-ROMs.)
Note
Visit the nCipher Web site support section to download Application

Guides that give advice on installing nCipher modules with a range
of third party applications.
43
nCipher supplies Windows 2000 Plug and Play drivers for the nCipher
module. These drivers have also been tested with Windows 2003
Server.
Take the following steps to install the nCipher server and associated
software:
1.
Log in as Administrator or as a user with local administrator

rights.
2.
Place the CD-ROM in the CD-ROM drive. If Autorun is enabled,

the installer runs automatically, detecting the version of
Windows and launching the appropriate installation program.
You can launch the installer (setup.exe, on the top level of the
CD-ROM) manually if Autorun is not enabled.
The installer displays the version number of the nCipher support
software that is to be installed.
Note
If you have an earlier installation of nCipher support software, the

installer detects this and gives you the option to uninstall the earlier
installation or quit the installer. The installer cannot install the
current release of nCipher support software unless any earlier
installation has been uninstalled. Uninstalling requires a reboot
before a new installation of the current software can commence.
Follow the onscreen instructions.
3.
The installer displays the nCipher license agreement. Accept the

license terms by clicking the Yes button for the installation to
continue.
4.
The installer displays a list of installable components. You must

install the hwsp Hardware Support bundle, and nCipher strongly
recommends installing the ctls Core Tools bundle. Otherwise,
choose to install all components, or select the components that
44
you require. See Appendix B: Components on nCipher

CD-ROMs for more information about choosing which
components to install.
By default, the installer places files in the C:\nfast directory, but
you are given the option of selecting a different directory. If the
installer detects an existing installation in a different directory, it
offers this other directory as the default.
5.
Note
If the installer detects an existing installation of the current release of

support software, it advises you of this. Click the Yes button to
continue.
6.
Note
Click the Next button, and the installer installs and performs basic
configuration of the selected components.
The installer advises you that it will create an icon on your

desktop for the nCipher CSP installation wizard.
Do not run the nCipher CSP installation wizard before you have
successfully installed the module.
When run, this wizard:
a.
installs the correct nCipher CSP
b.
makes the nCipher CSP the default SChannel provider, if

requested.
After you have completed the rest of the module installation

process, double click the nCipher CSP installation wizard icon to
install the nCipher CSP.
Note
You must install this version of the nCipher CSP to work with this
version of the nCipher software, even if you have a previous version
of the nCipher CSP installed.
For more information on using the nCipher CSP with IIS
(Internet Information Service) and Microsoft Certificate Server,
see the appropriate Operator Guide for your module and the
relevant application guide.
Click the Next button to continue the installation.
45
Note
7.
If you chose to install the nCipher SNMP agent, the installer

advises you that it does not run by default. Click the Next button
to continue.
8.
If you chose to install the nCipher PKCS #11 library and have an
existing PKCS #11 installation, the installer advises you of this.
The installer asks whether you want to configure the PKCS #11
library for use with Check Point VPN-1/Firewall-1. You can
choose to do one of the following:
a.
Select Yes, and then follow the steps in the Check Point
configuration dialog. See Check Points product
documentation for further information.
b.
Select No to continue the installation process without

configuring Check Point VPN-1/Firewall-1. You can
configure the PKCS #11 library for use with Check Point
VPN 1/Firewall 1 later by running the
ConfigPKCS11onCP.exe utility in the
C:\nfast\toolkits\\pkcs11 directory.
If you choose to configure the PKCS #11 library for use with Check
Point VPN-1/Firewall-1, install the PKCS #11 module only after
Check Point VPN-1/Firewall-1 is installed.
9.
When the installation is complete, click the Finish button.
After you have installed the software, perform post-installation tests

and software environment configurations as described in After
software installation on page 46.

Testing the installation
To check that the software has been installed correctly:
1.
Log in as a normal user.
2.
Open a command window.
46
3.
Verify that the server is running by using the following test

command (assuming that you installed the nCipher server in the
default directory):
C:\nfast\bin\enquiry
A successfully completed enquiry command returns output of a

form similar to the following:
server:
enquiry reply flags none
enquiry reply level Four
serial number ####-####-####
mode operational
version #.#.#
speed index ###
rec. queue ##..##
...
module #1:
...
mode operational
version #.#.#
...
connection status OK
The enquiry utility returns information on the nCipher server and

on each module.
-
The serial number returned is the electronic serial number.

This number is unique to each module. Keep a record of the
electronic serial number: you must quote it if you ever need
to contact Support at nCipher.
The version number for the server is the nCipher internal

release number of the server software.
The version number for the module is the nCipher internal

release number of the firmware.
If the enquiry utility returns an error message, refer to the

troubleshooting chapter in the Hardware Installation Guide.
47
Testing the smart card reader

On external smart card readers fitted to an nCipher PCI module, the
LED lights up red when the computer is switched on. If the LED does
not light up, check the connection. The LED changes color to green
whenever a card is inserted. If it does not change, check that you have
fully inserted the card.
Note
The LED is triggered by a mechanical switch that indicates only that

the card is inserted. It does not indicate that the card is a valid smart
card or that it is the correct way up.
The LED flashes briefly when you reset the module and when the
module changes state.
Note
Always insert the smart card with the contacts facing up.
You can check that the card reader of any module is working correctly
by inserting an nCipher smart card and using the following test
command (assuming that you installed the server in the default
directory):
C:\nfast\bin slotinfo -m MODULE [-s SLOT]
In this command, MODULE is the number of the module and SLOT is

the number of the slot. If you have only one module, MODULE is 1,
and if you do not specify a slot number, slotinfo returns information
about all slots.
This command should return either:
Module n slot 0:
Token not formatted
48
or
Module n slot 0:
Authentication key: 00000000-00000000-00000000-00000000-00000000
No data on token
3698 bytes free
Note
The authentication key and data size may vary.
Monitoring the module using Performance Monitor

You can monitor the performance of the nCipher modules that are
connected to a Windows host by using Microsofts Performance
Monitor.
When you install the nCipher server software it adds three new objects
to the Performance Monitor:
nCipher Connections
This provides statistics for each connection to the server with

an instance for each connection.
nCipher PerModule
This provides statistics for each nCipher module with an

instance for each module, identified by ModuleID.
nCipher ServerGlobals
This provides statistics for the nCipher server.

Note
To preserve security, connection instances are identified by a number.

This number is a simple counter and is not related to the ClientID .
Setting the environment variables

You can set nCipher specific environment variables as follows:
1.
Open the System dialog box by clicking the System icon in the
Control Panel.
49
2.
Select the Advanced tab and click the Environment Variables

button.
3.
To add a variable, click New. Alternatively, to edit an existing

variable select an entry in the System Variables list and click Edit.
4.
In the Variable Name text box, type or edit the name of the
environment variable (for example, NFAST_HOME).
5.
In the Variable Value text box, type or edit the value to use.
6.
Click the OK button to set the value, and then click the OK button
to close the dialog box.
7.
Restart the nFast Server service.
See Appendix C: Environment variables for detailed information on

the environment variables used by nCipher software.
Note
You must ensure that KeySafe and the hardserver are communicating
on the same sockets. If you have set the environment variables
NFAST_SERVER_PORT or NFAST_SERVER_PRIVPORT in the server
environment, they must also be set to the same value in the KeySafe
environment. The port on which the hardserver listens for local
privileged TCP connections (priv_port) must be set to 9001 and the
port on which the hardserver listens for local nonprivileged TCP
connections (nonpriv_port) must be set to 9000.
Logging and debugging

Note
The current release of nCipher support software uses controls for

logging and log files, as well as debugging, that differ from those used
in previous releases. However, settings you made in previous releases
to control logging, log files, and debugging are still generally
supported in the current release, although in some situations the
output is now formatted differently.
The nCipher Support Software generates logging information that is
configured through a set of four environment variables:
NFLOG_FILE
50
Note
NFLOG_SEVERITY
NFLOG_DETAIL
NFLOG_CATEGORIES
If none of these logging environment variables are set, the default

behaviour is to log nothing, unless this is overridden by any individual
library. If any of the four logging variables are set, all unset variables
are given default values.
Some components of the nCipher Support Software generate separate
debugging information which you can manage differently. If you are
setting up the module in order to develop software that uses it, you
should configure debugging at this point. Otherwise, you should
proceed to Creating and configuring a security world on page 56.
Detailed information about controlling logging information by means
of these environment variables is supplied in Appendix D: Logging
and debugging.
Configuring Java support for KeySafe

In order to use KeySafe, you must add the nfjava, kmjava, and keysafe
classes to your Java class path after nCipher support software
installation is complete. See the Operator Guide for more information
about KeySafe.

Configuring the hardserver
The hardserver handles secure transactions between the modules
connected to the host computer and applications that run on the host
computer. In addition, the hardserver controls any remote slots that
the module uses and loads any SEE (Secure Execution Engine)
machines that are to run on the module.
51
The hardserver can handle transactions for multiple modules. This

does not require configuration of the hardserver; see Chapter 7: Using
multiple modules for information.
The hardserver must be configured to control:
the way the hardserver communicates with remote modules
the way the hardserver communicates with local modules
the import and export of remote slots
the loading of SEE machines on to the module when the

hardserver starts up.
The hardserver configuration file defines the configuration of the

hardserver. It is stored in the directory
%NFAST_HOME%\kmdata\config, which by default is
C:\nfast\kmdata\config. A default version of this file is created when
the nCipher support software is installed. See Chapter 6: Configuring
the hardserver for full information about the hardserver configuration
file.
Note
In some previous releases of nCipher support software, hardserver

configuration was controlled by environment variables. The use of
these variables has been deprecated. If any of these environment
variables are still set, they override the settings in the configuration
file.
You must load the configuration file for the changes to the
configuration to take effect.
To configure the hardserver, follow these steps:
1.
Save a copy of the configuration file

C:\nfast\kmdata\config\config so that the configuration can be
restored if necessary.
2.
Edit the configuration file C:\nfast\kmdata\config\config to

contain the required configuration. (See Hardserver
configuration file on page 85 for descriptions of the options in the
configuration file.)
52
3.
4.
Run the cfg-reread command-line utility to load the new

configuration. See cfg-reread on page 228 for details.
Test that the hardserver is configured correctly by running the
enquiry command-line utility. (See enquiry on page 229 for full
details of the enquiry command-line utility and its output.)
Check that a module with the correct characteristics appears in

the output.
5.
Test that the client has access to the security world data. To do
this, run the nfkminfo command-line utility.
Check that a module with the correct ESN appears in the output
and has the state 0x2 Usable.
Setting up client cooperation

It is now possible to allow non-netHSM modules to automatically
access the remote file system (RFS) used by netHSM and payShield
NET modules and to share security world and key data stored in the
kmdata directory. Client modules that access data in this way are
described as cooperating clients.
To configure client cooperation for modules that are not netHSM or
payShield modules, complete the following steps:
1.
Configure the remote file system used by your netHSM module

to accept access by cooperating clients. For information about
how to do this see the netHSM Administrator Guide.
2.
On each client that is to be a cooperating client (that is, that is to

access the remote file system in order to share key data), you
must run the rfs-sync command with appropriate options:
53
For clients that use a local KNETI (the nCipher integrity key,
which is installed when the module is shipped) for
authorization and which are to be given write access to the
remote file system, run the command:
rfs-sync --setup rfs.rfs.rfs.rfs
For clients that do not have a local KNETI and require write
access, run the command:
rfs-sync --setup --no-authenticate rfs.rfs.rfs.rfs
In these commands, rfs.rfs.rfs.rfs is the IP address of the machine

where the remote file system is located.
Note
The rfs-sync utility uses lock files to ensure that updates are made in a
consistent fashion. If a rfs-sync --commit operation (the operation that
writes data to the remote file system) fails due to a crash or other
problem, it is possible for a lock file to be left behind. This would
cause all subsequent operations to fail with a lock timeout error.rfssync has options for querying the current state of the lock file, and for
deleting the lock file; however, these should only be used if necessary
to resolve this problem. Clients without write access cannot delete the
lock file.
To remove a cooperating client so the remote file system no longer
recognizes it, you must:
know the IP address of cooperating client you want to remove
54
manually update the remote_file_system section of the hardserver

configuration file by removing the following entries for that
particular client:
remote_ip=ccc.ccc.ccc.cccremote_esn=
keyhash=0000000000000000000000000000000000000000
native_path=c:\nfast\kmdata\local
volume=kmdata-local
allow_read=yes
allow_write=yes
allow_list=yes
is_directory=yes
is_text=no
and
remote_ip=ccc.ccc.ccc.cccremote_esn=
keyhash=0000000000000000000000000000000000000000
native_path=c:\nfast\kmdata\localsync-store
volume=kmdata-backup
allow_read=yes
allow_write=yes
allow_list=yes
is_directory=yes
is_text=no
In these commands, ccc.ccc.ccc.ccc is the IP address of the client.
Useful utilities
To find out the ESN and the hash of the KNETI key for a given IP
address, use the anonkneti command-line utility. A manual doublecheck is recommended for security.
A client can use rfs-sync --show to display the current configuration,
or rfs-sync --remove to revert to a stand-alone configuration. Reverting
to a stand-alone configuration leaves the current contents of the
kmdata directory in place. See rfs-sync on page 304 for more
information.
55

Before you can use the module to manage keys, you must create a
security world. A security world can only be created with a single
module. If you have more than one module, you must choose one with
which to create the new security world. You can add additional
modules to an existing security world later (as described in Adding or
restoring a module to the security world on page 155).
Before you start to create a security world:
The modules that you wish to add to the security world must be
in pre-initialization state, as described in Entering the
pre-initialization state on page 78.
You must be logged in to the host computer as a user who is

permitted to create privileged connections. See hardserver on
page 242.
You must have set the NFAST_HOME environment variable.
You should know what the security policy for the module is, and
in particular the number and quorum of administrator and
operator cards to be used.
You must have enough smart cards to form the security worlds
card sets.
On some internal modules, you must access the initialization link or

switch on the module. With such modules, always shut down your
computer and turn off the power before opening the case. Replace the
case before reconnecting the power.
You normally create a security world when you first install the
module. If you wish use the module to protect a different set of keys,
you can replace the security world with another one.
The process of creating a security world:
erases the module
creates a new module key for this security world
creates a new Administrator Card Set to protect this module key
56
stores the security world information on the computers hard

disk, or in the case of netHSM, the operating systems filesystem
and the remote filesystem. The information is encrypted using the
secrets stored on the Administrator Card Set.
Any Operator Cards created in a previous security world cannot be

used in the new security world. If you are replacing a security world,
you must erase all the Operator Cards created in the previous
security world before you create the new world.
You can create a security world from the command line with the newworld utility, as described here. Alternatively, you can use KeySafe (as
described in Creating a security world with KeySafe on page 131), or
the nCipher CSP wizard, as described in Creating the security world
using the CSP wizard on page 139.
Creating a security world by using new-world

Follow the directions in this section to create a security world from the
command line with the new-world utility.
Running the new-world command-line utility

Open a command window and type the command:
new-world [-i|--initialize] [-S|--no-remoteshare-cert] [-o|--overwrite] [-F|--strictfips-140-2-level-3] [-R|--no-recovery] [-tTIMEOUT|--nso-timeout=TIMEOUT] [-m|-module=MODULE] [-Q|--acs-quorum=K/N] [FEATURES]
In this command:
57
-i, --initialize
These options tell new-world to initialize a new security

world, replacing any existing kmdata directory.
Note
Replacing an existing security world in this way does not delete the
security worlds host and recovery data, but renames the existing
kmdata directory in which these reside as kmdata_nn (where nn is an
integer, 0 or greater, depending on how many security worlds have
been previously saved during overwrites).
-S, --no-remoteshare-cert
These options tell new-world to not to make the module a

target for remote shares.
-o, --overwrite
These options tell new-world to overwrite smart cards

without prompting. Any existing data will be erased. If a
value for this flag is not specified, new-world will prompt
you if a card contains data. This option does not enable you
to reuse Operator Cards from other security worlds.
-F, --strict-fips-140-2-level-3
These options tell new-world to create a security world that

conforms to the FIPS 140-2 requirements for roles and
services at level 3. If you do not specify this flag, new-world
creates a security world that complies with FIPS 140-2
requirements for level 2.
Note
FIPS 140-2 level 3 standard. It is included for those customers who
-R, --no-recovery
These options tell new-world to disable Operator Card Set

recovery. The effect of setting this flag is the same as for
specifying the feature !r.
58
By default, new-world creates key-recovery material that is

protected by the cryptographic keys on the Administrator
Card Set. This option does not give nCipher or any other
third party access to your keys. Keys can only be recovered
by using the Administrator Cards. nCipher recommends that
you leave Operator Card Set recovery enabled.
If you set the --no-recovery option, you will not be able to replace lost
or damaged Operator Card Sets and therefore will not be able to
access the keys that are protected by such cards. Key recovery cannot
be enabled later without reinitializing your security world and
discarding all your existing keys.
Note
All keys are recoverable unless otherwise specified at key generation,

even PKCS #11 keys that have the sensitive flag set to TRUE or
extractable flag set to FALSE.
-tTIMEOUT, --nso-timeout=TIMEOUT
These options allows you to specify the time-out

(TIMEOUT) for new security worlds. By default, an integer
given for TIMEOUT is interpreted in seconds, but you can
supply values for TIMEOUT in the form Ns, Nh, or Nd where
N is an integer and s specifies second, h specifies hours, and
d specifies days.
-m, --module=MODULE
These options specify the ModuleID to use. new-world

initializes only one module at a time. If you have multiple
modules, you must run new-world with --initialize for the first
module, and then run new-world with --program for the other
modules; see new-world on page 259.
-Q, --acs-quorum=K/N
In these options, K specifies the minimum number of smart

cards needed from the Administrator Card Set in order to
authorize a feature. You can specify lower K values for a
particular feature. All the K values must be less than or equal
59
to the total number of cards in the set. If a value for K is not

specified, new-world creates an Administrator Card Set that
requires a single card for authorization.
Note
Some applications do not have mechanisms for requesting that cards

be inserted. Therefore any Operator Card Sets that you create for use
with these applications must have K=1.
Note
If you are creating an Administrator Card Set for a payShield

installation, K must be greater than 1. N must therefore be greater
than 2.
N specifies the total number of smart cards to be used in the
Administrator Card Set. This value must be less than or

equal to 64. If a value for this option is not specified,
new-world creates an Administrator Card Set that contains a
single card.
Note
You should not create an Administrator Card Set for which the
required number of cards is equal to the total number of cards
because you will not be able to replace the Administrator Card Set if
even a single card is lost or damaged.
This option only takes effect if you are creating a new
security world.
new-world command-line utility features

Security world features can be specified on the command line.
60
You can specify multiple features as a comma-separated list of terms.

Each term consists of a feature name, optionally preceded by either a
dash (-) or an exclamation point (!) to turn off the feature and can
optionally be followed by an equals sign (=) and the threshold for this
feature.
Note
The ! character is interpreted by some shells as history expansion and

must be escaped with a backslash, \\!. The dash may be interpreted as
being the start of an command-line option unless you have used the f option or specified a module without including the -m flag.
Note
If you set the !fto flag, that is, turn off FTO, you will not be able to use
smart cards to import keys even if you set the --allow-smartcard-imports
option in the payshield-install utility.
Note
If you want to use extended debugging from the module, you must set
the dseeall flag.
The following feature names are available:
m
This feature specifies module programming (and cannot be

disabled).
r
This feature specifies Operator Card Set recovery (see

Replacing an Operator Card Set or recovering keys to
softcards on page 32).
p
This feature specifies PIN recovery. For information on

changing pass phrases, see Changing pass phrases with
cardpp on page 218 or the appropriate Operator Guide for
your module.
nv
This feature specifies that the Administrator Card Set is

needed to enable non-volatile memory allocation.
61
rtc

needed to enable real-time clock setting (see Real-time clock
(RTC) options on page 128).
dsee

needed to enable SEE World debugging.
dseeall
This feature specifies that SEE World debugging is enabled

for all users, without certificates.
fto

needed to enable foreign token operations.
If the threshold of a feature is set to 0, it may still be available using
the standard Administrator Card Set quorum.
The pass phrase recovery (p) and dseeall features are turned off by
default; the other options are turned on by default.
Note
The non-volatile memory and SEE world debugging options are

relevant only if you are using the Secure Execution Engine. If you
have bought the CodeSafe Developer Kit, refer to the CodeSafe
Developer Guide for more information.
Note
the dseeall flag.
The dseeall option is designed for testing purposes only. Do not enable
this feature on production security worlds as it may enable SEE
applications to leak security information.
62
For example, the following features:

m=1,r,!p, nv2, rtc1
create a security world for which:
a single card from the Administrator Card Set is required to add

a new module
the default number is required to replace an Operator Card Set
pass phrase recovery is not enabled
two cards are required to allocate nonvolatile memory
one card is required to set the real-time clock (applies to SEE

only).
new-world command-line utility output

If new-world cannot interpret the command line, it displays its usage
message and exits.
If you attempt to set a threshold for a feature that you have disabled
or if you attempt to set a threshold too high, new-world displays an
error and exits.
If the module is not in the pre-initialization state, new-world displays
and error and exits. See Entering the pre-maintenance state on page 76
new-world may give the following reasons why the module is not
ready for programming:
Initialization link not fitted

Internal PCI modules
In this case, move the mode switch to the initialization

position, and run the command again.
External modules
In this case, hold down the initialization switch, and run

the command again.
63
Maintenance link fitted

In this case, move the mode switch to the initialization

position, and run the command again.
External modules
In this case, remove the maintenance link, fit the

initialization link, and run the command again.
If the module is in the pre-initialization state, new-world prompts you
for smart cards and pass phrases as required.
When new-world has initialized the module, restart the module in the
operational state, as described in Entering the operational state on
page 79.

If you have a payShield net module, you must configure a payShield
installation as an environment for its payments functionality and
enable the features required for payments functionality.
The SEE activation feature, the payShield feature, and the payShield
acceleration feature must be enabled as described in Chapter 8:
Feature Enabling nCipher Modules before you can configure a
payShield installation. If the payShield feature is configured, the
CodeSafe feature is not available.
Before you start to configure a payShield installation:
You must have created a security world that has the following
options:
-
key recovery enabled.
use of an FTO Delegate key with a required number of cards

(and not with KNSO).
64
the number of cards required for the Administrator Card Set

set to a value greater than 1.
See About payShield Card Sets on page 187 for important advice
about the choice of a value for K.
-
the SEE debugging for all option enabled, if you wish to make
use of the extended payShield module debugging option.
(You must have configured the security worlds card
requirements separately to enable this option.)
This option is designed for testing purposes only. Do not enable it on

production security worlds as it may enable SEE applications to leak
security information.
You must know what the security policy and the associated card
sets for the payShield installation are. If this is not already
decided, see About payShield Card Sets on page 187.
card sets.
You must know which payShield functions are required.
Creating the payShield installation from the command line

This procedure involves Administrator cards, the payShield Master
Card Set and the Key Establishment Card Set. It must be performed
on a trusted host. See About payShield Card Sets on page 187 for full
details of the card sets created during this procedure.
You must be logged in as a user who is permitted to create privileged
connections. See hardserver on page 242 for more information.
The payshield-install utility creates a payShield installation in the
current security world. It fixes the installations operating properties
and creates both the Master Card Set and the Key Establishment Card
Set. It is extremely important that you choose the settings carefully
since you cannot change the properties of a payShield installation
after you have created it.
65
See payshield-install on page 283 for full details of the

payshield-install utility.
To run the payshield-install utility, type the following command,
specifying the options required for your installation:
payshield-install [options] psiname keyhash
In this command:
psiname
This is the name of the payShield installation to be created.

psiname must be in all lowercase characters because it is used for a
key generation operation.

keyhash
This is the hash of the nCipher payShield signing key. The

hash is:
25d0dfc32e980c7ab8f0fd7647db7fc2252f9851
Do not type a hash that differs from this value unless you are certain
that the new hash is from a valid payShield signing key. If you are in
any doubt as to the origin of the hash value you have been given, do
not create a payShield installation: contact Support at nCipher for
confirmation of the correct signing key hash.
As a minimum, specify the following:
payshield-install -S psiname keyhash
If you do not set the -S (--allow-smartcard-imports) option at this point,

your payShield installation can never import keys from smart cards,
but can only generate new keys.
66
The payshield-install utility performs or prompts for the following

operations in the order specified:
If you have set the --totally-insecure option, the payshield-install

utility issues the following warning:
WARNING: Creating an insecure payShield installation.
You must not set the --totally-insecure option, the -I

(--allow-insecureimports) option, or the -D (--allow-insecure-debug)
option when creating a live commercial payShield installation. If this
warning is displayed, the payShield installation you create is suitable
only for testing environments.
No sensitive keys or data should ever be allowed to pass through
a payShield installation created with the -I
(--allow-insecure-imports) option set.
The payshield-install utility prompts for a KFTO quorum of

security world Administrator cards. This quorum is the K value
that you specified for FTO when you created the security world.
The payshield-install utility prompts for a KFTO quorum of
security world Administrator Cards. This quorum is the K value
that you specified for FTO when you created the security world.
The payshield-install install utility loads the security worlds
KFTO and displays the following message:
payShield Master Cardset creation ...
It then prompts for new operator cards.
67
Following the onscreen prompts, each Master Card Set card

holder inserts a blank card and enters a name and pass phrase for
this card.
The payshield-install utility displays the following message:
payShield Key Establishment Cardset creation ...
It then prompts for new operator cards.
Following the onscreen prompts, each Key Establishment Card

Set card holder inserts a blank card and enters a name and pass
phrase for this card.
The payshield-install utility displays a success message and exits.
A successful operation might have output similar to the following:

payshield-install.exe: no card in module 1 slot 0
Insert an administrator card into module 1 slot 0 and press return...
Passphrase for administrator card 1:
payShield Master key generation ...
payShield Master key generated
Making FTO delegation certificate ...
payShield Master Cardset creation ...
Insert new operator card 1 into module 1 slot 0 and press return...
Passphrase for new operator card 1:
Name for card 1: master
payShield Master Cardset created
payShield Key Establishment key generation ...
payShield Key Establishment key generated
payShield Key Establishment Cardset creation ...
Insert new operator card 1 into module 1 slot 0 and press return...
Passphrase for new operator card 1:
Name for card 1: kec
payShield Key Establishment Cardset created
Successfully created new payShield Installaton psi
In the interests of brevity, the above output transcript shows the

creation of 1-of-1 card sets. Such a card set selection is not suitable
for a live, commercial payShield installation.
68
Configuring the payShield installation options

After payShield has been installed, there is further configuration to be
carried out.
Enabling payments functions

When you have configured the payShield installation, you must
enable payments functions.
Be very careful when deciding which payments functions are to be
enabled. Some functions (particularly the IBM PIN function) can
interact negatively with others, causing a reduction in the overall
security of the installation. Only enable functions that you will use.
To enable the required payments functions, run the following
command on the machine that is designated as the remote file system,
and then follow the onscreen instructions:
payshield-config psiname
In this command, psiname is the name that you supplied when you
created the payShield installation.
Configuring modules to use payShield

For each module you must create an entry in the load_seemachine
section of the hardserver configuration file. Make each entry of the
following form:
...
module module
machine_file=c:\nfast\nc-seemachines\payshield\version\emvsmtype1.sar
postload_prog=payshield
postload args=-n psiname [-d]
...
69
Separate the flags for each module by a dash on its own line, as in the
following example:
postload args=-n psiname [-d]
module MODULE
In this example:
MODULE
This represents the module number (for example, 1)

version
This represents the payShield SEE machine version and has

the format X.Y.Z.camA
psiname
This represents the name of the payShield installation that

the hardware security module is to host. This is the same as
the psiname passed to SPP_init() in any application that
wishes to use the payShield hardware security module.
-d
This flag specifies that the operating SEE World has the
dseeall feature set and that the operating payShield
installation has the -D option set. Both of these conditions
must have been specified at the time of SEE World creation

time, and their status can be checked using, respectively, the
nfkminfo and payshield-info command-line utilities. If either
of these conditions is not satisfied, then specifying -d in
postload_args inhibits SEE machine loading.
For further information on the hardserver configuration file, see
Chapter 6: Configuring the hardserver.
70

The Operator Card Set provides access to application keys. Operator
Card Sets are optional, but if you require one, create it before you start
to use the module with applications.
You can create Operator Card Sets with:
names for individual cards, as well as for the card set
K-of-N policies
optional pass phrases for any card within a given set
formal FIPS 140-2 level 3 compliance.
Some applications do not have a mechanism for requesting that cards

are inserted. If you create a card set for one of these applications, you
must set K to 1:
Application
Pass phrase
ISS
Not permitted
iPlanet
Required
Netscape Certificate Required

Server
You can create an Operator Card Set from the command line with the
createocs utility (as described here). Alternatively, you can use
KeySafe, or the nCipher CSP wizard. For more information about

creating Operator Card Sets, see the Operator Guide appropriate to
your module type.
Creating the Operator Card Set from the command line

To create an Operator Card Set:
71
1.
Use the command:
C:\nfast\bin\createocs -m MODULE|--module=MODULE -Q|--ocs-quorum=K/N

-N|--name=NAME [-M|--name-cards]
[[-p|--persist]|[-P|--no-persist]] [[-R|--no-pprecovery]|--pprecovery]
[-q|--remotely-readable] [-f|--force] [-T|--timeout=TIME]
In this command:
-m MODULE, --module=MODULE
These options specify the module number of the module

to be used to create the token. If you only have one
module, MODULE is 1.
-Q, --ocs-quorum=K/N
In these options, K is the minimum required number of

cards. If you do not specify the value K, the default is 1.
Note
Some applications do not have mechanisms for requesting that cards

be inserted. Therefore any Operator Card Sets that you create for use
with these applications must have K=1.
N is the total number of cards. If you do not specify the
value N, the default is 1.
-N, --name=NAME
These options enable you to name the card set. The card
set must be named with this option before individual
cards can be named using the -M, --name-cards=NAME
options.
-M, --name-cards
These options enable you to name individual cards

within the card set. You can only use this option after
the card set has been named by using the --name=NAME
72
option. createocs prompts for the names of the cards as

they are created. Not all applications can display
individual card names.
-p, --persist
These options create a persistent card set.

-P, --no-persist
These options create a non-persistent card set.

-R, --no-pprecovery
These options mean that the pass phrase for this card set
cannot be recovered. The pass phrase for the card set is
recoverable by default. You can specify this explicitly
with --pprecovery.
-q, --remotely-readable
These options allow this card set to be read remotely.

For information on configuring Remote Operator Card
Sets, see Chapter 13: Remote Operator Card Sets.
-f, --force
These options allow createocs to overwrite smart cards

without prompting. If you do not specify the --force
option, createocs prompts you if any smart card to be
used is not blank. You can only employ --force to reuse
Operator Cards from the current security world, or cards
containing unknown data. You cannot use the --force
option either to force the reuse of Administrator Cards
from the current security world without first erasing
them or to force the reuse of Operator Cards from other
security worlds.
-T, --timeout=TIME
These options set the time-out for the card set. Use the
suffix s to specify seconds, m for minutes, h for hours,
and d for days. If the timeout is set to 0, the Operator
73
Card never times out. Otherwise, the module

automatically unloads the Operator Card Set TIME after
the Operator Card was loaded.
If you have created a FIPS 140-2 level 3 compliant security
world, you must provide authorization to create new Operator
Cards; createocs prompts you to insert a card that contains this
authorization. Insert any card from the Administrator Card Set or
any Operator Card from the current security world.
When createocs has obtained the authorization from a valid card
or if no authorization is required, it prompts you to insert a card
into the module you specified.
2.
Insert the smart card to use.

If you insert an Administrator Card from another security world
or an Operator Card that you have just created, createocs displays
the following message:
Module x slot n: unknown card

Module x slot n: Overwrite card ?
(press Return)
where x is the module number and n is the slot number. If you

insert an Operator Card from another security world, createocs
displays the following message:
Module x slot n: inappropriate Operator Card (TokenAuthFailed).
When you have inserted a valid card, createocs prompts you to

type a pass phrase.
Note
The nCipher PKCS #11 library requires Operator Cards with pass
phrases.
Note
Some applications do not have mechanisms for entering pass phrases.

Do not give pass phrases to Operator Cards that are to be used with
these applications.
74
3.
Type a pass phrase and press Enter . Alternatively, press Enter if

you do not want this card to have a pass phrase.
A pass phrase can be up to 1024 characters long.
If you entered a pass phrase, createocs prompts you to confirm it.
4.
Type the pass phrase again and press Enter .

If the pass phrases do not match, createocs prompts you to input
and confirm the pass phrase again.
5.
When the new card has been created, if you are creating a card set
with more than one card in it, createocs prompts you to insert
another card.
For each additional card in the Operator Card Set, follow the
instructions from step 2 through step 4.
75
Chapter 4: Changing the module state

You change the module state to perform maintenance and
configuration tasks.

This section describes how to place nCipher modules in the premaintenance state. A module must be in the pre-maintenance state
before you can perform maintenance tasks like upgrading firmware.
Follow the directions for your particular model of module as
described in this section.

1.
Switch the mode switch to the maintenance position, as shown in

Figure 3.
Figure 3
PCI module back panel
Status LED
Clear switch
Mode switch
M
O
I
Maintenance
Smart card
connector
DC power
2.
Reset the module by pressing the clear button.
76
4 Changing the module state
When the self tests are complete, the unit should enter the premaintenance state. In this state, the Status LED emits repeated single
long flashes. Refer to the table below if the Status LED does not emit
repeated single long flashes:
LED
Note
State
Reason and remedy
Operational
Mainly on but
regularly blinks off
(The exact timing
depends on the
nCipher module.The
longer the LED
stays on the less the
load. At 100% load
the LED is off for as
long as it is on.)
The override switch is on. Refer to the

installation instructions in the Hardware
Installation Guide for information on
accessing and setting the override switch
to off.
Emits repeated
single short flashes
Pre-initialization
The mode switch is in the initialization

position. Repeat steps 1 to 2, positioning
the mode switch in the maintenance
position.
Flashes the Morse

SOS pattern
followed by a code
Error
The module has encountered an

unrecoverable error. There is a list of
these errors and the actions to take in the
Hardware Installation Guide.
If the Status LED remains continuously on or off for more than a

minute, it indicates that the self tests have failed terminally. Contact
Support at nCipher.
You can use the enquiry command-line utility to check that the
module is in the pre-initialization state. See enquiry on page 229 for
information about using this utility.
77

This section describes how to put nCipher modules in the preinitialization state. You must have at least one module in the preinitialization state before you can create a security world. A module
must be in the pre-initialization state before you can add it to an
existing security world.
On some internal modules, you must access the initialization link or
switch on the module. With such modules, always shut down your
computer and turn off the power before opening the case. Replace the
case before reconnecting the power.
Follow the directions for your particular model of module as
described in this section.

1.
Switch the mode switch to the initialization position, as shown in

Figure 4.
Figure 4
Status LED
Clear switch
Mode switch
M
O
I
Initialization
Smart card
connector
DC power
2.
78
The module performs self tests, during which the Status LED is on.
When the self tests are complete, the unit should enter the preinitialization state. In this state, the Status LED emits repeated single
short flashes. Refer to the table below if the Status LED does not emit
repeated single short flashes:
LED
Note
State
Reason and remedy
Operational
Mainly on but
regularly blinks off
(The exact timing
depends on the
nCipher module.The
longer the LED
stays on the less the
load. At 100% load
the LED is off for as
long as it is on.)
The override switch is on. Refer to the

installation instructions in the Hardware
Installation Guide for information on
accessing and setting the override switch
to off.
Emits repeated
single long flashes
Pre-maintenance
The mode switch is in the maintenance

position. Repeat steps 1 to 2, positioning
the mode switch in the initialization
position.
Flashes the Morse

SOS pattern
followed by a code
Error

If the Status LED remains continuously on for more than a minute, it

indicates that the self tests have failed terminally. Contact Support at
nCipher.
You can use the enquiry command-line utility to check that the
module is in the pre-initialization state. See enquiry on page 229 for
information about using this utility.

When you have created or restored a security world, return the module
to the operational state.
79
Internal PCI modules nC3022P-xxx

1.
Switch the mode switch to the operational position, as shown in

Figure 5.
Figure 5
nCipher PCI module back panel and switches
Status LED
Clear switch
Mode switch
M
O
I
Operational
Smart card
connector
DC power
2.
The module performs self tests, during which the Status LED is on.
When the self tests are complete, the unit should enter the operational
state. In this state the Status LED is mainly on, but blinks off regularly.
As the load on the unit increases, the length of time that the Status
80
LED is off increases. If the module is fully loaded, the Status LED is
off for as long as it is on. Refer to the table below if the Status LED is
not mainly on and blinking off regularly:
Note
LED
State
Reason and remedy
Emits repeated
single short flashes
Pre-initialization
The mode switch was in the

initialization position when you pressed
the clear button. Repeat the process
described in this section to set the mode
switch in the operational position.
Emits repeated
single long flashes
Pre-maintenance
The mode switch is in the maintenance

position. Repeat the process described in
this section to set the mode switch in the
operational position.
Flashes the Morse

SOS pattern
followed by a code
Error

If the Status LED remains continuously on for more than a minute, it

indicates that the self tests have failed terminally. Contact Support at
nCipher.
You can use the enquiry utility to discover whether the module is in
the operational state. (See enquiry on page 229 for information on
using this utility.)
Note
To prevent the chance of accidentally resetting the module into the

pre-initialization or pre-maintenance mode, you can turn on the
override switch. Refer to the Hardware Installation Guide for
information on accessing and setting the override switch.
81
Chapter 5: Uninstalling
This chapter provides information on uninstalling nCipher software.
Uninstalling the nCipher support software

Note
Note
Do not uninstall the nCipher software unless either you are certain it
is no longer required or you are going to upgrade it.
1.
Log on to the host computer as Administrator or as a user with

local administrator rights.
2.
Select Add/Remove Programs from the Windows Control Panel.
3.
Select the nCipher support software entry, and click the

Add/Remove button to uninstall the support software.
The uninstall process restores the Microsoft CSP as the default

SChannel CSP.
If required, you can safely remove the nCipher module after shutting
down all connected hardware.
82
Chapter 6: Configuring the hardserver

The hardserver handles secure transactions between the modules
connected to the host computer and applications that run on the host
computer. In addition, the hardserver controls any remote slots that
the module uses and loads any SEE machines that are to run on the
module.
The hardserver can handle transactions for multiple modules. This
does not require configuration of the hardserver. See Chapter 7: Using
multiple modules.
The hardserver must be configured to control:
the way the hardserver communicates with remote modules
the way the hardserver communicates with local modules
the import and export of remote slots
the loading of SEE machines on to the module when the

hardserver starts up.
You normally configure the hardserver when you install the module,
as described in Chapter 3: Getting the module working. This chapter
contains full information about configuring the hardserver and the
options available for configuring it in the configuration file.
Remote module connections

A remote module is a module that is not connected directly to the host
computer but with which the hardserver can communicate. It can be
one of the following:
a network-connected nCipher module that is configured to use

the host computer as a client computer. For information about
configuring network-connected modules, see the
netHSM/payShield net Administrator Guide.
83
6 Configuring the hardserver
Hardserver settings
a module to which an attended remote slot is imported for the

hardservers unattended local module.
You configure the hardservers communications with remote modules

in the server_remotecomms section of the hardserver configuration
file. This section defines the port on which the hardserver listens for
communications from remote modules. You should need to edit this
section only if the default port (9004) is not available.
See slot_imports for information about configuring remote slots.
Hardserver settings
You configure the hardservers settings in the server_settings section
of the configuration file.
This section defines how connections and hardserver logging are
handled. These settings can be changed while the hardserver is
running.
Hardserver start-up settings

You configure the hardservers start-up settings in the server_startup
section of the configuration file.
This section defines the sockets and ports used by the hardserver. You
should need to change this section only if the default ports for
privileged or unprivileged connections (9000 and 9001) are not
available.
Remote slots
You configure remote slots in the slot_imports and slot_exports
sections of the configuration file. The Remote Operator feature must
be enabled on the module, as described in Chapter 8: Feature
Enabling nCipher Modules.
84
SEE machines
These sections define the slots that are imported to or exported from
the module.
See Chapter 13: Remote Operator Card Sets for full information about
remote slots.
SEE machines
You configure the hardserver to load SEE machines on start-up in the
load_seemachine section of the configuration file. The SEE Activation
feature must be enabled on the module, as described in Chapter 8:
Feature Enabling nCipher Modules.
This section defines the SEE machines and optional user data to be
loaded, as well any other applications to be run in order to initalize the
machine after it is loaded.
See Chapter 9: Using CodeSafe Applications for information about
SEE machines.

The hardserver configuration file has the following sections that you
can update to configure the hardserver on an nShield module. If a
section is not present, it is assumed to have no entries.
server_settings
The server_settings section defines the settings for the client
hardserver that can be modified while the hardserver is running. The
section contains the following fields:
loglevel
This field specifies the level of logging performed by the

hardserver. It takes a value that is one of:
info
85
notice
client
remoteserver
error
serious
internal
startup
fatal
fatalinternal
The default is info.

See Logging and debugging on page 343.
If NFAST_SERVERLOGLEVEL is set, it overrides the value
in the configuration file.
logdetail
This field specifies the level of detail logged by the

hardserver. You can supply one or more of the following
flags in a space-separated list:
external_time
This flag specifies showing the external time (that

is, the time according to your machine's local
clock) with the log entry.
external_date
This flag specifies showing the external date (that

is, the date according to your machine's local clock)
with the log entry.
86
external_pid
This flag specifies showing the external process ID

with the log entry.
external_tid
This flag specifies showing the external thread ID

with the log entry.
external_time_t
This flag specifies showing the external time_ti

(that is, the time in machine clock ticks rather than
local time) with the log entry.
stack_backtrace
This flag specifies showing the stack backtrace

with the log entry.
stack_file
This flag specifies showing the stack file with the

log entry.
stack_line
This flag specifies showing the stack line number

with the log entry.
msg_severity
This flag specifies showing the message severity (a

severity level as used by the NFLOG_SEVERITY
environment variable) with the log entry.
msg_categories
This flag specifies showing the message category (a

category as used by the NFLOG_CATEGORY
environment variable) with the log entry.
87
msg_writeable
This flag specifies showing message writeables,

extra information that can be written to the log
entry, if any such exist.
msg_file
This flag specifies showing the message file in the

original library. This flag is likely to be most useful
in conjunction with nCipher-supplied example
code that has been written to take advantage of this
flag.
msg_line
This flag specifies showing the message line

number in the original library. This flag is likely to
be most useful in conjunction with nCiphersupplied example code that has been written to take
advantage of this flag.
options_utc
This flag specifies showing the date and time in

UTC (Coordinated Universal Time) instead of local
time.
connect_retry
The number of seconds to wait before retrying a remote

connection to a client hardserver. The default is 10.
connect_broken
The number of seconds of inactivity allowed before a

connection to a client hardserver is declared broken. The
default is 90.
88
connect_keepalive
The number of seconds between keepalive packets for remote

connections to a client hardserver. The default is 10.
connect_command_block
When a netHSM has failed, this specifies the number of

seconds the hardserver should wait before failing commands
directed to that netHSM with a NetworkError message. For
commands to have a chance of succeeding after a netHSM
has failed this value should be greater than that of
connect_retry. If it is set to 0, commands to a netHSM are
failed with NetworkError immediately it has failed. The
default is 35.
max_pci_if_vers
The maximum PCI interface version number. If this is set to

0 (the default) there is no limit.
These flags are those used by the NFLOG_DETAIL environment
variable (see Environment variables to control logging on page 343).
module_settings
The module_settings section defines the settings for the module that can
be changed while the hardserver is running. The section contains the
following fields:
esn
The electronic serial number of the module.

priority
The priority of the module. This is an integer from 1

(highest) to 100 (lowest). The default is 100.
89
server_remotecomms
The server_remotecomms section defines the remote communication
settings for the client hardserver. These are read only at hardserver
start-up. This section contains the following fields:
impath_port
The port on which the hardserver listens for incoming

impath connections. The default is 9004. Setting this field to
0 specifies that the hardserver does not listen for incoming
connections.
server_startup
The server_startup section defines the settings for the hardserver that
are loaded at startup. The section contains the following fields:
unix_socket_name
This field is not used on Windows systems.

unix_privsocket_name
This field is not used on Windows systems.

nt_pipe_name
The name of the pipe to use for non-privileged connections

on Windows. An empty string specifies none. The default is
\\.\pipe\crypto.
If the NFAST_SERVER environment variable is set, it
overrides the value in the configuration file.
nt_pipe_users
A list of users allowed to issue non-privileged connections

on Windows. If empty, any user can issue non-privileged
connections. This is the default.
90
nt_privpipe_name
The name of the pipe to use for privileged connections on

Windows. An empty string specifies none. The default is
\\.\pipe\privcrypto.
If the NFAST_PRIVSERVER environment variable is set, it
nt_privpipe_users
A list of users allowed to issue privileged connections on

Windows. If empty, any user can issue non-privileged
connections. This is the default.
If the NFAST_SERVER environment variable is set, it
nonpriv_port
The port on which the hardserver listens for local nonprivileged TCP connections. 0 specifies none. Java clients
default to connecting to 9000. The default is 0.
If the NFAST_SERVER_PORT environment variable is set, it
priv_port
The port on which the hardserver listens for local privileged

TCP connections. 0 specifies none. Java clients default to
connecting to 9001. The default is 0.
If the NFAST_SERVER_PRIVPORT environment variable is
set, it overrides the value in the configuration file.
load_seemachine
The load_seemachine section defines SEE machines that the module
should load and, if required, start for use by other clients. Each SEE
machine is defined by an entry as follows:
91
module
The module on to which to load the SEE machine. The value

must be an integer. A module with this ID must be
configured on the client computer.
machine_file
The file name of the SEE machine. (For payShield, the

correct version and path are found in the release notes on the
current nCipher CD-ROM.)
userdata
The file name of the userdata to pass to the SEE machine on

startup. If this field is blank (" "), the SEE machine is loaded
but not started. If this module is a payShield net module, this
field must be blank. The default is blank.
worldid_pubname
The PublishedObject name to use for publishing the KeyID of

the started SEE machine. If this field is blank (" "), the
KeyID is not published. This field is ignored if the value of
userdata is blank. If this module is a payShield net module,
this field must be blank.
postload_prog
The program to run after loading the SEE machine to

perform any initialization required by the SEE machine or its
clients. This program must accept an argument of the form 'm module#'. If this module is a payShield net module, this
field must be set to payshield.
92
postload_args
Arguments to pass to the program specified in postload_prog.

The argument '-m module#' is automatically passed as the
first argument. This field is ignored if postload_prog is not
specified or is blank. If this module is a payShield net
module, this field must be set to -n psiname [-d].
slot_imports
The slot_imports section defines the remote slots that the client
hardserver on an unattended module should import from remote
modules for use by modules connected directly to that local computer.
Each slot is defined by an entry as follows:
local_esn
The ESN of the local module to which to import the slot.

local_slotid
The SlotID to use to refer to the slot when it is imported on

the local module. The default is 2.
remote_ip
The IP address of the machine that hosts the slot to import

remote_port
The port number on which the remote hardserver is listening.

remote_esn
The ESN of the remote module from which to import the

slot,
remote_slotid
The SlotID of the slot to import on the remote module. The

value must be an integer. The default is 0.
93
slot_exports
The slot_exports section defines the slots on local modules that the
local hardserver should allow network modules to import. Each local
slot has an entry for each remote module that can import it, as follows:
local_esn
The ESN of the local module whose slot can be imported by

a network module.
local_slotid
The SlotID of the slot that is to be imported. The value must

be an integer. The default is 0.
remote_ip
The IP address of the network module that is allowed to

import the slot. The default is to allow all modules in the
security world to import the slot.
The IP address of the machine that is allowed to import the
slot.
remote_esn
The ESN of the module allowed to import the slot.
remote_file_system
This section is updated automatically when the rfs-setup utility is run.
You should not edit it manually.
The remote_file_system section defines a remote file system on the
client, by listing the modules allowed to access the filesystem on this
client. Each module is defined by an entry as follows:
94
remote_ip
The IP address of the network module that is allowed to

access the filesystem on this client.
remote_esn
The ESN of the remote module allowed to access the

filesystem on this client.
keyhash
The hash of the key with which the client must authenticate
itself to the module. The default is 40 zeros, which means
that no key authentication is required.
native_path
The local file name for the volume to which this entry
corresponds.
volume
The volume which the remote host would access to use this
entry.
allow_read
If this is set to yes, a remote server is allowed to read the

contents of the file. The default is no.
allow_write
If this is set to yes, a remote server is allowed to write to the

file. The default is no.
allow_list
If this is set to yes, a remote server is allowed to list the

contents of the file. The default is no.
95
is_directory
If this is set to yes, this entry represents a directory. The

default is no.
is_text
If this is set to yes, line endings should be converted to and

from the Unix convention for transfers

The payments configuration file is a temporary file used when
enabling payments functions. (See Enabling payments functions on
page 69.) The file has the following sections.
PINBlock formats
This section determines which PINBlock formats can be

used in specific situations. If a format is not listed, then it is
disabled and any attempt to use the format results in the
message AccessDenied.
Role i/o permissions
This section determines the types of keys that can be

imported or exported. Here you can specify which key block
formats are acceptable for each import or export operation.
Listing no formats for an operation means that the operation
is disabled. For example the following entry would mean
that TPKs:
Can be generated in attended operations (using the

VeriFone solution)
Cannot be generated automatically
Can (in principle) be exported as components or

wrapped in attended operations
96
Cannot be imported from components or wrapped in

attended operations
Can be imported automatically from a wrapped key.
role=KeyRole_TPK
gen_a=allow
gen_u=
ex_a=ExportFormat_XORComponents,ExportFormat_ECBWrapped
ex_u=
im_a=ExportFormat_XORComponents,ExportFormat_ECBWrapped
im_u=ExportFormat_ECBWrapped
nCipher does not recommend unattended key operations, since no

currently supported key block formats carry sufficient role or
integrity information.
97
Chapter 7: Using multiple modules

The hardserver can communicate with multiple nShield payShield
modules connected to the host. By default, the server accepts requests
from applications and submits each request to the first available
module. The server can share load across buses, which includes the
ability to share load across a mixture of modules.
If your application is multi-threaded, you can add additional modules
and expect performance to increase proportionally until you reach the
point where cryptography no longer forms a bottleneck in the system.
Identifying modules
Modules are identified in two ways:
by serial number
by ModuleID.
You can obtain the ModuleIDs and serial numbers of all your modules
by running enquiry. See enquiry on page 229.
Serial Number
The serial number is a unique 12-digit number that is permanently
encoded into each module. You should quote this number in any
correspondence with Support at nCipher.
ModuleID
The ModuleID is an integer assigned to the module by the server when
it starts. The first module it finds is given ModuleID 1, the next is given
ModuleID 2, and so on.
98
7 Using multiple modules
The order in which buses are searched and order of modules on a bus
depends on the exact configuration of the host. If you add or remove
a module, this can change the allocation of ModuleIDs to all the
modules on your system.
You can use the enquiry command-line utility to identify the PCI bus
and slot number associated with a module. See enquiry on page 229
for further information.
All commands sent to nShield payShield modules require a
ModuleID. Many nCipher commands, including all acceleration-only
commands, can be called with a ModuleID of 0. Such a call causes the
hardserver to send the command to the first available module. If you

purchased a developer kit, you can refer to the relevant developer
documentation for information about the commands that are available
on nCipher modules.
In general, the hardserver determines which modules can perform a
given command. If no module contains all the objects that are referred
to in a given command, the server returns an error status.
There are, however, some key-management operations that must be
performed together on the same module. In such cases, your
application must specify the ModuleID.
If you want to be able to share Operator Card Sets and keys between
modules, the modules must be in the same security world.

On standard installations, Operator Card Sets and keys are only
available for the specific module on which you have loaded them. If
you want to load an Operator Card Set on more than one module, you
need to physically insert the smart cards that make up the Operator
Card Set into each module in turn.
99
7 Using multiple modules
Adding a module
With Remote Operator enabled, you can load keys protected by an

Operator Card Set onto an unattended module by inserting the
relevant cards into a slot in an attended module. See Chapter 13:
Remote Operator Card Sets for information on configuring modules
to work in this way.
Adding a module
If you have a module installed, you can add further modules without
reinstalling the server software.
However, nCipher recommends that you always upgrade to the latest
server software and upgrade the firmware in existing modules to the
latest firmware.
Note
Before you install new hardware, check the release notes on the CDROM supplied with your new module for information about specific
compatibility issues, new features, and bug fixes.
1.
Install the module hardware. Refer to the Hardware Installation

Guide for information on installing nCipher hardware.
2.
Reboot your computer.
3.
Add the module to the security world. Refer to Adding or

restoring a module to the security world on page 155.
Module fail over

The nCipher support software supports fail over; that is, if a module
fails, the processing can be transferred automatically to another
module provided the necessary keys have been loaded. Depending on
the mode of failure, however, the underlying bus and Operating
System may not be able to recover and continue operating with the
remaining devices.
In order to maximize uptime, nCipher recommends that you fit the
redundant nCipher devices on a bus that is physically separate from
the primary devices.
100
Chapter 8: Feature Enabling nCipher Modules

nCipher modules support a range of optional features. Optional
features must be enabled with a certificate that you order from
nCipher. You can order the features when you purchase a module, or
you can obtain the certificate at a later date and use the Feature Enable
Tool to enable the features. See Ordering features for your module on
page 104 for details of ordering optional features. See Enabling
features on page 105 for details of enabling features.
The module firmware checks to confirm whether any features that it
attempts to use are enabled. It normally does this when it authorizes
the commands, or command options, that relate to a specific feature.
Most features are static; that is, they are enabled by means of a switch
in the modules EEPROM. A static feature remains enabled when the
module is reinitialized.
Some optional features are dynamic, that is, they are enabled by
means of a software switch in the modules volatile memory. A
dynamic feature must be enabled again if the module is reinitialized.
Once you have enabled features on a module, you must clear the
module to make them available.
Available Features
This section lists the features that can be added to modules.
Contact sales@ncipher.com for full details of all available features.
Elliptic Curve
Elliptic curves allow small key sizes to provide improved levels of
security and are commonly used in embedded devices.
See Developers Reference for full details of the elliptic curve feature.
101
8 Feature Enabling nCipher Modules
Available Features
Secure Execution Engine (SEE)

The SEE is a unique secure execution environment. The SEE features
available to you are:
SEE Activation
(EU+10)
Provided with the CodeSafe developer product to enable

you to develop and run SEE applications. The CodeSafe
developer product is only available to customers in the
Community General Export Area (CGEA, also known as
EU+10). Contact nCipher to find out whether your
country is currently within the CGEA.
SEE Activation
(Restricted)
Provided with specific products that include an SEE

application. This feature enables you to run your specific
SEE application, and is available to customers in any
part of the world.
See the CodeSafe/C Developer Guide for full details of the SEE.
Remote Operator support

Many nCipher customers keep critical servers in a physically secure
and remote position. The nCipher security world infrastructure,
however, often requires the physical presence of an operator to
perform tasks such as inserting cards. Remote Operator enables these
customers to manage nCipher enabled servers remotely using a secure
nCipher communications protocol over IP networks.
The Remote Operator feature must be ordered for and enabled on the
module installed in the remote server. Remote Operator cannot be
enabled remotely on an unattended module.
See Chapter 13: Remote Operator Card Sets for full details of using
Remote Operator.
102
payShield features
ISO smart card Support (ISS)

ISS, also called Foreign Token Open (FTO) allows data to be read to
and written from ISO 7816 compliant smart cards in a manner
prescribed by ISO7816-4. ISS allows you to develop and deploy a
security system that can make full use of ISO 7816 compliant smart
cards from any manufacturer.
Korean Certificate-based Digital Signature Algorithm (KCDSA)

This algorithm is used extensively in Korea as part of compliance with
local regulations specified by the Korean government.
See Developers Reference for full details of the KCDSA algorithm.
Client licenses
You can purchase additional client licenses that allow you to run
multiple clients for the module. Three clients are always enabled on
each module.
payShield features
If you have purchased payShield, the module is always supplied with
the following feature enabling tokens:
SEE Activation (Restricted), to allow software to run inside your

module
payShield Activation, to allow payShield software to run inside

your module.
payShield Rnumber, to set the performance variant of the

payShield module to the number number
ISO smart card support (ISS), also called Foreign Token Open
(FTO), to allow the use of non-nCipher smart cards.
103
For payShield applications you must enable these features using the
Feature Enable Tool, described in The Feature Enable Tool on page
105, before you can use the secure payment application.

When you have decided that you require a new feature, you can order
it for your module from nCipher Sales over the phone.
Before you call nCipher Sales, you should collect information about
your module as follows:
If possible, make a note of the module serial number.
Run the enquiry command and note down the Electronic Serial
Number of the module.
You must provide the ESN number to order a new feature.

If you prefer, you can include this information in an E-mail to
sales@ncipher.com. You can use the Feature Enable Tool to save the
ESN details to a file. See The Feature Enable Tool on page 105.
When your order has been processed, you receive a Feature Enabling
Certificate in one of the following ways:
nCipher E-mails you the Feature Enabling Certificate.
nCipher sends you a smart card that contains the Feature

Enabling Certificate.
The Feature Enabling Certificate contains the information that you

need to enable the features you have ordered.
For more information, including pricing of features, telephone or
Email your nearest nCipher sales representative using the contact
details from this guide, or the nCipher web site
(http://www.ncipher.com).
104
Enabling features
Enabling features
The Feature Enable Tool
The Feature Enable Tool utility, by default, scans the smart card
readers of all modules attached to the host, and enables any features
found on inserted FEM cards.
To use the Feature Enable Tool, you must be logged in as a user who
is permitted to create privileged connections.
You can enable a feature without having physical access to a module
by exporting the slot on your local module, importing that slot into the
remote module, and then running the Feature Enable utility on the
remote host.
The Feature Enable Tool offers you the choice of clearing the module
after it has enabled features. If you do not choose to clear the module
then (for example, because you have another process running on the
module), you must clear it later. You can use any appropriate method
to do this (for example, the nopclearfail utility or the Clear button).
Usage
fet.exe
Help options
-h, --help
display help for fet.exe

-v, --version
display the version number of fet.exe
105
Enabling features
-u, --usage
display a brief usage summary for fet.exe.

Note
If you are enabling the Remote Operator feature, you must enable it
on the module that is to be used as the remote module. See Chapter
13: Remote Operator Card Sets for details.
Viewing features already enabled on a module

The Feature Enable Tool can be used to view the status of modules
connected to the host or to confirm that a feature has been successfully
enabled on all modules connected to the host. To view the status of
features, run the tool without a smart card.
Enabling features with a smart card

When it is launched, the Feature Enable Tool automatically scans the
smart card readers of all modules attached to a host computer for any
Feature Enabling smart cards present in the smart card readers,
including imported slots.
To enable a new feature:
1.
Insert the Feature Enabling smart card from nCipher into a slot
available to the module to be updated.
2.
Run C:\nfast\bin\fet.exe to start the Feature Enable Tool.
If the update is performed successfully, a message confirms a

successful upgrade. If you do not see this message confirming a
successful upgrade, see the Enabling new features on your module
without a smart card on page 106.
Enabling new features on your module without a smart card

The Feature Enable Tool can also obtain the Feature Enabling
Certificate information supplied by nCipher from a file or from the
keyboard.
106
Enabling features
When you run the Feature Enable Tool without a Feature Enabling
smart card in any module slot, a message similar to the following is
displayed. There is a line for the features on each module, and a list of
options. In this example, only one module (ESN 511D-DB15-D438) is
attached to the host.
Feature Enable Tool
===================
ISO Smart Card Support
| Remote Operator
| | Korean Algorithms
| | | SEE Activation (EU+10)
Mod Electronic
| | | | SEE Activation (Restricted)
No. Serial Number
| | | | |
1 511D-DB15-D438 -- NO NO NO NO NO
1. Read FEM certificate(s) from a smart card or cards.
2. Read FEM certificate from a file.
3. Read FEM certificate from keyboard.
4. Write table to file.
Enter option :
If you select option 1, you are prompted to insert a Feature Enabling

smart card into a module slot and then press Enter . The Feature
Enable Tool then behaves in exactly the same way as if it were run with
the Feature Enabling cards already in the slots.
If you select option 2, you are prompted for the location and file name
of the Feature Enabling certificate. When you supply these, you are
prompted for the module number and the feature.
If you select option 3, you are prompted for the module number and
the feature, and are then asked to enter the certificate one line at a
time, followed by a period (.) on a line by itself. You can also cut
and paste a Feature Enabling certificate from an E-mail.
If you select option 4, the table of enabled features is written to a file.
You can include this file when you request new features from nCipher.
See Ordering features for your module on page 104.
107
Chapter 9: Using CodeSafe Applications

If you have enabled the Secure Execution Engine (SEE), your system
can run CodeSafe applications that implement special functionality.
Note
If you wish to use the SEE to run applications, you must order and
enable it as described in Chapter 8: Feature Enabling nCipher
Modules.
An SEE application is typically a standalone SEE machine that is
loaded automatically by the hardserver, for example, a CodeSafe C
application.
Please check the documentation supplied by your application vendor
for information about signatures that may be required to set up and
use the application, and any other installation and configuration
information.
CodeSafe/C applications
CodeSafe/C applications are standalone applications.
Each CodeSafe C application can consist of multiple parts, and its
installation can include several configuration steps. Please see your
application vendors documentation for instructions on installing and
configuring each application.
You may need to use the hardserver, loadmache and tct2 utilities when
configuring and loading an applicationl; see hardserver on page 242,
and .
108
Chapter 10: Using KeySafe

This chapter introduces KeySafe, nCiphers security world
management tool. It describes:
how to start KeySafe
KeySafes graphical interface
how to use buttons to select and run operations
how to use the keyboard to navigate KeySafe
how KeySafe reports errors.
Later chapters in this guide contain instructions for performing the

following operations with KeySafe:
creating a security world
adding a module to a security world
removing a module from a security world
replacing an Administrator Card Set
creating Operator Card Sets
replacing Operator Card Sets
Starting KeySafe
In order to use KeySafe, Suns Java run-time environment version 1.5,
or the equivalent developer kit must be installed. It is recommended
that you install it before you install the nCipher components. The Java
executable must be on your path.
Note
You can download Sun's Java Run-time Environment (and Java

Developer Kit) from http://www.sun.com/. If your security policy does
not allow the use of downloaded software, these components can be
obtained on CD-ROM from Sun or your Operating System vendor.
The keysafe.jar file must be specified in the Java class path.
109
10 Using KeySafe
Starting KeySafe
In order for KeySafe to work, you must set priv_port (the port on
which the hardserver listens for local privileged TCP connections) to
9001 and nonpriv_port (the port on which the hardserver listens for
local nonprivileged TCP connections) to 9000.
Note
See Setting the environment variables on page 49 and server_settings

on page 85 for information on setting these parameters.
Start KeySafe by selecting the KeySafe entry from the Programs folder
on the Windows Start menu.
The Windows KeySafe launcher checks that the components required
to run KeySafe are installed. Any missing components are listed in a
dialog box similar to the following:
110
10 Using KeySafe
The KeySafe window
When it starts, KeySafe displays a window similar to the one shown

below:
Note
nCipher recommends using a 16-bit or 24-bit color depth to ensure

accurate color reproduction. In environments with 8-bit color depth,
some colors may be represented incorrectly, although KeySafe still
operates.
The KeySafe window

The KeySafe window is divided into two areas:
the sidebar (on the left), subdivided into:

-
the menu buttons (at the top of the sidebar)
the Module Status tree (at the bottom of the sidebar)
the main panel area (on the right).
This layout is consistent throughout the KeySafe application.
111
10 Using KeySafe
The KeySafe window
Sidebar
The sidebar provides access to different parts of the KeySafe
application (with the menu buttons) and also displays information
about both the current security world and your module or modules
(with the Module Status tree).
Menu buttons
There are six menu buttons at the top of the sidebar:
Introduction
Clicking the Introduction menu button takes you to the

introductory panel that KeySafe displays at startup.
Keys
Clicking the Keys menu button takes you to the Key Operations
panel, from which you can choose to create, import, view, or
destroy keys.
Cards
Clicking the Cards menu button takes you to the Card Operations
panel, from which you can:
create, view, or erase Operator Cards
change the pass phrase on an Operator or Administrator

Card, or recover the pass phrase from an Operator Card
replace an Operator or Administrator Card Set.
Softcards
Clicking the Softcards menu button takes you to the Softcard

Operations panel, from which you can:
-
create, view or erase softcards
change or recover the pass phrase on a softcard
112
10 Using KeySafe
The KeySafe window
Modules
Clicking the Modules menu button takes you to the Module

Operations panel, from which you can initialize a security world,
add modules to a security world, or remove modules from a
security world. You cannot perform these operations on a module
that is not in the pre-initialization state.
Exit
Clicking the Exit button displays a dialog asking whether you are
sure you want to exit KeySafe. Click Yes (or press Enter ) to exit
KeySafe; click No to continue using KeySafe. Clicking the Exit
dialogs close-window button will take you back to your KeySafe
session. These features prevent you from closing KeySafe
accidentally.
While KeySafe is executing a command, the menu buttons are
disabled. Their normal functionality returns when the command is
completed.
Module Status tree

The Module Status tree, in the lower part of KeySafes sidebar,
displays information about the current security world and your
modules in the form of a tree diagram.
At the top of the Module Status tree is an icon representing the
computer on which the running copy of KeySafe is installed. The
name of this computer is spelled out to the right of the icon.
Below the computer icon in the Module Status tree are icons and text
identifiers representing the current security world and your
module(s). To the left of each icon is an expand/collapse toggle. By
default, when KeySafe starts, these toggles are on their collapsed
113
10 Using KeySafe
The KeySafe window
setting. Click the toggle to display expanded information about the

security world or module. Click the toggle again to collapse this
information.
Note
For purposes of clarity, screen shots in this guide are shown with some
of the Module Status tree toggles expanded.
Security world information
When you toggle the Module Status tree view of security world
information to its expanded setting, KeySafe reports Yes or No for
each of the following conditions:
the security world is initialized
key recovery is enabled for this security world (for more

information on key recovery, see Replacing Operator Card Sets
on page 202)
pass phrase recovery is enabled for a security world (for more

information on pass phrase recovery, see Replacing Operator
Card Sets on page 202)
It also gives the following information:
which type of key protects the security world (DES or

AES/Rijndael)
which FIPS 140-2 level the security world is operating at (level 2

or level 3)
The expanded security world information includes a folder labeled

Advanced, which itself can be toggled into an expanded view. This
folder displays advanced security world attributes related to nCiphers
Secure Execution Engine (SEE). When expanded, the Advanced
folder displays Yes or No for each of the following:
whether or not you have generated a real-time clock (RTC)

authorization key for this security world
whether or not you have generated a nonvolatile memory

(NVRAM) authorization key for this security world
114
10 Using KeySafe
The KeySafe window
whether or not you have generated a Secure Execution Engine

(SEE) debugging key for this security world
the level of SEE debugging that is enabled for this security world.
whether or not you enabled the Foreign Token Open key for this
security world
Module information
When you toggle the Module Status tree view of module information
to its expanded setting for a given module, KeySafe displays:
the modules electronic serial number (ESN), which is a unique

identifier. You must quote a modules ESN if you need to contact
Support at nCipher. Keep a record of the ESN(s) associated with
your module(s).
the modules state, which will be one of the following:

-
PreInitMode, indicating that the module is in the preinitialization state
InitMode, indicating that the module is in the initialization
state
-
Operational:Useable, indicating that the module is in the

current security world and can be used for key operations
Operational:Unknown, indicating that the modules state

could not be determined
Operational:Uninitialized, indicating that the module key is
set and that the module must be initialized before use

-
Operational:Factory, indicating that the module key is set to
the factory default

-
Operational:Foreign, indicating that the module is from an

unknown security world
Operational:AccelOnly, indicating that the module is an

acceleration-only module
115
10 Using KeySafe
The KeySafe window
Operational:Unchecked, indicating that, although the module

appears to be in the current security world, KeySafe could
not find a module initialization certificate (a module_ESN
file) for this module
Failed, indicating that the module has failed
PreMaintMode, indicating that the module is in the premaintenance state
MaintMode, indicating that the module is in the maintenance
state.
the status of the smart card reader slot(s).

You cannot initialize a security world from KeySafe unless you
have at least one module in the pre-initialization state
(PreInitMode). Likewise, if you want to add a module to an
existing security world, that module must be in the preinitialization state.
Note
For information about putting a module into the pre-initialization

state, see Entering the pre-initialization state on page 78. After you
have initialized a security world, in order for a module to be usable,
you must put it into the operational state (as described in Entering the
operational state on page 79).
-
for strict FIPS 140-2 level 3 security worlds, a FIPS Auth

Loaded entry will show if an Administrator Card or Operator
Card has been inserted to authorise a FIPS key required
operation.
The Module status tree has an Advanced folder that shows the
following details when expanded:
the version of the modules firmware
whether the module has a Real Time Clock (RTC)
whether the module has nonvolatile memory (NVRAM).
116
10 Using KeySafe
The KeySafe window
Main panel area

KeySafes main panel area is used to display information and options
pertaining to a chosen operation. For example, clicking the Modules
menu button takes you to the Module Operations panel in the main
panel area:
Navigation buttons
At the bottom left of the Module Operations panel are three navigation
buttons. Clicking a navigation button does not commit you to an
action, but instead selects an operation and loads another panel of
additional information and options related to the selected operation.
117
10 Using KeySafe
The KeySafe window
From the Module Operations panel, for example, clicking the Erase
Module navigation button does not itself erase a module, but rather
loads the Erase Module panel:
Command buttons
At the bottom right of the Erase Module panel is a command button
(the Erase Module! command button, in this case). Unlike clicking a
navigation button, clicking a command button does commit you to an
operation. Clicking a command button tells KeySafe to write or delete
data: it is not necessarily possible to reverse such changes even if you
subsequently cancel the operation.
For these reasons, command buttons are usually marked with an
exclamation point (!) if there is a danger that a command could
overwrite data that you may not want deleted. In some cases, clicking
a command button causes KeySafe to display a dialog box asking you
to confirm your command. Such features help prevent you from
accidentally destroying your data or keys.
118
10 Using KeySafe
The KeySafe window
Some panels require that, before you can click a command button, you
select options by means of radio buttons or that you enter data into text
fields:
If you click a command button without having entered data into a

mandatory text field or if KeySafe detects that the information you
provided is inconsistent or invalid, KeySafe displays an error
message. Click the messages OK button, and then provide or correct
the necessary information.
After you successfully issue a command by clicking a command
button, the sidebars menu buttons are disabled until the requested
command is completed.
Back buttons
Some KeySafe panels have Back buttons. Clicking a Back button takes
you to the panel from which the panel you are on is normally reached.
For example, clicking the Back button on the Erase Module panel takes
119
10 Using KeySafe
Errors
you to the Module Operations panel, and clicking the Back button on
the Examine/Change Card panel takes you to the Card Operations
panel.
Navigating with the keyboard

The Tab key always takes you to the next field or button. If the cursor
is not currently active in a text field, pressing the space bar or the
Enter key activates the currently selected button (as if you had
clicked it). Pressing the Shift - Tab button combination takes you to
the previous field (if any) or deselects an automatically selected
button (if any).
Errors
If KeySafe detects an error from which it cannot recover, it may
display a Fatal Error message, such as:
In this case, it could be that the nCipher server is unable to receive

TCP connections for some reason. The server program communicates
with clients by using named pipes or TCP sockets.
Note
See Setting the environment variables on page 49 and Hardserver

start-up settings on page 84 for information on setting these
parameters.
The error message shown could also indicate that the nCipher server
is not running (or that your module is physically disconnected). If the
nCipher server is not running, take the following steps:
1.
Exit KeySafe.
2.
Restart the server as described in the section hardserver on page

242.
3.
Restart KeySafe.
120
10 Using KeySafe
Errors
Another Fatal Error from which KeySafe cannot recover is:
This error may mean that your nCipher server or nCipher firmware is
not current. To update your firmware, take the following steps:
Note
1.
Exit KeySafe.
2.
Update the nCipher firmware as described in Appendix A:

Upgrading module firmware.
3.
Restart KeySafe.
The firmware upgrade process destroys all persistent data held in a

key-management module. If your security system requires that the
persistent data held in a key-management module must survive intact
during the upgrade or initialization of the key-management module, a
backup and recovery mechanism of your kmdata directory must be
implemented.
Other, more trivial errors include:
This error occurs if you are attempting to initialize, reprogram, or

erase a module that is not in the pre-initialization state.
This error occurs if you attempt to create a card set with more than 64
cards.
121
10 Using KeySafe
Errors
Contact Support at nCipher if you receive any other error message that
looks similar to the one shown below:
122
Chapter 11: Managing security worlds

You normally create a security world when you install the module.
This chapter contains detailed information about security worlds and
instructions for alternative methods of creating them and other tasks
that involve the security world.
Before you can use the nShieldpayShield module to manage keys, you
must create a security world. If you are using payShield you must then
configure the security world using the payshield-install utility as
described in About payShield installations on page 187.

The security world infrastructure stores encrypted key material and
related data in files on the host. For multiple hosts to use the same
security world, the system administrator must ensure that these files
are copied to all the hosts and updated when required.
Location of security world files

Security world files are created or updated in the directory specified
by the environment variable NFAST_KMLOCAL on the host. By
default, this is C:\nfast\kmdata\local.
Note
By default, the kmdata directory, and sub-directories, inherit

permissions from the user that creates them. Installation of nCipher
support software must be performed by a user with Administrator
rights that allow read and write operations, and the starting and
stopping of applications.
123
11 Managing security worlds
Files and operations

Security world operations create or modify files in the
C:\nfast\kmdata\local directory as follows:
Operation
Creates/modifies
Creates files...
Create a security
world
creates
world
module_ESN
Load a security
world
creates or modifies
module_ESN
Replace an
Administrator Card
Set
modifies
world
Create an Operator
Card Set
creates
Generate a key
creates
key_appname_ident
Create an Operator
Card Set
modifies
key_appname (for each key
Recover a key
modifies
cards_ident card_ident_cardno
(one per card)
that has been recovered)

key_appname (for each key
that has been recovered)
In this table:
ESN is the electronic security number of the module on which the
security world is created
ident is the identifier given to the card set or key when it is created
cardno is the number of the card in the card set
appname is the name of the application by which the key was
created.
The ident of a card set is a 40-character string that represents the hash
of the card sets logical token. The ident of a key is either user supplied
or a hash of the keys logical token, depending on the application that
created the key.
124
Required files
The following files must be present and up to date in the
C:\nfast\kmdata\local directory, or the directory specified by the
NFAST_KMLOCAL environment variable, for a host to use a security
world:
world
a module_ESN file for each module that this host uses
a cards_ident file for each cardset that is to be loaded from this

host
a card_ident_cardno file for each card in each cardset that is to be

loaded from this host
a key_appname_ident file for each key that is to be loaded from

this host.
These files are not updated automatically. You must ensure that they
are synchronized whenever the security world is updated on the
module.

Decide what kind of security world you need before you create it.
Depending on the kind of security world you need, you can choose
different options at the time of creation. For convenience, security
world options can be divided into the following groups:
basic options, which must be configured for all security worlds
recovery options, which must be configured if the security world,

keys, or pass phrases are to be recoverable
SEE options, which only need be configured if you are using

nCiphers Secure Execution Engine (SEE)
options relating to the replacement of an existing security world

with a new security world.
125
Security world options are highly configurable at the time of creation

but, so that they remain secure, not afterwards. For this reason,
nCipher recommends that you familiarize yourself with security
world options, especially those required by your particular situation,
before you begin to create a security world.
Security world basic options

When you create a security world, you must always configure the
basic options described here.
Security world key type

You must decide whether to use a Triple DES or AES key as the
security world key. The security world key is the key generated during
security world creation that protects the application keys and Operator
Card Sets in the created security world.
K and N
You must decide the total number of cards (N) in a security worlds
ACS and must have that many blank cards available before you start
to create the security world. You must also decide how many cards
from the ACS must be present (K) when performing administrative
functions on the security world.
Note
nCipher recommends that you do not create Administrator Card Sets

for which K is equal to N, because you cannot replace such an
Administrator Card Set if even 1 card is lost or damaged.
Note

installation, Kmust be greater than 1. Therefore, nCipher
recommends that in such casesN be greater than 2.
In many cases, it is desirable to make K greater than half the value ofN
(for example, if N is 7, to make K 4 or more). Such a policy makes it
harder for a potential attacker to obtain enough cards to access the
security world. Choose values of K and N that are appropriate to your
situation.
126
FIPS 140-2 level 3 compliance

By default, security worlds are created to comply with the roles and
services, key management, and self-test sections of the FIPS 140-2
standard at level 2. However, you can choose to enable compliance
with the FIPS 140-2 standard at level 3.
Note
FIPS 140- 2 level 3 standard. It is included for those customers who
If you enable compliance with FIPS 140-2 level 3 roles and services,
authorization is required for the following actions:
generating a new Operator Card Set
generating or importing a key, including session keys
erasing or formatting smart cards (although though you can

obtain authorization from a card you are about to erase).
In addition, you cannot import or export private or symmetric keys in

plain text.
Remote Operator
If you want to use a module without needing physical access to
present Operator Cards, the Remote Operator feature must be
explicitly enabled on the module; see Chapter 8: Feature Enabling
nCipher Modules. By default, modules are initialized into security
worlds with remote card set reading enabled. If you add a module for
which remote card reading is disabled to a security world for which
remote card reading is enabled, the module remains disabled.
Security world recovery options

By default, security worlds are created with recovery options enabled.
This means that the holder of an Administrator Card Set (ACS) can
transfer key data from the protection of a one Operator Card Set
(OCS) to another (thereby making the recovery of keys possible). You
127
can choose to disable these recovery options when creating a security

world. However, if you do so, all key recovery is impossible, even for
keys generated as recoverable (which is the default for key
generation).
If you do not enable recovery for a security world, you can never
replace lost or damaged Operator Card Sets and, therefore, in such a
case could never access the keys that are protected by such cards.
Recovery cannot be enabled later without reinitializing your security
world and discarding all your existing keys.
Security world SEE options

You must configure SEE options if you are using nCiphers Secure
Execution Engine (SEE). If you do not have SEE installed, the SEE
options are irrelevant.
SEE debugging
SEE debugging is disabled by default, but you can choose whether to
enable it for all users or whether to make it available only through use
of an ACS. In many circumstances, it is useful to enable SEE
debugging for all users in a development security world but to disable
SEE debugging in a production security world. Choose the SEE
debugging options that best suit your situation.
Real-time clock (RTC) options

Real-time clock (RTC) options are relevant only if you have
purchased and installed the nCipher CodeSafe Developer kit. If so, by
default, security worlds are created with access to RTC operations
enabled. However, you can choose to control access to RTC
operations by means of an ACS.
128
Nonvolatile memory (NVRAM) options

Nonvolatile memory (NVRAM) options are irrelevant unless you
have purchased and installed the nCipher CodeSafe Developer kit. If
so, by default, security worlds are created with access to NVRAM
operations enabled. However, you can choose to control access to
NVRAM operations by means of an ACS.
Security world replacement options

Options relating to security world replacement are relevant only if you
are replacing a security world.
If you replace an existing security world, its kmdata directory is not
overwritten but renamed kmdata_nn (where nn is an integer assigned
depending on how many other security worlds were previously
replaced in this way up to a maximum of 99). A new kmdata directory
(named kmdata) is created for the new security world. If you do not
wish to retain the kmdata_nn directory from the old security world,
you must delete it manually.

You normally create a security world when you first install the module
(as described in Chapter 3: Getting the module working). If you want
use the module to protect a different set of keys, you can replace the
security world with another one.
In order to create a security world, the following must apply:
Any modules that you wish to add to the security world must be
started in pre-initialization state, as described in Entering the
You must be logged in to the host computer as a user who is

permitted to create privileged connections. See hardserver on
page 242.
The NFAST_HOME environment variable must be set.
129
You should know what the security policy for the module is, and
in particular the number and quorum of administrator and
operator cards to be used. See Determining module requirements
on page 39 for details.
card sets.
When you have completed the operation and run the payshield-install
utility if required, you must restart the module in the operational state.
The process of creating a security world:
erases the module
creates a new module key for this security world
creates a new Administrator Card Set to protect this module key
stores the security world information on the computers hard

disk. The information is encrypted using the secrets stored on the
Any Operator Cards created in a previous security world cannot be

used in the new security world. If you are replacing a security world,
you must erase all the Operator Cards created in the previous
security world before you create the new world. See the Operator
Guide.
You can create a security world from the command line with the
new-world utility, as described in the section Creating a security world
by using new-world on page 57 in Chapter 3: Getting the module

working. Alternatively, you can create a security world with KeySafe,
or the nCipher CSP wizard. The new-world utility can also be used to
add a module to an existing security world.
You can use KeySafe, the nCipher CSP wizard, and the new-world to
create a security world for which you can specify different K values
for the Administrator Card Set. However, a security world that can
perform advanced operations, such as replacement of an Operator
Card Set, or that is compatibility with SEE, can only be created with
either KeySafe or the new-world command-line utility.
130
Creating a security world with KeySafe

1.
Start KeySafe. (For an introduction to KeySafe and information

on starting the software, see the appropriate Operator Guide for
your module.)
2.
Check the Module Status tree to ensure that you have a module
in the pre-initialization state (PreInitMode). See Entering the premaintenance state on page 76.
3.
Click the Modules menu button, which takes you to the Module
Operations panel.
4.
Click the Initialize Security World navigation button.
5.
If KeySafe finds existing security world data, it takes you to the

Existing Security World panel in order to confirm that you want
to delete this data by overwriting the existing security world:
131
Note
Overwriting an existing security world in this way does not delete that
security worlds host and recovery data, but renames the existing
kmdata directory in which these reside as kmdata_nn (where nn is a 2digit integer assigned depending on how many security worlds have
been previously saved during overwrites up to a maximum of 99).
If you want to overwrite an existing security world, click the
Overwrite Security World button on the Existing Security World
panel. KeySafe then takes you to the Initialize Security World
panel.
6.
If KeySafe does not find existing security world data, it takes you
to the Initialize Security World panel:
7.
Enter the total number of cards (N) that you wish to have in the
Administrator Card Set. This number must be less than or equal
to 64.
132
8.
Enter the number of Administrator Cards that are needed to

authorize any action. This number (K) must be less than or equal
to the total number of cards (N).
Note
nCipher recommends that you do not create an Administrator Card

Set for which K is equal to N, because you cannot replace such an
Administrator Card Set even if only 1 card is lost or damaged.
Note

installation, K must be greater than 1, and therefore N must be greater
than 2.
9.
Select the protection mode for the security world (that is, whether
the security world key is to be a Triple DES key or an AES key).
10. Select whether or not you want the new security world to comply
with the roles and services, key management, and self-test
sections of the FIPS 140-2 standard at level 3.
Note
This option provides compliance with the letter of the FIPS 140-2
level 3 standard, but does not improve the security of your keys. It is
included for those customers who have a regulatory requirement for
compliance.
11. To configure SEE options, proceed to the SEE options panel, and
follow these steps:
a.
Select whether or not you want to generate a real-time clock

(RTC) authorization key, and the number of Administrator
Cards required to change RTC details. This option is not
applicable unless you have purchased and installed the
nCipher CodeSafe Developer kit.
b.
Select whether or not you want to generate a nonvolatile

memory (NVRAM) authorization key, and the number of
Administrator Cards required to change NVRAM details.
This option is not applicable unless you have purchased and
installed the nCipher CodeSafe Developer kit.
c.
Choose the parameters for SEE debugging and the number

of Administrator Cards required to change SEE debugging
settings. These are:
133
Restricted
Generate Authorization Key
No Access Control.
Click the Use these settings button to return to the Initialize

Security World panel.
Note
If you wish to use SEE, you must have ordered and enabled it as
described in Chapter 8: Feature Enabling nCipher Modules.
12. KeySafe always generates recovery data for the security world
key. However, if you want to be able to recover Operator Cards
and application keys, you must proceed to the Initialize Security
World Advanced Options panel:
134
Use the Initialize Security World Advanced Options panel to create

key and pass phrase recovery material that is protected by the
cryptographic keys on the Administrator Card Set. This does not
give nCipher, or any other third party, access to your keys. Keys
can only be recovered by using the Administrator Cards.
Note
nCipher recommends that you always select the recovery option.

a.
Select whether or not you want to enable key recovery, and

the number of Administrator Cards required to authorize key
recovery.
b.
Select whether or not you want to enable pass phrase

recovery, and the number of Administrator Cards required to
authorize pass phrase recovery.
c.
Specify the number of Administrator Cards required to

authorize loading this security world on to another module.
d.
Select whether or not you want to enable generation of the

FTO key and the number of Administrator Cards required to
authorize the use of the FTO key.
Click the Use these settings button to return to the Initialize

Security World panel.
If you select No for the Do you want to enable key recovery? option, you
cannot replace lost or damaged Operator Card Sets and, therefore,
cannot access keys that are protected by such cards. This feature
cannot be enabled later without reinitializing your security world and
discarding all your existing keys.
Note
Note
If you disable FTO in the Initialize Security World Advanced Options

panel, you cannot use smart cards to import keys even if you set the
--allow-smartcard-imports option in the payshield-install utility.
SEEDebugging to Unrestricted.
135
13. Click the Initialize Security World! button. This takes you to the
Create Administrator Card Set panel:
14. KeySafe prompts you to insert the cards that are to form the
Insert a blank card and click the OK button. If you insert a nonblank card that KeySafe can erase, the Erase Card! button is
enabled, giving you the option of overwriting that card.
Note
When creating a card set, KeySafe recognizes a card that belongs to

the set before the card set is complete. If you accidentally insert a card
to be written again after it has already been written, you see a
warning.
136
15. KeySafe takes you to the Set Card Protection Pass Phrase panel:
If you want to set a pass phrase for this Administrator Card:

a.
select the Yes option
b.
enter the same pass phrase in both text fields
c.
click the OK button.
A given pass phrase is associated with a specific card, so each

card can have a different pass phrase. You can change these pass
phrases at any time by using KeySafes Examine/Change Card
option (available from the Card Operations panel) or the
cardpassphrase command-line utility.
If you do not want to set a pass phrase for this Administrator
Card:
d.
select the No option
e.
click the OK button.
137
16. KeySafe then prompts you for the next card (if any).
Note
When creating a card set, KeySafe recognizes a card that belongs to

the set before the card set is complete. If you accidentally insert a card
to be written again after it has already been written, you see the
following warning:
17. After you have created all the Administrator Cards, KeySafe
creates a new module key.
When initialization is complete, KeySafe displays a message:
Security world successfully initialized. Click the OK button, and
KeySafe returns you to its introduction panel.
18. After you have added a module to the security world, restart the
module in the operational state. (See Entering the premaintenance state on page 76).
If you have more than one module on this server, you can use
KeySafes Reprogram Module option to incorporate a new
module into your security world (or to restore an existing module
after a firmware upgrade), as described in Adding or restoring a
138
module to the security world on page 155. Alternatively, you can

also incorporate a new module into your security world by using
the new-world command-line utility (see new-world on page
259).
Creating the security world using the CSP wizard

The nCipher CSP installation wizard can be used to:
create a new security world
add a module to an existing security world
create Operator Card Sets, including K-of-N sets
install nCiphers Cryptographic Service Provider and/or

acceleration-only offload.
To create a security world by using the nCipher CSP wizard, follow

these steps:
139
1.
Run the wizard by double-clicking the icon on your desktop.

The wizard displays this window:
If any module is in the pre-maintenance or maintenance state, the

wizard displays a warning. In such a case, reset the module into
the pre-initialization state, and rerun the wizard.
2.
Click the Next button.

The wizard determines what actions to take based on the state of
the security world and the state of the modules that are attached
to your computer:
140
If the wizard cannot find a module that is capable of key

management, it loads the acceleration-only hook (which
does not provide key management capabilities). In such a
case, the wizard displays the following window:
141
If there is at least one module capable of key management

and there is no existing security world, the wizard displays
the following window:
142
3.
If there is an existing security world, the wizard displays the

following window:
Select one of the following options:

-
to create your first security world, select Create a new

security world
to replace the existing security world, select Create a new

security world
to use the existing security world, select Use the existing

security world, and click the Next button.
143
to proceed without creating a security world, select Install

cryptographic acceleration only and click the Next button. The
wizard installs the acceleration-only hook. This option only
provides acceleration and does not use the module to manage
keys.
If you choose either to Create a new security world or to use an

existing world, the following screen is displayed:
4.

If you are replacing an existing security world, go to step 14.
If there are no modules in the pre-initialization state, the wizard
prompts you to reset the modules as described in Entering the
Note
If you need to shut down the computer in order to access the

maintenance link or switch, rerun the wizard when you restart the
computer. It continues from this point.
144
5.
When all the modules are in the pre-initialization state, click the
Next button. The wizard displays the following window:
6.
Note
Either accept the default 2-of-3 scheme for the Administrator

Card Set or select the Use custom security policy option and enter
your own parameters for the sharing scheme:
-
the number of cards required (K) must be less than or equal

to the total number of cards
the total number of cards (N) must be at least 1 but no more

than 64.

installation, K must be greater than 1.
7.
Select either DES3 or AES for the security worlds module key
type.
145
8.
Note
Select the Configure advanced security world options option if you

want to continue on to further configuration options for the
security world when you have completed the selection of the
options on the current screen. Select the SEE settings option to
continue on to configure options for SEE.
You can select both the Advanced settings and the SEE settings option.
9.
Note
If you require compliance to level 3 of the roles and services

section of the FIPS 140-2 standard, select the Create a FIPS 1402 level 3 compatible security world option. If you select this option,
you must insert a card from the Administrator Card Set or an
existing Operator Card Set before you can create a new Operator
Card Set.
The Create a FIPS 140-2 level 3 compatible security world option provides
compliance with the letter of the FIPS 140-2 standard, but does not
improve the security of your keys. It is included for those customers
who have a regulatory requirement for compliance with this standard.
146
10. Click the Next button.

If you did not select the Configure advanced security world options
option, continue from step 11.
If you selected the Advanced settings option, the World Advanced
Options window is displayed:
Each tab in this window lets you specify the number of cards
required to authorize specific tasks:
Note
On the Add module tab, select the number of cards required

to add a module to the security world.
On the Key rec. tab, disable or enable key recovery. If you

enable key recovery, select the number of Administrator
Cards required to recover a key.
If you require key recovery, you must enable it when you create the
security world. If you do not enable key recovery now, it never will be
possible to recover keys in this security world.
147
Note
On the PP rec. tab, disable or enable pass phrase recovery. If

you enable pass phrase recovery, select the number of
Administrator Cards required to recover a pass phrase.
On the NVRAM tab, specify whether you require a key to

authorize the creation of entries in the modules NVRAM. If
you require this key, select the number of Administrator
Cards required to access the NVRAM. The NVRAM
authorization key is required if you want to use NVRAM to
store SEE program data or you require NVRAM key storage.
On the RTC tab, specify whether you require a key to

authorize setting the modules real-time clock (RTC). If you
require this key, select the number of Administrator Cards
required to set the clock.
On the DSEE tab, disable SEE debugging, enable SEE

debugging for all users, or enable SEE debugging and create
an associated key. If you enable debugging with this key,
select the number of Administrator Cards required to
authorize SEE debugging.
On the FTO tab, specify whether you require a key to

authorize foreign token operations (FTO). If you require this
key, select the number of Administrator Cards required to
perform foreign token operations.
FTO must be enabled to create a payShield installation.

11. Select Enable remote cardset support if required.
148
12. The wizard displays the following window:
If you want to protect this card with a pass phrase, select the Card
requires a pass phrase option. The wizard prompts you to enter
and confirm the pass phrase.
Note
The Next button is only enabled when you have entered two matching
pass phrases.
13. When you have entered the pass phrase, click the Next button.
14. Place the smart card in the module.
15. Click the Next button.
149
16. When the wizard successfully writes to this card, it prompts you
to insert the next card and to enter a pass phrase for this card.
Continue the process, following the onscreen instructions. When
the wizard has written the number of cards you requested, it
displays the following screen:
These smart cards form the Administrator Card Set for this
security world. The security of your key data depends on the
security of these smart cards.
150
17. If there are no more modules to add to the security world, go to

step 18.
If there are further modules to add to the security world, the
wizard prompts you to insert a card from the Administrator Card
Set in the next module. Follow this process:
a.
Insert one of the cards from the Administrator Card Set that
you have just created, and click the Next button. If the card is
not from the Administrator Card Set, the wizard prompts for
another card.
b.
If you defined a pass phrase for this smart card, the wizard
prompts you to enter it. Enter the pass phrase, and click the
Next button.
If the pass phrase is incorrect, the wizard displays an error
message. If you type the pass phrase incorrectly three times,
the wizard does not continue, and this module is returned to
the factory state.
Note
If the wizard stops because the incorrect pass phrase has been entered
three times, the module is not be added to the security world. Run the
wizard again in order to add this module to the security world.
c.
When your correct pass phrase is entered successfully, the

wizard prompts you for further smart cards and their pass
phrase until you have loaded the required number of
Administrator Cards and pass phrases, as defined in step 6.
If there are yet more modules to be programmed on this host, the

wizard returns you to repeat the process of inserting
Administrator Cards and entering their pass phrases for each
additional module being added to the security world.
151
18. When all the modules have been added to the security world, the
wizard displays this window:
19. Restart the module in the operational state (as described in

Entering the operational state on page 79).
152
20. The wizard displays the following window:
This window enables you to create Operator Cards for the new
security world. If you do not want to use Operator Card Sets to
protect your keys, select the Module protection option. If this
option is selected, the CSP only creates keys that are protected by
153
the security world. This option is suited to applications where 24hour operation is required, because no human intervention is
required to use application keys.
If you want to use Operator Card Sets to protect your keys, select
the Operator Card Set protection keys option.
If you are using Microsofts CA and you want the wizard to
prompt you every time you create or import a key, turn on the
Always use the wizard when creating or importing keys option. If
you leave this option turned off, the wizard attempts to protect the
new or imported key by using the card currently in the module.
You can change these settings by rerunning the wizard and
selecting the Use the existing security world option.
If your security world is FIPS compliant, the option to use
module-protected keys is not available.
Backing up the security world and CSP

In versions of the CSP after 1.11.0, the security world host data and
CSP container information is stored in the directory to which the
NFAST_KMDATA environment variable points (by default,
C:\nfast\kmdata ). The data in this directory is encrypted.
The contents of the NFAST_KMDATA directory, together with the
Administrator Card Set and Operator Card Sets, contain the entire
state of the nCipher CSP.

Store the Administrator Card Set in a safe place.
If you lose more than N minus K of these Administrator Cards you
cannot restore the security world or lost Operator Cards. For
example, if you have a 2-of-3 Administrator Card Set and you lose
154
Adding or restoring a module to the security

world
more than one card, you cannot restore the security world. If you have
created an Administrator card set where K equals N, then the loss of
one card stops you from being able to restore the security world.
To prevent this situation from occurring, replace lost or damaged
cards from the Administrator Card Set as soon as you discover the
loss or damage. See Replacing the Administrator Card Set on page
221.
The security of the keys that you create within this security world is
wholly dependent on the security of these smart cards.
The security world host data is stored in the directory to which the
NFAST_KMLOCAL environment variable points. (See the section
Security world files on page 123). The data in this directory is
encrypted. Ensure that this directory is backed up regularly. Check the
file permissions for this directory. Ensure that the nFast Administrator
role, and any user that you want to be able to create Operator Cards or
keys, has write permission for this directory. All other valid users
must have read permission.
Note
By default, the kmdata directory, and sub-directories, inherit

permissions from the user that creates them. Installation of nCipher
software must be performed by a user with Administrator rights that
allow read and write operations, and the starting and stopping of
applications.
The module can now be used to create Operator Cards and keys for
the new security world.
Adding or restoring a module to the security world

When you have created a security world, you can add additional
modules to it. These additional modules can be on the same host
computer as the original module or on any other host. The modules
may have previously been removed from the same security world, that
is, the security world can be restored on a module by adding the
module to the security world again.
155

world
You can also restore a module to a security world in order to continue

using existing keys and Operator Cards:
after you upgrade the firmware
if you replace the module
The additional modules can be any nCipher modules. For information

about adding a network-connected module to the security world, see
the documentation for the appropriate module type.
In order to add a module to a security world, you must:
have a copy of the security world data on this host. This is the host
data written by KeySafe, the nCipher CSP wizard, or new-world
when you created the security world. This data is stored in the
directory to which the environment variable NFAST_KMDATA
points (by default, C:\nfast\kmdata).
set the environment variable NFAST_KMDATA (if the security

world data is not in the default location).
be logged in to the host computer as a user who is permitted to

create privileged connections. See hardserver on page 242.
have started the module in pre-initialization state (as described in

Entering the pre-initialization state on page 78).
possess a sufficient number of cards from the Administrator Card

Set and the appropriate pass phrases.
Adding or restoring a module to a security world:
erases the module
reads the required number of cards (K) from the Administrator

Card Set so that it can re-create the secret
reads the security world data from the computers hard disk
uses the secret from the Administrator Card Set to decrypt the
security world key
stores the security world key in the modules nonvolatile

memory.
156

world
When you have added a module to a security world, you cannot access
any keys that were protected by a previous security world on the
module.
Note
It is not possible to program a module into two separate security

worlds simultaneously.
Initialization removes any data stored in a modules nonvolatile
memory (for example, data for an SEE program or NVRAM-stored
keys). To preserve this data, you must back it up before initializing the
module and restore it after the module has been reprogrammed.
nCipher provides the nvram-backup utility to enable data stored in
nonvolatile memory to be backed up and restored. See nvram-backup
on page 266 for details.
In order to continue using existing keys and Operator Cards, you must
reprogram the module:
after you upgrade the firmware
if you replace the module
if you need to add a module to an existing security world.
Adding a module to a security world with KeySafe

The current release of KeySafe works with multiple modules. In order
to add a module to an existing security world with KeySafe, follow
these steps:
1.

your module.)
2.
Click the Modules menu button. KeySafe takes you to the Module
Operations panel.
3.
Click the Reprogram Module navigation button.
157
4.
Note
Note

world
Select the module that you want to add to your security world by
clicking its listing in the Module Status tree.
The module that you want to add to your security world must be in the
pre-initialization state.
5.
Click the Reprogram Module! command button. KeySafe takes

you to the Load Administrator Card Set panel:
6.
Insert a card from the Administrator Card Set that is required to

authorize this action, and click the OK button. If a pass phrase is
required, you must then enter it.
A pass phrase is associated with a specific card. If, for example, you
insert card A but enter the pass phrase associated with card B,
KeySafe does not accept the pass phrase and prompts you to type it
again.
7.
Repeat the process for the number of Administrator Cards

required for authorization. When you have loaded the required
number of Administrator Cards, KeySafe loads the module key
onto the module.
158

world
After you have added a module to the security world:
Put the module into the operational state, as described in Entering

the operational state on page 79.
Return the Administrator Card Set to safe storage.
The newly added module can now be used with keys and cards from
the existing security world.
Adding a module to a security world with the nCipher CSP wizard

To add a module to an existing security world:
1.
Run the wizard by double-clicking the icon on your desktop.
2.
The wizard displays the window:
3.

If the wizard finds an existing security world, it displays the
following window:
159

world
If the wizard displays any of the other windows:

a.
b.
cancel the operation

check that you have correctly set the environment variable
NFAST_KMDATA
4.
c.
copy the local sub-directory from the NFAST_KMDATA

directory (that is, the directory to which the
NFAST_KMDATA environment variable points) of another
computer in the same security world or from a backup tape
of this computer to the NFAST_KMDATA directory of this
computer.
d.
run the wizard again.
Ensure that the Use the existing security world option is selected,
and click the Next button.
You can then proceed to add modules in the same manner that you add
multiple modules when you create a security world. Follow the
instructions for creating a security world in the section Creating the
security world using the CSP wizard on page 139 from step 17.
160

world
Adding a module to a security world with new-world

1.
Open a command window and type the command:
C:\nfast\bin\new-world [-l|--program] [-S|--no-remoteshare-cert] [-m|--module=MODULE]
In this command:
-l, --program
These options tell new-world to load the existing

security world from the kmdata directory into a module.
These options tell new-world not to make the module a

target for remote shares.
-m, --module=MODULE
These options specifiy the ModuleID to use. new-world

initializes only one module at a time. If you have
multiple modules, you must run new-world once for
every module that you want to add or restore.
If new-world cannot find the key-management data, it displays
the message:
new-world: no existing world to load.
If you intend to initialize the module into a new security world,

run new-world with the -i option.
If the module is not in the pre-initialization state, new-world
displays and error and exits. See new-world on page 259.
If the module is in the pre-initialization state, new-world prompts
you for smart cards and pass phrases as required.
2.
After new-world has reprogrammed the module, restart the

module in the operational state, as described in Entering the
operational state on page 79.
161
3.
Note
Store the Administrator Card Set in a safe place.
If any error occurs (for example, if you do not enter the correct pass
phrases), the module is reset to the factory state. The module does not
form part of the security world unless you run new-world again.

Erasing a module from a security world deletes from the module all
of the secret information that is used to protect your security world.
This returns the module to the factory state. Provided that you still
have the Administrator Card Set and the host data, you can restore the
secrets by adding the module to the security world. Erasing a module
removes any data stored in a its nonvolatile memory (for example,
data for an SEE program or NVRAM-stored keys). If you want to
preserve this data, you must back it up before erasing the module.
nCipher provides the nvram-backup utility to enable data stored in
nonvolatile memory to be backed up and restored. See the appropriate
Operator Guide for your module..
Erasing a module from a security world deletes from the module all
of the secret information that is used to protect your security world.
This returns the module to the factory state. Provided that you still
have the Administrator Card Set and the host data, you can restore the
secrets by adding the module to the security world.
In order to erase a module, you must:
be logged in to your computer as a user who is permitted to create

privileged connections. See hardserver on page 242.
have started the module in the pre-initialization state, as

described in Entering the pre-initialization state on page 78.
You do not need the Administrator Card Set in order to erase a

module. However, unless you have a valid Administrator Card Set
and the host data for this security world, you cannot restore the
security world after you have erased it.
162
After you have erased a module, it is in the same state as when it left
nCipher (that is, it has a random module key and a known KNSO).
Erasing a module with KeySafe

You can erase a module on a server with KeySafe by following these
steps:
1.

your module.)
2.
Click the Modules menu button. KeySafe takes you to the Module
Operations panel.
3.
Click the Erase Module navigation button. KeySafe takes you to

the Erase Module panel:
4.
Select the module that you want to erase by clicking its listing on
the Module Status tree. Then click the Erase Module! command
button.
163
5.
Note
KeySafe erases all secrets from the module, returning it to its

factory state.
If you have any keys that were protected by an erased module, you
cannot access them unless you restore these secrets. You cannot
restore these secrets unless you have the appropriate Administrator
Card Set.
Erasing a module with new-world

new-world can erase any modules that are in the pre-initialization
state.
Run new-world with the command:
new-world [-e|--factory] [-m|--module=MODULE]
In this command:
-e, --factory
These options tell new-world to restore a module to its

factory state.
-m, --module=MODULE
These options specify the ModuleID to use. new-world erases

only one module at a time. To erase multiple modules, you
must run new-world once for every module that you want to
erase.
Output
If new-world successfully erased a module, it does not display any
messages. Otherwise, new-world returns an error message.
164
Erasing a module with initunit

initunit erases any modules that are in the pre-initialization state.
Run initunit with the command:

C:\nfast\bin\initunit [-m|--module=MODULE]
In this command, --module=MODULE specifies the ModuleID of the

module you want to erase. If --module=MODULE is not specified, all
modules in the pre-initialization state are erased.
Output
If initunit is successful, for each module that is in the pre-initialization
state, it returns a message similar to this:
Initialising Unit #
Setting dummy HKNSO
Module Key Info:
HKNSO ###################
HKM ###################
Otherwise, initunit returns an error message.

Occasionally, you may want to replace your security world (for
example, if you believe that your existing world has been
compromised). You can remove an existing security world and
replace it with a new one. However:
you will not be able to access any of the keys that you have
previously used
165
Note
Displaying information about your security

world
before you remove an old security world, you must reformat any
smart cards that were used previously as Operator Cards within
this security world.
If you do not reformat the smart cards used as Operator Cards before
you reinitialize your module, you must throw them away because they
cannot be used, erased, or reformatted without the old security world
key.
You can, and should, reuse the smart cards from the old Administrator
Card Set. If you do not reuse or destroy these cards, then an attacker
with these smart cards, a copy of your data (for example, a weekly
backup) and access to any nCipher key management module can
access your old keys.
There are two ways to delete an existing security world:
Method 1:
a.
Delete the files in the directory to which the

NFAST_KMDATA environment variable points.
b.
Create a new security world.
c.
Add all your modules to this world.
Method 2:
a.
Remove all the modules from the security world.
b.
Delete the files in the directory to which the

NFAST_KMDATA environment variable points.
There may be copies of the security world data archive saved on your
backup media. If you have not reused or destroyed the old
Administrator Card Set, an attacker in possession of these cards
could access your old keys using this backup media.
Displaying information about your security world

You can use the nfkminfo command-line utility to display information
about the status of your security world as described in Displaying
information about your security world with nfkminfo on page 167.
166

world
You can use KeySafe to view details of Operator Cards in a security

world as described in the Operator Guide.
Displaying information about your security world with nfkminfo

To display information about the security world from the command
line, issue the following command:
nfkminfo [-w|--world-info] [-r|--repeat] [-p|--preload-client-id]
In this command:
-w, --world-info
These options specify that you want to display general

information about the security world. These options are the
default and need not be included explicitly.
-r, --repeat
These options display the information repeatedly. There is a

pause at the end of each set of information. The information
is displayed again when you press Enter .
-p, --preload-client-id
These options display the preloaded client ID value, if any.

The command also has the standard help options:
-h, --help
This option displays help for nfkminfo.

-v, --version
This option displays the version number of nfkminfo.

-u, --usage
This option displays a brief usage summary for nfkminfo.
167

world
Output
nfkminfo displays information similar to that shown in the following
examples:
generation 1
state
0x70000 Initialised Usable Recovery !PINRecovery
!ExistingClient !RTC !NVRAM !FTO !SEEDebug
n_modules 1
hknso
hash_knso
hkm
hash_km
hkmwk
hash_knwk
hkre
hash_kre
hkra
hash_kra
ex.client none
...
...
Module #1
generation 1
state
0x1 Useable
flags
0x10000 ShareTarget
n_slots
2
esn
34F3-9CB4-753B
hkml
hash_kml
Module #1 Slot #0 IC 11
generation
1
phystype
SmartCard
slotlistflags 0x2
state
0x4 Operator
flags
0x20000 RemoteEnabled
shareno
2
error
OK
Cardset
name
"fred"
k-out-of-n
1/2
flags
NotPersistent
timeout
none
card names
"" ""
hkltu
hash_kt
generation
1
168
phystype
slotlistflags
state
flags
shareno
shares
error
No Cardset

world
SoftToken
0x0
0x1 Empty
0x0
0
OK
No Pre-Loaded Objects
Security world
nfkminfo reports the following information about the security world:
generation
This indicates the nCipher internal number.

state
This indicates the status of the current world:

Initialised
indicates that the security world has been initialized

Usable
This indicates that there is at least one usable

module in this security world on this host.
!Usable
This indicates that there are no usable modules in

this security world on this host.
Recovery
This indicates that the security world has the key

recovery feature enabled.
169

world
!Recovery
This indicates that the security world has the key

recovery feature disabled.
StrictFIPS140
This indicates that the security world is FIPS 140-2

level 3 compliant. If this is not shown, the security
world is level 2 compliant only.
Note
This indicates that your security world is compliant with the roles and
services of the FIPS 140-2 level 3 standard. It is included for those
customers who have a regulatory requirement for compliance.
ExistingClient
This indicates that there is a Client ID set, for

example, by preload. This Client ID is given in the
ex.client output if the --preload-client-id flag was
supplied.
!ExistingClient
This indicates that no Client ID is set. The ex.client

output will be empty.
!SEEDebug
This indicates the security world has no SEE

Debugging delegation key.
SEEDebug
This indicates that the security world has an SEE

Debugging delegation key.
SEEDebugForAll
This indicates no authorization is required for SEE

Debugging.
170

world
PINRecovery
This indicates that the security world has the PIN

recovery feature enabled.
!PINRecovery
This indicates that the security world has the PIN

recovery feature disabled.
FTO
This indicates that the security world has an FTO

delegation key.
!FTO
This indicates that the security world has no FTO

delegation key.
NVRAM
This indicates that the security world has an

NVRAM delegation key.
!NVRAM
This indicates that the security world has no

NVRAM delegation key.
RTC
This indicates that the security world has an RTC

delegation key.
!RTC
This indicates that the security world has no RTC

delegation key.
171

world
n_modules
This indicates the number of nCipher modules connected to

this computer.
hknso
This indicates the SHA-1 hash of the nCipher Security

Officers key.
hkm
This indicates the SHA-1 hash of the security world key.

hkmwk
This indicates the SHA-1 hash of a dummy key used to load

the Administrator Card Set (the dummy key is the same on
all modules that use nCipher security worlds and is not
secret).
hkre
This indicates the SHA-1 hash of the recovery key pair.

hkra
This indicates the SHA-1 hash of the recovery authorization

key.
ex.client
This indicates the ClientID required to use any pre-loaded

keys and tokens.
k-out-of-n
This indicates the values of K and N for this security world.
172

world
other quora
This indicates the number (quora) of Administrator Cards

(K) required to perform certain other functions as configured
for this security world.
Module
For each module in the security world, nfkminfo reports:
generation
This indicates the version of the module data.

state
This indicates is one of the following:

PreInitMode
This indicates that the module is in the preinitialization state.

InitMode
This indicates that the module is in the initialization

state.
Unknown
This indicates that the modules state could not be

determined.
Usable
This indicates that the module is programmed in the

current security world and can be used.
173

world
Uninitialized
This indicates that the module does not have the

nCipher Security Officers key set and that the
module must be initialized before use.
Factory
This indicates indicating that the module has

module key zero only and that the nCipher Security
Officers key is set to the factory default.
Foreign
This indicates that the module is from an unknown

security world.
AccelOnly
This indicates that the module is acceleration only.

Unchecked
This indicates that, although the module appears to

be in the current security world, nfkminfo could not
find a module initialization certificate (a
module_ESN file) for this module.
Failed
This indicates that the module has failed.

MaintMode
This indicates that the module is in the maintenance

state.
flags
This displays ShareTarget if the module has been initialized

to allow reading of remote card sets.
174

world
n_slots
This indicates the number of nCipher slots on the module

(there is one slot for each physical smart card reader, plus
one slot for each soft token and for any remote slots
available).
esn
This indicates the electronic serial number of the module (if

the module is not in the Usable state, the electronic serial
number may not be available).
hkml
This indicates the hash of the module signing key (if the
module is not in the Usable state, this value may not be
available).
Slot
For each nCipher slot on the module, nfkminfo reports:
IC
This indicates the insertion count for this slot (which is 0 if

there is no card in the slot).
generation
This indicates the version of the slotinfo structure.

phystype
This indicates the type of slot, which can be one of:
SmartCard
SoftToken.
slotlistflags
These are flags describing the capabilities of the slot:
175

world
0x1
This indicates that the slot uses a protected PIN

path.
0x2
This indicates that the slot supports challengeresponse authentication.

state
This can be one or more of the following flags:

Blank
This indicates that the smart card in the reader is

unformatted.
Admin
This indicates that the smart card in the reader is

part of the Administrator Card Set.
Empty
This indicates indicating that there is no smart card

in the reader.
Error
This indicates that the smart card in the reader

could not be read (the card may be from a different
security world).
Operator
This indicates that the smart card in the reader is an

Operator Card.
176

world
flags
This displays Passphrase if the smart card requires a pass

phrase.
shareno
This indicates the number of the card within the card set.
error
This indicates the error status encountered if the smart card

could not be read:
OK
This indicates that there were no errors.

TokenAuthFailed
This indicates that the smart card in the reader

failed challenge response authentication (the card
may come from a different security world).
PhysTokenNotPresent
This indicates that there is no card in the reader.

If you purchased a developer kit, you can refer to the relevant
developer documentation for a full list of error codes.
Card set
If there is an Operator Card in the reader, nfkminfo reports:
name
This indicates the name given to this card set.

k-out-of-n
This indicates the values of K and N for this card.
177

world
flags
This displays one or more of each of the following pairs of

flags:
NotPersistent
This indicates that the Operator Card is not

persistent.
Persistent
This indicates that the Operator Card is persistent.

NotRemoteEnabled
This indicates that the card in the slot is not from a

Remote Operator Card Set.
RemoteEnabled
This indicates that the card in the slot is from a

Remote Operator Card Set.
PINRecoveryForbidden(disabled)
This indicates that the card in the slot does not have
PIN recovery enabled. This is always true if PIN
recovery is disabled for the security world.
PINRecoveryRequired(enabled)
This indicates that the card in the slot does have

PIN recovery enabled.
timeout
the period of time in seconds after which the module

automatically removes the Operator Card Set. If timeout is
set to none, the Operator Card Set does not time out.
178
Windows Cryptographic Services Provider

(CSP)
card
names the names of the cards in the set, not all software can
give names to individual cards in a set.
hkltu
the SHA-1 hash of the secret on the card.

For more information about nfkminfo, see the appropriate Operator
Guide for your module.
Windows Cryptographic Services Provider (CSP)

Container storage format
Note
Versions of the CSP later than 1.11.0 have an updated container

storage mechanism. CSP containers are now stored as part of the
nCipher security world instead of in the Windows registry file.
Versions of the CSP later than 1.11.0 use a non-backwardscompatible container and key storage format. If you are installing
version 1.11.0 or later of the CSP over older versions, you must run
thecspmigrateutility in order to convert containers and keys from the
old system to the new system.
CSP versions 1.11.0 and later have a number of advantages over older
versions:
The CSP state is easily mirrored between multiple machines

simply by copying the contents of the kmdata directory or by
sharing the kmdata directory across a network.
The CSP key files can have arbitrary names (previously, the
names of key files were linked to their key type and their
container name). This new method facilitates the importation of
existing nCipher security world keys into the CSP.
179

(CSP)
Every different container is now guaranteed to have a distinct

storage location. There were circumstances in CSP versions older
than 1.11.0 in which two containers with similar names could
have shared the same keys wrongly.
However, there are some points to bear in mind concerning CSP

versions 1.11.10 and later:
If you want to share the same key between multiple computers,

nCipher supplies the cspimport utility for transferring keys
between containers.
Any existing containers with older versions of the CSP must be

migrated to the new format. nCipher provides a utility,
cspmigrate, to migrate containers from the old to the new system.
180

(CSP)
Setting up the Microsoft CA with an existing key

If you want to set up the Microsoft CA with an existing key, select the
check box labelled Use an existing key in the Advanced Options section
of the CA setup process. You are presented with a menu of suitable
containers (machine containers that contain signature keys) from
which to select:
If the key you select already has a certificate associated with it, you
can choose to use the same certificate for the CA. Such a choice is
typically used if you are reinstalling the CA and using the same key.
Setting up IIS 5 with an existing key

If you want to set up IIS (Internet Information Service) 5 with an
existing key, the process is slightly more complicated. The standard
IIS wizard does not allow you to use an existing container; the only
way you can use an existing container is by using the Microsoft CA
to enroll for the server certificate.
181

(CSP)
For example, in order to generate a suitable server certificate using the

web interface of the Microsoft CA, make the following selections in
order:
1.
Request a certificate
2.
Advanced request
3.
Submit a certificate request to this CA using a form
At this point in the process, the advanced certificate request form

is displayed. Ensure that the two following options are selected:
-
the intended purpose must be Server Authentication

Certificate
Note
the Use local machine store option must be enabled.
If you do not enable these options, the created certificate is not

suitable for use as a Web server certificate and SSL does not work.
The selected CSP must also be a suitable nCipher CSP (typically,
nCipher Enhanced SChannel Cryptographic Provider for an RSA key).
In order to use an existing key set, enable the Use existing key sets
name. The key size option is ignored in this case because the key size
was decided at the original key creation time.
182

(CSP)
The portion of the advanced certificate request form used for the CSP
and key setup is shown below, with all needed options selected
correctly:
Migrating an existing security world to the new CSP format

There is a set of utilities supplied with CSP version 1.11.0 and later
that help you migrate from the Windows registry-based CSP container
storage to the new CSP format. The new CSP format stores all
information about a security world in the kmdata directory.
These utilities are:
cspcheck
This utility checks that CSP container files are intact and
uncorrupted, and also that referenced key files exist. Use
cspcheck in conjunction with nfkmcheck, but run nfkmcheck
first in order to test the integrity of your security world files.
183

(CSP)
cspimport
This utility allows you to insert keys manually into existing

CSP containers. This utility has two modes that either allow
you to change a containers key association to that of an
arbitrary nCipher security world key or to copy CSP keys
between containers.
cspmigrate
This utility moves an existing security worlds CSP

container information from the registry to the security
worlds kmdata directory.
csputils
This utility lists CSP containers and provides detailed

information about them. It can also be used to delete
container files if the current user has administrative
privileges.
keytst
This utility displays information about existing CSP key

containers by using the Microsoft CryptoAPI. If you have
the appropriate permissions, keytst also allows you to create
containers and their keys, as well as delete containers.
A further CSP utility, cspimport, lets you insert keys manually into
existing CSP containers. This utility has two modes that allow you
either to change a containers key association to that of an arbitrary
nCipher security world key or to copy CSP keys between containers.
Each of these commands has an -h option that display the usage
message for the command.
184

The utilities mk-reprogam and key-xfer-im are used to transfer keys
between security worlds. Before you can use these utilities to transfer
keys, the following must be the case:
the security world from which keys are being transferred must
have recovery enabled (the destination security world can be nonrecoverable).
the key being transferred must have recovery enabled or be

module-protected
you must have the Administrator Card Sets for both the exporting
module and the importing module.
If one of the modules is a netHSM, it should be imported
To transfer keys:
1.
Program the module to which you intend to transfer the key into
one of the security worlds involved.
If one of the security worlds is FIPS 140-2 level 3 compliant and
the other is not, then program the module into the security world
that is not FIPS 140-2 level 3 compliant.
2.
Run the mk-reprogram utility on the exporting security world in

order to program a module key from that security world to a
module in the importing security world. See mk-reprogram on
page 255.
To authorize this operation, you must first present a quorum of
Administrator Cards for KNSO for the exporting (current) security
world, then a quorum of Administrator Cards for module
programming from the importing security world.
Note
If you change security worlds by using the command new-world -l, the
programmed module key is lost.
185
3.
Run the key-xfer-im utility on the exporting security world in

order to transfer the key to the importing security world. See keyxfer-im on page 250 for full details of the utility.
If you are transferring the key from a security world that is FIPS
140-2 level 3 compliant to one that is not, you must use the -export-add option. If you are transferring the key from a security
world that is not FIPS 140-2 level 3 compliant to one that is, you
must use the --export-delete option. These options must precede
the key file name in the key-xfer-im command.
Also, remember that the default or current security world is set by
the NFAST_KMDATA environment variable, which defaults to
%NFAST_HOME%\kmdata. For more information about this
environment variable, see Appendix C: Environment variables.
4.
Initialize the importing security world.

To verify that module-protected keys have been imported:
a.
Run the following command:
C:\nfast\bin\preload --module-prot exit
The output shows whether the key was imported

successfully.
b.
Check the C:\nfast\kmdata\local\ directory to see if the key

has been exported.
You can use preload to load other types of keys to verify that they
have been imported.See the Operator Guide for details.
5.
If you have transferred keys that protect PKCS #11 objects, run
postrocs on the target module once the key transfer is complete.
See postrocs on page 286.
186
Chapter 12: About payShield installations

You must create security worlds specifically for use with the
payShield module and then use the payshield-install utility to
configure an associated payShield installation. Normally, you
configure a payShield installation in this way when you set up the
module; see Creating and configuring a payShield installation on page
64 for details.
This chapter contains reference information about payShield
installations.
All installation activities which make use of the security world
Administrator Card Set, the Key Establishment Card Set or the
payShield Master Card Set must be performed on a trusted host. This
host should not be connected to any network and should be stored and
used in a physically secure location. Ideally the hosts software,
including the operating system and the nCipher software, should be
freshly installed from trusted media. The security and integrity of a
payShield installation cannot be guaranteed if any of these card sets
is compromised.
You can usually create a payShield installation with an existing
security world, but nCipher strongly recommends creating a new
security world for your payShield installation.

In the process of setting up a security world and payShield
installation, you create three card sets, each of which plays a different
role in your key management infrastructure.
187
12 About payShield installations
Administrator Card Set

You create an Administrator Card Set (ACS) during security world
creation. The security of all keys and data protected by the security
world depend on it. See After you have created a security world on
page 154 for further general information on the ACS. In particular, the
ACS must be used only on a trusted system.
payShield Master Card Set

Each payShield installation that you create has its own Master Card
Set. The security of all keys and data protected by the payShield
installation depend on it. It is used only when performing critical
administrative operations on the installation, for example, upgrading
the payShield SEE machine. It should not be exposed at any other
time. Master Card Sets must be used only on a trusted system.
payShield Key Establishment Card Set

Each payShield installation you create has its own Key Establishment
Card Set. This card set is used exclusively during the establishment
(import or generation) of keys in the payShield installation. A quorum
from this card set is required in order to establish a new key in the
payShield installation.
Card Set Quorums

nCipher recommends that you give careful consideration to the choice
of K and N for the ACS and Master Card Set. Any quorum of K
Administrator Card holders or K Master Card holders can perform
administrative functions, such as weakening or overriding the security
protection of payShield keys. This means that any attacker who
obtains a quorum of cards and pass phrases can do the same.
nCipher suggests as a minimum a quorum of 3 cards out of 5 (that is,
a 3-of-5 card set) for the ACS and Master Card Set.
188
Additionally, the Administrator Card Set has a separate quorum for

Foreign Token Open operations (FTO). An FTO quorum of
Administrator Cards is required (and sufficient) to authorize the
reading of data directly from non-nCore-format smart cards. Thus, the
FTO quorum of Administrator Cards must be used to enable the
payShield system to use the module smart-card reader to exchange
key setup information with the VeriFone handset. Similarly, any
attacker who can use the FTO quorum of Administrator Cards may be
able to interfere with and subvert key establishment, including
reading key components from transfer smart cards.
The quorum for FTO should be selected to prevent this. nCipher
suggests as a minimum a quorum of 3.
nCipher recommends that you give careful consideration to the choice
of K and N for the Key Establishment Card Set. Any quorum of K Key
Establishment Card holders can introduce new keys, as can an
attacker who is able to use K Key Establishment Cards with a module
in the security world. If new keys are not authorized and secure, they
may compromise the security of other payShield keys and PINS that
are being processed.
nCipher suggests as a minimum a quorum of 2 cards out of 4 (that is,
a 2-of-4 card set) for the Key Establishment Card Set.
Card Holders
The entire security of the keys you create within the payShield
installation and of the data that they protect depends on the security of
the security world and of the payShield installation card sets. You
must ensure that all cards are stored securely and in the custody of
trusted personnel. Cards should never be exposed needlessly.
No individual should ever have possession of more than one card from
a particular card set, although an individual may hold one card from
each of a number of different card sets.
189

lmku
This type is the Local Master Key for key and data
encryption.
lmkr
This type is the Local Master Key for key encryption only.
zmk
This type is the Zone Master Key.

cvk
This type is for CVC generation and verification.

cvkv
This type is for CAVV generation and verification.

pvk
This type is the Pin Verification Key.

tpk
This type is the Terminal PIN Key.

zpk
This type is the Zone PIN Key.

mksmi
This type is for secure messaging for the integrity master key
mkidn
This type is the dynamic number master key
190
mkac
This type is the AC (ARQ, AAC, TC) master key

mkdac
This type is for the static data authentication master key.

A Local Master Key (lmk) can be used for the encryption both of key
material and of data such as PINs. However, nCipher considers it
useful to split and restrict the capabilities of certain key types.
Therefore, the following two new types of lmk are provided for use
with payShield:
lmku for the encryption of keys and data
lmkr for the encryption of keys only
When specifying an lmk in a payShield installation, you must select

one of these types of lmk depending on your requirements. These are
treated as strictly separate roles and cannot be changed after creation.

This section describes the properties required of a security world for
payShield installations. For general information on creating security
worlds, see Creating a security world on page 129. Security worlds for
payShield must have FTO and key recovery enabled. You must set K
for the Administrator Card Set to a value other than 1.
See Card Set Quorums on page 188 for important advice about the
choice of a value for K.
If you wish to make use of the extended payShield module debugging
option you must also select the dseeall feature. This option is designed
for testing purposes only. Do not enable it on production security
worlds as it may enable SEE applications to leak security
information.
191
It is extremely important that you choose the settings carefully

because you cannot change the properties of a security world after you
have created it.
192
Chapter 13: Remote Operator Card Sets

This chapter describes:
Note
the concept of the Remote Operator functions
how to configure Remote Operator.
If you wish to use the Remote Operator feature, you must enable it as
described in Chapter 8: Feature Enabling nCipher Modules. The
Remote Operator feature must be ordered for, and enabled on, the
module that you intend to use as the remote, unattended module.
About Remote Operator

The Remote Operator facility enables the contents of a smart card
inserted into the slot of one module (the attended module, such a
client module) to be securely transmitted and loaded onto another
module (the unattended module, such as a netHSM). This is useful
when you need to load a key protected by an Operator Card Set onto
a machine to which you do not have physical access, for example,
because it is in a secure area.
For Remote Operator to work, the modules must be in the same
security world. The Operator Card Set is inserted into a slot in the
attended module. From this module, the contents of the card set are
transmitted over secure channels to another module. This module, the
unattended module, loads the contents of the Operator Card Set. You
do not need physical access to this module during the loading of the
card set.
The following limitations apply to Remote Operator:
Non-persistent card sets cannot be accessed remotely.
The createocs utility cannot use remote slots to write new cards or
card sets.
193
13 Remote Operator Card Sets
You can export a slot from an attended module and import a slot to any
(unattended) module in the security world. The unattended module
for import may be a local module connected to the host or a networkconnected module such as a netHSM or payShield net module.. (You
can import or export slots between netHSM or payShield net modules
and local modules only if the local module uses a hardserver whose
version is 2.6.10 or higher.) Before you can import a slot to one
module, you must first export it from another module.

This section describes how to configure Remote Operator.
Before you configure Remote Operator

Requirements for Remote Operator
Before you start to configure Remote Operator, you must do the
following:
Initialize two modules in the same security world, as described

below.
Initialize the unattended module as described below.
Ensure both the attended and unattended module are in the

operational state, as described in Entering the operational state on
page 79.
Create an Operator Card Set with the correct permissions, as

described in Creating a Remote Operator Card Set on page 196.
Configure each hardserver to allow communication between the

modules.
194
Initializing modules for Remote Operator

Firmware version 2.6.10 or greater must be installed in both the
attended and unattended module. Use the enquiry utility to determine
the version of the firmware on the modules. For instructions on
upgrading firmware, see Appendix A: Upgrading module firmware
or the documentation for the appropriate module type.
After updating the firmware, the unattended module must be
reinitialized into the security world by using KeySafe or new-world.
Note
By default, a module is initialized with remote card set reading

enabled. If you do not want a module to be able to read remote card
sets, you must configure it accordingly. Use the command new-world S MODULE (where MODULE is the modules ModuleID number) if
you do not want this module to be able to read remote card sets. See
new-world on page 259
Note
for full information.

The attended module does not need to be re-initialized.
If a module has been initialized to allow loading of remote card sets,
nfkminfo displays a module section of the following form:
Module #1
generation
state
flags
n_slots
esn
hkml
2
0x2 Usable
0x10000 ShareTarget
3
8851-43DF-3795
391eb12cf98c112094c1d3ca06c54bfe3c07a103
The ShareTarget flag indicates that the module can be used as an

attended module for the loading of Remote Operator Card Sets.
195
Creating a Remote Operator Card Set

You must create card sets that allow themselves to be loaded remotely
for use with Remote Operator. A module with firmware 2.0.2 (PCI
modules) or greater must be used to create the card sets.
Create each card set using Keysafe or the -q option for createocs. (For
information on createocs, see the Operator Guide.). The cards must
have been created to be persistent; see Creating the Operator Card Set
on page 71.
Note
All the modules must be included in the security world before you
generate the Operator Card Set. If you are not using client
cooperation, the kmdata directories must be manually synchronized
after you generate the Operator Card Set.
If the card in the given slot is from a remotely enabled card set,
nfkminfo displays a slot section similar to the following:
generation
1
phystype
SmartCard
slotlistflags
0x2
state
0x5
Operator flags
0x20000 RemoteEnabled
shareno
1
shares
LTU(Remote)
error
OK
In this output, the RemoteEnabled flag indicates the card can be loaded
remotely.
Importing and exporting slots

To import a slot from an attended module on to an unattended module:
196
1.
Configure the host of the attended module to export the slot. To

do this, add an entry for the slot to be imported to the slot_exports
section of the configuration file
as described in slot_exports on page 94
.
2.
Configure the host of the unattended module to import the slot.

To do this, add an entry for the slot exported in step 1 to the
slot_imports section of the configuration file on the host.
Exporting a remote slot

Import and export of slots is set up in the slot_exportssection of the
hardserver configuration file for each module. The Remote Operator
feature must be enabled on the module.
The slot_exports section defines the slots on local modules that the
local hardserver should allow network modules to import. Each local
slot has an entry for each remote module that can import it, as follows:
local_esn
The ESN of the local module whose slot can be imported by
a network module.
local_slotid
The SlotID of the slot to be imported. The value must be an
integer. The default is 0.
remote_ip
The IP address of the machine that is allowed to import the
slot.
remote_esn
The ESN of the module allowed to import the slot.
197
Importing remote slots

Import and export of slots is set up in the hardserver configuration file
for each module.
The slot_imports section in this file defines the remote slots that the
local hardserver on an unattended module should import from remote
modules for use by modules connected directly to the local computer.
Each slot is defined by an entry as follows:
local_esn
The ESN of the local module to which to import the slot.
remote_ip
The IP address of the machine that hosts the slot to import
remote_port
The port number on which the remote hardserver is listening.
remote_esn
The ESN of the remote module from which to import the
slot,
remote_slotid
The SlotID of the slot to import on the remote module. The
value must be an integer. The default is 0.
198
Loading Remote Operator Card Sets

After the hardserver has been configured, the remote slots can be used
by all the standard nCipher libraries. A remote slot can be used to load
any Operator Card Sets that have been created to allow remote
loading. See the chapter in the Operator Guide that covers the
application you wish to use with remote cards for more information.
Note
After an Operator Card Set has been inserted into a remote slot, for
each time a given card is inserted, the module only allows each share
on that card to be read once. If there is a second attempt to read shares
from that card before the card is reinserted, the operation fails with a
UseLimitsUnavailable error.
Creating keys protected by Remote Operator Card Sets

After you have created card sets that can be loaded remotely, use
generatekey and preload, or Keysafe, to create keys protected by them.
Note
KeySafe can list the imported slot but cannot use it.
If you already have card-set protected keys that you want to use, but
the card set is not remotely loadable, you can use Keysafe to protect
the key under a new card set that is remotely loadable. This only
succeeds if the key was initially generated with recovery enabled. If
you created the key without enabling key recovery, you cannot protect
the key under a different card set. In this case, you must generate a
new key.
199
Chapter 14: Administration tasks with cards and

softcards
This chapter describes tasks with card sets and softcards that require
an Administrator Card Set to authorize them.
For other card and softcard tasks, see the appropriate Operator Guide
for your module.
If you want to configure smart cards for use with a remote module, see
Chapter 13: Remote Operator Card Sets.
This chapter describes the following operations:
replacing an unknown pass phrase for an Operator Card
replacing an Operator Card Set or recovering keys to a different

softcard
replacing the Administrator Card Set.
changing a softcard pass phrase with ppmk (in security worlds

where pass phrase recovery is enabled and the pass phrase is
unknown).
Before you can perform any of these operations, you must first create
a security world, as described in Chapter 11: Managing
security worlds.

To replace a pass phrase for an Operator Card when you do not know
the current pass phrase, you must:
have created a security world with pass phrase recovery
have the number of cards from the Administrator Card Set

required to recover a pass phrase.
200
14 Administration tasks with cards and softcards
Replacing a pass phrase with cardpp (on a client)

Take the following steps:
1.
Run the cardpp utility using the command:
C:\nfast\bin\cardpp --recover [-m|--module=MODULE]
In this command:
--recover
This option tells cardpp to recover the pass phrase.

-m, --module=MODULE
These options specify the number of the module to use.

If you only have one module, MODULE is 1. If you do
not specify a module number, cardpp uses all modules
by default.
2.
At the prompt, supply the number of cards from the

Administrator Card Set required to authorize pass phrase
recovery.
3.
At the prompt, insert the Operator Card whose pass phrase you
want to replace.
4.
At the prompt, type the pass phrase or press Enter if you do not
want to set a pass phrase.
5.
If you have entered a pass phrase, at the prompt, confirm it.

cardpp sets the new pass phrase and prompts you for another
Operator Card.
6.
To change the pass phrase on further cards, repeat steps 3 though

5, or press Q to quit.
Administrator cards should only be inserted in a server you know is

secure.
201

In order to prevent you from losing access to your keys if the smart
card you are using as the Operator Card is lost or damaged, nCipher
supplies several utilities that can recover the keys protected by the lost
Operator Card to another token:
KeySafe includes an option to replace Operator Card Sets on the

Card Operations panel (click the Replace OCS navigation button).
The rocs command-line utility provides an interactive method or

a command-line only method to replace Operator Card Sets.
When you replace an Operator Card Set, the key material is not
changed by the process. The process deletes the original host data
(that is, the encrypted version of the key or keys and the smart card
data file) and replaces this data with host data protected by the new
Operator Card Set.
In order to replace an Operator Card Set, you must have:
Note
enabled key recovery when you created the security world
If you did not enable key recovery, or if you created the security world
with an early version of pkcs-init that did not support key recovery, you
cannot recover keys from lost or damaged smart cards.
created the original Operator Card Set using createocs, createocsimple, KeySafe, or the nCipher PKCS #11 library version 1.6 or
later
If you initialized the token using ckinittoken from the nCipher PKCS
#11 library version 1.5 or earlier, you must contact Support at
nCipher to arrange for them to convert the token to the new format
while you still possess a valid card.
202
Note
a sufficient number of cards from the Administrator Card Set to

authorize recovery
All recovery options require authorization from the Administrator

Card Set. If any of the smart cards in the Administrator Card Set are
lost or damaged, immediately replace the entire Administrator Card
Set.
initialized a second Operator Card Set using createocs, createocsimple, KeySafe, or the nCipher PKCS #11 library version 1.6 or
later.
Note
The new Operator Card Set need not have the same K-of-N policy as
the old set.
If you are sharing the security world across several host computers,
you must ensure that the changes to the host data are propagated to all
your computers. One way to achieve this is to use client cooperation;
see Setting up client cooperation on page 53.
Replacing Operator Card Sets with KeySafe

In order to replace an Operator Card Set, you must have another
Operator Card Set onto which to copy the first sets data. If you do not
already have an existing second Operator Card Set, you must create a
new one. See the Operator Guide for details.
When you have a second Operator Card Set ready, follow these steps
in order to replace the first Operator Card Set:
1.

your module.)
2.
Click the Cards menu button. KeySafe takes you to the Card
Operations panel.
203
3.
Click the Replace OCS navigation button, and KeySafe takes you
to the Replace Operator Card Set panel:
204
This panel lists existing Operator Card Sets in tabular form. For
each card set it displays:
Name
the name of the card set

Required (K)
the number of cards needed to re-create a key

Total (N)
the total number of cards in the set

Persistent
whether or not the card set is persistent

Recoverable Key Count
the number of private keys protected by this card set that

can be recovered
Nonrecoverable Key Count
the number of private keys protected by this card set that

cannot be recovered.
You can click and drag with your mouse in order to resize this
table's column widths and to rearrange the column order.
Clicking a column heading sorts the rows in ascending order
based on that column heading.
Note
4.
Select an Operator Card Set that you want to replace by clicking

its list entry.
5.
Click the Replace OCS! command button.
If the card set does not have any recoverable keys, it cannot be
replaced.
205
6.
Note
KeySafe takes you to the Load Administrator Card Set panel,

where it prompts you to insert cards from the Administrator Card
Set in order to authorize the action. Each time you insert an
Administrator Card into the modules smart card slot, you must
click the OK button to load the card.
Only insert your Administrator Card Set into a module that is

connected to a trusted server.
7.
When you have loaded enough cards from the Administrator

Card Set to authorize the procedure, KeySafe takes you to the
Load Operator Card Set panel, where it prompts you to insert the
Operator Card Set that is to protect the recoverable keys (this is
the Operator Card Set onto which you are copying data from the
Operator Card Set you are replacing). Each time you insert an
card from the new Operator Card Set into the modules smart
card slot, you must click the OK button.
When you have loaded enough cards from the new Operator Card
Set, KeySafe creates new working versions of the recoverable
keys that are protected by this card set.
KeySafe deletes the original host data for all recovered keys and
replaces this data with host data that is protected by the new
Operator Card Set. If there are no nonrecoverable keys protected
by the card set, KeySafe also removes the old card set from the
security world. However, if the Operator Card Set has
nonrecoverable keys, the host data for the original card set and
for the nonrecoverable keys is not deleted. These keys can only
be accessed with the original Operator Card Set. If you want to
delete these files, use the Remove OCS option.
8.
When the process is complete, KeySafe displays a dialog box

indicating that the Operator Card Set has been successfully
replaced. Click the OK button. KeySafe returns you the Replace
Operator Card Set panel, where you may replace another
Operator Card Set or choose a different operation.
206
Recovering keys to Operator Card Sets or softcards with rocs

You can use the rocs utility interactively, or you can supply all the
parameters on the command line.
Using rocs interactively

Run the rocs utility using the command:
C:\nfast\bin\rocs
rocs displays the following prompt:

'rocs' key recovery tool
Useful commands: 'help', 'help intro', 'quit'.
rocs >
In order to use rocs to replace an Operator Card Set or recover keys to

a softcard, take the following steps:
Note
1.
You must select a module to use by using the module command,

which is described in the section module number on page 213.
2.
List the Operator Card Sets and softcards in the current security
world by using the list cardsets command, which is described in
the section list cardsets on page 210.
3.
Select the Operator Card Set or softcard to which you want to

transfer the keys by using the target command, which is described
in the section target cardset-spec on page 214.

4.
List the keys in the current security world using the list keys
command, which is described in the section list keys on page 212.
207
5.
Select the keys that are to be recovered by using the mark

command, which is described in the section mark key-spec on
page 213.
6.
If you have selected any keys by mistake, deselect them by using

the unmark command, which is described in the section unmark
key-spec on page 215.
7.
After you have selected the keys that are to be recovered, transfer
these keys by using the recover command, which is described in
the section recover on page 214.
rocs prompts you to insert a card from the Administrator Card
Set.
8.
Insert a card from the Administrator Card Set.

rocs prompts you for the pass phrase for this card. This action is
repeated until you have loaded the required number of cards from
the Administrator Card Set.
If you do not have the required number of cards from the
Administrator Card Set, press Q and then Enter . The rocs utility
returns you to the rocs > prompt without processing any keys.
Administrator cards should only be inserted in a server you know is
secure.
208
9.
If you are recovering keys to an Operator Card Set:

a.
rocs prompts you to insert a card from the first Operator Card
Set that you have selected as the target. Operator Card Sets
are processed in ascending numerical order as listed by the
list cardsets command.
b.
Insert a card from this Operator Card Set.
c.
rocs prompts you for the pass phrase for this card. This action
is repeated until you have loaded the required number of

cards from the Operator Card Set.
If you are recovering keys to a softcard, rocs prompts you for the
pass phrase for the softcard that you have selected as the target.
If you decide that you do not want to transfer the keys to the
selected card set or softcard, press Q and then Enter (to
quit).rocs returns you to the rocs > prompt and does not process
any further Operator Card Sets or softcards.
When you have loaded the target softcard or the required number
of cards from the target Operator Card Set, rocs transfers the
selected keys to the target Operator Card Set or softcard.
If you have selected other target Operator Card Sets or softcards,
rocs prompts for a card from the next Operator Card Set.
10. Repeat step 9 for each selected target.

11. If you have transferred the correct keys, write the key blobs to
disk by using the save function (described in the section save keyspec on page 214). If you have transferred a key by mistake, you
can restore it to its original protection by using the revert
command (described in the section revert key-spec on page 214).
At the rocs prompt, you can use the following commands:
help topic
help intro
list cardsets
list keys
209
Note
mark key-spec
module number
quit
recover
rescan
revert key-spec
save key-spec
status
target cardset-spec
unmark key-spec
You can specify a command by typing enough characters to identify

the command uniquely. For example, for the status command, you can
type st and then press Enter .
help
With no arguments specified, help shows a list of available commands
with brief usage messages and a list of other help topics. With an
argument, help shows detailed help information about a given topic.
help intro displays a brief step-by-step guide to using rocs.
list cardsets
This command lists the Operator Card Sets and softcards in the
current security world. For example:
No.
1
2
3
Name
test
test2
test3
Keys (recov)
6 (6)
3 (2)
1 (1)
Sharing
3 of 5; 20 minute timeout
2 of 3
1 of 1; persistent
In this output:
210
No.
This is the card set or softcard number, which can be used to

identify this card set in rocs commands.
Name
This is the Operator Card Set or softcard name

Keys
This is the number of keys protected by this Operator Card

Set or softcard
(recov)
This is the number of recoverable keys

Sharing
This indicates the K of N parameters for this Operator Card

Set
persistent
This indicates that the Operator Card Set is persistent and

does not have a time-out set
### minute timeout
This indicates that the Operator Card Set is persistent and

has a time-out set.
211
list keys
This command lists the keys in the current security world, as in the
following example:
No.
1
2
R 3
4
5
Name
rsa-test
Id: uc63e0ca3cb032d71c1c
Server-Cert
Id: uc63e0ca3cb032d71c1c
Server-Cert
App
hwcrhk
pkcs11
pkcs11
pkcs11
pkcs11
Protected by
module
test2
test --> test2
test --> test3
module (test ---> fred2)
where:
No.
This is the key number, which can be used in mark and

unmark commands.
Name
This is the key name.

App
This is the application with which this key is associated.

Protected by
This indicates the protection method:

method
description
module
key protected by the security world
name
key protected by the named Operator Card Set or softcard
name-->name2
key protected by the Operator Card Set or softcard name1 marked

for recovery to Operator Card Set or softcard name2
module (name)
PKCS #11 public object, which are protected by the security

world but associated with a specific Operator Card Set or softcard
module (name-->name2)
PKCS #11 public object marked for recovery
212
mark key-spec
This command marks the listed keys that are to be recovered to the
target Operator Card Set or softcard. You can mark one or more keys
by number, ident, Operator Card Set or softcard, or hash. See
Specifying keys on page 217 for details. To mark more than one key
at a time, ensure that each key-spec is separated from the other by
spaces, as in the following example:
mark key-spec1 key-spec2 key-spec3
If you have not selected a target Operator Card Set or softcard, or if

rocs cannot parse the key-spec, then rocs displays an error message.
You can mark and remark the keys to be recovered to various target
Operator Card Sets or softcards. Remarking a key displaces the first
target in favor of the second target.
Note

module number
This command selects the module to be used. The module number
must correspond to a module in the current security world. If the
module does not exist, is not in the security world, or is otherwise
unusable, then rocs displays an error message and does not change to
the selected module.
quit
This command allows you to leave rocs. If you attempt to quit when
you have recovered keys but have not saved them, rocs displays a
warning.
213
recover
This command transfers the marked keys to their target Operator Card
Sets or softcards. This operation is not permanent until you save these
keys by using the save command.
rescan
This command updates the card set and key information.
revert key-spec
This command returns keys that have been recovered, but not saved,
to being protected by the original protection method. If the selected
keys have not been recovered, rocs displays an error message.
save key-spec
This command writes the new key blobs to disk. If you specify a
key-spec, only those keys are saved. Otherwise, all recovered keys are
saved.
status
This command lists the currently selected module and target Operator
Card Set or softcard.
target cardset-spec
This command selects a given Operator Card Set or softcard as the
target. You can specify the card set or softcard name, the number
returned by list cardsets, or the hash.
214
unmark key-spec
This command unmarks the listed keys. Unmarked keys are not
recovered.
Using rocs from the command line

You can select all the options on the command line using the
command:
C:\nfast\bin\rocs -m|--module=MODULE [-t|--target=CARDSET-SPEC]
[-k|--keys=KEYS-SPEC] [-c|--cardset=CARDSET-SPEC] [-i|--interactive]
In this command:
-m, --module=MODULE
specify the module number of the module to use.

-t, --target=CARDSET-SPEC
specifies the Operator Card Set or softcard to be used to

protect the keys. See Specifying card sets on page 217 for
details.
-k, --keys=KEYS-SPEC
selects the keys to be recovered. See Specifying keys on page

217 for details.
-c, --cardset=CARDSET-SPEC
selects all keys that are protected by the given Operator Card
Set or softcard. See Specifying card sets on page 217 for
details.
-i, --interactive
forces rocs to start interactively even if you have already

selected keys.
215
The rocs command also has the standard help options:

-h, --help
displays help for rocs

-v, --version
displays the version number of rocs

-u, --usage
displays a brief usage summary for rocs.

You must specify the target before you specify keys.
You can use multiple --keys=KEYS-SPEC and --cardset=CARDSETSPEC options, if necessary.
You can specify multiple targets on one command line by including
separate --keys=KEYS-SPEC or --cardset=CARDSET-SPEC options for
each target. If a key is defined by --keys=KEYS-SPEC or
--cardset=CARDSET-SPEC options for more than one target, it is
transferred to the last target for which it is defined.
If you have selected a module, a target Operator Card Set or softcard,
and keys to recover but have not specified the --interactive option, rocs
automatically recovers the keys. rocs prompts you for the
Administrator Card Set and Operator Card Set or softcard, as
described in Using rocs interactively on page 207.
Note
If you use rocs from the command line, all keys are recovered and
saved automatically. You cannot revert the keys unless you still have
cards from the original Operator Card Set.
If you do not specify the target and keys to recover, or if you specify
the --interactive option, rocs starts in interactive mode with the
selections you have made. You can then use further rocs commands to
modify your selection before using the recover and save commands to
transfer the keys.
216
Specifying card sets

The value of CARDSET-SPEC identifies one or more Operator Card
Sets or softcards. It may have any of the following forms:
[number] cardset-number
selects the Operator Card Set or softcard with the given

number from the list produced by the list cardsets command
[name] cardset-name
selects card sets or softcards by their names (the card set or

softcard name may be a wildcard pattern in order to select all
matching Operator Card Sets or softcards)
hash cardset-hash
selects the Operator Card Set or softcard with the given hash.
In order to specify multiple Operator Card Sets or softcards, include
several CARDSET-SPECs on the command line.
Note

Specifying keys
The --keys=KEYS-SPEC option identifies one or more keys. It may
have any of the following forms:
mark key-number
This selects the key with the given number from the list
produced by the list keys command. Examples of usage are:
rocs -t target_OCS -k key_number
217
and
rocs -t target_OCS -k "mark 56"
appname:keyident
This selects keys by their internal application name and

ident. You must supply at least one of appname or keyident,
but you can use wildcard patterns for either or both in order
to select all matching keys. An example of usage is:
rocs -t target_OCS --keys="simple:simplekey"
hash keyhash
This selects the key with the given key hash. An example of
usage is:
rocs -t target_OCS --keys="hash e364[...]"
--cardset cardset-spec
This selects all keys protected by a given card set

If you have generated your security world with pass phrase recovery,
the cardpp utility allows you to:
change a pass phrase
add a pass phrase to a card that currently does not have one
remove a pass phrase from a card that currently has one
218
replace the pass phrase of an Operator Card even though you do

not know the current pass phrase. This operation requires
authorization from the Administrator Card Set. Changing a pass
phrase with cardpp when you do know the current pass phrase
does not require authorization from the Administrator Card Set;
for more information see the Operator Guide appropriate for
your module.
Each card in a card set can have its own individual pass phrase. You
can even have a set in which some cards have pass phrases and others
do not. A pass phrase can be of any length and can contain any
characters that you can type.
Changing pass phrases with cardpp (pass phrase not known)

To change a pass phrase for an Operator Card using the cardpp
command-line utility when you do not know the pass phrase, you
must:
have sufficient cards from the Administrator Card Set to

authorize the action.
If these conditions are met, take the following steps:

1.
Run the cardpp utility using the command:
C:\nfast\bin\cardpp --recover [-m|--module=MODULE]
In this command:
--recover
tells cardpp to recover the pass phrase.

-m, --module=MODULE
specify the number of the module to use. If you only

have one module, MODULE is 1. If you do not specify a
module number, cardpp uses all modules by default.
219
2.
When cardpp prompts you, insert sufficient cards from the

Administrator Card Set to authorize pass phrase recovery.
3.
When cardpp prompts you, insert the Operator Card whose pass
phrase you want to replace.
4.
When cardpp prompts you for the new pass phrase, type the pass
phrase or press Enter if you do not want to set a pass phrase.
5.
If you have entered a pass phrase cardpp asks you to confirm it.
After you confirm, cardpp sets the new pass phrase and prompts
you for another Operator Card.
6.
If you do not want to continue press Q to quit.

If you have generated your security world with pass phrase recovery,
the ppmk utility allows you both to change a softcards pass phrase if
you know the current pass phrase and recover a softcards pass phrase
even if you do not know the current pass phrase.
Changing a pass phrase with ppmk when you do know the current
pass phrase does not require authorization from the Administrator
Card Set; for more information see the Operator Guide appropriate
for your module.
Changing a pass phrase with ppmk when you do not know the current
pass phrase requires authorization from the Administrator Card Set.
Changing pass phrases with ppmk (pass phrase not known)

To change a pass phrase for a softcard using the ppmk command-line
utility when you do not know the pass phrase, you must:
have sufficient cards from the Administrator Card Set to

authorize the action.
If these conditions are met, take the following steps:
220
1.
Run the ppmk utility using the command:
C:\nfast\bin\ppmk --recover NAME|IDENT
In this command, --recover tells ppmk to recover the pass phrase.

You can identify the softcard whose pass phrase you want to
recover by its name (NAME) or by its logical token hash as listed
by nfkminfo (IDENT).
2.
When ppmk prompts you, insert sufficient cards from the

Administrator Card Set to authorize pass phrase recovery.
3.
When prompted, type a pass phrase for the new softcard, and
press Enter . A pass phrase can contain any characters that you
can type and can be up to 1024 characters long.
4.
ppmk prompts you to confirm the pass phrase. Type the pass
phrase again and press Enter .
If the pass phrases do not match, ppmk prompts you to input and
confirm the pass phrase again.
Administrator Card Sets should only be inserted in a trusted server.
After you have confirmed the new pass phrase, ppmk finishes
configuring the softcard to use the new pass phrase.

Replacing the Administrator Card Set uses K of the cards in the
current Administrator Card Set in order to:
1.
load the secret information that is to be used to protect the

archived copy of the security world key.
2.
create a new secret that is to be shared between a new set of cards
3.
create a new archive that is to be protected by this secret.
221
If you discover that one of the cards in the current Administrator Card
Set has been damaged or lost, use the command-line utility racs or the
KeySafe Replace Administrator Card Set option to create a new set
immediately. If further cards are damaged, you may not be able to recreate your security world.
nCipher recommends that you erase your old Administrator Cards as
soon as you have created the new Administrator Card Set. An attacker
with the old Administrator Card Set and a copy of the old host data
could still re-create all your keys. With a copy of a current backup,
they could even access keys that were created after you replaced the
Note
Before you start to replace an Administrator Card Set, you must

ensure that you have enough blank cards to create a complete new
Administrator Card Set. If you start the procedure without enough
cards, you will have to cancel the procedure part way through.
Replacing an Administrator Card Set with KeySafe

When you have enough cards to create a complete new Administrator
Card Set ready, follow these steps in order to replace the old
1.

your module.)
2.
Click the Cards menu button. KeySafe takes you to the Card
Operations panel.
3.
Click the Replace ACS navigation button, and KeySafe takes you
to the Replace Administrator Card Set panel.
4.
If you are sure that you want to replace the Administrator Card
Set, click the Replace ACS! command button
222
5.
Note
KeySafe takes you to the Load Administrator Card Set panel,

where it prompts you to insert cards from the Administrator Card
Set in order to authorize the action. Each time you insert an
Administrator Card into the modules smart card slot, you must
click the OK button to load the card.
Only insert your Administrator Card Set into a module that is

connected to a trusted server.
6.
Note
When you have loaded enough Administrator Cards to authorize

the action, KeySafe takes you to the Create Administrator Card
Set panel, where it prompts you to insert the cards that are to form
the Administrator Card Set. These must be blank cards or cards
that KeySafe can erase. KeySafe will not let you use cards from
the existing Administrator Card Set. If you do not have enough
cards to form a complete new Administrator Card Set, cancel the
operation now.
When creating a card set, KeySafe recognizes cards that belongs to

the set even before the card set is complete. If you accidentally insert
a card to be written again after it has already been written, KeySafe
displays a warning.
223
7.
When you insert a blank card, KeySafe takes you to the Set Card
Protection Pass Phrase panel:
8.
If you want to set a pass phrase for this Administrator Card:

a.
Select the Yes option.
b.
Enter the same pass phrase in both text fields.
c.
Click the OK button.
KeySafe then prompts you for the next card (if any). A given pass
phrase is associated with a specific card, so each card can have a
different pass phrase. You can change these pass phrases at any
time by using KeySafes Examine/Change Card option (available
from the Card Operations panel) or the cardpp command-line
utility.
9.
If you do not want to set a pass phrase for this Administrator

Card:
a.
Select the No option.
b.
Click the OK button.
224
10. After you have created all the Administrator Cards, KeySafe
displays a message:
ACS successfully replaced. Now consider erasing your old Administrator Cards
Click the OK button, and KeySafe returns you to its introduction

panel.
11. When you have finished replacing the Administrator Card Set,
erase the old Administrator Cards.
Replacing an Administrator Card Set with racs

Note
Before you start to replace an Administrator Card Set, you must

ensure you have enough cards to create a complete new Administrator
Card Set. If you start the procedure without enough cards, you will
have to cancel it part of the way through.
The racs utility creates a new Administrator Card Set to replace a set
that was created with the new-world utility.
Use the command:
C:\nfast\bin\racs.exe [-m|--module=MODULE] [-f|--force]
In this command:
--module=MODULE
specifies the ModuleID of the module to use.

--force
tells racs to allow the use of smart cards that already contain
data. Any existing data is erased. If a value for this flag is not
specified, racs prompts you if a card contains data.
When you have finished replacing the Administrator Card Set, erase
the old Administrator Cards.
225
Chapter 15: nShield Administrator Utilities

This chapter contains reference information about the utilities
referred to in this manual. See Appendix E: Installed Utilities for a
full list of all the utilities supplied with the nCipher software.
Help options
If a utility has the standard help options, these are not included in the
synopsis or in the description. The standard help options are as
follows:
-h, --help displays help for the utility
-v, --version displays the version number of the utility
-u, --usage displays a brief usage summary for the utility
Some commands have alternative help options. These are described

but are not included in the synopsis.
226
15 nShield Administrator Utilities
anonkneti
anonkneti
This utility displays the ESN and HKNETI key hash from a netHSM
module identified by its IP address. This information is required to
configure your client hardserver to import the remote module.
This utility uses an anonymous host and is insecure. Use it only if you
trust your network. Otherwise, obtain the ESN and HKNETI of the
module from the welcome screen.
Usage
c:\nfast\bin\anonkneti [-m module] [-p port] IP_address
In this command:
-m module
This option specifies the module to query. The default is

module 1.
-p port
This option specifies the port to use to communicate with the

module.
IP_address
This option specifies the IP address of the module from

which to obtain the ESN and HKNETI key hash.
227
cfg-reread
cfg-reread
This utility loads the hardserver configuration from the configuration
file.
Usage
C:\nfast\bin\cfg-reread.exe
This command has no options or parameters. It loads the file

C:\nfast\kmdata\config\config as the clients current configuration. See
server_remotecomms on page 90 for details of the configuration file.
The cfg-reread utility calls a number of separate utilities, each of
which loads one section of the configuration file. If you update only
one section of the configuration file, you can reload just that section
by running the corresponding command as follows:
Utility
Configuration file
section
Updates ...
hsc_loadseemachine.exe
load_seemachine
SEE machine settings
hsc_serverremotecomms.exe
server_remotecomms
Remote communications
settings
hsc_serversettings.exe
module_settings
server_settings
Module settings and

hardserver settings
hsc_slotimports.exe
slot_imports
Imported slot settings
hsc_slotexports.exe
slot_exports
Exported slot settings
228
enquiry
enquiry
The enquiry utility returns information about the nCipher server and
the modules connected to it.
Usage
enquiry -m|--module=MODULE
In this command, --module=MODULE is the module number of the

module about which you want to receive information. If you do not
specify a module, enquiry returns information about all modules.
Output
enquiry returns the following data for the server and each module:
enquiry reply flags
Failed indicates that the module has failed. This failure may
be because the module is in the Error state or because there
is a problem on the PCI bus.

enquiry reply level
This is the version of enquiry that the module (or hardserver)

supports. For release 9.0 and later, this level is Six or higher.
serial number
This is the electronic serial number of the module. Please

quote this number when contacting Support at nCipher. For
the server, this field contains the electronic serial numbers
for all attached modules.
mode
This is one of:
229
enquiry
operational
initialisation
maintenance
pre-initialisation
pre-maintenance
uninitialised.
For the server, this is always operational.

version
This is the version of the nCipher server or firmware.

speed index
This is the estimated number of 1024-bit modular

exponentiations that the module can perform in 1 second.
rec. queue
This is the recommended minimum and maximum number

of jobs in the job queue to keep the module fully loaded.
level one flags
If the module supports enquiry level One or greater, one or

more of the following flags is set:
Hardware
The Hardware flag is always set.

HasTokens
The HasTokens flag is set if the module has a smart

card interface.
230
enquiry
MaintenanceMode
The MaintenanceMode flag is set if the module is in

maintenance or pre-maintenance state.
InitialisationMode
The InitialisationMode flag is set if the module is in

initialization or pre-initialization state.
PreMaintInitMode
The PreMaintInitMode flag is set if the module is in

pre-maintenance or pre-initialization state.
version string
For modules that support enquiry level One or greater, this

indicates the version of the nCipher server or firmware.
checked in
For modules that support enquiry level One or greater, this

indicates the date on which the firmware was last modified.
level two flags
This is for nCipher internal use only..

Note
There should be no level two flags set. If any are set, contact Support
at nCipher.
max write size
Currently, this is 8192 for nShield/payShield modules.

level three flags
For modules that support enquiry level Three or greater, the

KeyStorage flag is set if you have a key-management
module. If this flag is set for any of the attached modules, it
is also set for the server.
231
enquiry
level four flags
For modules that support enquiry level Four or greater, one

or more of the following flags can be set:
OrderlyClearUnit
The OrderlyClearUnit flag is set for firmware

release 1.40 and later.
HasRTC
The HasRTC flag is set if the module has a RealTime Clock.

HasNVRAM
The HasNVRAM flag is set if the module has

nonvolatile memory.
HasNSOPermsCmd
The HasNSOPermsCmd flag is set if the module

supports the SetNSOPerms nCore API command. If
you purchased a developer kit, you can refer to the
relevant developer documentation for information
on nCore API commands.
ServerHasPollCmds
The ServerHasPollCmds flag is set if the server or

any module supports the PollModuleState and
PollSlotList API commands. If you purchased a
developer kit, you can refer to the relevant
developer documentation for information on nCore
API commands.
232
enquiry
FastPollSlotList
The FastPollSlotList flag is set for a particular

module if PollSlotList on that module does not
require module interaction. This is the case if both
the hardserver and the module support the relevant
extensions.
HasSEE
The HasSEE flag is set if the module firmware

supports the Secure Execution Engine (SEE).
HasKLF
The HasKLF flag is set if the module has a longterm fixed signing key.
HasShareACL
The HasShareACL flag is set for a module if the

firmware supports creation of ACLs on smart card
shares. If this flag is set, then the module is capable
of creating Operator Card Sets that can be loaded
remotely.
HasFeatureEnable
The HasFeatureEnable flag is set if the module

supports feature enabled functions. See Chapter 8:
Feature Enabling nCipher Modules for information
on the features available and how to enable them.
HasFileOp
The HasFileOp flag is set if the module supports

operations using nonvolatile memory.
HasPCIPush
The HasPCIPush flag is set by the module if it has

PCI push functionality.
233
enquiry
HasKernelInterface
The HasKernelInterface flag is set if the module has

a kernel interface.
HasLongJobs
The HasLongJobs flag is set if the module supports

unlimited time for job completion.
SeverHasLongJobs
The SeverHasLongJobs flag is set if the hardserver

supports unlimited time for job completion.
AESModuleKeys
The AESModuleKeys flag is set if the module

supports the use of the AES Algorithm (Rijndael)
for module keys.
NTokenCmds
The NTokenCmds flag is set if the module supports

the commands necessary for nToken.
For the server, the level four flags field contains all the flags
set for attached modules.
module type code
For modules that support enquiry level Five or greater, this

field contains the numeric value of the module type. This can
be:
0 for the server
5 for models nC3022W-nnn, nC4022W-nnn, and
nC4032W-nnn
6 for models nC3022P-nnn, nC4022P-nnn, nC4032P-
nnn, and nC4132P-nnn
234
enquiry
7 for models nC3023P-nnn, nC4023P-nnn, and
nC4033P-nnn
11 for model nC4031Z-nnn.
product name
For modules that support enquiry level Five or greater, this is

the product name. For the server, this is nFast server.
device name
For modules that support enquiry level Five or greater, the

ModuleID, bus, and slot for the device, as reported in log
messages. For example, #1 PCI bus 0 id 2 means ModuleID 1
on PCI bus 0 with PCI ID 2. device name is blank in the
information on the server and for installations where the
server software is earlier than version 1.60.5.
EnquirySix version
For modules that support enquiry level Six, this is the

extended enquiry reply level six version number. (The
highest currently supported level is Five.)
impath kx groups
For modules that support enquiry level Six, this lists the
available key exchange groups that this module can use
when it makes a connection with another module.
feature ctrl flags
For modules that support enquiry level Six version 1 or

greater, this is always set to LongTerm. This field does not
exist for the server.
235
enquiry
features enabled

greater, this lists the features currently enabled. Possible
values are as follows:
Value
Feature that is enabled
Feature name
ForeignTokenOpen
Foreign Token access features (ISS).
ISO Smart Card Support
RemoteShare
Remote Operator Card support
Remote Operator
KISAAlgorithms
Support for KISA algorithm suite

(KCDSA, SEED, HAS160 hash
function)
Korean Algorithms.
GeneralSEE
Allows any SEE machine to be

loaded. Available only within CGEA
locations.
SEE Activation (EU+10)
EllipticCurve
Allows small key sizes to provide

improved levels of security.
Elliptic Curve
If no features are enabled, this field is set to StandardKM.

This field does not exist for the server.
version serial

greater, this is the version serial number of the module.
remote server port

greater, this is the port on which the hardserver listens for
communications from remote modules. (The default is
9004.)
kneti hash

greater, this is the HKNETI key hash (if present) of this
module.
236
enquiry
rec. LongJobs queue

greater, this is the recommended minimum and maximum
number of jobs in the job queue to keep the modules that
support LongJobs fully loaded.
SEE machine type

greater, this is gen1AIF for modules with ARM processors
and PowerPCSXF for modules with Power PC processors.
This information is needed if you are developing CodeSafe
applications (see the CodeSafe Developers Guide for more
information).
237
floodtest
floodtest
The floodtest utility performs hardware speed testing using modular
exponentiation with the Chinese Remainder Theorem.
Usage
C:\nfast\bin\floodtest.exe [--crt|--no-crt] [-Q|--query] [-R|--no-round-robin] [-l|-job-size=BITS]
[-t|--stop-after=TIME] [-j|--outstanding-jobs=COUNT] [-n|--jobs-count=COUNT]
[[[-K|--skew-check=SKEW ]| [-T|--min-check=COUNT ]] [-C|--check-start=TIME ]]
[--overprint][-o|--output=FILE] [-r|--report-interval=TIME]
Program options
--crt
This option specifies use of CRT optimization. This is the

default.
--no-crt
This option specifies no use of CRT optimization

-Q, --query
These options specify use Query mode (spinlock) rather than

Wait mode
-R, --no-round-robin
These options specify that replies be accepted in any order.

(The default is that replies are accepted on a round-robin
basis.)
238
floodtest
-l, --job-size=BITS
These options set the size of exponentiation modulus to the

number of bits specified in BITS. The default is 1024. The
value of BITS must be between 64 and 4096. BITS must be a
multiple of 64
Note
Certain older modules (with serial numbers beginning 01-52, 01-54,

01-56, 01-P2, 01-P4, or 01-P6) can run out of memory if you run
floodtest with sizes greater than 2048, especially if the module has any
keys or tokens loaded.
-j, --outstanding-jobs=COUNT
These options try to keep COUNT number of jobs

outstanding at a time. The default value of COUNT is the
maximum number of jobs recommended for the hardserver,
plus 1.
-t, --stop-after=TIME
These options specify the maximum time to run the test. Use
the suffix s to specify seconds, m for minutes, h for hours,
and d for days. The default value of TIME is infinity.
-n, --jobs-count=COUNT
These options specify the maximum number of jobs to run.

The default value of COUNT is infinity.
Automatic checking options

-T, min-check=COUNT
These options perform threshold checking, starting after

either 15 seconds or the time specified by --check-start.
Subsequently, when floodtest writes an output line, it quits
with an error message if the overall average number of
modular exponentiations each second drops below COUNT.
239
floodtest
-K, --skew-check=SKEW
These options perform skew checking, after either 15

seconds or the time specified by --check-start. floodtest
records the overall average number of modular
exponentiations each second as rec_ave. Subsequently, when
floodtest writes an output line, it quits with an error message
if the average is outside the range rec_aveSKEW.
Note
The --min-check and --skew-check options are mutually exclusive.

-C, --check-start=TIME
This option specifies the time in seconds at which threshold

or skew checking starts. The default value of TIME is 15.
Output options
--overprint
This option prints results all on one line, using \r rather than
\n.
-o, --output=FILE
This option specifies that results be written to FILE in

addition to stdout.
-r, --report-interval=TIME
This option displays, at the specified interval of TIME

seconds, the total number of exponentiations achieved, and
the rate at which they are performed. The default value of
TIME is 1.
240
floodtest
Output
floodtest returns output similar to this:
hardware, speed index 296, using rec. max outstanding + 1 = 46
1,
148 59.2,
151
overall
2,
410 140.32, 206
overall
3,
677 190.992, 226
overall
4,
944 221.395, 267
overall
5,
1190 231.237, 256.5 overall
...
The first column, to the right of the line numbers, shows the number
of seconds.
The second shows the total number of exponentiations performed.
The third column shows the number of exponentiations achieved this
second.
The last column shows a moving average of the number of
exponentiations achieved each second.
241
hardserver
hardserver
The hardserver is the communications service between applications
and nCipher modules.
You must be logged in as Administrator to use the command-line
options for this command.
Usage
hardserver.exe [-c|--command-line]
The hardserver is configured by means of configuration files. See

Hardserver configuration file on page 85 for information.
The -c or --command-line options run the hardserver program as a
command line program instead of as a service
Hardserver startup
The hardserver utility is the hardserver program. It is installed as a
service and started automatically.
On startup, the hardserver looks for scripts in the
directory and executes them as
follows:
%NFAST_HOME%\scripts\hardserver.d
On hardserver startup, all batch files whose names begin with S

are executed in strict lexicological order (for example,
S01_myscript.bat followed by S02_myscript.bat).
On module reset, if and only if the module is being reset into

operation mode, all batch files whose names begin with M are
executed in strict lexicological order (for example,
M01_myscript.bat followed by M02_myscript.bat ).
When the hardserver starts, it clears all modules and runs all the S
scripts and then all the M scripts in order for all operational modules.
242
hardserver
Stopping the hardserver

1.
Ensure that you are logged in as a user who is permitted to stop

and that services (for example, a Local Administrator).
2.
Open the Computer Management dialog. This is usually found by

choosing Programs > Administrative Tools from the Start menu.
3.
Highlight the Services entry under Services and Applications.

nFast Server should be listed with the status Started.
4.
Scroll down the list of services until you have highlighted the
nFast Server entry, and click the Stop button in order to stop the
server.
Restarting the nCipher server

1.
Ensure that you are logged in as as a user who is permitted to

create privileged connections.
2.
Open the Computer Management dialog. This is usually found by

choosing Programs > Administrative Tools > Computer
Management from the Start menu.
3.
Highlight the Services entry under Services and Applications.

nFast Server should be listed with the status Stopped.
4.
Scroll down the list of services until you have highlighted the
nFast Server entry, and click the Start button in order to restart the
server.
243
initunit
initunit
The initunit utility initializes a unit with a random module key and a
known KNSO. This utility makes a key-management module usable
but does not enable any key archival or recovery.
Usage
In order to use initunit, you must be logged in to the host computer as
root or as a user in the group nfast and must start the module in the
pre-initialization state. See Entering the pre-maintenance state on
page 76 for information on putting the module into a pre-initialization
state.
C:\nfast\bin\initunit.exe [-m|--module=MODULE] [-n|--ntoken]
In this command:
-m, --module=MODULE
These options specify the module number (MODULE) of the

module you want to initialize. If you do not specify a
module, initunit initializes all modules that are in a preinitialization state.
-n, --ntoken
These options specify the initialization of a module as an

nToken.
244
initunit
Output
If initunit is successful, it returns a message similar to this for each
module that has been initialized:
Initialising Unit #
Setting dummy HKNSO
Module Key Info:
HKNSO
###################HKM
###################
Otherwise, it returns an error message that points to the reason for the
initialization failure.
245
loadkeys
loadkeys
The loadkeys utility is used with a payShield installation. It imports,
generates or exports keys. Its use is described in full in the Keyloading
Solution Guide.
Usage
C:\nfast\bin\loadkeys.exe [options] psiname
In this command, psiname is the name of the payShield installation

that you are going to import the key into. psiname must consist of 16,
or fewer, lower case alphanumeric characters.
Options
Modes of Operation
-I, --import
These options import a key (requires --format option).

-E, --export
These options export a key (requires --format option).

-G, --generate
These options generate a new key.

--batch
This option specifies that the application does not prompt for
nonessential options that have not been specified on the
command line. Non-essential options include key export
options, rolespecific options and group memberships.
246
loadkeys
General options
-m, --module=MODULE
These options select the hardware security module to use.

The default is 1.
-f, --format=FORMAT
These options specify the import or export format for the

key. This can be wrapped or components.
--kcvf=CV_FORMAT
These options specify the key Check Value format. This can
be one of none (for no check value), zero (for the
encryptzeros method) or self (for the encrypt-self method).
-d, --debug
These options enable library debugging.

-k, --key-name=NAME
These options specify the name for the imported key. This
can be either the name of the key to be exported or the name
to give the newly imported key, depending upon the
operation.
Import/Generate options
-l, --length=LENGTH
These options set the lengths for each component. LENGTH

can be 8, 16 or 24 bytes.
This is equal to the length of the resulting derived key, or half
the length of the derived key if you are importing cvk or cvkv
keys.
247
loadkeys
You can omit this option if the key type specified in

--role=ROLE has only one permitted length.
-r, --role=ROLE
These options specify the role for the imported key

-g, --group=NAME
These options add the key to group NAME. NAME can be a

maximum of 16 characters. The option may be specified
multiple times.
-a, --export-attended
These options makes the key exportable in attended

operations.
-A, --no-export-attended
These options specify that the key is not to be exportable in

attended operations.
Component options
--ccvf=CV_FORMAT
These options specify the component Check Value format.

This can be one of none (for no check value), zero (for the
encrypt zeros method) or self (for the encrypt-self method).
-n, --num=COMPONENTS
These options specify the total number of components. This

can be an integer from 2 through 9.
248
loadkeys
Wrapped options
-w, --wrapper=NAME
These options specify the name of the wrapping key. key. If

the payShield key that you specify cannot be loaded, the
application prompts you for another name.
Reduced AC import options

-i, --iipb=MASK
These options specify the IIPB mask to be used with this

reduced AC key operation. The default is ffff000000000000.
IBM PIN key options

--dtable=TABLE
This option specifies the decimalization table that is to be

used with a new PVKIBM key.
--pan-n=PAN
This option specifies the number of PAN digits to be

required for PIN generation with a new PVKIBM key. PAN
can be an integer from 0 through 12: the default is 12.
249
key-xfer-im
key-xfer-im
The key-xfer-im utility transfers a key into a second security world.
The module must previously have had the second security worlds
module key loaded using the mk-reprogram utility, described in mkreprogram on page 255. (See Transferring keys between security
worlds on page 185.)
Usage
key-xfer-im SOURCE-KMDATA-LOCAL DESTINATION-KMDATA-LOCAL NEW-PROTECT KEY-FILE [KEYFILE ...] [NEW-PROTECT KEY-FILE [KEY-FILE ...]]
Parameters
SOURCE-KMDATA-LOCAL
The full path name of the kmdata file for the source security
world.
DESTINATION-KMDATA-LOCAL
The full path name of the kmdata file for the target security
world.
NEW-PROTECT
The protection for the key in the target security world.

You must specify either --module or --cardset. If you specify
--cardset, it must be followed by the key hash for the
destination card set.
In addition, you can also specify options to configure the key
protection further:
250
key-xfer-im
--export-leave
This option is used to leave the keys list of

operations requiring authorization from the
Administrator Card Set (ACS)= the same. This is
the default.
--export-add
This option is used to add export to the keys list of

operations requiring authorization from the ACS.
This option is available only when exporting keys
from a strict FIPS 140-2 level 3 security world into
a non-strict FIPS 140-2 level 3 security world.
--export-delete
This option is used to remove export from the keys

list of operations requiring authorization from the
ACS. This option is available only when exporting
keys from a non-strict FIPS 140-2 level 3 security
world into a strict FIPS 140-2 level 3 security
world.
--aclbase-recovery
This option is used to base the Access Control List

(ACL) of the exported key on the ACL in the
recovery key blob. This is the default.
--aclbase-working
This option is used to base the ACL of the exported

key on the ACL in the working key blob.
KEY-FILE
This is the full path of source kmdata file for the key. The
module must have module keys from both worlds: program
it into one world with new-world and use mk-reprogram to
251
key-xfer-im
add the other module key. If transferring between Strict

FIPS-140 level 3 and non-strict worlds, the modules owning
world must be non-strict.
The following example command demonstrates the second step in
moving a module from a security world that is not FIPS 140 2 level 3
compliant to one that is:
key-xfer-im C:\nfast\kmdata\local\ C:\nfast\kmdata-FIPS\local\ --module --export-delete
KEY-FILE
252
loadrom
loadrom
The loadrom utility loads new firmware into a module. Firmware is
supplied as an encrypted and signed file. See Upgrading module
firmware on page 323 for information on upgrading firmware.
You can also use loadrom to obtain information about the firmware.
Usage
C:\nfast\bin\ [-v|--view] [-n|--notypecheck] [-m|--module=MODULE]
[-b|--maxblocksize=SIZE] NFF_file
In this command NFF_file is the name of the file that contains the
firmware. This has the extension .nff. See Appendix A: Upgrading
module firmware for information on the file name for your module.
Help options
-h, --help
These options display help for loadrom.exe.

-V, --version
These options display the version number of loadrom.exe.

-u, --usage
These options display a brief usage summary for

loadrom.exe.
Programming options
-v, --view
These options only display information about the .nff file and
do not load it.
253
loadrom
-i, --ioboard
This option is for nCipher internal use only.

-m, --module=MODULE
These options load the firmware on the module MODULE.

-b, --maxblocksize=SIZE
These options set the maximum block size in bytes for

module programming.
--notypecheck
This option omits the module type check.
Output
If you select the --view option, loadrom displays output similar to this:
File :..\..\module\firmware\2-18-13\ncx3p-21.nff
Firmware : PCI Type 3 firmware version 2.18.13cam1 (VSN 21)
for : nC1003P/nC3023P
Filetype : NFast3
Programming chunks: 12
Confidentiality key:
nC3023P confidentiality key (dorris #2)
Confidentiality mech:
DES3mCBCi64pPKCS5
Signatures:
#0: <unknown> integrity key
#1: nC3023P integrity key (dorris-1)
During installation and when upgrading module firmware you can

compare the output of loadrom --view with the information provided
by the enquiry command-line utility to ensure that the correct version
of the firmware is present on the module. See enquiry on page 229.
254
mk-reprogram
mk-reprogram
The mk-reprogram utility programs a security-world module key into
a module to which it does not yet belong. A key that is to be
transferred from one security world to another must be loaded into a
module that:
has been programmed into one of the security worlds
has had the module key of the target security world loaded into it
using mk-reprogram.
After the security-world module key has been loaded, you can use the
key-xfer-im utility to transfer a key into the second security world.
(See Transferring keys between security worlds on page 185.)
Usage
mk-reprogram.exe [[--module MODULE-NO----] CHANGES
In this command CHANGES specifies the parameters of the

reprogrammed security world, as described in Keywords on page 256.
kmdata must be from the security world that includes the module.
Options
--module=MODULE-NO
specifies the module on to which to program the security

world. The default is the first available module.
--protocol
specifies the protocol to use.

--owner kmlocal-path
specifies the path to the source module's kmlocal directory.
255
mk-reprogram
Keywords
CHANGES can be one of the following:
list
lists the details of the security world.

add kmdata-path
adds the path to the local kmdata directory. This directory

must be from the security world that includes the specified
module.
delete MODULE-KEY-HASH
deletes the specified module key hash.
Example
The following example command demonstrates the first step in
moving a module-protected key from a security world that is not FIPS
140 1 level 3 or FIPS 140 2 level 3 compliant to one that is:
mk-reprogram --module 1 add C:\nfast\kmdata_FIPS\local
256
ncversions
ncversions
The ncversions utility displays installed nCipher support software
components and their versions. The utility lists all components,
whether installed individually or as part of a component bundle, and
also the component bundles themselves. See Components on nCipher
CD-ROMs on page 330.
Usage
C:\nfast\bin\ncversions.exe
Output
The following in an example of a component list produced by
ncversions:
Comp
Output Version Repository/Build no.
---------------------------------------------------------------convrt
user
1.1.0
cam/1
csee
armdev 0.10.5
cam/3
csee
seedev 0.10.5
cam/3
ctd
agg
0.0.12
cam/4
ctls
agg
0.0.13
cam/3
cutils
devel
1.4.2
cam/8
emvjni
user
0.2.2
cam/36
emvspj
user
0.2.6
cam/20
emvspj
devel
0.2.6
cam/20
emvspp
user
1.5.10
cam/14
emvspp
devel
1.5.10
cam/14
gcchk
user
1.1.1
cam/2
...
...
...
...
...
...
...
...
ncversions displays a line of information for each component:
257
ncversions
Comp
This gives the component's identifying code

Output
This identifies the type of component, such as:
user for a user component
devel for a developer component
agg for a component bundle
Version
This identifies the version of the component

Repository/Build no.
This identifies the repository and build number.
258
new-world
new-world
The new-world utility creates a security world that supports SEE
functions and remote Operator Card Set use. new-world also allows
you to specify different thresholds for different operations, such as:
adding a module
replacing an Operator Card Set
authorizing real-time clock operations
authorizing nonvolatile memory operations.
new-world can also be used to add a module to an existing security
world.
To use the new-world utility, you must be logged in to the host
computer as Administrator or a user who is permitted to create
privileged connections.
Note
If you create a security world with new-world, this security world is

created with only one module. If you use other modules, then you must
add them to the security world with new-world or KeySafe.
Usage
new-world -i|initialize [-S|--no-remoteshare-cert][-o|--overwrite][-F|--strict-fips140-level-2-level-3] [-R|--no-recovery][-m|--module]MODULE] -Q|--acs-quorum=K/N FEATURES
-k|--km-type=KEY-TYPE [--reduced-features]
new-world -l|program [-S|--no-remoteshare-cert][-m|--module=MODULE]
new-world -e|--factory -m|--module=MODULE
259
new-world
Module selection option

-m, --module=MODULE
These options specify the module to use. new-world

initializes only one module at a time. If you have multiple
modules, you must run new-world once for every module.
The default is 1.
Action selection options

-i, --initialize
These options tell new-world to initialize a new security

world and program it into the module specified in
--module=MODULE, replacing any existing kmdata
directory.
-l, --program
These options tell new-world to load the existing security

world from the kmdata directory into a module specified in
--module=MODULE.
-e, --factory
These options tell new-world to erase a module, restoring it

to factory state.
Note
You must not include more than one of the --initialize, --program, and -factory options. If you do not specify any of these options and a
kmdata directory already exists, new-world loads the security world
found within the directory. If you do not specify any of these options
and no kmdata directory exists, new-world creates a security world.
260
new-world
Module reprogramming options

These options tell new-world that the selected module is not

a target for remote shares.
New security world options

-Q, --acs-quorum=K/N,
In these options K is the maximum number of smart cards

required from the Administrator Card Set to authorize a
feature. You can specify lower thresholds for a particular
feature. Thresholds must be less than or equal to the total
number of cards in the set.
N is the total number of smart cards to be used in the
Administrator Card Set. This value must be less than or
equal to 64.
Note
You should not create an Administrator Card Set for which the
required number of cards is equal to the total number of cards
because you cannot replace the Administrator Card Set if even a
single card is lost or damaged.
The --acs-quorum=K/N option only takes effect if you are
creating a new security world.
261
new-world
-F, --strict-fips-140-2-level-3
These options create a security world that conforms to the

FIPS 140-2 requirements for roles and services at level 3. If
you do not specify this flag, new-world creates a security
world that complies with FIPS 140-2 requirements for level
2.
Note
FIPS 140-2 level 3 standard. It is included for those customers who
The current release of the nCipher PKCS #11 library works with a
FIPS 140-2 level 3 compliant security world. However, if you intend
to use the security world with the PKCS #11 applications iPlanet
Enterprise Server or iPlanet Proxy Server, do not specify this flag.
The --strict-fips-140-2-level-3 option only has any effect if you
are creating a new security world.
-O, --overwrite
These options tell new-world to allow the use of smart cards

that already contain data. Any existing data is erased. If a
value for this flag is not specified, new-world prompts you if
a card contains data.
-R, --no-recovery
These options tell new-world to disable Operator Card Set

recovery. The effect of setting this flag is the same as for
specifying the feature !r.
By default, new-world creates key-recovery material that is
protected by the cryptographic keys on the Administrator
Card Set. This option does not give nCipher or any other
third party access to your keys. Keys can only be recovered
by using the Administrator Cards. nCipher recommends that
you leave Operator Card Set recovery enabled.
262
new-world
If you do not enable this option at the time of security world

creation, you can never enable recovery for keys in the
security world.
If you do not enable this option when you create the ACS,
you can never enable recovery for any card sets protected by
the ACS.
-k, --km-type=KEY-TYPE
These options specify the type of key that is to protect the

new security world. KEY-TYPE can be des3 or rijndael).
Features
When initializing a security world, features may be specified as
arguments after the module number. Some features are enabled by
default, and you can give the command new-world --help-features to
display a list of features indicating which are enabled by default when
initializing a security world with new-world.
Features are specified as a comma-separated list of terms. Each term
consists of a feature name, optionally preceded by either a dash (-) or
an exclamation point (!) to turn off the feature and can optionally be
followed by an equal sign (=) and the threshold for this feature.
However, the ! character, used to turn off a given feature, is
interpreted by some shells (for example, the C shell and its
derivatives, bash and zsh) as requesting a history expansion. In such
cases, you must escape the ! character by preceding it with a \
character, as in the following example:
new-world 2 rtc,nv,\!r
Additionally, any feature entered on the command line with a leading

hyphen (-) can be interpreted as an option. Attempting to pass a
feature as a nonexistent option in this way returns an error (for
example, unknown option). Prevent errors of this kind by using the
263
new-world
standard POSIX double hyphen (--) marker to indicate that any

subsequent features on the command line are not to be interpreted as
options, as in the following example:
new-world -m 2 -- -r
Currently understood feature names are:
m, for module programming (this feature cannot be disabled)
r, for Operator Card Set recovery
p, for pass phrase recovery
dsee, to make an SEE debugging key
dseeall, enable SEE debugging without authorization
nv, for nonvolatile memory allocation
rtc, real-time clock setting
fto, Foreign Token Open authorization. Use this feature with ISO
Smartcard Support.
The dsee and dseeall options are not applicable unless you have
purchased and installed nCiphers CodeSafe Developer kit.
For example, the following features:
m=1,r,!p,nv=2,rtc=1
create a security world for which:
a single card from the Administrator Card Set is required to add

a new module
the default number is required to replace an Operator Card Set
pass phrase recovery is not enabled
2 cards are required to allocate nonvolatile memory
264
Note
new-world
1 card is required to set the real-time clock.
Under most conditions, it is advisable to turn on such features as nv,

rtc, dsee, and (if desired) p. There is usually no benefit in turning on
both dsee and dseeall simultaneously.
Output
If new-world cannot interpret the command line, it displays its usage
message and exits.
If you attempt to set a threshold for a feature that you have disabled
or if you attempt to set a threshold too high, new-world displays an
error and exits.
If the module is not in the pre-initialization state, new-world displays
and error and exits. To put the module in the pre-initialization state,
see Entering the pre-maintenance state on page 76.
If the module is in the pre-initialization state, new-world prompts you
for smart cards and pass phrases as required.
When new-world has initialized the module, restart the module in the
operational state.
265
nvram-backup
nvram-backup
The nvram-backup utility copies files between a modules nonvolatile
memory and a smart card. It can be used to back up and restore files
that are stored in NVRAM. Files you can back up and restore are data
files stored in NVRAM by an SEE program and NVRAM-stored
keys. See the Operator Guide for more details.
Do not store keys in NVRAM unless you must do so to satisfy
regulatory requirements.
Note
nCipher introduced NVRAM key storage only for users who must store
keys within the physical boundary of a module to comply with
regulatory requirements. NVRAM-stored keys provide no additional
security benefits and their use exposes your Administrator Card Set to
increased risk. Storing keys in nonvolatile memory also reduces loadbalancing and recovery capabilities. Because of these factors,
nCipher recommends you always use standard security world keys
unless explicitly required to use NVRAM-stored keys.
To use nvram-backup you specify an action and, optionally, the
location of the files to be acted on. Available actions are list, copy and
delete. You can list the contents of, and delete files from, a modules
NVRAM, and copy files from NVRAM to a smart card. You can list
files on a smart card and copy from a card to a modules NVRAM.
You cannot use nvram-backup to delete files from a smart card.
Note
Use the bulkerase utility to format cards for use with nvram-backup.
If you are using a FIPS 140-2 level 3 compliant security world, you
will be prompted for an Administrator Card or Operator Card from the
security world to authorize copying of files to or from NVRAM and
deletion of files from the modules NVRAM.
When you copy files to a modules NVRAM or delete files from
NVRAM, you are required to insert a quorum of Administrator Cards
for NVRAM authentication.
266
nvram-backup
Usage
C:\nfast\bin\nvram-backup.exe -l|--list -M|--from-module|-S|--from-smartcard [-m|-module=MODULE] [-s|--slot=SLOT] [-f|--force] [-v|--verbose] [-x|--hex] [FILES]
C:\nfast\bin\nvram-backup.exe -c|--copy -M|--from-module|-S|--from-smartcard [-m|-module=MODULE] [-s|--slot=SLOT] [-f|--force] [-v|--verbose] [-x|--hex] [FILES]
C:\nfast\bin\nvram-backup.exe -d|--delete -M|--from-module [-m|--module=MODULE] [-s|-slot=SLOT] [-f|--force] [-v|--verbose] [-x|--hex] [FILES]]
Help options
-h, --help
These options display help for nvram-backup.exe.

-V, --version
These options display the version number for nvrambackup.exe.

-u, --usage
These options display a brief usage summary for nvrambackup.exe.

-l, --list
These options list files either on a modules NVRAM or on

a smart card. By default nvram-backuplists the contents of
the modules NVRAM.
267
nvram-backup
-c, --copy
These options copy files between a modules NVRAM and a

smart card.
You cannot copy from a modules NVRAM to a smart card
those files whose ACL prohibits copying. Copying is
prevented by use of the --no-copy option in the nvram-sw
utility described in nvram-sw on page 272.
-d, --delete
These options delete files from a modules NVRAM. You

cannot use nvram-backup to delete files from a smart card. If
you attempt to use nvram-backup to delete files from a smart
card, a message displays and nvram-backup terminates..
Transfer direction options

-M, --from-module
These options read files from a modules NVRAM for

copying to a smart card or for listing, or deletes files from the
modules NVRAM.
-S, --from-smartcard
These options reads files from a smart card for copying to a

modules NVRAM or for listing.
Module selection options

-m, --module=MODULE
These options specify the module for nvram-backup to use.

The default is 1.
268
nvram-backup
-s, --slot=SLOT
These options identify the slot on the selected module for the
specified nvram-backup action. The default is 0. You do not
need to specify a slot when listing the contents of, or deleting
files from, a modules NVRAM.
File selection option

FILES
This specifies the files for nvram-backup to copy, list or
delete. If you do not specify a file, nvram-backup performs
the action on all available files. Wildcards are permitted in
the file selection option, for example b* to select all
NVRAM-stored keys. For information on identifying file
types by their FileIDs, see nvram-sw on page 272.
General options
-f, --force
These options force nvram-backup to delete or overwrite a

file without requesting confirmation.
-v, --verbose
These options provide verbose output.

-x, --hex
These options specify that hex notation is used for the file
selection option.
--no-length
When used with the --list option, the --no-length option

specifies that file lengths are not printed.
269
nvram-backup
Output
To list the contents of the default modules NVRAM, use the
command:
C:\nfast\bin\nvram-backup.exe --list
nvram-backup displays file information in the following format:

File ID (hex)
------------725178c71ba5cf959318fc
625178c71ba5cf959318fc
72d2fb7c9d0c58f6424855
62d2fb7c9d0c58f6424855
File ID (ASCII)
---------------
File Length
-----------
In this example, four files are stored in the modules NVRAM, two
NVRAM-stored keys and their associated recovery information. For
information on identifying file types by their File IDs, see nvram-sw
on page 272.
To obtain a listing of the contents of a modules NVRAM with further
information, including file size, use the nvram-sw utility.
To back up NVRAM-stored keys from the default module to a smart
card, use the command:
C:\nfast\bin\nvram-backup.exe --copy --from-module b*
If you have a FIPS 140-2 level 3 compliant security world, you must
provide authorization to back up files stored on NVRAM. nvrambackup prompts you to insert a smart card from this security world for
authorization.
270
1.
nvram-backup
If prompted, insert a smart card from the current security world.

When nvram-backup has obtained authorization, it prompts you
to insert a card into the module and slot you specified for nvrambackup actions.
2.
Insert the smart card to use and press Enter .

nvram-backup copies the specified file(s) and terminates.
You can check the success of the command by listing the contents of
the smart card. Use the command:
C:\nfast\bin\nvram-backup.exe --list --from-smartcard
To delete NVRAM-stored keys from the default module, use the

command:
C:\nfast\bin\nvram-backup.exe --delete *b
If you have a FIPS 140-2 level 3 compliant security world, you must
provide authorization to delete files from the modules NVRAM.
nvram-backup prompts you to insert a smart card from this security
world for authorization.
1.
If prompted, insert a smart card from the current security world.

Deleting files from a modules NVRAM requires authentication
and you are prompted to insert Administrator Cards for NVRAM
authentication.
2.
Insert the required number of cards, each one in turn, into the
authentication slot.
When authentication is complete, for each file that matches the
specified criteria, nvram-backup prompts for confirmation.
3.
Input yes to delete a file or no to retain it in NVRAM.
When all files have been listed for confirmation, nvram-backup

terminates.
271
nvram-sw
nvram-sw
The nvram-sw utility views and modifies NVRAM areas.
Usage
C:\nfast\bin\nvram-sw.exe -a|--alloc [-m|--module=MODULE] [-b|--bytes=BYTES] [-n|-nvram-id=ID] [-k|--key=APPNAME,IDENT][--no-copy]
C:\nfast\bin\nvram-sw.exe -d|--delete [-m|--module=MODULE] [-n|--nvram-id=ID]
C:\nfast\bin\nvram-sw.exe -w|--write [-m|--module=MODULE] [-f|--file=FILE]
C:\nfast\bin\nvram-sw.exe -r|--read [-m|--module=MODULE] [-f|--file=FILE]
C:\nfast\bin\nvram-sw.exe -c|--delete-noadmin [-m|--module=MODULE] [-n|--nvram-id=ID]
C:\nfast\bin\nvram-sw.exe -i|--acl [-m|--module=MODULE] [-n|--nvram-id=ID]
C:\nfast\bin\nvram-sw.exe -l|--list [-m|--module=MODULE]
C:\nfast\bin\nvram-sw.exe -a|--alloc [-m|--module=MODULE] [-b|--bytes=BYTES] [-n|-nvram-id=ID] [-k|--key=APPNAME,IDENT][--no-copy]
Help options
-h, --help
These options display help for nvram-sw.exe.
272
nvram-sw
-V, --version
These options display the version number for nvram-sw.exe.

-u, --usage
These options display a brief usage summary for nvramsw.exe.

-a, --alloc
These options allocate a new NVRAM area on the module

specified in MODULE. An Administrator Card Set must be
inserted to perform this action.
-d, --delete
These options delete the NVRAM area on the module

specified in MODULE. An Administrator Card Set must be
inserted to perform this action.
-w, --write
These options write data to the NVRAM area on the module

specified in MODULE. The data is written from the file
specified in FILE, if present. Otherwise, it is written from
stin. If the ACL of the NVRAM area requires it, an Operator
Card Set must be inserted to perform this action. This action
may not be permitted by the ACL of the NVRAM area.
-r, --read
These options read data from the NVRAM area on the

module specified in MODULE. The data is written to the file
specified in FILE, if present. Otherwise it is written to stdout.
If the ACL of the NVRAM area requires it, an Operator Card
Set must be inserted to perform this action. This action may
not be permitted by the ACL of the NVRAM area.
273
nvram-sw
-c, --delete-noadmin
These options delete the NVRAM area on the module

specified in MODULE when no Administrator Card Set is
required. If the ACL of the NVRAM area requires it, an
Operator Card Set must be inserted to perform this action.
-i, --acl
These options display the ACL of the NVRAM area on the

module specified in MODULE. If the ACL of the NVRAM
area requires it, an Operator Card Set must be inserted to
perform this action.
-l, --list
These options list the entire contents of the NVRAM.
General options
-m, --module=MODULE
These options specify the module to use. The default is 1.

-v, --verbose
These option provides verbose output.

-x, --hex
These option specify that hex notation is used for the ID

value supplied to the --nvram-id option.
Action specific options

-b, --bytes=BYTES
These option specify the number of bytes to allocate for -alloc or to read for --read. The default is 100.
274
nvram-sw
-n, --nvram-id=ID
These option specify the identifier of the NVRAM file for all
actions except --list. The default is test-file
-f, --file=FILE
These option specify the file to be read or written for the -read and --write options. If this option is not specified for
these actions, stdin or stdout is used by default.
-k, --key=APPNAME, IDENT
These option specify a key during the --alloc action. This key
is required for all subsequent --read or --write actions on the
NVRAM area.
--no-copy
This option used with the --alloc option allocates a file with
an ACL that does not allow copying.
Identifying files
Files created by nCipher security world tools often have a FileID that
consists of a character identifying the type followed by a
M_ShortHash. You can use this information to identify the type of
files stored in NVRAM and for specifying types of files for use with
an nCipher security world utility.
275
nvram-sw
nCipher uses following identifying characters:

File type
Description
0x1
Counter for a MSCAPI key-exchange

key NVRAM-counted use limit. The
hash is of the MSCAPI container.
0x2
Counter for a MSCAPI signature key

NVRAM-counted use limit. The hash is
of the MSCAPI container.
0x53 (S)
Old PKCS #11 token identifier. If you

have such tokens present, contact
Support at nCipher.
0x62 (b)
Working blob for a NVRAM-stored key.
0x72 (r)
Recovery blob for a NVRAM-stored key.
0x74 (t)
Logical token identifier. The hash of a

logical token stored in a share on this
smart card. The contents include the
remaining 10 bytes of the full hash and
other information about the token.
0x80 (z)
Old PKCS #11 token identifier. If you

have such tokens present, contact
Support at nCipher.
nCipher may define further file types in future, but the first byte is
always in the range 0-127 (top bit clear). nCipher recommends that
third party developers use FileIDs with a first byte in the range 128255 (top bit set).
nCipher also uses the following specific FileIDs:
276
nvram-sw
FileID (hex)
FileID (ascii)
Description
5761726e 74496448 6c7475
WarntIdHltu
Smart card file

created by the
nCipher Warranting
server. Contains the
hash of LTID.
5761726e 74496442 6c6f62
WarntIdBlob
Smart card file

created by the
nCipher Warranting
server. Contains a
blob of KID under
LTID.
74657374 2d66696c 650000
test-file
NVRAM file. This is

the default FileID for
nvram-sw.
277
payshield-config
payshield-config
The payshield-config utility modifies the payShield installations
settings. The utility must be run immediately after running payshieldinstall or payshield-install - -retarget to complete the setup or
retargeting of the payShield installation.
This utility can be used to enable the AcquirePIN Clear PIN
functionality. It uses its own key role which is incompatible with other
payShield PIN functions (KeyRole_AWK). Use of this function is not
recommended as best practice. You should only enable the
AcquirePIN function if the payShield installation will be running in a
physically secure location with trusted operators and network at all
times.
Any PIN entered via the AcquirePIN function cannot be considered to
be secured by the module. Using the same PIN and PAN combination
for both AcquirePIN and PVV/Offset PIN operations may therefore
negate the security of PVV/Offset.
This utility can also be used to enable IBM PIN functions and
unattended key import and export. Enabling these functions may
reduce the security of the system and is not recommended. If any of
these functions are needed, the proper restrictions should be applied.
If you are not sure whether you need these functions, or do not know
what the proper restrictions are, please contact nCipher Support.
Usage
payshield-config.exe [-h|- -help][-v|- -version][-u|- -usage] [{-m|--module}=MODULE]
[{-s|- -slot}=SLOT] [{-c|--configfile}=FILENAME] [{-d|--dump-config}=FILE] [-helpfeatures]PSINAME FEATURES
-m, --module=MODULE
278
payshield-config
-s, --slot=SLOT
These options identify the slot to use. The default is 0.

-c, --configfile=FILENAME
These options specify the configuration file to insert into the

PUD. If the option is not used, then a default configuration
is written to the PUD, unless one is already present.
-d, --dump-config=FILENAME
These options dump the configuration file that is stored in

the PUD.
--help-features
This option describes the syntax for non-interactive feature

selection, including a list of features that can be specified in
the comma-separated list FEATURES.
Altering the Installation Settings

The following settings can be changed using the payshield-config
utility:
which payments functions are enabled or disabled
acceptable PINBlock formats for PIN operations
acceptable import and export formats for key roles.
279
payshield-info
payshield-info
The payshield-info utility displays information about a specified
payShield installation.
Usage
payshield-info.exe [-i|--info][-k|--keys][-n|--name]=keynamePSINAME
General options
-V, --verbose
These options display verbose key details, where applicable.

-s, --sort=KEY
These options select the output sort mode for the --keys and
--roles modes.
Operation mode options

-i, --info
These options display basic information about the PSI.

-k, --keys
These options display keys for the named PSI.

-f, --features
These options display the features enabled in the PUD.

-c, --config
These options dumpt the configuration files stored in the

PUD.
280
payshield-info
-n, --name=keyname
These options display detailed information about the named

key.
-r, --role=keyrole
These options display all the keys in the payShield

installation named PSINAME that have the role specified in
keyrole (for example, PVKP). To view keys for which role
information is unavailable, use --role=unknown.
Keywords
PSINAME
The name of the payShield installation to provide
information about.
Output
The following information is displayed:
The name of the payShield installation
The version of the SEE machine in use
The K and N values of the Master Card Set
The K and N values of the Key Establishment Card Set
The hash of the Master key
The hash of the Key Establishment Key
The maximum possible number of loaded keys
The flags that are set on the payShield installation
281
payshield-info
For example:
PSI Name: qapsi
EMVSM version: 1.0.6+ 2003-01-13 16:55:51. jgeater
Master Key Hash: d42e1791a4e5ea5021444e521bb2c650093efd4d
Estab Key Hash: a06fe51b52725b344dade13a59466bdb77400c1f
Max Keys: 1000
Flags (0x3e0000): TotallyInsecure InsecureImport InsecureDebug
SmartcardImport UnrestrictedImport
Cardsets:
allocated 0053BCD8
Estab CardSet: 1/1 (aaa002b568604e5bbc3a63dcdb0209cd478f317b)
Master CardSet: 1/1 (b9a595b21446ca82dee93a482d60848ec0f1b5dd)
282
payshield-install
payshield-install
The payshield-install utility is used to configure a security world
specifically for the requirements of your payShield installation.
Usage
payshield-install.exe [--master-quorum=K/N --estab-quorum=K/N[{-m|--module}=MODULE] [{s|- -slot}=SLOT] [{-A|- -adminslot}=ADMIN_SLOT] [{-L|--max-loaded-keys}=NUM] [--nonfips-temporarykeys] [--totally-insecure] [--override-keyhash-check] [-D|- -allowinsecure-debug] [-S|--allow-smartcard-import] [-I|- -allow-insecure-import] [-U|- allow-unrestricted-import] [--require-estab-always] [--retarget-see-machine] [-acquirepin-wait=INT] PSINAME KEYHASH
Security options
--master-quorum=K/N
This option specifies the K-of-N sharing parameters for the

Master card set. The default is 3 of 5 (3/5).
--estab-quorum=K/N
This option specifies the K-of-N sharing parameters for the

Key Establishment card set. The default is 2 of 4 (2/4).
-m, --module=MODULE

-s, --slot=SLOT
These options specify the slot to use. The default is 0.

-A, --adminslot=SLOT
These options specify the slot to use for loading FIPS and
FTO authorizations. The default is 0.
283
payshield-install
-L, --max-loaded-keys=NUM
These options specify the maximum number of keys the SEE

machine is allowed to load (default=1000).
--non-fips-temporarykeys
This options prohibits the passing of temporary keys through

the hardware security modules firmware.
--totally-insecure
This option allows you to set the --allow-insecure-debug and

--allow-insecure-imports options, which make the installation
totally insecure.
--override-keyhash-check
This option overrides the key hash check against known

payShield SEE machine signing key hashes.
-D, --allow-insecure-debug
These options allow the generation of insecure debug. They

require you to have also set the --totally-insecure option.
-S, --allow-smartcard-imports
These options allow the import of keys from smart cards.

-L, --allow-insecure-imports
These options allow the importing of keys non-interactively.

They require you to have also set the --totally-insecure
option.
-L, --allow-insecure-imports
These options allow the importing of keys non-interactively.

They require you to have also set the --totally-insecure
option.
284
payshield-install
When these options are set, you can use the

payShield/Verifone key import method to import nonpayShield keys into your security world. These keys are
described as unrestricted because they are imported as
module protected and their encrypt/decrypt ACL
permissions are not restricted by a certifier or SEE world.
-U, --allow-unrestricted-imports
These options allow the importing of keys with ACLs that

allow unrestricted use.
--require-estab-always
This option requires establishment cards to be presented for

unrestricted key imports.
This is not a security feature.
--acquirepin-wait=INT
This option forces at least INT centiseconds of elapsed time

between AcquirePIN operations. The default is 0 (that is, no
rate limiting).
The delay rate for AcquirePIN is enforced separately for each
module. If you have two nShield modules, then two
AcquirePIN operations are allowed in the specified time
period.
Keywords
PSINAME
This is the payShield installation name, which must be of 16

or fewer lowercase alphanumeric characters.
KEYHASH
This is the hash of the nCipher SPP SEE machine signing

key.
285
postrocs
postrocs
The postrocs utility performs clean-up tasks after key-xfer-im has been
used to transfer keys that protect PKCS #11 objects.
Usage
C:\nfast\bin\postrocs [-m|--module=MODULE] [-s|--slot=SLOT]
Help options
-h, --help
These options display help for postrocs.exe.

-V, --version
These options display the version number for postrocs.exe.

-u, --usage
These options display a brief usage summary for

postrocs.exe.
Options
-m, --module=MODULE
These options specify the target module for the key transfer.
The default is 1.
-s, --slot=SLOT
These options specify the target slot for the key transfer. The
default is 0.
286
ppmk
ppmk
This utility allows you to manage softcards. It can be used to perform
the following tasks:
listing softcards
creating a new softcard
checking or changing a softcards pass phrase
recovering a softcards pass phrase
deleting a softcard.
Usage
C:\nfast\bin\ppmk.exe --new [-r|-R] NAME
C:\nfast\bin\ppmk.exe -l
C:\nfast\bin\ppmk.exe -icCpr|--delete [PRELOAD-OPTIONS] NAME|IDENT
NAME
This option specifies the name of a new or existing softcard.

IDENT
This option specifies the identifier of an existing softcard

-n, --new
These options create a new softcard. When creating a new

softcard with these options, the -r/--recover options make the
pass phrase of the new softcard recoverable, while the -R/-non-recoverable options make it unrecoverable.
-l, --list
These options list all softcards in the current security world.
287
ppmk
-i, --info NAME|IDENT
These options show the details of the softcard specified by

NAME or IDENT.
-c, --check NAME|IDENT
These options check the pass phrase of the softcard specified

by NAME or IDENT.
-C, --change NAME|IDENT
These options change the pass phrase of the softcard

specified by NAME or IDENT.
-p, --preload [PRELOAD-OPTIONS]
This option preloads a softcard. PRELOAD-OPTIONS are as

follows:
-m, --module=MODULE preloads a softcard on the
specified module number. The default value for

MODULE is all.
-f, --preload-file=FILE specifies the location of an
alternative loaded objects file.

-r, --recover
These options allow you to recover the pass phrase of a

softcard (if it was created with a recoverable pass phrase).
--recoverable
This options specifies that the pass phrase of a new softcard

is to be recoverable; this is the default, so it is not normally
necessary to specify this option in order to create a softcard
with a recoverable pass phrase. The pass phrase recovery key
Krp be loaded in order to create a softcard with a recoverable
pass phrase.
288
ppmk
-R, --non-recoverable
These options specify that the pass phrase of a new softcard

is to be non-recoverable.
--delete NAME|IDENT
This option deletes the softcard specified by NAME or

IDENT.
289
preload
preload
The preload command-line utility enables keys to be loaded onto a
module before an application is run. The application can be run
immediately in the same session or the first session can be paused and
the application can be run in a separate session. Additional keys can
be loaded while a session is running.
For applications that do not support K-of-N Operator Card Sets,
preload enables K-of-N Operator Card Sets and module-protected
keys to be loaded before the application is run. You can use the
preload command to preload K-of-N Operator Card Sets before
running PKCS #11 applications.

Some command-line options may cause preload to function
interactively by prompting for Operator Cards.
Note
Currently, preload can be used only with command-line utilities.
Usage
C:\nfast\bin\preload.exe [-m MODULE|--module=MODULE] [-c IDENT|--cardset=IDENT] [-cardset-name=NAME] [-s IDENT|--softcard=IDENT] [-o|--any-one] [-i|--interactive] [-A
APP|--appname=APP] [-K PATTERN|--key-ident=PATTERN] [-n PATTERN| --name-pattern=PATTERN]
[--name-exact=NAME] [-M|--module-prot] [--no-cardset-keys] [--admin=NAME] [-F|--requirefips] [-N|--no-fips] [-f PRELOADFILE|--preload-file=PRELOADFILE] [-R|--reloadeverything] | pause | exit
Module selection options

-m MODULE, --module=MODULE
These options select the module (where MODULE is a

module number) onto which keys are to be loaded.
Repeating the option with different values for MODULE
enables a number of selected modules to be used. By default,
preload loads keys on all usable modules.
290
preload
Card set selection options

Note
The current release of the preload command-line utility cannot load

softcards; use the ppmk command-line utility to load softcards (see
ppmk on page 287). However, the preload command can load
softcard-protected keys; see Key selection options on page 292.
-c IDENT, --cardset=IDENT
These options specify that all Operator Card Sets that match
IDENT are to be loaded. The IDENT variable can be the hash
or the name of a card set; the preload command tries to guess
whether IDENT is a hash or a name based on the form you
supply.
If you definitely want to preload a named card set, use the
--cardset-name=NAME option instead.
Use KeySafe or the nfkminfo command-line utility to
identify keys and cards that are used by particular
applications. For further information, see the appropriate
Operator Guide for your module. Card set patterns or names
are treated as substrings.
--cardset-name=NAME
This option specify an Operator Card Set with the given

name NAME to be loaded.
-o, --any-one
This option loads a single Operator Card Set and then stops.
-i, --interactive
This option causes preload to load Operator Card Sets

interactively until you tell it to stop.
291
preload
Key selection options

Note
If you specify keys and do not explicitly select Operator Card Sets with
--cardset, or use --module-prot, then preload loads only the Operator
Card Sets that are required by the specified keys. By default, if no key
selection options are used, preload loads all keys on the loaded
Operator Card Set(s) and, if --module-prot is specified, all moduleprotected keys.
-A APP, --appname=APP
These options specify the application to be used by a

subsequent --key-ident or --name-exact options. You can set
multiple instances of the --appname option to specify more
than one application. Examples of APPNAME include:
custom
embed
hwcrhk
netscape
simple
ssleay
-K PATTERN, --key-ident=PATTERN
These options load all keys whose ident includes or matches

PATTERN for the application previously specified by APP.
PATTERN is treated as a substring. You can set multiple
instances of these options to load keys that match more than
one pattern.
-K, --key-ident=PATTERN
These options load all keys with an ident that includes or

matches PATTERN for the application previously specified
by APP. You can set multiple instances of the --key-ident
option to load more than one key. Use KeySafe or the
292
preload
nfkminfo command-line utility in order to identify keys that
are used by particular applications. For further information,

see the appropriate Operator Guide for your module.
-n PATTERN, --name-pattern=PATTERN
These options load all keys (for the APP specified by

--appname) whose name includes or matches PATTERN.
PATTERN is treated as a substring. You can set multiple
instances of these options to load keys that match more than
one pattern.
If you want to load a particular named key, use the
--name-exact=NAME option instead.
--name-exact=NAME
This option loads the key whose name is specified by NAME

for the APP specified by --appname.
-s IDENT, --softcard=IDENT
These options load all keys protected by softcards matching

IDENT. The IDENT variable can be the hash or the name of
a softcard; the preload command tries to guess whether
IDENT is a hash or a name based on the form you supply.
Note
The current release of the preload command-line utility can only load
softcard-protected keys, not softcards themselves. To load softcards,
use the ppmk command-line utility; see ppmk on page 287.
If you definitely want to preload a named softcard, use the
--softcard-name=NAME option instead.
Use the ppmk or nfkminfo command-line utilities to identify

keys and softcards that are used by particular applications.
For further information, see the appropriate Operator Guide
for your module. Softcard patterns or names are treated as
substrings.
293
preload
--softcard-name=NAME
This option loads all keys protected by softcards matching

NAME.
Note
The current release of the preload command-line utility can only load
softcard-protected keys, not softcards themselves. To load softcards,
use the ppmk command-line utility; see ppmk on page 287.
Use the ppmk or nfkminfo command-line utilities to identify
keys and softcards that are used by particular applications.
For further information, see the appropriate Operator Guide
for your module. Softcard patterns or names are treated as
substrings.
-M, --module-prot
These options load module-protected keys in addition to any

keys specified by other options.
--no-cardset-keys
This option specifies that keys protected by the requested

Operator Card Sets are not automatically loaded.
--admin=KEYS
This option loads the administrator keys specified by KEYS;

to load more than one administrator key, the value of KEYS
can be a comma-separated list, or you can. specify all to load
all administrator keys. Allow administrator keys are: NSO,
M, RA, P, NV, RTC, FIPS, MC, RE, DSEE, and FTO.
Note
When using preload to load non-persistent tokens, you must ensure

that you have enough remaining Operator Cards in order to load the
token onto the final module. Usually, this means you need one or more
cards than you have modules, depending on the circumstances. For
example, if you have 4 modules and K is 3, then N must be at least 6
so that there are at least 3 cards remaining to load the token onto the
final module.
294
preload
FIPS options
-F, --require-fips
These options specify that FIPS authorization is required.

-N, --no-fips
These options specify that FIPS authorization must never be

loaded. The default is to load FIPS authorization if possible
but not to fail if loading FIPS authorization is not possible.
Loading options
-f PRELOADFILE, --preload-file=PRELOADFILE
These options specify a preloaded objects file to be used.

-R, --reload-everything
These options specify the reloading of keys and tokens that

are already loaded.
Output examples
If you want to load keys from a number of Operator Card Sets in
module 2 and use them immediately in an application, for example,
with nfkminfo, give the following command:
C:\nfast\bin\preload -R -m 2 nfkminfo
If there is no card in the specified module, preload displays the

following message:
Loading cardset(s):
Module 2 slot 0: empty
Insert/change card(s) (or change module mode).
295
preload
Insert a card in the smart card reader, and preload displays:

Loading cardset(s):
Module 2 slot 0: 'pt2' #1
Module 2 slot 0: Enter passphrase:
Enter the appropriate pass phrase, and preload displays:

Loading cardset(s):
Module 2 slot 0:- passphrase supplied - reading card
Module #2 Slot #0: Remove card.
If you insert a card that has no pass phrase, preload displays:

Loading cardset(s):
Module 2 slot 0: 'ct' #1
Module 2 slot 0: Read this card? (press Return)
296
preload
Press Enter to confirm reading this card, and preload displays:

Loading cardset(s):
Module 2 slot 0: 'ct' #1
Module 2 slot 0:- confirmed - reading card
Being finished, now press Ctrl - D , and preload displays:

Loading cardset(s):
Loaded seeconf testconf key (DES3) on modules 2
Loaded seeinteg testinteg key (RSAPrivate) on modules 2
Loaded simple cs key (DES3) on modules 2
Loaded simple test12 key (RSAPrivate) on modules 2
Executing nfkminfo
To preload a specific key with an ident of mykey for the application

seeconf on all modules, give the following command:
C:\nfast\bin\preload -A seeconf -K mykey pause
297
preload
The preload command then displays the following message:

Loading 'pt2':
Insert/change card(s) (or change module mode).
Insert a card in module 1, and preload displays:

Loading `pt2':
Module 1 slot 0: `pt2' #1

Loading 'pt2':
Module 1: completed.
Remove the card, and preload displays:

Loading 'pt2':
Module #1 Slot #0: Insert appropriate card.
298
preload
Inset the appropriate card in module 2, and preload displays:

Loading 'pt2':
Module #1 Slot #0: Insert appropriate card.
Press the TAB key to switch messages, and preload displays:

Loading 'pt2':

Loading 'pt2':
Card reading complete.
Loaded seeconf testconf key (DES3) on modules 1, 2
Loading complete; now pausing
299
preload
You can use the preloaded keys and tokens when running commands
in a separate command window. For example, to load keys for
generatekey that were preloaded in the preceding example, open
second command window and give the command:
C:\nfast\bin\preload generatekey hwcrhk
In such an example, the preloaded keys and cards remain loaded at

least until the open preload -A seeconf -K mykey pause command is
terminated in the first window.
300
racs
racs
The racs utility creates a new Administrator Card Set to replace a set
that was created with the new-world utility.See Replacing an
Administrator Card Set with racs on page 225.
Usage
racs [-m|--module=MODULE]
Options
-m, --module=MODULE
These options specifies the ModuleID to use.
301
rfs-setup
rfs-setup
This utility creates a default remote file system on the client. You run
rfs-setup when you first configure a client. See Setting up client
cooperation on page 53 for details of client configuration.
Usage
C:\nfast\bin\rfs-setup.exe
[-c|--configfile=FILENAME] [-f|--force]
<ADDRESS> module_ESN keyhash
--gang-client module_ip_address module_ESN keyhash
--gang-client --write-noauth module_IP_address
Options
-c, --configfile=FILENAME
These options specify a configuration file named

FILENAME to use.
-f, --force
These options specify that any existing remote file system is

to be overwritten.
--gang-client
This option configures the remote file system to accept

connections from a cooperating client. For this option,
module_IP_address is the IP address of the cooperating client
while module_ESN and keyhash are respectively the
electronic serial number (ESN) and key hash for the local
module.You must supply values for module_ESN and keyhash
when using the --gang-client option unless you also pass the
--write-no-auth option.
302
rfs-setup
--write-noauth
This option allows cooperating clients to access the remote

file system without HKNETI authorization. You do not need
to supply module_ESN or keyhash with this option.
nCipher does not recommend using the --write-noauth option except
on completely secure networks.
module_IP_address
This option specifies the IP address of the module.

module_ESN
This option specifies the ESN of the module.

keyhash
This option specifies the HKNETI (key hash) of the module.

You can obtain the ESN and HKNETI of the module from the modules
front panel. You can also obtain it with the anonkneti utility. See
anonkneti on page 227 for details.
303
rfs-sync
rfs-sync
This utility synchronises the kmdata between a cooperating client and
the remote file system it is configured to access. It should be run when
a cooperating client is initialised in order to retrieve data from the
remote file system and also whenever a client needs to update its local
copy of the data or, if the client has write access, to commit changes
to the data. See Chapter 3: Getting the module working for more
details about client cooperation.
Usage
C:\nfast\bin\rfs-sync.exe [-U|--update] [-c|--commit] [-s|--show] [--remove] [--setup
[setup_options] ip_address]
Options
-U, --update
These options update local key-management data from the

remote file system.
Note
If a cooperating client has keys in its kmdata/local directory that are

also on the remote file system, if these keys are deleted from the remote
file system and then rfs-sync --update is run on the client, these keys
remain on the client they are until manually removed.
-c, --commit
These options commit local key-management data changes

to the remote file system.
-s, --show
These options display the current synchronisation

configuration.
304
rfs-sync
--setup
This option sets up a new synchronisation configuration.

Specifics of the configuration can be altered using
setup_options as follows:
-a, --authenticate
These set-up options specify use of KNETI

authentication. This is the default.
--no-authenticate
This set-up option specifies that KNETI

authentication should not be used.
-m, --module=module
These options select which module to use for

KNETI authorisation. The default is module 1. This
option can only be used with with the --authenticate
option.
-p, --port=port
These options specify the port on which to connect

to the remote file system. The default is 9004.
ip_address
This option specifies the IP address of the remote

file system.
--remove
This option removes the synchronisation configuration.

The rfs-sync command also has additional administrative options for
examining and removing lock files that have been left behind by failed
rfs-sync --commit operations. Using the --who-has-lock option displays
305
rfs-sync
the task ID of the lock owner. As a last resort, you can use the rfs-sync
command-line utility to remove lock files. In such a case, the --killlock option forcibly removes the lock file.
306
rtc
rtc
The rtc utility reads the time from a modules onboard real-time
clock. It can also be used to set the clock.
Usage:
rtc [[-g|--get-clock]|[-t|--set-clock [-a|--no-admin-keys] [-A|--adjust]]] [-m|-module=MODULE] TIME

-g, --get-clock
These options tell rtc to read the modules clock time. This
is the default if no action option is specified.
-t, --set-clock
These options tell rtc to read the modules s clock time to

TIME.
Clock setting options

-a, --no-admin-keys
These options tell rtc not to read Administrator cards.

--adjust
This option tells rtc to calibrate the clock drift.
Module selection option

-m, --module=MODULE
These options tell rtc to read or write the clock of the module
MODULE. If MODULE is not specified, the default is 1.
307
rtc
Reading the clock

Use the command:
rtc [-g|--get-clock] [-m|--module=MODULE]
In this command:
--get-clock if used explicitly tells rtc to set the clock.
--module=MODULE tells rtc to set the clock and adjust the drift
rate.
rtc returns a message similar to this:
time on module 1 is 2001-03-21 12:33:12
Note
The rechargeable back-up battery in some nShield modules (used to

maintain RTC operation when the module is unpowered) can last as
long as two weeks without recharging. If the module is without power
for longer than this, the battery is discharged and RTC time is lost; no
other nonvolatile data is lost if this occurs. In such a case, however,
attempts to read the clock (such as with ncdate or rtc) return a
BadTokenData error status. You can resolve this by resetting the clock
and leave the module powered up for at least 10 hours to recharge the
battery to recharge.
Setting the clock

Use the command:
rtc [[-t|--set-clock]|[-A|--adjust]] [-a|--no-admin-keys] [-m|--module=MODULE] [TIME]
In this command:
--set-clock tells rtc to set the clock.
--adjust tells rtc to set the clock and adjust the drift rate.
308
rtc
--no-admin-keys tells rtc not to read the Administrator Card Set.
--module=MODULE specifies the ModuleID to use.
TIME is the time to which to set the clock in the form YYYY-MMDD/HH:MM:SS, where -, /, and : are arbitrary delimiter
characters that can be any non-numeric character.
Unless you give the --no-admin-keys option, rtc prompts you for the
number of cards required from the Administrator Card Set to enable
it to set the real-time clock.
If you do not specify a time, rtc uses the time from the host computer's
clock.
If you specify a time, rtc asks you to confirm the operation. This
feature enables you to check that you have entered the time correctly.
309
slotinfo
slotinfo
The slotinfo utility returns information about the tokens that are
present in a module. slotinfo can also be used to format a token.
Usage
C:\nfast\bin\slotinfo -m|--module=MODULE [-s|--slot=SLOT]
Module selection
-m, --module=MODULE
These options specify the module number of the module to

be used. You must specify a module number.
-s, --slot=SLOT
These options specify the number of the slot to be used. If

this option is set, slotinfo returns information about the files
on the token. If, however, you do not specify --slot, slotinfo
returns information about all slots.
--format
This option tells slotinfo to format the token that is currently

in the slot. You must specify a slot number if you want to
format a token. The token is formatted without a challenge
response key.
Note
Use of the --format option is deprecated. If you use slotinfo with the
--format option to format a token, it does not remove the card from the
security world lists and cannot erase cards in FIPS 140-2 level 3
compliant security worlds.
slotinfo does not update the security world host data. If you are using
an nCipher security world:
310
Use createocs to format Operator Cards
Use KeySafe or createocs to erase cards.
slotinfo
Output
slotinfo --module=1 returns information in the format:
Slot Type Token IC Flags Details
#0 Smartcard present 1 A
#1 Software Tkn - 0
In this output:
Type Unconnected means that the slot is a remote slot for this
module, but the hardserver has failed to import it. The reason for
the failure is given in the Details field.
An A in the Flags field means that the token supports token

authentication in a call to format token.
An R in the Flags. field means that the slot is a remote slot.
slotinfo --module=1 --slot=0 returns information in the format:

Module # slot #:
Authentication key: 00000000-00000000-00000000-00000000-00000000
No data on token
3698 bytes free
slotinfo --module=1 --slot=0 --format returns:

Formatting token in module 1 slot 0:
Formatted token OK
311
sppupgradekeys
sppupgradekeys
The sppupgradekeys utility upgrades keys created on older payShield
installations so that they can be used with newer payShield
installations. You can use the optional EXPORTFILE to specify (by
name) those keys that are to be allowed to be exported in attended
operations.
Note
This utility requires a quorum of administrator cards and must only

run on a secure host.
Usage
sppupgradekeys [options] psiname [EXPORTFILE]
Options
-m, --module=MODULE
These options specify the number of the module to be used.

The default is 1.
-s, --slot=SLOT
These options specify the number of the slot to be used. The

default is 0.
--no-name-keys
This option prevents the names of keys being bound to their

ACL. If you have already run sppupgradekeys, this will make
the operation faster.
312
sppupgradekeys
Key worlds
psiname
This is the name of the payShield installation that you are
going to import the key into. psiname must consist of 16, or
fewer, lower case alphanumeric characters.
EXPORTFILE
This is a file containing lines of the form:
NAME
Each line specifies, by name, a keys that can be exported.
313
stattree
stattree
The stattree utility returns the statistics gathered by the nCipher server
and modules.
Usage
C:\nfast\bin\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 module.
Statistics are displayed in the form of a tree. At each node in the tree,
either a set of statistics or a list of sub-categories is displayed. Each
node has a label which consists of one of the following:
a tag that identifies its contents as described in Node tags on page

316.
a number the corresponds to an instance in the category, for

example, a module identifier or a client connection identifier
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.
314
stattree
A typical fragment of output from stattree looks like this:

+PerModule:
+#1:
+ModuleObjStats:
-ObjectCount 4
-ObjectsCreated 4
-ObjectsDestroyed 0
+ModuleEnvStats:
-MemTotal 14389248
-MemAllocKernel 86016
-MemAllocUser 0
-CurrentTempC 39.50
-MaxTempC 39.50
-MinTempC 39.50
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 module number 3:
$ stattree PerModule 3 ModuleObjStats
+#PerModule:
+#3:
+#ModuleObjStats:
-ObjectCount
6
-ObjectsCreated
334
-ObjectsDestroyed
328
315
stattree
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 module:
Category
Contains
ModuleJobStats
This tag holds statistics related to the nCipher commands

handled by this module.
ModulePCIStats
This tag is for nCipher PCI and netHSM modules only. It

holds statistics related to the PCI connection between this
card 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 modules.
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
clients statistics appear under node #24 in the stattree
output.
PerModule
Statistics kept by the modules. There is one instance node

for each module, numbered using the standard module
numbering. The statistics provided by each module
depend on the module type and firmware version.
316
stattree
Category
Contains
ModuleJobStats
Statistics for the commands (jobs) processed by a

module. Appears under the PerModule category.
ModulePCIStats
Statistics from the modules PCI host interface. Appears

only on PCI-interfaced modules.
ModuleObjStats
Statistics for the modules 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 modules operating

environment.
Statistics IDs
ID
Value
Uptime
The length of time (in seconds) since a module 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 a module.
Contains the number of commands currently being
processed.
ReplyCount
The total number of replies returned from server to client,

or from module to server.
CmdBytes
The total length of all the command blocks sent for

processing.
ReplyBytes
The total length of all the reply block 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 module that the module does not
understand), or that the data transfer mechanism is faulty.
317
stattree
ID
Value
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 module that the
module 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 a module 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 a module to

become available on the specified client connection.
When a module 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 modules. When a
module accepts a command from a client, QOutstanding
decreases by 1 and this number 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 modules. When a
module accepts a LongJobs command from a client,
QOutstanding decreases by 1 and this number increases
by 1. Commands that are processed purely by the server
are never included in this count.
318
stattree
ID
Value
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 module 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 write data from the host was

rejected by the module. 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
modules interface.
HostWriteBadData
Not currently reported by the module. Attempts to write

bad data to the module are reflected in HostWriteErrors.
HostWriteOverruns
Not currently reported by the module. Write overruns are

reflected in HostWriteErrors.
HostWriteNoMemory
Not currently reported by the module. Write failures due

to lack of memory are reflected in HostWriteErrors.
HostReadCount
The number of times a read operation to the module was

attempted. The module can defer a read if it has no replies
at the time, but expects some to be available later.
Typically the module 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 a module 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 module returned no

data because there were no commands waiting for
completion. In general, this only happens a small number
of times during module startup or reset. It can also
happen if PauseForNotifications is disabled.
HostReadUnderruns
Not currently reported by the module.
319
stattree
ID
Value
HostReadDeferred
The number of times a read operation to the module was

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

operation which has been deferred. This normally
happens only if the clear key is pressed while the module
is executing commands. Otherwise it might indicate a
device driver, interface, or firmware problem.
PFNIssued
The number of PauseForNotifications commands

accepted by the module 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 will not occur.
PFNRejected
The number of PauseForNotifications commands rejected

by the module when received from the hardserver. This
can happen during module 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 module. Normally, this is one
less than the PFNIssued figure, since there is normally
one such command outstanding.
ANIssued
The number of Asynchronous Notification messages

issued by the module to the hardserver. These messages
indicate such things as the clear key being pressed and the
module 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 module.

The fast channel facility is unsupported on current
modules. This number should always be zero.
ChanJobsCompleted
The number of fast channel jobs completed by the

module.The fast channel facility is unsupported on
current modules. This number should always be zero.
320
stattree
ID
Value
CPULoadPercent
The current processing load on the module, represented

as a number between 0 and 100. Because a module
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, modules report 100% CPU load when all RSA
processing capacity is occupied; when performing nonRSA tasks the main CPU or another resource (such as the
random number generator) can be saturated without this
statistic reaching 100%.
HostIRQs
On PCI modules, the total number of interrupts received

from the host. On current modules, 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 zero on current modules.
HostDebugIRQs
On PCI modules, the number of debug interrupts

received. This is used only for driver testing, and should
be zero in any production environment.
HostUnhandledIRQs
On PCI modules, the number of unidentified interrupts

from the host. If this is nonzero, a driver or PCI bus
problem is likely.
HostReadReconnect
On PCI modules, 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 modules
ModuleObjStats node.
ObjectsDestroyed
The number of items in the modules 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
module contains a small number of objects that are
always present.
321
stattree
ID
Value
CurrentTempC
The current temperature (in degrees Celsius) of the

module main circuit board. First-generation modules do
not have a temperature sensor and do not return
temperature statistics.
MaxTempC
The maximum temperature recorded by the modules

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

temperature sensor. This is stored in non-volatile
memory, which is cleared only when the unit is
initialized. First-generation modules 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 module. 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 a module. 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 module; will be zero for non-SEE use.
This includes the size of the SEE Machine image, and the
total heap space available to it. The modules kernel does
not know (and does not report in the statistics) how much
of the user-modes heap is currently free, and how much
is in use.
322
Appendix A: Upgrading module firmware

nCipher module firmware is supplied on your nCipher CD-ROM. The
following sections describe how to load updated firmware onto you
nCipher module.
There are separate instructions for modules that are mounted
internally in your computer and those that are mounted in external
boxes supplied by nCipher.
nCipher modules can be damaged by static discharge. nCipher
recommends that you wear an anti-static wristband or similar device
while handling modules.
Version Security Number

All nCipher firmware includes a Version Security Number (VSN).
This number is increased whenever nCipher improves the security of
the firmware or adds significant new functionality.
For firmware version 2.12.0 and subsequent releases, nCipher
supplies several versions of the module firmware. You can always
upgrade to firmware with an equal or higher VSN than that currently
installed on your module.
You can never load firmware with a lower VSN than the currently
installed firmware.
Ensuring you use firmware with the highest available VSN allows you
to benefit from security improvements and enhanced functionality. It
also prevents future downgrades of the firmware that could potentially
weaken security. However, you may choose to install firmware that
does not have the highest available VSN. For example, if you have a
regulatory requirement to use FIPS-approved firmware, you should
install the latest available FIPS validated firmware which may not
have the highest VSN. Similarly, if you want to install a version with
323
A Upgrading module firmware
enhanced features without committing yourself to the upgrade, you

can do so providing upgrade only to firmware with a VSN equal to
that currently installed on your module.
In general, nCipher recommends using the latest firmware with the
highest available VSN.
To support the use of Feature Enable, the VSN was increased for the
firmware release 2.x.x. If you install this firmware in order to use
optional features, you cannot then reload earlier firmware. For
firmware versions 2.x.x and above, the firmware filenames have
changed to include the model code of your module.

Your nCipher CD-ROM contains several sets of firmware for each
supplied product. These can include:
Note
the latest available FIPS-approved firmware with the base VSN
the latest available FIPS-approved firmware with a higher VSN
the latest available firmware awaiting FIPS approval with the

base VSN
the latest available firmware awaiting FIPS approval with a

higher VSN.
For firmware release 2.12.0 only one version of the FIPS-approved

firmware is supplied.
You should ensure you are using the latest firmware, unless you have
a regulatory requirement to use firmware that has been FIPS
validated. In the latter case, you should ensure that you are using the
latest available FIPS validated firmware. See the release notes for
details of current versions.
324
What must I do?
Firmware files are in the firmware directory on the CD-ROM, under a

directory identified by the firmware version. To display information
about a firmware file on the CD-ROM, enter the following command:
C:\nfast\bin\loadrom --view E:\firmware\ver\filename.nff
In this command, E is the drive letter of your CD-ROM, ver is a

firmware version number and filename is a file name.
See loadrom on page 253 for full details of the loadrom utility.
What must I do?

In order to use the new firmware, you must:
1.
Install the latest server software as described in Chapter 3:

Getting the module working.
2.
Install the latest firmware, as described below.
This appendix assumes that you have installed the nCipher server as
a service. This is the default installation procedure described in
Chapter 3: Getting the module working.
Where commands are described, it is assumed that you have installed
the nCipher software in the default location, C:\nfast\. If you have
chosen to install the nCipher software in another directory, replace
references to this directory with the name of the directory in which
you have chosen to install the software.
This chapter describes how to upgrade module firmware for
nShield/payShield modules only. If you have another module refer to
the corresponding chapter in the appropriate Administrator Guide.
Key data
The firmware upgrade process destroys all persistent data held in a
key management module.
325
If your security system requires that the persistent data held in a

key-management module live beyond the upgrade or initialization of
the key management module, a backup and recovery mechanism must
be implemented.
If you are using an SEE program that stores data in nonvolatile
memory, or NVRAM key storage, use the nvram-backup utility to
backup your data before upgrading and to restore the data after the
upgrade is complete. See nvram-backup on page 266 for further
information on this utility.

The process of installing or updating firmware on a nCipher module
can be broken down into three basic steps:
1.
Ensure the module is in maintenance mode (thus taking it out of

any security world of which it is part).
2.
Install the appropriate firmware.
3.
Initialize the module.
This three-step process is diagrammed in Maintenance mode and

firmware installation on page 327. The methods needed to change a
given module to the maintenance mode and to initialize it after
firmware installation depend on the model of module. Follow the
directions in this appendix that are appropriate to the specific model
of module whose firmware you are upgrading.
326
Figure 6
PCI modules
Maintenance mode and firmware installation
If you are upgrading a module which has SEE program data or

NVRAM-stored keys in its nonvolatile memory, use thenvram-backup
utility to backup your data befores nonvolatile memory
usingnvram-backup. See nvram-backup on page 266 for information
on using this utility.
PCI modules
If you have a PCI module, you can upgrade the firmware without
having to open your computer case, provided that the override switch
is off. (Refer to the installation instructions in the Hardware
Installation Guide for information on accessing the override switch
and switching it off.)
To upgrade the firmware on a PCI module, follow these steps:
1.
Log in to the host Administrator.
2.
Place the mode switch in the maintenance position, as shown in

Figure 7 or , depending on your module type.
327
Figure 7
PCI modules
Status LED
on off
Clear switch
Mode switch
M
O
I
J1 override
J2 unused
Smart card
connector
DC power
3.
Reset the module by pressing the Clear button or by issuing the

nopclearfail command.
4.
Note
Use the enquiry command-line utility to check that the module is

in the pre-maintenance state. (See enquiry on page 229 for
information on using this utility.)
If the PCI module is still in the operational state, it means that the
override switch is on. Refer to the installation instructions in the
Hardware Installation Guide for information on accessing the
override switch and switching it off.
5.
Place the nCipher CD-ROM in the CD-ROM drive and mount it

on your file system.
6.
In order to load the new firmware, use the command:
C:\nfast\bin\loadrom E:\firmware\ver\filename.nff
In this command, E is the drive letter of your CD-ROM, ver is a

firmware version number and filename is a file name.
The firmware files are signed and encrypted: you can load only
the correct version for your module.
7.
Switch the mode switch to the Initialization position.
328
8.
Reset the module by pressing the clear button until the LED
flashes short pulses to indicate that the module is in preinitialization state. Alternatively, issue the nopclearfail command.
9.
Switch the mode switch to the Operational position.
10. Reset the module by pressing the clear button or by issuing the
nopclearfail command.
11. Log in to the host as normal.

After you have installed new firmware and initialized the module, you
can create a new security world with the module or reinitialize the
module into an existing security world.
If you are initializing the module into a new security world, see
Creating a security world on page 129.
If you are reinitializing the module into an existing security world, see
Adding or restoring a module to the security world on page 155.
329
Appendix B: Components on nCipher CD-ROMs

nCipher supplies the hardserver and associated software as bundles of
common components that provide much of the required software for
your installation. In addition to the component bundles, nCipher
provides individual components for use with specific applications and
features supported by certain nCipher modules. This appendix lists
the contents of the component bundles and the additional software
supplied on your nCipher CD-ROM. For information on installing the
supplied software, see Chapter 3: Getting the module working.
You can list installed components, both those installed as part of the
standard bundles and those installed individually, by using the
ncversions command-line utility described in the Operator Guide
appropriate to your module type.

nCipher supplies component bundles containing many of the
necessary components for your installation. Certain standard
component bundles are offered for installation on all standard nCipher
support software CD-ROMs, while additional component bundles are
found on CipherTools and CodeSafe CD-ROMs.
Standard component bundles

You are always offered the following standard component bundles on
all standard nCipher support software CD-ROMs:
Standard component bundles
hwsp Hardware Support (mandatory)
ctls Core Tools (recommended)
javasp Java Support (including KeySafe)
330
B Components on nCipher CD-ROMs
On nCSS User and CipherTools CD-ROMs, you are also offered the
psusr payShield User standard component bundle.
The component bundles consist of various individual components.
The hwsp Hardware Support (mandatory) bundle contains the nCipher
server and kernel device drivers:
hwsp Hardware Support (mandatory) bundle
nfdrv Windows device drivers
nfserv Hardserver process executables and scripts
sdrv nFast Win 2000 driver signatures
cfgall Hardserver config file support
nflog Logging library support
The ctls Core Tools (recommended) bundle contains all the nCipher
command-line utilities, including generatekey, low level utilities, and
test programs:
ctls Core Tools (recommended) bundle
convrt Command line key conversions
nftcl Command line key management (Tcl)
nftcl Command line key generation and import
nfuser Low level utilities and test programs
nfuser Command line remote server management
opensl nftcl certificate generation utility
sworld Command line key management (C)
tclsrc Tcl run time
tclstf Small Tcl utilities
nftcl Command line key generation and import
tct2 Trusted Code Tool 2 command-line utility
pysrc Python source for developers
nfpy nFPython header files
331
nCipher recommends that you always install the ctls Core Tools
bundle.
Note
The Core Tools bundle includes the tclsrc Tcl run times tools for
creating the security world, KeySafe, and new-world. This does not
affect any other installation of Tcl on your computer.
The javasp Java Support (including KeySafe)s Java applications,
including KeySafe:
javasp Java Support (including KeySafe) bundle
jutils Java utilities
jutils JNI shared library for jutils.jar
kmjava Java Key Management classes
ksafe KeySafe 2
nfjava nFast Java generic stub classes
nftcl Java Key Management Support
The psusr payShield User bundle contains the components required if

you want to use payShield secure payments:
psusr payShield User bundle
emvspp payShield command-line tools
emvsms SEE machine for EMV library
emvspj payShield Java interface
emvjni Dynamic shared library for payShield JNI
Additional component bundles

nCipher supplies the following additional component bundles on
CipherTools CD-ROMs:
Additional CipherTools component bundles
ctd CipherTools Developer
jd Java Developer
332
nCipher supplies the following additional component bundles on

CodeSafe CD-ROMs:
Additional CodeSafe component bundles
csd CodeSafe Developer
jd Java Developer
The ctd CipherTools Developer bundle contains components supplied

with the CipherTools Developer Kit:
ctd CipherTools Developer bundle
emvspj JNI library for payShield Java
emvspp payShield developer library
hwcrhk Crypto Hardware Interface (CHIL) dev kit
nflibs nCipher libraries and headers, and example C source for utility functions
nfuser nCore & KM tools and example source
pkcs11 nFast PKCS#11 developers library
sworld Key Management C library developers kit
tclsrc Tcl run time - Headers and Libraries
cutils C utilities library
nflog Logging library
hilibs GS libs & headers
The csd CodeSafe Developer bundle contains components supplied

with the CodeSafe Developer Kit:
csd CodeSafe Developer bundle
csee Codesafe-C moduleside example code
csee Codesafe-C hostside example code
module Firmware test scripts
nflibs Generic stub libraries and headers, and example C source for utility functions
333
csd CodeSafe Developer bundle

nfuser nCore & KM tools and example source
sworld Key Management C library developers kit
tclsrc Tcl run time - Headers and Libraries
cutils C utilities library
nflog Logging library
hilibs GS libs & headers
jhsee Java hostside developer's kit
jhsee Java hostside SEE examples
ssllib Codesafe-SSL hostside code
ssllib Codesafe-SSL moduleside code
nfpy Libs and headers for codesafe/python
The jd Java Developer bundle contains components to support

development of Java applications:
jd Java Developer bundle
jcecsp Java Key Management developer
jutils Java utilities source and javadocs
kmjava Java Key Management developer
nfjava Java Generic Stub examples & javadoc
334
nCSS User CD-ROM
nCSS User CD-ROM

nCipher supplies the following component bundles and additional
components on the nCSS User CD-ROM:
Component Bundles
psusr payShield User
Individual Components
hwcrhk Crypto Hardware Interface (CHIL) plugin
jcecsp nCipherKM JCA/JCE provider classes
mscapi CSP support files
mscapic nCipher Win 2000 domestic strength CSP
ncsnmp nCipher SNMP monitoring agent
pkcs11 nCipher pkcs11 library
CipherTools CD-ROM
components on the CipherTools CD-ROM:
Component Bundles
psusr payShield User
ctd CipherTools Developer
jd Java Developer
335
CodeSafe CD-ROM
sslyp Open SSL source code patch file
CodeSafe CD-ROM
components on the CodeSafe CD-ROM:
Component Bundles
csd CodeSafe Developer
jd Java Developer
gccsrc Prebuilt arm-gcc for Codesafe/C
gccsrc Prebuilt powerpcm-gcc for Codesafe/C
336
Components Required for Particular

Functionality
Components Required for Particular Functionality

Some functionality requires particular component bundles or
individual components to be installed.
nCipher recommends that you ensure that you have installed the hwsp
Hardware Support (mandatory) and ctls Core Tools (recommended)
bundles. If you have a CipherTools CD-ROM, nCipher recommends
that you install the ctd CipherTools Developer bundle. If you have a
CodeSafe CD-ROM, nCipher recommends that you install the csd
CodeSafe Developer bundle.
If you have a CodeSafe CD-ROM and you are developing in C,
if your module has a part code of the form nC4XX2 or Bn1XXX,

install the gccsrc Prebuilt arm-gcc for Codesafe/C component.
if your module has a part code of the form nC4XX3 or Bn2XXX,

install the gccsrc Prebuilt powerpc-gcc for Codesafe/C component.
In these part codes, X represents any integer.

If you have a CipherTools CD-ROM or a CodeSafe CD-ROM and you
are developing in Java, install the jd Java Developer and javasp Java
Support (including KeySafe) bundles; after installation, ensure that you
have added the .jar files to your CLASSPATH.
KeySafe
To use KeySafe, install the ctls Core Tools and the javasp Java Support
(including KeySafe) bundles.
payShield secure payments

If you have an nCipher Support Software (nCSS) CD-ROM or a
CipherTools CD-ROM and you want to use payShield secure
payments, install the psusr payShield User bundle.
337
Windows CSP
If you require the Windows CSP, you must install the CSP
components:

If you want to use the module with PKCS #11 applications, including
release 4.0 or later of Netscape Enterprise Server, iPlanet Enterprise
Edition 4, or Netscape Certificate Server 4, install the pkcs11 nCipher
PKCS11 library. For detailed PKCS #11 configuration options, see the
Operator Guide appropriate to your module type.
Cryptographic Hardware Interface Library

applications
If you want to use the module with the Cryptographic Hardware
Interface Library (CHIL) applications, install the hwcrhk Crypto
Hardware Interface (CHIL) plugin component and, if required, the
NCsslyp OpenSSL source code patch file component.
Note
nCipher supports OpenSSL 0.9.7g and later.
nCipherKM JCA/JCE cryptographic service provider

If you want to use the nCipherKM JCA/JCE cryptographic service
provider, you must install the javasp Java Support (including KeySafe)
bundle and also the jcecsp nCipherKM JCA/JCE provider classes
component.
Note
In order to use the nCipherKM JCA/JCE cryptographic service

provider, you must also add the nfjava.jar, kmjava.jar, jutils.jar, and
kmcsp.jar files to your CLASSPATH after installation is complete. For
details, see Operator Guide .
338
An additional JCE provider nCipherRSAPrivateEncrypt is supplied

that is required for RSA encryption with a private key. Install this
provider above the standard nCipherKM provider and ensure that the
file rsaprivenc.jar is in your CLASSPATH. nCipher has successfully
tested SSLSocketClientWithClientAuth (JSSE sample code) with
iPlanet 4.1 and 6.0 SP5 with this provider.
For details about configuring these providers, see the Operator Guide.

If you want to use the nCipher SNMP monitoring agent to monitor
your modules, install the ncsnmp nCipher SNMP monitoring agent
component. During the first installation process of the nCipher SNMP
agent, the agent displays the following message:
If this is a first time install, the nCipher SNMP Agent will not run by default. Please
see the manual for further instructions.
For instructions on how to activate the agent after installation, see the
Operator Guide appropriate to your module type.
339
Appendix C: Environment variables

nCipher software uses the following environment variables:
Variable
Description
NFAST_DEBUG
This variable enables debug logging for the hardserver

and the PKCS #11 library. You must set
NFAST_DEBUG equal to a nonzero value in order for
debug messages to be logged (see Logging and
debugging on page 343). For more information, see
also Hardserver debugging on page 350 and Logging
and debugging information for PKCS #11 on page
349.
NFAST_HOME
This variable controls the location of the nCipher

software, which is set by the nCipher installation
script. By default, the nCipher software is located in
C:\nfast\. You only need to change this variable if you
move the nCipher files. See NFAST_KMDATA and
NFAST_KMLOCAL.
NFAST_HWCRHK_LOGFILE
This variable sets the name of the file to which the

CHIL (Cryptographic Hardware Interface Library)
writes its log from applications. This is in addition to
the logging done according to the mechanisms in the
published hwcrhk API, which vary according to the
application in use.
NFAST_KMDATA
This variable sets the location of the kmdata directory.

If this environment variable is not set, the module
looks for the security world data in the local directory
of the kmdata directory, in the nCipher installation
directory. See NFAST_HOME and NFAST_KMDATA.
NFAST_KMLOCAL
This variable sets the location of the key-management

and security world data directory. If this environment
variable is not set, the module looks for the security
world data in the local directory of the kmdata
directory in the nCipher installation directory. See
NFAST_HOME and NFAST_KMDATA.
340
C Environment variables
Variable
Description
NFAST_NFKM_TOKENSFILE
NFAST_NFKM_TOKENSSELECT
This variable sets the default values for a file in which

ClientID and KeyIDs are stored by the preload
command-line utility. Refer to for information on
using this utility.
NFAST_SEE_MACHINEENCKEY_DEFAULT
This variable is the name of the SEEConf key needed

to decrypt SEE-machine images.
NFAST_SEE_MACHINEENCKEY_module
This variable is the name of the SEEConf key needed

to decrypt the SEE-machine image targeted for the
specified module. It overrides
NFAST_SEE_MACHINEENCKEY_DEFAULT for the
specified module.
NFAST_SEE_MACHINEIMAGE_DEFAULT
This variable is the path of the SEE machine image to

load on to any module for which a specific image is
not defined.
NFAST_SEE_MACHINEIMAGE_module
This variable is the path of the SEE machine image to

load on to the specified module. it overrides the use of
NFAST_SEE_MACHINEIMAGE_DEFAULT for the
specified module.
NFAST_SEE_MACHINESIGHASH_DEFAULT
This variable is the default key hash of the vendor

signing key.
NFAST_SEE_MACHINESIGHASH_module
This variable is the key hash of the vendor signing key

for the specified module. It overrides
NFAST_SEE_MACHINESIGHAST_DEFAULT for the
specified module.
341
C Environment variables
Variable
Description
NFAST_SERVER_PORT
NFAST_SERVER_PRIVPORT
If this variable is set in the nFast servers environment,

the values are used to specify the TCP port numbers
that the nFast server uses for connections over TCP
sockets. This variable is available for this purpose for
backward compatibility only: you should configure
ports in the configuration file, as described in
server_remotecomms on page 90. If you set this
variable, it overrides the values in the configuration
file.
If this variable is not set, the nFast server defaults to
using port 9000 and port 9001.
If this variable is set in a C application, the application
connects to the nFast server using TCP sockets rather
than named pipes. The value of the environment
variable determines the port to connect to. It must be
the same value as used by the nFast server.
You need only change these environment variables if
another application is already using the default port
numbers.
NFLOG_CATEGORIES
This variable is used to filter log messages by

supplying a colon-separated list of allowable message
categories; see Logging and debugging on page 343. If
no value is supplied, all message categories are
logged.
NFLOG_SEVERITY

supplying a minimum severity level to be logged; see
Logging and debugging on page 343. If no value is
supplied, the default severity level is WARNING.
NFLOG_DETAIL

supplying a bitmask of detail flags; see Logging and
debugging on page 343. The default is
time+severity+writeable.
NFLOG_FILE
This variable is used to specify a filename (or file

descriptor) in which log messages are to be written;
see Logging and debugging on page 343. The default
is stderr (the equivalent of file descriptor &2).
OPENSSL_HWCRHK_LOG
This variable sets the directory in which the CHIL

(Cryptographic Hardware Interface Library) creates
its log file. This must be a directory for which the user
as which the CHIL-enabled application runs has write
permission.
342
Appendix D: Logging and debugging

Note
The current release of nCipher support software uses controls for

logging and log files, as well as debugging, that differ from those used
in previous releases. However, settings you made in previous releases
to control logging, log files, and debugging are still generally
supported in the current release, although in some situations the
output is now formatted differently.

The nCipher Support Software generates logging information that is
configured through a set of four environment variables:
NFLOG_FILE
This environment variable specifies the name of a file (or a

file descriptor, if prefixed with the & character) to which
logging information is written. The default is stderr (the
equivalent of &2).
NFLOG_SEVERITY
This environment variable specifies a minimum severity

level for logging messages to be written (all log messages
less severe than the specified level are ignored). The level
can be one of (in order of greatest to least severity):
1.
FATAL
2.
SEVERE
3.
ERROR
4.
WARNING
5.
NOTIFICATION
343
D Logging and debugging
6.
DEBUGn (where n can be an integer between 1 and 10
inclusive that specifies different level of debugging

detail, with 10 representing the greatest level of detail).
Note
nCipher recommends not setting the severity level to DEBUGn unless

you are directed to do so by Support at nCipher.
The default severity level is WARNING.

NFLOG_DETAIL
This environment variable takes a hexadecimal value from a

bitmask of detail flags as described in the following table
(the logdetail flags are also used in the hardserver
configuration file to control hardserver logging; see
Hardserver configuration file on page 85):
Hexadecimal
flag
Function
0x00000001
This flag shows the external time (that is, external_time

the time according to your machine's local
clock) with the log entry. It is on by
default.
0x00000002
This flag shows the external date (that is, external_date

the date according to your machine's local
clock) with the log entry.
0x00000004
This flag shows the external process ID

with the log entry.
external_pid
0x00000008
This flag shows the external thread ID

with the log entry.
external_tid
0x00000010
This flag shows the external time_t (that

is, the time in machine clock ticks rather
than local time) with the log entry.
external_time_t
0x00000020
This flag shows the stack backtrace with

the log entry.
stack_backtrace
0x00000040
This flag shows the stack file with the log stack_file
entry.
0x00000080
This flag shows the stack line number

with the log entry.
logdetail flags
stack_line
344
Hexadecimal
flag
Function
logdetail flags
0x00000100
This flag shows the message severity (a

severity level as used by the
NFLOG_SEVERITY environment
variable) with the log entry. It is on by
default.
msg_severity
0x00000200
This flag shows the message category (a

category as used by the
NFLOG_CATEGORY environment
variable) with the log entry.
msg_categories
0x00000400
This flag shows message writeables, extra msg_writeable

information that can be written to the log
entry, if any such exist. It is on by default.
0x00000800
This flag shows the message file in the

original library. This flag is likely to be
most useful in conjunction with nCiphersupplied example code that has been
written to take advantage of this flag.
0x00001000
This flag shows the message line number msg_line

in the original library. This flag is likely to
be most useful in conjunction with
nCipher-supplied example code that has
been written to take advantage of this
flag.
0x00002000
This flag shows the date and time in UTC options_utc

(Coordinated Universal Time) instead of
local time.
msg_file
345
NFLOG_CATEGORIES
This environment variable takes a colon-separated list of

categories on which to filter log messages (categories may
contain the wild-card characters * and ?). If you do not
supply any values, then all categories of messages are
logged. This table lists the available categories:
Category
Description
nflog
This category logs all general messages relating to nflog.
nflog-stack
This category logs messages from StackPush and StackPop

functions.
memory-host
This category logs messages concerning host memory.
memory-module
This category logs messages concerning module memory.
gs-stub
This category logs general generic stub messages. (Setting

this category works like using the dbg_stub flag with the
logging functionality found in previous nCipher support
software releases.)
gs-stubbignum
This category logs bignum printing messages. (Setting this

category works like using the dbg_stubbignum flag with the
software releases.)
gs-stubinit
This category logs generic stub initialization routines.

(Setting this category works like using the dbg_stubinit flag
with the logging functionality found in previous nCipher
support software releases.)
gs-dumpenv
This category logs environment variable dumps. (Setting this

category works like using the dbg_dumpenv flag with the
software releases.)
nfkm-getinfo
This category logs nfkm-getinfo messages.
nfkm-newworld
This category logs messages about world generation.
nfkm-admin
This category logs operations using the Administrator Card

Set.
nfkm-kmdata
This category logs file operations in the kmdata directory.
nfkm-general
This category logs general NFKM library messages.
nfkm-keys
This category logs key loading operations.
346
Category
Description
nfkm-preload
This category logs preload operations.
nfkm-ppmk
This category logs softcard operations.
serv-general
This category logs general messages about the local

hardserver.
serv-client
This category logs messages relating to clients or remote

hardservers.
serv-internal
This category logs severe or fatal internal errors.
serv-startup
This category logs fatal startup errors.
servdbg-stub
This category logs all generic stub debugging messages.
servdbg-env
This category logs generic stub environment variable

messages.
servdbg-underlay
This category logs messages from the OS-specific device

driver interface
servdbg-statemach
This category logs information about the servers internal

state machine.
servdbg-perf
This category logs messages about the server's internal

queueing.
servdbg-client
This category logs external messages generated by the client.
servdbg-messages
This category logs server command dumps.
servdbg-sys
This category logs OS-specific messages.
hwcrhk
This category logs messages from the CHIL (Cryptographic

Hardware Interface Library).
pkcs11-sam
This category logs all security assurance messages from the

PKCS #11 library.
pkcs11
This category logs all other messages from the PKCS #11
library.
rqcard-core
This category logs all card-loading library operations that

involve standard message passing (including slot polling).
rqcard-logic
This category logs all card-loading library messages from

specific logics.
rqcard-logic
This category logs all card-loading library messages from the

current user interface.
347
You can set a minimum level of hardserver logging by supplying one

of the values for the NFLOG_SEVERITY environment variable in the
hardserver configuration file, and you can likewise specify one or
more values for the NFLOG_CATEGORIES environment variable.
See Chapter 6: Configuring the hardserver for more detailed
information about controlling hardserver logging.
Note
If none of the four environment variables are set, the default behavior
is to log nothing, unless this is overridden by any individual library.
If any of the four variables are set, all unset variables are given
default values.

By default, the nCipher CSP for Windows sends log messages to the
event log. In order to send log messages to a file, edit the registry, and
then set the value of the registry key
HKLM\Software\nCipher\Cryptography\LogLevel as follows:
Note
Value
Output
Messages are sent to the event log.
Error messages are sent to the log file.
Function calls and error messages are sent to the log file.
All information, including debugging information, is sent to the

log file.
Do not set this value to 3 unless either you are asked to do so by

Support at nCipher or you are debugging your own code. At this level
of logging, a single SSL connection generates approximately 30
kilobytes of log messages. In addition, sensitive information may
appear in the log file.
The log file is created in the directory C:\nfast\log\ unless you set the
registry key HKLM\Software\nCipher\Cryptography\PathName to the
name of another directory.
348
Logging and debugging information for PKCS

#11
Logging and debugging information for PKCS #11

In order to get PKCS #11 logging and debugging output, you must set
the CKNFAST_DEBUG environment variable equal to 1 and specify
any appropriate pkcs11 categories using the NFLOG_CATEGORIES
environment variable.
This environment variable takes a colon-separated list of categories
on which to filter log messages (categories may contain the wildcards
characters * and ?).
The following table maps PKCS #11 debug level numbers to the
corresponding NFLOG_SEVERITY value
PKCS
#11
debug
level
PKCS #11 debug NFLOG_SEVERITY

meaning
value
Output in log
DL_None
NONE
DL_EFatal
FATAL
"Fatal error:"
DL_EError
ERROR
"Error:"
DL_Fixup
WARNING
"Fixup:"
DL_Warning
WARNING
"Warning:"
DL_EApplic
ERROR
"Application error:"
DL_Assumption
NOTIFICATION
"Unsafe
assumption:"
DL_Call
DEBUG2
">> "
DL_Result
DEBUG3
"< "
DL_Arg
DEBUG4
"> "
10
DL_Detail
DEBUG5
"D "
11
DL_DetailMutex
DEBUG6
"DM "
349
Hardserver debugging is controlled by specifying one or more
servdbg-* categories (from the NFLOG_CATEGORIES environment
variable) in the hardserver configuration file (see Hardserver
configuration file on page 85). However, unless you also set the
NFAST_DEBUG environment variable to a non-zero value, no
debugging is produced (regardless of whether or not you specify
servdbg-* categories in the hardserver configuration file). This
behavior helps guard against the additional load debugging places on
the CPU usage; you can set the desired servdbg-* categories in the
hardserver configuration file, and then enable or disable debugging by
setting the NFAST_DEBUG environment variable.
Note
If the NFAST_DEBUG environment variable is used to control

debugging (instead of simply enabling or disabling it), the logdetail
value in the hardserver configuration file (one of the values for the
NFLOG_LEVEL environment variable) controls the level of detail
printed. Standard debugging messages are printed at level DEBUG2.
Environment variables are at DEBUG3, bignums and other byteblocks
are printed at DEBUG4, and extra verbose debugging is available at
DEBUG5.

PAYSHIELD_DEBUGFILE
The environment variable PAYSHIELD_DEBUGFILE is

used to set the name of the file that can be used by payShield
to record log messages returned from the hostside payShield
library.
PAYSHIELD_DEBUG
The environment variable PAYSHIELD_DEBUG is used to

set the level and destination of log messages returned from
the hostside payShield library.
350
The payShield library can be configured to return log

information from various categories and to either of two
different locations.
The environment variable PAYSHIELD_DEBUG should be
set to an integer which represents the kind of logging
desired.
The integer value used to set PAYSHIELD_DEBUG must be
calculated by ORing the binary values assigned to each log
information category.
Value
payShield log information category
00000000
Log no data at all
00000001
Log errors to the payShield logfile
00000010
Log warnings to the payShield logfile
00000100
Log informational messages to the payShield logfile
00001000
Log debug data to the payShield logfile
00010000
Log errors to the system log
00100000
Log warnings to the system log
01000000
Log informational messages to the system log
10000000
Log debug data to the system log
For example, to log payShield errors to the system log, and

also log payShield warnings and errors to the payShield
logfile specified by PAYSHIELD_DEBUGFILE,
PAYSHIELD_DEBUGFILE must be set to 19.
19 is the integer value of the binary number 00010011,
calculated by ORing 00010000, 00000001 and 00000010
together.
351

This section describes how you can specify the debugging
information generated by Java.
Note
Do not set NFJAVA_DEBUG or NFJAVA_DEBUGFILE in the

environment because Java does not pick up variables from the
environment.
Setting the Java debugging information level

In order to make the Java generic stub output debugging information,
set the Java property NFJAVA_DEBUG. The debugging information
for NFJAVA, NFAST, and other libraries (for example, KMJAVA) can
all use the same log file and have their entries interleaved.
You set the debugging level as a decimal number. To determine this
number:
1.
Select the debugging information that you want from the

following list:
NONE =
0x00000000 (debugging off)
MESS_NOTIFICATIONS = 0x00000001 (occasional messages including important errors)
MESS_VERBOSE =
0x00000002 (all messages)
MESS_RESOURCES =
0x00000004 (resource allocations)
FUNC_TRACE =
0x00000008 (function calls)
FUNC_VERBOSE =
0x00000010 (function calls + arguments)
REPORT_CONTEXT =
0x00000020 (calling context e.g ThreadID and time)
FUNC_TIMINGS =
0x00000040 (function timings)
NFJAVA_DEBUGGING =
0x00000080 (Output NFJAVA debugging info)
2.
Add together the hexadecimal value associated with each type of

debugging information.
For example, to set NFJAVA_DEBUGGING and
MESS_NOTIFICATIONS, add 0x00000080 and 0x00000001 to
make 0x00000081.
352
3.
Convert the total to a decimal and specify this as the value for the
variable.
For example, to set NFJAVA_DEBUGGING and
MESS_NOTIFICATIONS, include the line:
NFJAVA_DEBUG=129
For NFJAVA to produce output, NFJAVA_DEBUG must be set to

at least NFJAVA_DEBUGGING + MESS_NOTIFICATIONS.
Other typical values are:
-
255: All output
130: nfjava debugging and all messages

(NFJAVA_DEBUGGING and MESS_VERBOSE)
20: function calls and arguments and resource allocations

(FUNC_VERBOSE and MESS_RESOURCES)
Setting the Java debugging file

You can set the NFJAVA_DEBUGFILE property to direct output to a
given file name, for example:
java -DNFJAVA_DEBUGFILE=myfile -classpath .... classname
If NFJAVA_DEBUGFILE is not set, the standard error stream

System.err is used.
Note
Set these variables only when developing code or at the request of

Support at nCipher.
Debug output contains all commands and replies sent to the
hardserver in their entirety, including all plain texts and the
corresponding cipher texts as applicable.
353
Appendix E: Installed Utilities

The following utility files are supplied in the bin subdirectory of your
nCipher installation:
Utility
Description
cardpp
This utility adds, changes,

removes, or verifies a pass phrase.
It is described in Changing pass
phrases with cardpp on page 218
and the Operator Guide.
cfg-reread
This utility loads the hardserver

configuration from the
configuration file. It is described
in cfg-reread on page 228.
checkmod
This utility checks modulo

exponentiations. It is described in
the Operator Guide.
ckimportbackend
This utility is internal to nCipher.
ckinfo
This utility is for PKCS #11

developer use. It displays
C_GetInfo, C_GetSlotInfo, and
C_GetTokenInfo results. See the
Developer Reference for details of
all API calls.
cklist
This utility is for PKCS #11

developer use. It lists some details
of objects on all slots. It lists
public and private objects if
invoked with a PIN argument and
public objects only if invoked
with the -n (--nopin) option. It
does not output any potentially
sensitive attributes, even if the
object has CKA_SENSITIVE set to
FALSE.
354
E Installed Utilities
Installed Utilities
Utility
Description
ckmechinfo
This is a PKCS #11 developer

utility. Refer to the relevant
developer documentation.
ckrsagen
This is a PKCS #11 developer

utility. Refer to the relevant
developer documentation.
cksigtest
This utility measures module

signing speed with nCipher PKCS
#11 library calls. It is described in
the Operator Guide.
config
This utility is a Netscape

configuration tool. It is described
in the relevant integration guide.
createocs
This utility creates or erases

Operator Card Sets. It is described
in Creating the Operator Card Set
from the command line on page
71.
cryptest
This utility tests all defined

symmetric cryptographic
mechanisms. It is described in the
Operator Guide.
cspcheck
This utility checks that CSP

container files are intact and
uncorrupted and that referenced
key files exist. It is described in
the Operator Guide.
cspimport
This utility allows you to insert

keys manually into existing CSP
containers. It is described in the
Operator Guide.
cspmigrate
This utility moves CSP container

information for an existing
security world from the registry
into the security world. It is
described in the Operator Guide.
355
Installed Utilities
Utility
Description
cspnvfix
This utility regenerates the

NVRAM key counter area for a
specified nCipher CSP key. It is
csptest
This utility tests installed

Cryptographic Service Providers.
It is described in the Operator
Guide.
csputils
This utility lists and gives detailed

information about CSP
Operator Guide.
des_kat
This utility performs DES knownanswer tests. It is described in the

Operator Guide.
dump_marshalled
This utility can be used to

examine nCipher data formats.
Contact Support at nCipher for
information.
enquiry
This utility returns information

about the nCipher server and
connected modules. It is described
in enquiry on page 229.
floodtest
This utility performs hardware

speed testing. It is described in
floodtest on page 238.
fwcheck
This utility verifies the firmware.

Guide.
genkeyprops
generatekey
This utility generates or imports

keys. It is described in the
Operator Guide.
hardserver
This is the hardserver program. It

is installed as a service and run
automatically. Information on
stopping and restarting it
manually is given in hardserver on
page 242.
356
Installed Utilities
Utility
Description
iisinstallcert
This utility is an IIS configuration

tool. It is described in the relevant
integration guide.
initunit
This utility initializes a module. It

is described in initunit on page
244.
key2pem
keytst
This utility displays information

about existing CSP key
Operator Guide.
key-xfer-im
This utility imports a module key

that has been programmed into a
new security world. It is described
in key-xfer-im on page 250.
killrecov
This utility disables the Replace

Operator Card Set feature for a
security world. Contact Support at
nCipher for information.
kmfile-dump
This utility displays keymanagement information from a

security worlds key-management
data file. It is described in the
Operator Guide.
kptest
This utility tests the consistency

of encryption and decryption, or
of signature and verification, with
the RSA and DSA algorithms. It
is described in the Operator
Guide.
loadkeys
This utility prepares Key Detail

cards and loads keys for
payShield installations. It is
loadrom
This utility loads new firmware

into a module. It is described in
loadrom on page 253.
357
Installed Utilities
Utility
Description
mkaclx
This utility contains example code

for key generation. It is described
in the Operator Guide.
mk-reprogram
This utility programs a module

key that is in one security world to
another security world. It is
described in mk-reprogram on
page 255.
ncdate
This utility sets, updates and

views the time on a modules
realtime clock. It is described in
the Operator Guide.
ncthread-test
This utility stress tests modules

and tests nCore API concurrent
connection support. It is described
in the Operator Guide.
ncversions
This utility displays the versions

of installed nCipher support
software components. It is
described in ncversions on page
257.
new-world
This utility creates a security

world that supports SEE
functions. It is described in
new-world on page 259.
nffwd
nfkminfo

about a security world, cards, and
keys. It is described in the
Operator Guide.
nopclearfail
This utility clears a module, puts a

module into the error state, or
retries a failed module. It is
nvram-backup
This utility copies files between a

module's NVRAM and a smart
card allowing files to be backed
up and restored. It is described in
the Operator Guide.
358
Installed Utilities
Utility
Description
nvram-sw
This utility modifies and displays

information about NVRAM areas.
It is described in nvram-sw on
page 272.
payshield-config
This utility enables the Master

Card Set holders to modify a
payShield installations settings. It
is described in payshield-config
on page 278.
payshield-info

about a payShield installation. It
Guide.
payshield-install
This utility configures a security

world specifically for payShield
modules. It is described in
payshield-install on page 283 in
the Administrator Guide.
pollbare
This example utility returns

information about state changes.
Guide.
postrocs
This utility is required after key

transfer if the previous Operator
Card Set protected PKCS #11
objects. It is described in postrocs
on page 286.
ppmk
This utility is used to manage

softcards. It is described in ppmk
on page 287.
preload
This utility loads keys onto a

module before an application is
run in another session. It is
pubkey-find
This example utility returns

information the key, certificate, or
certificate request in a file. It is
359
Installed Utilities
Utility
Description
racs
This utility creates a new

It is described in Replacing an
Administrator Card Set with racs
on page 225.
randchk
This utility runs a universal

statistical test on random numbers
returned by the module. It is
rdlinene
rfs-sync
This utility copies security world

and key data from a remote file
system to a module. It is used with
modules which are not netHSM or
payShield net modules. It is
described in rfs-sync on page 304.
rtc
This utility reads and sets the

modules real-time clock. It is
sigtest
This utility measures module

speed using RSA or DSA
signatures or signature
verifications. It is described in the
Operator Guide.
slotinfo
This utility returns information

about tokens in a module. It can
also be used to format a token. It
Guide.
sppupgradekeys
This utility upgrades keys created

on older payShield installations. It
is described in sppupgradekeys on
page 312.
stattree
This utility returns statistics

gathered by the nCipher server
and modules. It is described in
stattree on page 314.
360
Appendix F: The nCipher SNMP monitoring agent

Note
The nCipher SNMP monitoring agent provides you with components

that can be added to your (third-party) SNMP manager application.
Every SNMP manager adds monitor components differently. Please
consult the documentation supplied with your SNMP Manager
application for details on how to add the nCipher MIB files.
The Simple Network Management Protocol (SNMP) was developed
in 1988 and revised in 1996. It is currently regarded as the standard
method of network management. It is widely supported and offers
greater interoperability than traditional network management tools
(for example, rsh or netstat). This makes it ideal for use for the large
array of platforms that nCipher supports and also avoids the overhead
of remote login and execution, helping to reduce network congestion
and improve performance.
The SNMP protocol defines a collection of network management
functions allowing management stations to gather information from,
and transmit commands to, remote machines on the network. Agents
running on the remote machines can take information gathered from
the system and relay this information to the manager application.
Such information could have been requested from the underlying
operating system or gained by interrogating the hardware.
The SNMP protocol defines the following SNMP messages:
get
This message is sent by a manager to retrieve the value of an

object at the agent.
set
This message is sent by a manager to set the value of an

object at the agent.
361
F The nCipher SNMP monitoring agent
trap
This message is sent by an agent to notify a management

station of significant events.
In the development of the nCipher SNMP agent, nCipher has used
open-source tools that are part of the NET-SNMP project (formerly
UCD-SNMP). More information on SNMP in general, and the data
structures used to support SNMP installations, is available from the
NET-SNMP project Web site: http://net-snmp.sourceforge.net/. This
site includes some support information and offers access to discussion
E-mail lists. You can use the discussion lists to monitor subjects that
might affect the operation or security of the nCipher SNMP agent or
command-line utilities.
Discuss any enquiries arising from information on the NET-SNMP
website with Support at nCipher before posting potentially sensitive
information to the NET-SNMP website.

The nCipher SNMP Agent enables other computers on the network to
connect to it and make requests for information. The nCipher agent is
based on the NET-SNMP kit, which has been tested but not fully
reviewed by nCipher. nCipher strongly recommends that the nCipher
agent is deployed only on a private network, or protected from the
global Internet by an appropriate firewall.
The nCipher SNMP agent is installed and activated separately. After
installing the nCipher SNMP components, an activation command
must be issued. This two-stage process is to avoid the inadvertent
activation of SNMP capabilities that could supply management
information from servers and nCipher modules that are not explicitly
protected, or which could potentially expose the host computer to
attacks on the nCipher SNMP agent itself.
362
Default settings
Default settings
By default, installing nCipher support software for Windows 2000 or
Windows 2003 also installs the nCipher SNMP agent but does not
activate it. The nCipher SNMP agent can be specifically excluded
from an nCipher installation by deselecting the box associated with
the SNMP agent in the installation component list. The default
installation directory for the nCipher Management Information Base
(MIB) and the SNMP configuration files (snmp.conf and snmpd.conf)
is %NFAST_HOME%\etc\snmp\.
Do you already have an SNMP agent running?

If you already have an SNMP agent running, you need to configure
the ports used by the agents to avoid conflicts before enabling the
nCipher SNMP agent. See the NET-SNMP project Web site:
http://net-snmp.sourceforge.net/. A port is assigned by editing the
agentaddress entry in the snmpd.conf file or by editing the defaultPort
entry in snmp.conf. If both files have been edited, the agentaddress
entry in snmpd.conf takes priority, and the defaultPort entry in
snmp.conf is ignored.
Activation of the SNMP agent

To activate the nCipher SNMP agent:
1.
Log in as Administrator.
2.
Open a command line window.
3.
Enter the following command:
e:\ncipher\devel\ncsnmp\src\ntbuild\agent\snmpd.exe -register [param list]
363
Further Information
where param list is a list of startup parameters: see Useful nCipher

SNMP agent command-line switches on page 382 for more details.
This installs the agent as a Windows Service and also starts the new
service.
To de-activate and uninstall the nCipher SNMP agent, enter the
following command:
e:\ncipher\devel\ncsnmp\src\ntbuild\agent\snmpd.exe -unregister
Further Information
Protecting the nCipher SNMP installation
The nCipher SNMP Agent allows other computers on the network to
connect to it and make requests for information. The nCipher agent is
based on the NET-SNMP code base, which has been tested but not
fully reviewed by nCipher. nCipher strongly recommends that the
nCipher agent be deployed only on a private network or protected
from the global Internet by an appropriate firewall.
The default nCipher SNMP installation allows read-only access to the
Management Information Base (MIB) with any community string.
There is no default write access to any part of the MIB.
Every effort has been taken to ensure the confidentiality of
cryptographic keys even when the SNMP agent is enabled. In
particular, the nCipher module is designed to prevent the theft of keys
even if the security of the host system is compromised, provided that
the Administrator Cards are used only with trusted hosts. Care must
be used when changing the configuration of the nCipher SNMP agent.
nCipher strongly advises that you set up suitable access controls in
snmpd.conf, or a firewall, to protect the agent and the information it
can return.
364
Further Information
Care has also been taken to ensure that malicious attackers are unable
to flood your module with requests by flooding your SNMP agent.
Command results from administration or statistics commands are
cached, and therefore the maximum rate at which the agent sends
commands to the module is throttled. See <Undefined CrossReference> for details on setting the cache time-outs.
Configuring the nCipher SNMP agent

The nCipher package uses various configuration files to configure its
applications. This section describes the overall nature of the
configuration files for the SNMP agent.
If you are installing the nCipher SNMP agent to a host that has an
existing, non-nCipher, SNMP agent installation, you may need to edit
the SNMP configuration files (snmpd.conf and snmp.conf) associated
with the nCipher SNMP agent to change the port on which the agent
listens for SNMP requests. See Do you already have an SNMP agent
running? on page 363.
Note
Make sure you protect the configuration files if you are storing
sensitive information in them.
By default, the nCipher SNMP configuration file (snmp.conf) is
located in the $NFAST_HOME\etc\snmp\ directory. In this directory,
the agent looks for files with the extension of .conf.
Note
The default search path can be overridden by setting the environment

variable SNMPCONFPATH to a semi-colon (;) separated list of
directories for which to search.
For further information about SNMP configuration files, see the
standard SNMP documentation available from the NET-SNMP
project Web site: http://net-snmp.sourceforge.net/
365
Further Information
Re-reading snmpd.conf and snmpd.local.conf

The nCipher SNMP agent can be forced to re-read its configuration
files with an snmp set of integer(1) to
enterprises.nCipher.reloadConfig.0(.1.3.6.1.4.1.7682.999.0).
The SNMP configuration file - snmp.conf

The snmp.conf configuration file contains directives that apply to all
SNMP applications. These directives can be configured to apply to
specific applications, see the standard SNMP documentation
available from the NET-SNMP project Web site: http://netsnmp.sourceforge.net/. The snmp.conf configuration file is not
required for the agent to operate and report MIB entries.
The SNMP agent configuration file - snmpd.conf

The snmpd.conf configuration file defines how the nCipher SNMP
agent operates. It is required only if an agent is running. This file can
contain any of the directives described in this section.
The snmpd.conf file can also contain any of the directives available for
use in the snmp.conf file. See the standard SNMP documentation
available from the NET-SNMP project Web site: http://netsnmp.sourceforge.net/.
The snmpd.conf file can also contain the following nCipher-specific
directives:
statstimeout
This directive specifies the maximum length of time for

which statistics commands are cached. The default is 60
seconds.
admintimeout
This directive specifies the maximum length of time for

which administrative commands are cached. The default is 5
seconds.
366
Using the nCipher SNMP agent with a manager

application
keytable
This directive sets the initial state of the key table to none, all,
or query. See listKeys in Administration sub-tree overview
on page 369.

application
Note
The nCipher SNMP monitoring agent provides you with components

that can be added to your (third-party) SNMP manager application.
Every SNMP manager adds monitor components differently. Please
consult the documentation supplied with your SNMP Manager
application for details on how to add the nCipher MIB files.
Manager configuration
The manager application is the interface through which the user is
able to perform network management functions. A manager
communicates with agents using SNMP primitives (get, set, trap) and
is unaware of how data is retrieved from, and sent to, managed
devices. This form of encapsulation raises two main issues:
the manager is hidden from all platform specific details
the manager can communicate with agents running on any IPaddressable machine.
As a consequence, manager applications are generic and can be

bought off the shelf. You may already be running SNMP managers,
and if so, you can use them to query the nCipher agent.
Note
The manager is initially unaware of the MIB tree structure at a

particular node. Managed objects can be retrieved or modified, but
only if their location in the tree is known.
367

application
It is more useful if the manager can see the MIB tree present at each
managed node. The MIB module descriptions for a particular node
must be parsed by a manager-specific MIB compiler and converted to
configuration files. These files are read by the manager application at
run time.
The nCipher SNMP agent is designed to monitor all current nCipher
modules. The SNMP agent can monitor e-commerce accelerator and
key management modules, working with all supported versions of
nCipher firmware (contact Support at nCipher for details of supported
firmware).
nCipher MIB module overview

A large proportion of the nCipher SNMP system is fully specified by
the structure of the MIB; the behavior of the agent depends on
relaying information according to the layout of the MIB.
The nCipher MIB module resides at a registered location in the MIB
tree determined by the Internet Assigned Numbers Authority (IANA).
The private enterprise number of 7682 designated by the IANA
corresponds to the root of the nCipher branch, and by convention this
(internal) node is the company name.
The MIB module groups logically related data together, organizing
itself into a classification tree, with managed objects present at leaf
nodes. The nC-series node (enterprises.nCipher.nC-series) is placed as
a sub-tree of the nCipher root (enterprises.nCipher); this allows future
product lines to be added as additional sub-trees. The structure of the
tree underneath the registered location is vendor-defined, and this
specification defines the structure chosen to represent nCipherspecific data.
MIB functionality
The nCipher MIB module separates module information into the
following categories:
368

application
retrieval of status and information about installed nC-series

modules
retrieval of live statistics of performance of installed nC-series

modules
These categories form the top-level nodes of the nCipher sub-tree; the
functionality of the first category is in the administration sub-tree, and
the second category is in the statistics sub-tree. The top-level tree also
contains 3 items that it would be useful to check at-a-glance:
Node name
R/W
Type
Remarks
hardserverFailed
TruthValue
True if the remote nCipher server is not

running. If the nCipher server is not running,
then most of the rest of the information is
unreliable or missing.
modulesFailed
TruthValue
True if any modules have failed
load
Unsigned32
Percentage of total available capacity

currently utilized
Administration sub-tree overview

The administration sub-tree (enterprises.nCipher.nCseries.administration) contains information about the permanent state
of the nCipher server and the connected modules. It is likely that most
of the information in this branch rarely changes over time, unlike the
statistics branch. The information given in the administration sub-tree
is mostly acquired by the NewEnquiry command and is supplied both
per-module and (where appropriate) aggregated over all modules.
369

application
The following table gives details of the individual nodes in the

administration sub-tree.
Node name
R/W
Type
Remarks
SecurityWorld
TruthValue
True if a security world is installed and

operational
hardserverRunning
Enum
1: Running
2: NotRunning
This variable reflects the current state of the

hardserver (Running or NotRunning)
noOfModules
Unsigned32
Number of nC-series modules
hsVersion
DisplayString
Hardserver version string
[global]speedIndex
Unsigned32
Number of 1024-bit signatures per second
[global]minQ
[global]maxQ
Unsigned32
Minimum and maximum recommended

queues
swState
DisplayString
Security World display flags, as reported by

nfkminfo
listKeys
R/W
Enum
1: none
2: all
3: query
4: resetquery
Controls the behavior of the key table

(switch off, display all keys, enable
individual attribute queries, clear the query
fields). Displaying all keys can result in a
very long list.
serverFlags
DisplayString
Supported hardserver facilities (the

NewEnquiry level 4 flags)
remoteServerPort
Gauge
TCP port the hardserver is listening on
swGenTime
DisplayString
Security worlds generation time
swGeneratingESN
DisplayString
ESN of the module that generated the

security world
listKeys can be preset using the keytable config directive in snmpd.conf

(see <Undefined Cross-Reference>).
370

application
Security world hash sub-tree

The following table gives details of the nodes in the security world
hash sub-tree (enterprises.nCipher.nCseries.administration.swHashes):
Node name
R/W
Type
Remarks
hashKNSO
MHash
Hash of the nCipher security officers key
hashKM
MHash
Hash of the security world key
hashKRA
MHash
Hash of the recovery authorization key
hashKRE
MHash
Hash of the recovery key pair
hashKFIPS
MHash
Hash of the FIPS authorization key
hashKMC
MHash
Hash of the module certification key
hashKP
MHash
Hash of the pass phrase recovery key
hashKNV
MHash
Hash of the nonvolatile memory (NVRAM)

authorization key
hashKRTC
MHash
Hash of the real time clock authorization

key
hashKDSEE
MHash
Hash of the SEE Debugging authorization

key
hashKFTO
MHash
Hash of the Foreign Token Open

authorization key
371

application
Security world quorums sub-tree

The following table gives details of the nodes in the security world
quorums sub-tree (enterprises.nCipher.nCseries.administration.swQuorums):
Node name
R/W
Type
Remarks
adminQuorumK
Unsigned
The default quorum of admin cards
adminQuorumN
Unsigned
The total number of cards in the admin

cardset
adminQuorumM
Unsigned
The quorum required for module

reprogramming
adminQuorumR
Unsigned
The quorum required to recover keys for

operator card recovery
adminQuorumP
Unsigned
The quorum required to recover the pass

phrase for an operator card
adminQuorumNV
Unsigned
The quorum required to access nonvolatile

memory (NVRAM)
adminQuorumRTC
Unsigned
The quorum required to update the real time

clock
adminQuorumDSEE
Unsigned
The quorum required to view full SEE

debug information
adminQuorumFTO
Unsigned
The quorum required to use a Foreign Token

Open Delegate Key
372

application
Module administration table

The following table gives details of the nodes in the module
administration table (enterprises.nCipher.nCseries.administration.moduleAdminTable):
Node name
R/W
Type
Remarks
moduleAdminIndex
Integer
Module number of this row in the table
mode
Enum
1: Operational
2: Pre-init
3: Init
4: Pre-maint
5: Maint
6: AccelOnly
7: Failed
8: Unknown
Current module state
fwVersion
DisplayString
Firmware version string
serialNumber
DisplayString
Module Electronic Serial Number (ESN)
moduleType
DisplayString
Module type code
productName
DisplayString
(only returned if module supports enquiry

level 5)
hwPosInfo
DisplayString
Hardware bus/slot info (such as PCI slot

number). Modules only return a meaningful
value if they support enquiry level 5.
moduleSecurityWorld
TruthValue
Indicates whether or not the module is in the

current SW
smartcardState
DisplayString
Description of smartcard in slot (empty,

unknown card, admin/operator card from
current SW, failed). N/A for acceleration
only modules.
373

application
Node name
R/W
Type
Remarks
moduleSWState
Enum
Current module and security world state
1: unknown
2: usable
3: maintmode
4: uninitialized
5: factory
6: foreign
7: accelonly
8: failed
9: unchecked
10: initmode
11: preinitmode
12: outofrange
moduleSWFlags
DisplayString
Security World flags for this module
hashKML
MHash
Hash of the modules secret key
moduleFeatures
DisplayString
Features enabled on this module
moduleFlags
DisplayString
Like serverFlags, but per-module
versionSerial
Gauge
Firmware Version Security Number (VSN);

see Version Security Number on page 323.
hashKNETI
MHash
KNETI hash, if present
longQ
Gauge
Max. rec. long queue
connectionStatus
DisplayString
Connection status (for imported modules)
connectionInfo
DisplayString
Connection information (for imported

modules)
machineTypeSEE
DisplayString
SEE machine type
374

application
Slot administration table

The following table gives details of the nodes in the slot
administration table (enterprises.nCipher.nCseries.administration.slotAdminTable):
Node name
R/W
Type
Remarks
slotAdminModuleIndex R
Unsigned32
Module number of the module containing

the slot
slotAdminSlotIndex
Unsigned32
Slot number (1-based, unlike nCore which

is 0-based)
slotType
Slot type
Enum
1: Datakey
2: Smart card
3: Emulated
4: Soft token
5: Unconnected
6: Out of range
7: Unknown
slotFlags
DisplayString
Flags referring to the contents of the slot

(from slotinfo)
slotState
Enum
1: Unused
2: Empty
3: Blank
4:
Administrator
5: Operator
6: Unidentified
7: Read error
8: Partial
9: Out of range
Partial refers to cards in a partially-created
cardset.
slotListFlags
DisplayString
Flags referring to attributes of the slot (from

getslotlist)
slotShareNumber
Unsigned32
Share number of card currently in slot, if

present
slotSharesPresent
DisplayString
Names of shares present in card currently in

slot.
375

application
Cardset administration table

The following table gives details of the nodes in the cardset
administration table (enterprises.nCipher.nCseries.administration.cardsetAdminTable):
Node name
R/W
Type
Remarks
hashKLTU
MHash
Hash of the token protected by the cardset
cardsetName
DisplayString
cardsetK
Unsigned32
cardsetN
Unsigned32
Total number of cards in the cardset
cardsetFlags
DisplayString
Other attributes of the cardset
Required number of cards in the cardset
cardsetNames
DisplayString
Names of individual cards, if set
cardsetTimeout
Unsigned32
Token time-out period, in seconds, or 0 if

none
cardsetGenTime
DisplayString
Generation time of cardset
Key administration table

The key administration table is visible as long as the listKeys node in
the administration sub-tree is set to a value other than none.
376

application
The following table gives details of the nodes in the key

administration table (enterprises.nCipher.nCseries.administration.keyAdminTable):
Node name
R/W
Type
Remarks
keyAppname
DisplayString
Application name
keyIdent
DisplayString
Name of key, as generated by the

application
keyHash
MHash
Required and total number of cards in the

cardset
keyRecovery
Enum
1: Enabled
2: Disabled
3: No key
4: Unknown
5: Invalid
6: Unset
The value unset is never returned by the key

table. It is used in the key query field to
mean do not care.
keyProtection
Enum
1: Module
2: Cardset
3: No key
4: Unknown
5: Invalid
6: Unset

mean do not care.
keyCardsetHash
MHash
Hash of the cardset protecting the key, if

applicable
keyFlags
DisplayString
Certificate and public key flags
keyExtraEntities
Unsigned32
Number of extra key attributes.
keySEEInteg
DisplayString
SEE integrity key, if present
keyGeneratingESN
DisplayString
ESN of the module that generated the key, if

present
keyTimeLimit
Gauge
Time limit for the key, if set
keyPerAuthUseLimit
Gauge
Per-authentication use limit for the key
Key query sub-tree

The key query sub-tree is used if the listKeys node in the
administration sub-tree is set to query.
377

application
If these values are set, they are taken as required attributes for filtering
the list of available keys; if multiple attributes are set, the filters are
combined (AND rather than OR).
The following table gives details of the nodes in the key query subtree (enterprises.nCipher.nC-series.administration.keyQuery):
Node name
R/W
Type
keyQueryAppname
R/W
DisplayString
Application name
keyQueryIdent
R/W
DisplayString
Name of key, as generated by the

application
keyQueryHash
R/W
DisplayString
Required and total number of cards in the

cardset
keyQueryRecovery
R/W
Enum
1: Enabled
2: Disabled
3: No key
4: Unknown
5: Invalid
6: Unset

mean do not care.
keyQueryProtection
R/W
Enum
1: Module
2: Cardset
3: No key
4: Unknown
5: Invalid
6: Unset

mean do not care.
keyQueryCardsetHash
R/W
DisplayString
Hash of the cardset protecting the key, if

applicable
keyQueryFlags
R/W
DisplayString
Certificate and public key flags
keyQueryExtraEntities
R/W
Unsigned32
Number of extra key attributes
keyQuerySEEInteg
R/W
DisplayString
SEE integrity key, if present
keyQueryGeneratingES R/W
N
DisplayString
ESN of the module that generated the key, if

present
keyQueryTimeLimit
R/W
Gauge
Time limit for the key, if set (0 for no limit)
keyQueryPerAuthUseL R/W
imit
Gauge
Per-authentication use limit for the key (0

for no limit)
Remarks
378

application
Statistics sub-tree overview

The statistics sub-tree (enterprises.nCipher.nC-series.statistics)
contains rapidly-changing information about the state of the nCipher
modules, the work they are doing, the commands being submitted,
and so on.
Note
Do not rely on information returned from the agent to change

instantaneously on re-reading the value. To avoid loading the nCipher
module with multiple time-consuming statistics commands, the agent
can choose to cache the values over a specified period. You can
configure this period in the agent configuration file (see The SNMP
agent configuration file - snmpd.conf on page 366).
Statistics sub-tree and module statistics table

The following table gives details of the nodes in the statistics sub-tree,
and the module statistics table (enterprises.nCipher.nCseries.statistics.moduleStatsTable):
Node name
R/W
Type
moduleStatsIndex
Integer
Remarks
Module number of this row (for
moduleStatsTable)
[hs]uptime
Counter32
Uptime of the hardserver or module
cmdCount[All]
Counter32
Returned aggregated for all modules and all

commands, and per-module for all
commands
cmdBytes[All]
Counter32
cmdErrors[All]
Counter32
replyCount[All]
Counter32
replyBytes[All]
Counter32
replyErrors[All]
Counter32
Returned as for cmdCount. When permodule total, aggregate all the different
error states into one counter. When
aggregated, returned value is combined
module errors added to hardserver
marshalling/unmarshalling errors.
see notes above for cmdErrors
379

application
Node name
R/W
Type
clientCount
Counter32
maxClients
Counter32
deviceFails
Counter32
deviceRestarts
Counter32
load[All]
Counter32
outstandingCmds
Counter32
objectCount
Counter32
clock
DisplayString
Depending on the module settings, this can

require KNSO permissions to read (and
therefore depend on the installation
parameters of the agent)
currentTemp
DisplayString
Character representation of the current temp

value (SNMP does not provide for a
floating-point type)
maxTemp
DisplayString
Maximum temperature the module has ever

reached
nvRAMInUse
Counter32
volatileRAMInUse
Counter32
Remarks
Total no. of outstanding commands over all

modules
netHSM statistics table

The following table gives details of the nodes in the netHSM statistics
table (enterprises.nCipher.nC-series.statistics.netHSMStatsTable):
Node name
R/W
Type
Remarks
netHSMStatsIndex
Integer
Table index (not module number)
netHSMUptime
Counter32
netHSM host system uptime
netHSMCPUUsage
Gauge32
CPU usage of netHSM host processor
netHSMUserMem
Gauge32
Total user memory of netHSM
netHSMKernelMem
Gauge32
Total kernel memory of netHSM
netHSMCurrentTemp
DisplayString
Internal netHSM temperature (sensor 1)
netHSMMaxTemp
DisplayString
Max. recorded temp (sensor 1)
380

application
Node name
R/W
Type
Remarks
netHSMCurrentTemp2
DisplayString
Internal netHSM temperature (sensor 2)
netHSMMaxTemp2
DisplayString
Max. recorded temp (sensor 2)
netHSMPower5V
DisplayString
netHSM 5V power reading
netHSMPower12V
DisplayString
netHSM 12V power reading
netHSMFanSpeed
Gauge32
Fan 1 speed (RPM)
netHSMFan2Speed
Gauge32
Fan 2 speed (RPM)
netHSMFan3Speed
Gauge32
Fan 3 speed (RPM)
netHSMIPAddress
IpAddress
IP address of netHSM
netHSMDescription
DisplayString
Textual description of module (for example,

Local module #3)
Software versions table

The following table gives details of the nodes in the software versions
table (enterprises.nCipher.softwareVersions.softwareVersionsTable);
see ncversions on page 257:
Node name
R/W
Type
Remarks
compIndex
Integer
Table index
compName
DisplayString
Component name
compOutput
Component
output name
Component name
compMajorVersion
Gauge
compMinorVersion
Gauge
compPatchVersion
Gauge
compRepository
DisplayString
compBuildNumber
Gauge
Repository name
381
Useful nCipher SNMP agent command-line

switches
Useful nCipher SNMP agent command-line switches

SNMP agent (snmpd) switches
The SNMP agent that binds to a port and awaits requests from SNMP
management software is snmpd. Upon receiving a request, snmpd
processes the request, collects the requested information and/or
performs the requested operation(s) and returns the information to the
sender.
The nCipher SNMP agent supports a limited subset of command line
switches that can be specified when starting the agent.
Usage
e:\ncipher\devel\ncsnmp\src\ntbuild\agent\snmpd.exe -register [param list] |
-unregister |
[-h] [-v] [-f] [-a] [-d] [-V] [-P PIDFILE):] [-q] [-D] [-p NUM]
[-L] [-l LOGFILE] [-r]
In this command:
-h
This option displays a usage message.

-register [param list]
This option registers the agent as a Windows service, and

starts the service.
param list is a startup parameter list for service, the same as
normal parameters, for example

snmpd.exe -register -p 2002
registers snmpd.exe as service, which listens on port 2002.
382

switches
Some options do not make sense when the agent is running

as service.
-unregister
This option unregisters the service if it is already registered.

-H
This option displays the configuration file directives that the

agent understands.
-v
This option displays version information.

-f
This option specifies not forking from the calling shell.

-a
This option specifies logging addresses.

-d
This option specifies the dumping of sent and received UDP

SNMP packets.
-V
This option specifies verbose display.

-P PIDFILE
This option specifies the use of a file (PIDFILE) to store the

process ID.
-q
This option specifies that information be printed in a more

parsable format (quick print).
383

switches
-D
This option turns on debugging output.

-p NUM
This option specifies running on port NUM instead of the

default: 161.
-c CONFFILE
This option specifies reading CONFFILE as a configuration

file.
-C
This option specifies that the default configuration files not

be read.
-L
This option prints warnings/messages to stdout/err.

-s
This option logs warnings/messages to syslog.

-r
This options specifies not exiting if root-only accessible files

cannot be opened.
-I [-]INITLIST
This option specifies a list of MIB modules to initialize (or

not). Runsnmpd with -Dmib_init for a list.
-l LOGFILE
This option prints warnings/messages to a file LOGFILE (by

default, LOGFILE=log/snmpd.log).
384

As an alternative to using an SNMP manager application, nCipher
supplies several command-line utilities to test your SNMP installation
and that enable you to obtain information about your nCipher module
from the nCipher SNMP agent:
snmptest
This utility monitors and manages SNMP information.

snmpget
This utility queries for SNMP information on a network

entity.
snmpset
This utility sets SNMP information on a network entity.

snmpgetnext
This utility queries for SNMP information on a network

entity.
snmptable
This utility obtains and prints an SNMP table.

snmptranslate
This utility translates SNMP objects into something more

useful.
snmpwalk
This utility communicates with a network entity using GET

NEXT request.
385
snmpbulkwalk
This utility communicates with a network entity using

BULK request.
These tools are general purpose SNMP utilities and can be configured
for use with other SNMP agents. For more information on configuring
and using these tools, refer to the NET-SNMP project Web site:
http://net-snmp.sourceforge.net/.
386
nCipher addresses
nCipher Corporation Ltd.
nCipher Inc.
Cambridge, UK
Boston Metro Region, USA
Jupiter House
Station Road
Cambridge
CB1 2JD
UK
92 Montvale Avenue, Suite 4500

Stoneham, MA 02180
USA
Tel:
Fax:
Tel:
+44 (0) 1223 723600

+44 (0) 1223 723601
Fax:
800-NCIPHER
800-6247437
+1 (781) 994 4000
+1 (781) 994 4001
E-mail:
E-mail:
sales@ncipher.com
support@ncipher.com
sales@us.ncipher.com
support@ncipher.com
Internet addresses
Web Site:
http://www.ncipher.com/
Online Documentation:
http://active.ncipher.com/documentation/
Note
nCipher also maintain international sales offices. Please contact the

UK, or the US, head office for details of your nearest nCipher
representative.

Nshield Admin PDF

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Nshield Admin PDF

Uploaded by

Copyright:

Available Formats

nShield/payShield Administrator

Commercial Computer Software - proprietary

nShield/payShield Administrator Guide Windows v5.5

Contents of this guide

nCipher security worlds

KeySafe and security worlds

Applications and the security world

The nCipher PKCS #11 library and security worlds

Getting the module working

Determining module requirements

nShield/payShield Administrator Guide Windows v5.5

Prerequisites to software installation

Software installation procedure

After software installation

Configuring the module

Creating and configuring a security world

Creating and configuring a payShield installation

Creating the Operator Card Set

Changing the module state

Entering the pre-maintenance state

Entering the pre-initialization state

Entering the operational state

Uninstalling the nCipher support software

Configuring the hardserver

Remote module connections

Hardserver start-up settings

Hardserver configuration file

Payments configuration file

Using multiple modules

Multiple modules and Remote Operator

nShield/payShield Administrator Guide Windows v5.5

Module fail over

Feature Enabling nCipher Modules

Ordering features for your module

Using CodeSafe Applications

The KeySafe window

Managing security worlds

Security world files

Security world options

Creating a security world

After you have created a security world

Adding or restoring a module to the security world

Erasing a module from a security world

Deleting the security world

Displaying information about your security world

Windows Cryptographic Services Provider (CSP)

Transferring keys between security worlds

nShield/payShield Administrator Guide Windows v5.5

About payShield installations

About payShield Card Sets

Supported payShield Key Types

payShield security world properties

Remote Operator Card Sets

About Remote Operator

Configuring Remote Operator

Administration tasks with cards and softcards

Replacing an Operator Cards pass phrase

Replacing Operator Card Sets

Changing pass phrases with cardpp

Changing pass phrases with ppmk

Replacing the Administrator Card Set

nShield Administrator Utilities