You are on page 1of 387

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

nShield/payShield Administrator Guide Windows v5.5

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

nShield/payShield Administrator Guide Windows v5.5

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

nShield/payShield Administrator Guide Windows v5.5

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

nShield/payShield Administrator Guide Windows v5.5

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

nShield/payShield Administrator Guide Windows v5.5

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

nShield/payShield Administrator Guide Windows v5.5

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

nShield/payShield Administrator Guide Windows v5.5

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.

nShield/payShield Administrator Guide Windows v5.5

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.

Contents of this guide


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.

nShield/payShield Administrator Guide Windows v5.5

11

1 Introduction

Contents of this guide

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.

nShield/payShield Administrator Guide Windows v5.5

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.

nShield/payShield Administrator Guide Windows v5.5

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.

nShield/payShield Administrator Guide Windows v5.5

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 .

nShield/payShield Administrator Guide Windows v5.5

15

1 Introduction

Additional Documentation

Additional Documentation
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.

nShield/payShield Administrator Guide Windows v5.5

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.

nShield/payShield Administrator Guide Windows v5.5

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

nShield/payShield Administrator Guide Windows v5.5

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.

nShield/payShield Administrator Guide Windows v5.5

19

2 nCipher security worlds

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.

nShield/payShield Administrator Guide Windows v5.5

20

2 nCipher security worlds

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.

nShield/payShield Administrator Guide Windows v5.5

21

2 nCipher security worlds

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.

nShield/payShield Administrator Guide Windows v5.5

22

2 nCipher security worlds

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

nShield/payShield Administrator Guide Windows v5.5

23

2 nCipher security worlds

Application independence

Application independence
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

nShield/payShield Administrator Guide Windows v5.5

24

2 nCipher security worlds

Platform independence

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.

Platform independence
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.

nShield/payShield Administrator Guide Windows v5.5

25

2 nCipher security worlds

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

nShield/payShield Administrator Guide Windows v5.5

26

2 nCipher security worlds

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

nShield/payShield Administrator Guide Windows v5.5

27

2 nCipher security worlds

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.

nShield/payShield Administrator Guide Windows v5.5

28

2 nCipher security worlds

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.

nShield/payShield Administrator Guide Windows v5.5

29

2 nCipher security worlds

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.

nShield/payShield Administrator Guide Windows v5.5

30

2 nCipher security worlds

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.

nShield/payShield Administrator Guide Windows v5.5

31

2 nCipher security worlds

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.

Replacing the Administrator Card Set


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.

nShield/payShield Administrator Guide Windows v5.5

32

2 nCipher security worlds

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.

nShield/payShield Administrator Guide Windows v5.5

33

2 nCipher security worlds

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

nShield/payShield Administrator Guide Windows v5.5

34

2 nCipher security worlds

KeySafe and security worlds

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 and security worlds


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:

nShield/payShield Administrator Guide Windows v5.5

35

2 nCipher security worlds

Note

KeySafe and security worlds

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.

nShield/payShield Administrator Guide Windows v5.5

36

2 nCipher security worlds

Applications and the security world

Applications and the security world


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.

nShield/payShield Administrator Guide Windows v5.5

37

2 nCipher security worlds

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.

nShield/payShield Administrator Guide Windows v5.5

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:

nShield/payShield Administrator Guide Windows v5.5

39

3 Getting the module working

Prerequisites to software installation

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.

Prerequisites to software installation


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.

nShield/payShield Administrator Guide Windows v5.5

40

3 Getting the module working

Prerequisites to software installation

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.

nShield/payShield Administrator Guide Windows v5.5

41

3 Getting the module working

Prerequisites to software installation

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.

nShield/payShield Administrator Guide Windows v5.5

42

3 Getting the module working

Software installation procedure

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.

Software installation procedure


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.

nShield/payShield Administrator Guide Windows v5.5

43

3 Getting the module working

Software installation procedure

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

nShield/payShield Administrator Guide Windows v5.5

44

3 Getting the module working

Software installation procedure

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.

nShield/payShield Administrator Guide Windows v5.5

45

3 Getting the module working

Note

After software installation

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.

After software installation


Testing the installation
To check that the software has been installed correctly:
1.

Log in as a normal user.

2.

Open a command window.

nShield/payShield Administrator Guide Windows v5.5

46

3 Getting the module working

3.

After software installation

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.

nShield/payShield Administrator Guide Windows v5.5

47

3 Getting the module working

After software installation

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

nShield/payShield Administrator Guide Windows v5.5

48

3 Getting the module working

After software installation

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.

nShield/payShield Administrator Guide Windows v5.5

49

3 Getting the module working

After software installation

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

nShield/payShield Administrator Guide Windows v5.5

50

3 Getting the module working

Note

NFLOG_SEVERITY

NFLOG_DETAIL

NFLOG_CATEGORIES

Configuring the module

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 module


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.

nShield/payShield Administrator Guide Windows v5.5

51

3 Getting the module working

Configuring the module

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

nShield/payShield Administrator Guide Windows v5.5

52

3 Getting the module working

3.
4.

Configuring the module

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:

nShield/payShield Administrator Guide Windows v5.5

53

3 Getting the module working

Configuring the module

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

nShield/payShield Administrator Guide Windows v5.5

54

3 Getting the module working

Configuring the module

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.

nShield/payShield Administrator Guide Windows v5.5

55

3 Getting the module working

Creating and configuring a security world

Creating and configuring a security world


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

nShield/payShield Administrator Guide Windows v5.5

56

3 Getting the module working

Creating and configuring a security world

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:

nShield/payShield Administrator Guide Windows v5.5

57

3 Getting the module working

Creating and configuring a security world

-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

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

nShield/payShield Administrator Guide Windows v5.5

58

3 Getting the module working

Creating and configuring a security world

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

nShield/payShield Administrator Guide Windows v5.5

59

3 Getting the module working

Creating and configuring a security world

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.

nShield/payShield Administrator Guide Windows v5.5

60

3 Getting the module working

Creating and configuring a security world

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.

nShield/payShield Administrator Guide Windows v5.5

61

3 Getting the module working

Creating and configuring a security world

rtc

This feature specifies that the Administrator Card Set is


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

This feature specifies that the Administrator Card Set is


needed to enable SEE World debugging.
dseeall

This feature specifies that SEE World debugging is enabled


for all users, without certificates.
fto

This feature specifies that the Administrator Card Set is


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

If you want to use extended debugging from the module, you must set
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.

nShield/payShield Administrator Guide Windows v5.5

62

3 Getting the module working

Creating and configuring a security world

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.

nShield/payShield Administrator Guide Windows v5.5

63

3 Getting the module working

Creating and configuring a payShield installation

Maintenance link 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, 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.

Creating and configuring a payShield installation


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

nShield/payShield Administrator Guide Windows v5.5

64

3 Getting the module working

Creating and configuring a payShield installation

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.

You must have enough smart cards to form the security worlds
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.

nShield/payShield Administrator Guide Windows v5.5

65

3 Getting the module working

Creating and configuring a payShield installation

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.

nShield/payShield Administrator Guide Windows v5.5

66

3 Getting the module working

Creating and configuring a payShield installation

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.

nShield/payShield Administrator Guide Windows v5.5

67

3 Getting the module working

Creating and configuring a payShield installation

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.

nShield/payShield Administrator Guide Windows v5.5

68

3 Getting the module working

Creating and configuring a payShield installation

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

nShield/payShield Administrator Guide Windows v5.5

69

3 Getting the module working

Creating and configuring a payShield installation

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.

nShield/payShield Administrator Guide Windows v5.5

70

3 Getting the module working

Creating the Operator Card Set

Creating the Operator Card Set


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:

nShield/payShield Administrator Guide Windows v5.5

71

3 Getting the module working

1.

Creating the Operator Card Set

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

nShield/payShield Administrator Guide Windows v5.5

72

3 Getting the module working

Creating the Operator Card Set

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

nShield/payShield Administrator Guide Windows v5.5

73

3 Getting the module working

Creating the Operator Card Set

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.

nShield/payShield Administrator Guide Windows v5.5

74

3 Getting the module working

3.

Creating the Operator Card Set

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.

nShield/payShield Administrator Guide Windows v5.5

75

Chapter 4: Changing the module state


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

Entering the pre-maintenance state


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.

Internal PCI modules


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.

nShield/payShield Administrator Guide Windows v5.5

76

4 Changing the module state

Entering the pre-maintenance 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.

nShield/payShield Administrator Guide Windows v5.5

77

4 Changing the module state

Entering the pre-initialization state

Entering the pre-initialization state


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.

Internal PCI modules


1.

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


Figure 4.

Figure 4

PCI module back panel

Status LED
Clear switch
Mode switch

M
O
I

Initialization

Smart card
connector

DC power

2.

Reset the module by pressing the clear button.

nShield/payShield Administrator Guide Windows v5.5

78

4 Changing the module state

Entering the operational state

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

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

Entering the operational state


When you have created or restored a security world, return the module
to the operational state.

nShield/payShield Administrator Guide Windows v5.5

79

4 Changing the module state

Entering the operational state

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.

Reset the module by pressing the clear button.

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

nShield/payShield Administrator Guide Windows v5.5

80

4 Changing the module state

Entering the operational state

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

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

nShield/payShield Administrator Guide Windows v5.5

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.

nShield/payShield Administrator Guide Windows v5.5

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.

nShield/payShield Administrator Guide Windows v5.5

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.

nShield/payShield Administrator Guide Windows v5.5

84

6 Configuring the hardserver

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.

Hardserver configuration file


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

nShield/payShield Administrator Guide Windows v5.5

85

6 Configuring the hardserver

Hardserver configuration file

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.

nShield/payShield Administrator Guide Windows v5.5

86

6 Configuring the hardserver

Hardserver configuration file

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.

nShield/payShield Administrator Guide Windows v5.5

87

6 Configuring the hardserver

Hardserver configuration file

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.

nShield/payShield Administrator Guide Windows v5.5

88

6 Configuring the hardserver

Hardserver configuration file

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.

nShield/payShield Administrator Guide Windows v5.5

89

6 Configuring the hardserver

Hardserver configuration file

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.

nShield/payShield Administrator Guide Windows v5.5

90

6 Configuring the hardserver

Hardserver configuration file

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
overrides the value in the configuration file.
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
overrides the value in the configuration file.
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
overrides the value in the configuration file.
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:

nShield/payShield Administrator Guide Windows v5.5

91

6 Configuring the hardserver

Hardserver configuration file

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.

nShield/payShield Administrator Guide Windows v5.5

92

6 Configuring the hardserver

Hardserver configuration file

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.

nShield/payShield Administrator Guide Windows v5.5

93

6 Configuring the hardserver

Hardserver configuration file

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:

nShield/payShield Administrator Guide Windows v5.5

94

6 Configuring the hardserver

Hardserver configuration file

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.

nShield/payShield Administrator Guide Windows v5.5

95

6 Configuring the hardserver

Payments configuration file

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

Payments configuration file


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

nShield/payShield Administrator Guide Windows v5.5

96

6 Configuring the hardserver

Payments configuration file

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.

nShield/payShield Administrator Guide Windows v5.5

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.

nShield/payShield Administrator Guide Windows v5.5

98

7 Using multiple modules

Multiple modules and Remote Operator

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.

Multiple modules and Remote Operator


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.

nShield/payShield Administrator Guide Windows v5.5

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.

nShield/payShield Administrator Guide Windows v5.5

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.

nShield/payShield Administrator Guide Windows v5.5

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.

nShield/payShield Administrator Guide Windows v5.5

102

8 Feature Enabling nCipher Modules

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.

nShield/payShield Administrator Guide Windows v5.5

103

8 Feature Enabling nCipher Modules

Ordering features for your module

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.

Ordering features for your module


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

nShield/payShield Administrator Guide Windows v5.5

104

8 Feature Enabling nCipher Modules

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

nShield/payShield Administrator Guide Windows v5.5

105

8 Feature Enabling nCipher Modules

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.

nShield/payShield Administrator Guide Windows v5.5

106

8 Feature Enabling nCipher Modules

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.

nShield/payShield Administrator Guide Windows v5.5

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 .

nShield/payShield Administrator Guide Windows v5.5

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.

nShield/payShield Administrator Guide Windows v5.5

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:

nShield/payShield Administrator Guide Windows v5.5

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.

nShield/payShield Administrator Guide Windows v5.5

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

nShield/payShield Administrator Guide Windows v5.5

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

nShield/payShield Administrator Guide Windows v5.5

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

nShield/payShield Administrator Guide Windows v5.5

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

nShield/payShield Administrator Guide Windows v5.5

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

nShield/payShield Administrator Guide Windows v5.5

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.

nShield/payShield Administrator Guide Windows v5.5

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.

nShield/payShield Administrator Guide Windows v5.5

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

nShield/payShield Administrator Guide Windows v5.5

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.

nShield/payShield Administrator Guide Windows v5.5

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.

nShield/payShield Administrator Guide Windows v5.5

121

10 Using KeySafe

Errors

Contact Support at nCipher if you receive any other error message that
looks similar to the one shown below:

nShield/payShield Administrator Guide Windows v5.5

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.

Security world files


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.

nShield/payShield Administrator Guide Windows v5.5

123

11 Managing security worlds

Security world files

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.

nShield/payShield Administrator Guide Windows v5.5

124

11 Managing security worlds

Security world options

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.

Security world options


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.

nShield/payShield Administrator Guide Windows v5.5

125

11 Managing security worlds

Security world options

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

If you are creating an Administrator Card Set for a payShield


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.

nShield/payShield Administrator Guide Windows v5.5

126

11 Managing security worlds

Security world options

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

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

nShield/payShield Administrator Guide Windows v5.5

127

11 Managing security worlds

Security world options

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.

nShield/payShield Administrator Guide Windows v5.5

128

11 Managing security worlds

Creating a security world

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.

Creating a security world


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

The NFAST_HOME environment variable must be set.

nShield/payShield Administrator Guide Windows v5.5

129

11 Managing security worlds

Creating a security world

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.

You must have enough smart cards to form the security worlds
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
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. 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.

nShield/payShield Administrator Guide Windows v5.5

130

11 Managing security worlds

Creating a security world

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:

nShield/payShield Administrator Guide Windows v5.5

131

11 Managing security worlds

Note

Creating a security world

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.

nShield/payShield Administrator Guide Windows v5.5

132

11 Managing security worlds

8.

Creating a security world

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

If you are creating an Administrator Card Set for a payShield


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:

nShield/payShield Administrator Guide Windows v5.5

133

11 Managing security worlds

Creating a security world

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:

nShield/payShield Administrator Guide Windows v5.5

134

11 Managing security worlds

Creating a security world

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.
If you want to use extended debugging from the module, you must set
SEEDebugging to Unrestricted.

nShield/payShield Administrator Guide Windows v5.5

135

11 Managing security worlds

Creating a security world

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
Administrator Card Set.
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.

nShield/payShield Administrator Guide Windows v5.5

136

11 Managing security worlds

Creating a security world

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.

nShield/payShield Administrator Guide Windows v5.5

137

11 Managing security worlds

Creating a security world

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

nShield/payShield Administrator Guide Windows v5.5

138

11 Managing security worlds

Creating a security world

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:

nShield/payShield Administrator Guide Windows v5.5

139

11 Managing security worlds

1.

Creating a security world

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:

nShield/payShield Administrator Guide Windows v5.5

140

11 Managing security worlds

Creating a security world

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:

nShield/payShield Administrator Guide Windows v5.5

141

11 Managing security worlds

Creating a security world

If there is at least one module capable of key management


and there is no existing security world, the wizard displays
the following window:

nShield/payShield Administrator Guide Windows v5.5

142

11 Managing security worlds

3.

Creating a security world

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.

nShield/payShield Administrator Guide Windows v5.5

143

11 Managing security worlds

Creating a security world

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.

Click the Next button.


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
pre-initialization state on page 78.

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.

nShield/payShield Administrator Guide Windows v5.5

144

11 Managing security worlds

5.

Creating a security world

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.

If you are creating an Administrator Card Set for a payShield


installation, K must be greater than 1.
7.

Select either DES3 or AES for the security worlds module key
type.

nShield/payShield Administrator Guide Windows v5.5

145

11 Managing security worlds

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

Creating a security world

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.

nShield/payShield Administrator Guide Windows v5.5

146

11 Managing security worlds

Creating a security world

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.

nShield/payShield Administrator Guide Windows v5.5

147

11 Managing security worlds

Note

Creating a security world

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.

nShield/payShield Administrator Guide Windows v5.5

148

11 Managing security worlds

Creating a security world

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.

nShield/payShield Administrator Guide Windows v5.5

149

11 Managing security worlds

Creating a security world

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.

nShield/payShield Administrator Guide Windows v5.5

150

11 Managing security worlds

Creating a security world

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.

nShield/payShield Administrator Guide Windows v5.5

151

11 Managing security worlds

Creating a security world

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

nShield/payShield Administrator Guide Windows v5.5

152

11 Managing security worlds

Creating a security world

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

nShield/payShield Administrator Guide Windows v5.5

153

11 Managing security worlds

After you have created a security world

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.

After you have created a security world


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

nShield/payShield Administrator Guide Windows v5.5

154

11 Managing security worlds

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.

nShield/payShield Administrator Guide Windows v5.5

155

11 Managing security worlds

Adding or restoring a module to the security


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.

nShield/payShield Administrator Guide Windows v5.5

156

11 Managing security worlds

Adding or restoring a module to the security


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.

Start KeySafe. (For an introduction to KeySafe and information


on starting the software, see the appropriate Operator Guide for
your module.)

2.

Click the Modules menu button. KeySafe takes you to the Module
Operations panel.

3.

Click the Reprogram Module navigation button.

nShield/payShield Administrator Guide Windows v5.5

157

11 Managing security worlds

4.
Note

Note

Adding or restoring a module to the security


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.

nShield/payShield Administrator Guide Windows v5.5

158

11 Managing security worlds

Adding or restoring a module to the security


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.

Click the Next button.


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

nShield/payShield Administrator Guide Windows v5.5

159

11 Managing security worlds

Adding or restoring a module to the security


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.

nShield/payShield Administrator Guide Windows v5.5

160

11 Managing security worlds

Adding or restoring a module to the security


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.
-S, --no-remoteshare-cert

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.

nShield/payShield Administrator Guide Windows v5.5

161

11 Managing security worlds

3.
Note

Erasing a module from a security world

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


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.

nShield/payShield Administrator Guide Windows v5.5

162

11 Managing security worlds

Erasing a module from a security world

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.

Start KeySafe. (For an introduction to KeySafe and information


on starting the software, see the appropriate Operator Guide for
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.

nShield/payShield Administrator Guide Windows v5.5

163

11 Managing security worlds

5.
Note

Erasing a module from a security world

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.

nShield/payShield Administrator Guide Windows v5.5

164

11 Managing security worlds

Deleting the security world

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.

Deleting the security world


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

nShield/payShield Administrator Guide Windows v5.5

165

11 Managing security worlds

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.

nShield/payShield Administrator Guide Windows v5.5

166

11 Managing security worlds

Displaying information about your security


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.

nShield/payShield Administrator Guide Windows v5.5

167

11 Managing security worlds

Displaying information about your security


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
Module #1 Slot #1 IC 0
generation
1

nShield/payShield Administrator Guide Windows v5.5

168

11 Managing security worlds

phystype
slotlistflags
state
flags
shareno
shares
error
No Cardset

Displaying information about your security


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.

nShield/payShield Administrator Guide Windows v5.5

169

11 Managing security worlds

Displaying information about your security


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.

nShield/payShield Administrator Guide Windows v5.5

170

11 Managing security worlds

Displaying information about your security


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.

nShield/payShield Administrator Guide Windows v5.5

171

11 Managing security worlds

Displaying information about your security


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.

nShield/payShield Administrator Guide Windows v5.5

172

11 Managing security worlds

Displaying information about your security


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.

nShield/payShield Administrator Guide Windows v5.5

173

11 Managing security worlds

Displaying information about your security


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.

nShield/payShield Administrator Guide Windows v5.5

174

11 Managing security worlds

Displaying information about your security


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:

nShield/payShield Administrator Guide Windows v5.5

175

11 Managing security worlds

Displaying information about your security


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.

nShield/payShield Administrator Guide Windows v5.5

176

11 Managing security worlds

Displaying information about your security


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.

nShield/payShield Administrator Guide Windows v5.5

177

11 Managing security worlds

Displaying information about your security


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.

nShield/payShield Administrator Guide Windows v5.5

178

11 Managing security worlds

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.

nShield/payShield Administrator Guide Windows v5.5

179

11 Managing security worlds

Windows Cryptographic Services Provider


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

nShield/payShield Administrator Guide Windows v5.5

180

11 Managing security worlds

Windows Cryptographic Services Provider


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

nShield/payShield Administrator Guide Windows v5.5

181

11 Managing security worlds

Windows Cryptographic Services Provider


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

nShield/payShield Administrator Guide Windows v5.5

182

11 Managing security worlds

Windows Cryptographic Services Provider


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

nShield/payShield Administrator Guide Windows v5.5

183

11 Managing security worlds

Windows Cryptographic Services Provider


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

nShield/payShield Administrator Guide Windows v5.5

184

11 Managing security worlds

Transferring keys between security worlds

Transferring keys between security worlds


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.

nShield/payShield Administrator Guide Windows v5.5

185

11 Managing security worlds

3.

Transferring keys between security worlds

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.

nShield/payShield Administrator Guide Windows v5.5

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.

About payShield Card Sets


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.

nShield/payShield Administrator Guide Windows v5.5

187

12 About payShield installations

About payShield Card Sets

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.

nShield/payShield Administrator Guide Windows v5.5

188

12 About payShield installations

About payShield Card Sets

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.

nShield/payShield Administrator Guide Windows v5.5

189

12 About payShield installations

Supported payShield Key Types

Supported payShield Key Types


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

nShield/payShield Administrator Guide Windows v5.5

190

12 About payShield installations

payShield security world properties

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.

payShield security world properties


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.

nShield/payShield Administrator Guide Windows v5.5

191

12 About payShield installations

payShield security world properties

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.

nShield/payShield Administrator Guide Windows v5.5

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.

nShield/payShield Administrator Guide Windows v5.5

193

13 Remote Operator Card Sets

Configuring Remote Operator

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.

Configuring Remote Operator


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.

nShield/payShield Administrator Guide Windows v5.5

194

13 Remote Operator Card Sets

Configuring Remote Operator

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.

nShield/payShield Administrator Guide Windows v5.5

195

13 Remote Operator Card Sets

Configuring Remote Operator

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:

Module #1 Slot #0 IC 1
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:

nShield/payShield Administrator Guide Windows v5.5

196

13 Remote Operator Card Sets

1.

Configuring Remote Operator

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.

nShield/payShield Administrator Guide Windows v5.5

197

13 Remote Operator Card Sets

Configuring Remote Operator

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.

nShield/payShield Administrator Guide Windows v5.5

198

13 Remote Operator Card Sets

Configuring Remote Operator

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.

nShield/payShield Administrator Guide Windows v5.5

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.

Replacing an Operator Cards pass phrase


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.

nShield/payShield Administrator Guide Windows v5.5

200

14 Administration tasks with cards and softcards

Replacing an Operator Cards pass phrase

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.

nShield/payShield Administrator Guide Windows v5.5

201

14 Administration tasks with cards and softcards

Replacing Operator Card Sets

Replacing Operator Card Sets


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.

nShield/payShield Administrator Guide Windows v5.5

202

14 Administration tasks with cards and softcards

Note

Replacing Operator Card Sets

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.

Start KeySafe. (For an introduction to KeySafe and information


on starting the software, see the appropriate Operator Guide for
your module.)

2.

Click the Cards menu button. KeySafe takes you to the Card
Operations panel.

nShield/payShield Administrator Guide Windows v5.5

203

14 Administration tasks with cards and softcards

3.

Replacing Operator Card Sets

Click the Replace OCS navigation button, and KeySafe takes you
to the Replace Operator Card Set panel:

nShield/payShield Administrator Guide Windows v5.5

204

14 Administration tasks with cards and softcards

Replacing Operator Card Sets

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.

nShield/payShield Administrator Guide Windows v5.5

205

14 Administration tasks with cards and softcards

6.

Note

Replacing Operator Card Sets

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.

nShield/payShield Administrator Guide Windows v5.5

206

14 Administration tasks with cards and softcards

Replacing Operator Card Sets

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.

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

nShield/payShield Administrator Guide Windows v5.5

207

14 Administration tasks with cards and softcards

Replacing Operator Card Sets

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.

nShield/payShield Administrator Guide Windows v5.5

208

14 Administration tasks with cards and softcards

9.

Replacing Operator Card Sets

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

nShield/payShield Administrator Guide Windows v5.5

209

14 Administration tasks with cards and softcards

Note

mark key-spec

module number

quit

recover

rescan

revert key-spec

save key-spec

status

target cardset-spec

unmark key-spec

Replacing Operator Card Sets

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:

nShield/payShield Administrator Guide Windows v5.5

210

14 Administration tasks with cards and softcards

Replacing Operator Card Sets

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.

nShield/payShield Administrator Guide Windows v5.5

211

14 Administration tasks with cards and softcards

Replacing Operator Card Sets

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

nShield/payShield Administrator Guide Windows v5.5

212

14 Administration tasks with cards and softcards

Replacing Operator Card Sets

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

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

nShield/payShield Administrator Guide Windows v5.5

213

14 Administration tasks with cards and softcards

Replacing Operator Card Sets

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.

nShield/payShield Administrator Guide Windows v5.5

214

14 Administration tasks with cards and softcards

Replacing Operator Card Sets

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.

nShield/payShield Administrator Guide Windows v5.5

215

14 Administration tasks with cards and softcards

Replacing Operator Card Sets

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.

nShield/payShield Administrator Guide Windows v5.5

216

14 Administration tasks with cards and softcards

Replacing Operator Card Sets

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

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.

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

nShield/payShield Administrator Guide Windows v5.5

217

14 Administration tasks with cards and softcards

Changing pass phrases with cardpp

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

Changing pass phrases with cardpp


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

nShield/payShield Administrator Guide Windows v5.5

218

14 Administration tasks with cards and softcards

Changing pass phrases with cardpp

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 created a security world with pass phrase recovery

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.

nShield/payShield Administrator Guide Windows v5.5

219

14 Administration tasks with cards and softcards

Changing pass phrases with ppmk

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.

Changing pass phrases with ppmk


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 created a security world with pass phrase recovery

have sufficient cards from the Administrator Card Set to


authorize the action.

If these conditions are met, take the following steps:

nShield/payShield Administrator Guide Windows v5.5

220

14 Administration tasks with cards and softcards

1.

Replacing the Administrator Card Set

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


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.

nShield/payShield Administrator Guide Windows v5.5

221

14 Administration tasks with cards and softcards

Replacing the Administrator Card Set

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
Administrator Card Set.
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
Administrator Card Set.
1.

Start KeySafe. (For an introduction to KeySafe and information


on starting the software, see the appropriate Operator Guide for
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

nShield/payShield Administrator Guide Windows v5.5

222

14 Administration tasks with cards and softcards

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

Replacing the Administrator Card Set

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.

nShield/payShield Administrator Guide Windows v5.5

223

14 Administration tasks with cards and softcards

Replacing the Administrator Card Set

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.

nShield/payShield Administrator Guide Windows v5.5

224

14 Administration tasks with cards and softcards

Replacing the Administrator Card Set

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.

nShield/payShield Administrator Guide Windows v5.5

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.

nShield/payShield Administrator Guide Windows v5.5

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.

nShield/payShield Administrator Guide Windows v5.5

227

15 nShield Administrator Utilities

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

nShield/payShield Administrator Guide Windows v5.5

228

15 nShield Administrator Utilities

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:

nShield/payShield Administrator Guide Windows v5.5

229

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

230

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

231

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

232

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

233

15 nShield Administrator Utilities

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

nShield/payShield Administrator Guide Windows v5.5

234

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

235

15 nShield Administrator Utilities

enquiry

features enabled

For modules that support enquiry level Six version 1 or


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

For modules that support enquiry level Six version 2 or


greater, this is the version serial number of the module.
remote server port

For modules that support enquiry level Six version 4 or


greater, this is the port on which the hardserver listens for
communications from remote modules. (The default is
9004.)
kneti hash

For modules that support enquiry level Six version 4 or


greater, this is the HKNETI key hash (if present) of this
module.

nShield/payShield Administrator Guide Windows v5.5

236

15 nShield Administrator Utilities

enquiry

rec. LongJobs queue

For modules that support enquiry level Six version 5 or


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

For modules that support enquiry level Six version 5 or


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

nShield/payShield Administrator Guide Windows v5.5

237

15 nShield Administrator Utilities

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

nShield/payShield Administrator Guide Windows v5.5

238

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

239

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

240

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

241

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

242

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

243

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

244

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

245

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

246

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

247

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

248

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

249

15 nShield Administrator Utilities

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:

nShield/payShield Administrator Guide Windows v5.5

250

15 nShield Administrator Utilities

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

nShield/payShield Administrator Guide Windows v5.5

251

15 nShield Administrator Utilities

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

nShield/payShield Administrator Guide Windows v5.5

252

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

253

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

254

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

255

15 nShield Administrator Utilities

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

nShield/payShield Administrator Guide Windows v5.5

256

15 nShield Administrator Utilities

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:

nShield/payShield Administrator Guide Windows v5.5

257

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

258

15 nShield Administrator Utilities

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

nShield/payShield Administrator Guide Windows v5.5

259

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

260

15 nShield Administrator Utilities

new-world

Module reprogramming options


-S, --no-remoteshare-cert

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.

nShield/payShield Administrator Guide Windows v5.5

261

15 nShield Administrator Utilities

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

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

nShield/payShield Administrator Guide Windows v5.5

262

15 nShield Administrator Utilities

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

nShield/payShield Administrator Guide Windows v5.5

263

15 nShield Administrator Utilities

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

nShield/payShield Administrator Guide Windows v5.5

264

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

265

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

266

15 nShield Administrator Utilities

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.

Action selection options


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

nShield/payShield Administrator Guide Windows v5.5

267

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

268

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

269

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

270

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

271

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

272

15 nShield Administrator Utilities

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.

Action selection options


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

nShield/payShield Administrator Guide Windows v5.5

273

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

274

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

275

15 nShield Administrator Utilities

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:

nShield/payShield Administrator Guide Windows v5.5

276

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

277

15 nShield Administrator Utilities

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

These options specify the module to use. The default is 1.

nShield/payShield Administrator Guide Windows v5.5

278

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

279

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

280

15 nShield Administrator Utilities

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

nShield/payShield Administrator Guide Windows v5.5

281

15 nShield Administrator Utilities

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)

nShield/payShield Administrator Guide Windows v5.5

282

15 nShield Administrator Utilities

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

These options specify the module to use. The default is 1.


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

nShield/payShield Administrator Guide Windows v5.5

283

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

284

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

285

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

286

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

287

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

288

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

289

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

290

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

291

15 nShield Administrator Utilities

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

nShield/payShield Administrator Guide Windows v5.5

292

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

293

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

294

15 nShield Administrator Utilities

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
Module 2 slot 2: empty
Insert/change card(s) (or change module mode).

nShield/payShield Administrator Guide Windows v5.5

295

15 nShield Administrator Utilities

preload

Insert a card in the smart card reader, and preload displays:


Loading cardset(s):
Module 2 slot 0: empty
Module 2 slot 2: empty
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: empty
Module 2 slot 2: empty
Module 2 slot 0: 'pt2' #1
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: empty
Module 2 slot 2: empty
Module 2 slot 0: 'pt2' #1
Module 2 slot 0:- passphrase supplied - reading card
Module 2 slot 0: empty
Module 2 slot 0: 'ct' #1
Module 2 slot 0: Read this card? (press Return)

nShield/payShield Administrator Guide Windows v5.5

296

15 nShield Administrator Utilities

preload

Press Enter to confirm reading this card, and preload displays:


Loading cardset(s):
Module 2 slot 0: empty
Module 2 slot 2: empty
Module 2 slot 0: 'pt2' #1
Module 2 slot 0:- passphrase supplied - reading card
Module 2 slot 0: empty
Module 2 slot 0: 'ct' #1
Module 2 slot 0:- confirmed - reading card
Module #2 Slot #0: Remove 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
Loaded simple test3 key (RSAPrivate) on modules 2
Loaded simple test4 key (RSAPrivate) on modules 2
Loaded simple test5 key (RSAPrivate) on modules 2
Loaded simple test6 key (RSAPrivate) on modules 2
Loaded simple test7 key (RSAPrivate) on modules 2
Loaded simple test8 key (RSAPrivate) on modules 2
Loaded simple test9 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

nShield/payShield Administrator Guide Windows v5.5

297

15 nShield Administrator Utilities

preload

The preload command then displays the following message:


Loading 'pt2':
Module 1 slot 0: empty
Module 2 slot 0: empty
Module 2 slot 2: empty
Insert/change card(s) (or change module mode).

Insert a card in module 1, and preload displays:


Loading `pt2':
Module 1 slot 0: empty
Module 2 slot 0: empty
Module 2 slot 2: empty
Module 1 slot 0: `pt2' #1
Module 1 slot 0: Enter passphrase:

Enter the appropriate pass phrase, and preload displays:


Loading 'pt2':
Module 1 slot 0: empty
Module 2 slot 0: empty
Module 2 slot 2: empty
Module 1 slot 0: 'pt2' #1
Module 1 slot 0:- passphrase supplied - reading card
Module 1: completed.
Module #1 Slot #0: Remove card.

Remove the card, and preload displays:


Loading 'pt2':
Module 1 slot 0: empty
Module 2 slot 0: empty
Module 2 slot 2: empty
Module 1 slot 0: 'pt2' #1
Module 1 slot 0:- passphrase supplied - reading card
Module 1: completed.
Module #1 Slot #0: Insert appropriate card.

nShield/payShield Administrator Guide Windows v5.5

298

15 nShield Administrator Utilities

preload

Inset the appropriate card in module 2, and preload displays:


Loading 'pt2':
Module 1 slot 0: empty
Module 2 slot 0: empty
Module 2 slot 2: empty
Module 1 slot 0: 'pt2' #1
Module 1 slot 0:- passphrase supplied - reading card
Module 1: completed.
Module 2 slot 0: 'pt2' #1
Module #1 Slot #0: Insert appropriate card.

Press the TAB key to switch messages, and preload displays:


Loading 'pt2':
Module 1 slot 0: empty
Module 2 slot 0: empty
Module 2 slot 2: empty
Module 1 slot 0: 'pt2' #1
Module 1 slot 0:- passphrase supplied - reading card
Module 1: completed.
Module 2 slot 0: 'pt2' #1
Module 2 slot 0: Enter passphrase:

Enter the appropriate pass phrase, and preload displays:


Loading 'pt2':
Module 1 slot 0: empty
Module 2 slot 0: empty
Module 2 slot 2: empty
Module 1 slot 0: 'pt2' #1
Module 1 slot 0:- passphrase supplied - reading card
Module 1: completed.
Module 2 slot 0: 'pt2' #1
Module 2 slot 0:- passphrase supplied - reading card
Card reading complete.
Loaded seeconf testconf key (DES3) on modules 1, 2
Loading complete; now pausing

nShield/payShield Administrator Guide Windows v5.5

299

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

300

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

301

15 nShield Administrator Utilities

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:\nfast\bin\rfs-setup.exe
C:\nfast\bin\rfs-setup.exe
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.

nShield/payShield Administrator Guide Windows v5.5

302

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

303

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

304

15 nShield Administrator Utilities

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

nShield/payShield Administrator Guide Windows v5.5

305

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

306

15 nShield Administrator Utilities

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

Action selection options


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

nShield/payShield Administrator Guide Windows v5.5

307

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

308

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

309

15 nShield Administrator Utilities

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:

nShield/payShield Administrator Guide Windows v5.5

310

15 nShield Administrator Utilities

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

nShield/payShield Administrator Guide Windows v5.5

311

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

312

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

313

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

314

15 nShield Administrator Utilities

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

nShield/payShield Administrator Guide Windows v5.5

315

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

316

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

317

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

318

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

319

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

320

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

321

15 nShield Administrator Utilities

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.

nShield/payShield Administrator Guide Windows v5.5

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

nShield/payShield Administrator Guide Windows v5.5

323

A Upgrading module firmware

Firmware on the CD-ROM

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.

Firmware on the CD-ROM


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.

nShield/payShield Administrator Guide Windows v5.5

324

A Upgrading module firmware

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.

nShield/payShield Administrator Guide Windows v5.5

325

A Upgrading module firmware

Firmware installation overview

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.

Firmware installation overview


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.

nShield/payShield Administrator Guide Windows v5.5

326

A Upgrading module firmware

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.

nShield/payShield Administrator Guide Windows v5.5

327

A Upgrading module firmware

Figure 7

PCI modules

PCI module back panel

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.

nShield/payShield Administrator Guide Windows v5.5

328

A Upgrading module firmware

After firmware installation

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 firmware installation


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.

nShield/payShield Administrator Guide Windows v5.5

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 component bundles


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)

nShield/payShield Administrator Guide Windows v5.5

330

B Components on nCipher CD-ROMs

nCipher component bundles

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

nShield/payShield Administrator Guide Windows v5.5

331

B Components on nCipher CD-ROMs

nCipher component bundles

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

nShield/payShield Administrator Guide Windows v5.5

332

B Components on nCipher CD-ROMs

nCipher component bundles

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
pysrc Python source for developers
nfpy nFPython header files

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

nShield/payShield Administrator Guide Windows v5.5

333

B Components on nCipher CD-ROMs

nCipher component bundles

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
pysrc Python source for developers
nfpy nFPython header files
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

nShield/payShield Administrator Guide Windows v5.5

334

B Components on nCipher CD-ROMs

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
hwsp Hardware Support (mandatory)
ctls Core Tools (recommended)
javasp Java Support (including KeySafe)
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
nCipher supplies the following component bundles and additional
components on the CipherTools CD-ROM:
Component Bundles
hwsp Hardware Support (mandatory)
ctls Core Tools (recommended)
javasp Java Support (including KeySafe)
psusr payShield User
ctd CipherTools Developer
jd Java Developer

nShield/payShield Administrator Guide Windows v5.5

335

B Components on nCipher CD-ROMs

CodeSafe CD-ROM

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
sslyp Open SSL source code patch file

CodeSafe CD-ROM
nCipher supplies the following component bundles and additional
components on the CodeSafe CD-ROM:
Component Bundles
hwsp Hardware Support (mandatory)
ctls Core Tools (recommended)
javasp Java Support (including KeySafe)
csd CodeSafe Developer
jd Java Developer

Individual Components
gccsrc Prebuilt arm-gcc for Codesafe/C
gccsrc Prebuilt powerpcm-gcc for Codesafe/C
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

nShield/payShield Administrator Guide Windows v5.5

336

B Components on nCipher CD-ROMs

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.

nShield/payShield Administrator Guide Windows v5.5

337

B Components on nCipher CD-ROMs

PKCS #11 applications

Windows CSP
If you require the Windows CSP, you must install the CSP
components:

mscapic nCipher Win 2000 domestic strength CSP

mscapi CSP support files

PKCS #11 applications


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 .

nShield/payShield Administrator Guide Windows v5.5

338

B Components on nCipher CD-ROMs

nCipher SNMP monitoring agent

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.

nCipher SNMP monitoring agent


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.

nShield/payShield Administrator Guide Windows v5.5

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.

nShield/payShield Administrator Guide Windows v5.5

340

C Environment variables

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.

nShield/payShield Administrator Guide Windows v5.5

341

C Environment variables

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

This variable is used to filter log messages by


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

This variable is used to filter log messages by


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.

nShield/payShield Administrator Guide Windows v5.5

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.

Environment variables to control logging


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

nShield/payShield Administrator Guide Windows v5.5

343

D Logging and debugging

Environment variables to control logging

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.

nShield/payShield Administrator Guide Windows v5.5

logdetail flags

stack_line

344

D Logging and debugging

Environment variables to control logging

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.

nShield/payShield Administrator Guide Windows v5.5

msg_file

345

D Logging and debugging

Environment variables to control logging

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
logging functionality found in previous nCipher support
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
logging functionality found in previous nCipher support
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.

nShield/payShield Administrator Guide Windows v5.5

346

D Logging and debugging

Environment variables to control logging

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.

nShield/payShield Administrator Guide Windows v5.5

347

D Logging and debugging

Logging from the nCipher CSP

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.

Logging from the nCipher CSP


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.

nShield/payShield Administrator Guide Windows v5.5

348

D Logging and debugging

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 "

nShield/payShield Administrator Guide Windows v5.5

349

D Logging and debugging

Hardserver debugging

Hardserver debugging
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.

Debugging information for payShield


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.

nShield/payShield Administrator Guide Windows v5.5

350

D Logging and debugging

Debugging information for payShield

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.

nShield/payShield Administrator Guide Windows v5.5

351

D Logging and debugging

Debugging information for Java

Debugging information for Java


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.

nShield/payShield Administrator Guide Windows v5.5

352

D Logging and debugging

3.

Debugging information for Java

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.

nShield/payShield Administrator Guide Windows v5.5

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.

nShield/payShield Administrator Guide Windows v5.5

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.

nShield/payShield Administrator Guide Windows v5.5

355

E Installed Utilities

Installed Utilities

Utility

Description

cspnvfix

This utility regenerates the


NVRAM key counter area for a
specified nCipher CSP key. It is
described in the Operator Guide.

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
containers. It is described in the
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.


It is described in the Operator
Guide.

genkeyprops

This utility is internal to nCipher.

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.

nShield/payShield Administrator Guide Windows v5.5

356

E Installed Utilities

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

This utility is internal to nCipher.

keytst

This utility displays information


about existing CSP key
containers. It is described in the
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
described in the Operator Guide.

loadrom

This utility loads new firmware


into a module. It is described in
loadrom on page 253.

nShield/payShield Administrator Guide Windows v5.5

357

E Installed Utilities

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

This utility is internal to nCipher.

nfkminfo

This utility displays information


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
described in the Operator Guide.

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.

nShield/payShield Administrator Guide Windows v5.5

358

E Installed Utilities

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

This utility displays information


about a payShield installation. It
is described in the Operator
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.
It is described in the Operator
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
described in the Operator Guide.

pubkey-find

This example utility returns


information the key, certificate, or
certificate request in a file. It is
described in the Operator Guide.

nShield/payShield Administrator Guide Windows v5.5

359

E Installed Utilities

Installed Utilities

Utility

Description

racs

This utility creates a new


Administrator Card Set.
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
described in the Operator Guide.

rdlinene

This utility is internal to nCipher.

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
described in the Operator Guide.

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
is described in the Operator
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.

nShield/payShield Administrator Guide Windows v5.5

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.

nShield/payShield Administrator Guide Windows v5.5

361

F The nCipher SNMP monitoring agent

Activating the nCipher SNMP 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.

Activating the nCipher SNMP agent


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.

nShield/payShield Administrator Guide Windows v5.5

362

F The nCipher SNMP monitoring agent

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]

nShield/payShield Administrator Guide Windows v5.5

363

F The nCipher SNMP monitoring agent

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.

nShield/payShield Administrator Guide Windows v5.5

364

F The nCipher SNMP monitoring agent

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/

nShield/payShield Administrator Guide Windows v5.5

365

F The nCipher SNMP monitoring agent

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.

nShield/payShield Administrator Guide Windows v5.5

366

F The nCipher SNMP monitoring agent

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.

Using the nCipher SNMP agent with a manager


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.

nShield/payShield Administrator Guide Windows v5.5

367

F The nCipher SNMP monitoring agent

Using the nCipher SNMP agent with a manager


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:

nShield/payShield Administrator Guide Windows v5.5

368

F The nCipher SNMP monitoring agent

Using the nCipher SNMP agent with a manager


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.

nShield/payShield Administrator Guide Windows v5.5

369

F The nCipher SNMP monitoring agent

Using the nCipher SNMP agent with a manager


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

nShield/payShield Administrator Guide Windows v5.5

370

F The nCipher SNMP monitoring agent

Using the nCipher SNMP agent with a manager


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

nShield/payShield Administrator Guide Windows v5.5

371

F The nCipher SNMP monitoring agent

Using the nCipher SNMP agent with a manager


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

nShield/payShield Administrator Guide Windows v5.5

372

F The nCipher SNMP monitoring agent

Using the nCipher SNMP agent with a manager


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.

nShield/payShield Administrator Guide Windows v5.5

373

F The nCipher SNMP monitoring agent

Using the nCipher SNMP agent with a manager


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

nShield/payShield Administrator Guide Windows v5.5

374

F The nCipher SNMP monitoring agent

Using the nCipher SNMP agent with a manager


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.

nShield/payShield Administrator Guide Windows v5.5

375

F The nCipher SNMP monitoring agent

Using the nCipher SNMP agent with a manager


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.

nShield/payShield Administrator Guide Windows v5.5

376

F The nCipher SNMP monitoring agent

Using the nCipher SNMP agent with a manager


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

The value unset is never returned by the key


table. It is used in the key query field to
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.

nShield/payShield Administrator Guide Windows v5.5

377

F The nCipher SNMP monitoring agent

Using the nCipher SNMP agent with a manager


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

The value unset is never returned by the key


table. It is used in the key query field to
mean do not care.

keyQueryProtection

R/W

Enum
1: Module
2: Cardset
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.

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)

nShield/payShield Administrator Guide Windows v5.5

Remarks

378

F The nCipher SNMP monitoring agent

Using the nCipher SNMP agent with a manager


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

nShield/payShield Administrator Guide Windows v5.5

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

F The nCipher SNMP monitoring agent

Using the nCipher SNMP agent with a manager


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)

nShield/payShield Administrator Guide Windows v5.5

380

F The nCipher SNMP monitoring agent

Using the nCipher SNMP agent with a manager


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

nShield/payShield Administrator Guide Windows v5.5

Repository name

381

F The nCipher SNMP monitoring agent

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.

nShield/payShield Administrator Guide Windows v5.5

382

F The nCipher SNMP monitoring agent

Useful nCipher SNMP agent command-line


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

nShield/payShield Administrator Guide Windows v5.5

383

F The nCipher SNMP monitoring agent

Useful nCipher SNMP agent command-line


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

nShield/payShield Administrator Guide Windows v5.5

384

F The nCipher SNMP monitoring agent

Using the SNMP command line tools

Using the SNMP command line tools


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.

nShield/payShield Administrator Guide Windows v5.5

385

F The nCipher SNMP monitoring agent

Using the SNMP command line tools

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

nShield/payShield Administrator Guide Windows v5.5

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.