nShield/payShield Operator Guide

Windows
Version: 5.5
Date: 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 Operator Guide Windows v5.5 2

Contents

Chapter 1: Introduction 7
General information 7
Audience 8
Contents of this guide 8
Conventions 9
Additional Documentation 12
Further information 12

Chapter 2: nCipher security worlds 14

Security 16
Application independence 20
Platform independence 21
Flexibility 21
Robustness 26
Scalability 30
KeySafe and security worlds 31
Applications and the security world 32
The nCipher PKCS #11 library and security worlds 33
Risks 33

Chapter 3: Using KeySafe 35

Starting KeySafe 36

nShield/payShield Operator Guide Windows v5.5 3

 The KeySafe window 37
Errors 46

Chapter 4: Managing cards and softcards 49

Creating Operator Card Sets 50
Creating softcards 66
Erasing Operator Cards and softcards 71
Viewing cards and softcards 75
Changing card and softcard pass phrases 81
Lost cards 85

Chapter 5: Working with keys 86

Generating keys 86
Importing keys 93
Listing supported applications with generatekey 98
Retargeting keys with generatekey 98
Viewing keys 99
Discarding keys 103
Restoring keys 103

Chapter 6: nCipher application interfaces 104

Cryptographic Hardware Interface Library (CHIL) 104
nCipherKM JCA/JCE CSP 105
PKCS #11 115
Check Point VPN-1/Firewall-1 140
nCipher native and Custom applications 140
Microsoft Cryptographic API 141

nShield/payShield Operator Guide Windows v5.5 4

Chapter 7: nShield Operator Utilities 142
Help options 142
bulkerase 143
cardpp 144
ckcerttool 146
checkmod 148
cksigtest 149
createocs 153
cryptest 156
cspcheck 158
cspimport 159
cspmigrate 168
cspnvfix 174
csptest 175
csputils 179
des_kat 184
enquiry 185
floodtest 194
fwcheck 198
generatekey 200
hardserver 221
initunit 223
keytst 225
kmfile-dump 231
kptest 233

nShield/payShield Operator Guide Windows v5.5 5

 mkaclx 238
modstate 242
ncdate 243
ncthread-test 245
ncversions 247
nfkminfo 249
nfkmverify 251
nopclearfail 257
nvram-backup 260
nvram-sw 266
pollbare 272
postrocs 273
ppmk 274
preload 277
pubkey-find 288
randchk 293
rfs-setup 294
rfs-sync 296
sigtest 299
slotinfo 304
stattree 306

Appendix A: Cryptographic algorithms 315

FIPS Information 317

nShield/payShield Operator Guide Windows v5.5 6

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

This guide describes key-management tasks, which do not require an

Administrator Card Set. It contains instructions for performing these
tasks using KeySafe or the command line.

nShield/payShield Operator Guide Windows v5.5 7

1 Introduction Audience

The Administrator Guide describes how to install the required

software and how to manage security worlds.

Audience
Read this guide if you need to manage keys or perform other tasks on
an nShield module that do not require an Administrator Card.

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: Using KeySafe introduces KeySafe, nCipher’s security

world management tool.

Chapter 4: Managing cards and softcards describes how to create

Operator Card Sets.

Chapter 5: Working with keys describes how to generate and import

keys, view existing keys, and dispose of keys that are no longer
required.

Chapter 6: nCipher application interfaces describes how to configure

your application to use a module.

Chapter 7: nShield Operator Utilities describes the command-line

utility functions that are supplied by nCipher.

nShield/payShield Operator Guide Windows v5.5 8

1 Introduction Conventions

Appendix A: Cryptographic algorithms lists the cryptographic

algorithms that are supported by nCipher modules.

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 an nCipher nToken
nC2023p-000 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, Any nCipher module that
nC40nnX-nnn, or supports key management
nHnnnn (nForce, nShield,
payShield, netHSM
300/800/1600, payShield
net, or payShield Ultra
net).
OEM PCI 1600 nC3033P-1600 The OEM PCI 1600
key-management module modules are supplied to
OEM customers only.

In this table, n is any integer.

nShield/payShield Operator Guide Windows v5.5 9

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

nShield/payShield Operator Guide Windows v5.5 10

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 Operator Guide Windows v5.5 11

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.pdf
hardware installation and troubleshooting; a
printed copy is also supplied with nCipher
modules (part number N-001027).
CodeSafe/C Developer’s Guide, for reference CodeSafe_C_Developer.pdf
material about developing in C for the Secure
Execution Environment.
Integration Guide, for information on developing Integration_Guide.pdf
applications with an nCipher module using
industry standard interfaces.
nCore Developer’s Guide, for information on nCore_Developer_Guide.pdf
developing applications with an nCipher module
using the nCipher API and NFKM library.
nCore Developer’s Reference, for reference nCore_Developer_Ref.pdf
material covering nCipher API, C generic stub,
and NFKM libraries.
payShield Developer Reference, for payShield payShield_Developer_Ref.pdf
developer reference material
Key-loading Solution Guide, for information Key-loading_Solution.pdf
about nCipher’s key-loading solution.

Further information
Release notes containing the latest information about the nCipher
products are available in the release directory of the CD-ROM.

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.

nShield/payShield Operator Guide Windows v5.5 12

1 Introduction Further information

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 [email protected].

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 [email protected].

nShield/payShield Operator Guide Windows v5.5 13

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 life-
cycle 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 Operator Guide Windows v5.5 14

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
19 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 19 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 Operator Guide Windows v5.5 15

2 nCipher security worlds Security

Figure 1 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 Operator Guide Windows v5.5 16

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:
• 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.
Note 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 Operator Guide Windows v5.5 17

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 the
Administrator Guide for more information.

nShield/payShield Operator Guide Windows v5.5 18

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 world’s
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 140-
2 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 Operator Guide Windows v5.5 19

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 Operator Guide Windows v5.5 20

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 Operator Guide Windows v5.5 21

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 Operator Guide Windows v5.5 22

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 Operator Guide Windows v5.5 23

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 28.
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 card and softcard pass
phrases on page 81. 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 module’s 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.

Keys that are protected by a given Operator Card Set cannot be shared
simultaneously between a large pool of modules.

nShield/payShield Operator Guide Windows v5.5 24

2 nCipher security worlds Flexibility

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:
• 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.
Note 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.

You can manually remove all keys protected by persistent cards by

pressing the module’s 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.

nShield/payShield Operator Guide Windows v5.5 25

2 nCipher security worlds Robustness

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.

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.

nShield/payShield Operator Guide Windows v5.5 26

2 nCipher security worlds Robustness

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.

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.

nShield/payShield Operator Guide Windows v5.5 27

2 nCipher security worlds Robustness

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.

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

nShield/payShield Operator Guide Windows v5.5 28

2 nCipher security worlds Robustness

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, softcard-
protected 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.

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.

nShield/payShield Operator Guide Windows v5.5 29

2 nCipher security worlds Scalability

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
kmdata directory. Client modules that access data in this way are
described as cooperating clients. See the Administrator Guide for
more information.

nShield/payShield Operator Guide Windows v5.5 30

2 nCipher security worlds KeySafe and security worlds

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:

• create a security world and its Administrator Card Set, either
FIPS 140-2 level 2 or 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.
• add a module to a security world

nShield/payShield Operator Guide Windows v5.5 31

2 nCipher security worlds Applications and the 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.

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.

nShield/payShield Operator Guide Windows v5.5 32

2 nCipher security worlds The nCipher PKCS #11 library 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 ([email protected]).

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.

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.

nShield/payShield Operator Guide Windows v5.5 33

2 nCipher security worlds Risks

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:
• 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.
Note 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 Operator Guide Windows v5.5 34

Chapter 3: Using KeySafe
This chapter introduces KeySafe, nCipher’s security world
management tool. It describes:
• how to start KeySafe
• KeySafe’s 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:
• replacing an Administrator Card Set
• listing the Operator Card Sets in the current security world
• changing the pass phrase on an Operator Card
• removing a lost Operator Card Set from a security world
• erasing an Operator Card
• adding a new key to a security world
• importing an existing key into a security world
• listing the keys in the current security world
• deleting a key from a security world.
Note By default, KeySafe uses the same mechanisms and supports the same
features and applications as the generatekey command-line utility (see
generatekey on page 200).

nShield/payShield Operator Guide Windows v5.5 35

3 Using KeySafe Starting KeySafe

Starting KeySafe
In order to use KeySafe, Sun’s 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.

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 the Administrator Guide for information on setting these
parameters. (For information about setting environment variables,
see the appropriate Administrator Guide for your module.)

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 Operator Guide Windows v5.5 36

3 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 Operator Guide Windows v5.5 37

3 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 Operator Guide Windows v5.5 38

3 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
dialog’s 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 KeySafe’s 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 Operator Guide Windows v5.5 39

3 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 the Administrator Guide)
• pass phrase recovery is enabled for a security world (for more
information on pass phrase recovery, see the Administrator
Guide)

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 nCipher’s
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 Operator Guide Windows v5.5 40

3 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 module’s electronic serial number (ESN), which is a unique
identifier. You must quote a module’s ESN if you need to contact
Support at nCipher. Keep a record of the ESN(s) associated with
your module(s).
• the module’s state, which will be one of the following:
- PreInitMode, indicating that the module is in the pre-
initialization 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 module’s 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 Operator Guide Windows v5.5 41

3 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 pre-
maintenance 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 pre-
initialization state.
Note For information about putting a module into the pre-initialization
state, see the Administrator Guide. After you have initialized a
security world, in order for a module to be usable, you must put it into
the operational state (see the appropriate Administrator Guide for
your module).
- 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 module’s firmware
• whether the module has a Real Time Clock (RTC)
• whether the module has nonvolatile memory (NVRAM).

nShield/payShield Operator Guide Windows v5.5 42

3 Using KeySafe The KeySafe window

Main panel area

KeySafe’s 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 Operator Guide Windows v5.5 43

3 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 Operator Guide Windows v5.5 44

3 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 message’s OK button, and then provide or correct
the necessary information.

After you successfully issue a command by clicking a command

button, the sidebar’s 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 Operator Guide Windows v5.5 45

3 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 the Administrator Guide 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
221.
3. Restart KeySafe.

nShield/payShield Operator Guide Windows v5.5 46

3 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:
1. Exit KeySafe.
2. Update the nCipher firmware as described in the Administrator
Guide.
3. Restart KeySafe.
Note 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 Operator Guide Windows v5.5 47

3 Using KeySafe Errors

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

nShield/payShield Operator Guide Windows v5.5 48

Chapter 4: Managing cards and softcards
When a security world has been created, you can create Operator Card
Sets, softcards, and keys. See Chapter 5: Working with keys for
information about creating keys.

The security world has three levels of protection for keys:

• keys protected directly by the security world, which can be used
at any time without further authorization
• keys protected by a softcard, which can only be used by the
operator who possesses the relevant pass phrases
• keys protected by an Operator Card Set, which can only be used
by the operator who possesses the Operator Card Set and, if these
have been set, any relevant pass phrases.

This chapter describes tasks with Operator Card Sets and softcards.
These tasks do not normally require an Administrator Card Set to
authorize them.
Note Some tasks described in this chapter, when performed within a
security world that complies with the FIPS 140-2 level 3 standard, do
require either an Administrator Card or an Operator Card from an
existing set for authorization.

This chapter describes the following tasks:

• creating Operator Card Sets
• creating softcards
• erasing Operator Cards
• erasing softcards
• viewing Card Sets
• viewing softcards
• changing a pass phrase

For other card tasks, see the Administrator Guide.

nShield/payShield Operator Guide Windows v5.5 49

4 Managing cards and softcards Creating Operator Card Sets

Creating Operator Card Sets

You must create an Operator Card Set before you create the keys that
it is to protect.

Operator Card Sets belong to the security world in which they are
created. When you create an Operator Card Set, the smart cards in that
set can only be read by modules belonging to the same security world.
The cards cannot be read, erased, or reformatted by a module from a
different security world.
Note IIS can only use Operator Card Sets that require a single card for
authorization and which do not have a pass phrase set.
Note iPlanet can only use Operator Card Sets that require a single card for
authorization. This card must have a pass phrase set.
Note Netscape Certificate Server can only use Operator Card Sets that
require a single card for authorization. This card must have a pass
phrase set.

Persistent Operator Card Sets

If you create a standard Operator Card Set, you can only use the keys
that are protected by the card while the last required smart card
remains in the smart card reader. If you want to be able to use the keys
after you have removed the card, you must make that card set
persistent.

Keys protected by a persistent card set can be used for as long as the
application that loaded the Operator Card Set remains connected to
the module (unless that application removes the keys).

Time-outs
Operator Card Sets can be created with a time-out, so that they can
only be used for limited time after the Operator Card Set is loaded. An
Operator Card Set is loaded by most applications at start up or when
the user supplies the last required pass phrase. Once an Operator Card

nShield/payShield Operator Guide Windows v5.5 50

4 Managing cards and softcards Creating Operator Card Sets

Set has timed out, it is not loadable by another application unless it is

removed and reinserted. Time-outs operate independently of Operator
Card Set persistence.

FIPS 140-2 level 3-compliant security worlds

When you attempt to create an Operator Card Set for a security world
that complies with FIPS 140-2 level 3, you are prompted to insert an
Administrator Card or Operator Card from an existing set. You may
need to specify to the application the slot you are going to use to insert
the card. You need to insert the card only once in a session.

Creating an Operator Card Set with KeySafe

KeySafe enables you to create Operator Card Sets with:
• their own names
• K-of-N policies
• optional pass phrases for any card within a given set.
• formal FIPS 140-2 level 3 compliance.

To create an Operator Card Set with KeySafe, follow these steps:

1. Start KeySafe. (For an introduction to KeySafe and information
on starting the software, see Chapter 3: Using KeySafe.)
2. Click the Cards menu button. KeySafe takes you to the Card
Operations panel.

nShield/payShield Operator Guide Windows v5.5 51

4 Managing cards and softcards Creating Operator Card Sets

3. Click the Create New OCS navigation button. KeySafe takes you
to the Create Operator Card Set panel:

4. Enter a name for the card set.

5. If you are creating the card set in a FIPS 140-2 level 3
security world, insert an Administrator Card or an existing
Operator Card when prompted.
6. Choose whether you want pass phrase recovery to be enabled for
the card set.
7. Choose whether you want the card set to be used remotely. For
more information, see see the appropriate Administrator Guide
for your module type.
8. Choose whether you want this Operator Card Set to be persistent.
9. Enter the total number of Operator Cards (N) that you want this
Operator Card Set to have. This number must be less than or
equal to 64.

nShield/payShield Operator Guide Windows v5.5 52

4 Managing cards and softcards Creating Operator Card Sets

10. Choose whether you want this Operator Card Set to have a time-
out, after which the card set must be inserted again, and enter
value for the time-out length in seconds.
11. Enter the number of Operator Cards needed to re-create a key (K).
K must be less than or equal to N.
12. When you have entered all the details, click the Create OCS!
command button. KeySafe takes you to a new Create Operator
Card Set panel, which prompts you to insert a card to use as the
first card in the set:

13. Insert a blank card into the appropriate smart card slot. If you
insert a card from another Operator Card Set or another
security world, KeySafe asks whether you want to erase it. If you
insert an Administrator Card from the current security world,
KeySafe prevents you from accidentally erasing it.
Note When creating a card set, KeySafe recognizes cards that already
belong 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
receive a warning.

nShield/payShield Operator Guide Windows v5.5 53

4 Managing cards and softcards Creating Operator Card Sets

14. After you insert a blank card (or have erased an existing card),
click the OK button to continue the process of creating an
Operator Card Set. KeySafe takes you to the Set Card Protection
Pass Phrase panel:

nShield/payShield Operator Guide Windows v5.5 54

4 Managing cards and softcards Creating Operator Card Sets

Select whether or not you want to set a pass phrase for the
currently inserted card. Each card in a set can have an individual
pass phrase, and you can also create a set in which some cards
have pass phrases and others do not.
Note Because neither IIS nor OpenSSL/SSLeay have mechanisms for
entering pass phrases, you must not give pass phrases to Operator
Cards that are to be used with these applications.
If you want to set a pass phrase for the currently inserted card,
enter the same pass phrase in both text fields. A pass phrase can
contain any characters you can type except for tabs or carriage
returns (because these keys are used to move between data
fields).
You can change a pass phrase at any time. If you do not set a pass
phrase now, you can use KeySafe’s Change Pass Phrase option
(on the Examine/Change Card panel) to add one later. Likewise,
if you later decide that you do not need a pass phrase on a card,
you can use this option to remove it.
After entering your desired pass phrase (if any) in both text fields,
click the OK button. Unless you have entered details for the last
card in the set, KeySafe returns you to the Create Operator Card
Set panel and prompts you to enter the next card in the set to be
written.
15. After KeySafe has written the details of the last smart card in the
set, it displays a dialog box indicating that the Operator Card Set
has been successfully created. Click the OK button, and KeySafe
returns you to the Create Operator Card Set panel, where you can
create another Operator Card Set or choose a different operation
by clicking one of the menu buttons.

nShield/payShield Operator Guide Windows v5.5 55

4 Managing cards and softcards Creating Operator Card Sets

Creating an Operator Card Set with the CSP wizard

The nCipher CSP wizard enables you to create a K-of-N Operator
Card Set that is suitable for use with the nCipher Cryptographic
Service Provider (CSP). You can only create an Operator Card Set
using the CSP wizard if you already have a security world and have
an Administrator Card Set available for that security world.

To create an OCS by using the CSP wizard, follow these steps:

1. Ensure that you have created the security world and that all the
modules are in the operational state.
2. Run the wizard by double-clicking the icon on your desktop.
3. The wizard displays the window:

4. Click the Next button.

The wizard determines what actions to take based on the state of
the security world and of the modules that are attached to your
computer:

nShield/payShield Operator Guide Windows v5.5 56

4 Managing cards and softcards Creating Operator Card Sets

- If the wizard cannot find the security world, it displays the

following window:

In such a case, you should:

• cancel the operation
• check that you have correctly set the environment
variable NFAST_KMDATA
• copy the local sub-directory from the
NFAST_KMDATA world or from a backup tape of this
computer to the NFAST_KMDATA directory of this
computer
• run the wizard again.

nShield/payShield Operator Guide Windows v5.5 57

4 Managing cards and softcards Creating Operator Card Sets

- If there is an existing security world, the wizard displays the

following window:

• In order to use the existing security world, ensure that

the Use the existing security world option is selected, and
click the Next button.
• If there are any modules in the pre-initialization state,
the wizard adds them to the security world as described
in the Administrator Guide.

nShield/payShield Operator Guide Windows v5.5 58

4 Managing cards and softcards Creating Operator Card Sets

5. When all modules are in the operational state, the wizard displays
the following window:

6. Ensure that the Operator Card Set option is enabled, and then
select the Create a new Operator Card Set option.
If you want the Operator Card Set to be persistent, select the
Persistent option. Persistence is described in Persistent Operator
Card Sets on page 50.

nShield/payShield Operator Guide Windows v5.5 59

4 Managing cards and softcards Creating Operator Card Sets

7. Click the Next button, and if you have a FIPS world, the wizard
displays the following window:

Note This shows 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.
Under the constraints of level 3 of the FIPS 140-2 standard,
Operator Cards cannot be created without authorization. To
obtain authorization, insert any card from the Administrator Card
Set or any Operator Card belonging to the current security world.
The wizard does not enable the Next world, the wizard warns you
and prompts you for another card.
8. Click the Next button.
The wizard prompts you for a smart card to use as the first card
in the Operator Card Set.

nShield/payShield Operator Guide Windows v5.5 60

4 Managing cards and softcards Creating Operator Card Sets

9. Insert a blank smart card to be used as the Operator Card, and

click the Next button.
Do not use a card from the Administrator Card Set or an existing
Operator Card.
If you insert a card that is not blank, the installer asks you if you
want to erase it
10. When you have inserted an appropriate card, the wizard displays
the following window:

If you want to protect this card with a pass phrase, turn on the
Card will require a pass phrase option, and enter the pass phrase.
You must enter the pass phrase in both fields to ensure that you
have typed it correctly.
Note Operator Cards with pass phrases are required by the nCipher
PKCS #11 library.

nShield/payShield Operator Guide Windows v5.5 61

4 Managing cards and softcards Creating Operator Card Sets

11. If you have not yet written all the smart cards in the Operator
Card Set, the wizard prompts you for another card. Repeat step 9
and step 10 for all smart cards in the set.
12. When you have created the Operator Card Set, the wizard
displays the following window:

If you want to create another Operator Card Set, click the Back
button.
When you have created all the Operator Card Sets that you
require, click the Next button to install the CSP.

Creating the Operator Card Set from the command line

To create an Operator Card Set:

nShield/payShield Operator Guide Windows v5.5 62

4 Managing cards and softcards Creating Operator Card Sets

1. Use the command:

C:\nfast\bin\createocs -m MODULE|--module=MODULE -Q|--ocs-quorum=K/N

-N|--name=NAME [-M|--name-cards]
[[-p|--persist]|[-P|--no-persist]] [[-R|--no-pprecovery]|--pprecovery]
[-q|--remotely-readable] [-f|--force] [-T|--timeout=TIME]

In this command:
-m MODULE, --module=MODULE
These options specify the module number of the module
to be used to create the token. If you only have one
module, MODULE is 1.
-Q, --ocs-quorum=K/N
In these options, K is the minimum required number of
cards. If you do not specify the value K, the default is 1.
Note Some applications do not have mechanisms for requesting that cards
be inserted. Therefore any Operator Card Sets that you create for use
with these applications must have K=1.
N is the total number of cards. If you do not specify the
value N, the default is 1.
-N, --name=NAME
These options enable you to name the card set. The card
set must be named with this option before individual
cards can be named using the -M, --name-cards=NAME
options.
-M, --name-cards
These options enable you to name individual cards
within the card set. You can only use this option after
the card set has been named by using the --name=NAME

nShield/payShield Operator Guide Windows v5.5 63

4 Managing cards and softcards Creating Operator Card Sets

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 the Administrator Guide.
-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 Operator Guide Windows v5.5 64

4 Managing cards and softcards Creating Operator Card Sets

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 Operator Guide Windows v5.5 65

4 Managing cards and softcards Creating softcards

3. Type a pass phrase and press Enter . Alternatively, press Enter if

you do not want this card to have a pass phrase.
A pass phrase can be up to 1024 characters long.
If you entered a pass phrase, createocs prompts you to confirm it.
4. Type the pass phrase again and press Enter .
If the pass phrases do not match, createocs prompts you to input
and confirm the pass phrase again.
5. When the new card has been created, if you are creating a card set
with more than one card in it, createocs prompts you to insert
another card.
For each additional card in the Operator Card Set, follow the
instructions from step 2 through step 4.

Creating softcards
You must create a softcard before you create the keys that it is to
protect.

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).
Softcards belong to the security world in which they are created.

nShield/payShield Operator Guide Windows v5.5 66

4 Managing cards and softcards Creating softcards

A softcard’s pass phrase is set when you generate it, and you can use
a single softcard to protect multiple keys. Softcards are persistent;
after a softcard is loaded, it remains valid for loading the keys it
protects until its KeyID is destroyed.
Note It is possible to generate multiple softcards with the same name or
pass phrase. For this reason, the hash of each softcard is made unique
(unrelated to the hash of its pass phrase).
Note To use softcards with PKCS #11, you must have
CKNFAST_LOADSHARING set to a nonzero value. When using pre-
loaded softcards or other objects, the PKCS #11 library automatically
sets CKNFAST_LOADSHARING=1 (load-sharing mode on) unless it
has been explicitly set to 0 (load-sharing mode off).
As with Operator Card Sets, if debugging is enabled, a softcard’s pass
phrase hash is available in the debug output (as a parameter to a
ReadShare command).

You can create softcards from the command-line (see Creating

softcards with ppmk on page 67) or with KeySafe (see Creating
softcards with KeySafe on page 69).

Creating softcards with ppmk

To create a new softcard using the ppmk command-line utility, follow
these steps:

nShield/payShield Operator Guide Windows v5.5 67

4 Managing cards and softcards Creating softcards

1. Decide whether you want the new softcard’s pass phrase to be

recoverable or non-recoverable. To create a softcard with a
recoverable pass phrase, give the command:

ppmk.exe --new --recoverable NAME

To create a softcard with a non-recoverable pass phrase, give the

command:

ppmk.exe --new --non-recoverable NAME

In these commands, NAME specifies the name of the new

softcard to be created.
2. If you are working within a FIPS 140-2 level 3 compliant security
world, you must provide authorization to create new softcards;
ppmk 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. If you insert
an Administrator Card from another security world, ppmk
displays an error message and prompts you to insert a card with
valid authorization. When ppmk has obtained the authorization
from a valid card or if no authorization is required, it prompts you
to type a pass phrase.
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.

After you have confirmed the pass phrase, ppmk completes creation
of the new softcard.

See ppmk on page 274 for more usage information about ppmk.

nShield/payShield Operator Guide Windows v5.5 68

4 Managing cards and softcards Creating softcards

Creating softcards with KeySafe

To create a softcard with KeySafe, follow these steps:
1. Start KeySafe. (For an introduction to KeySafe and information
on starting the software, see Chapter 3: Using KeySafe.)
2. Click the Softcards menu button. KeySafe takes you to the
Softcard Operations panel.
3. Click the Create New Softcard navigation button.
KeySafe takes you to the Create Softcard panel:

4. Choose parameters for the softcard:

a. Enter a name for the softcard.
b. Choose whether you want pass phrase recovery to be
enabled for the softcard.

nShield/payShield Operator Guide Windows v5.5 69

4 Managing cards and softcards Creating softcards

5. Click the Create Softcard! command button.

If you are creating the softcard in a FIPS 140-2 level 3
security world, insert an Administrator Card or an existing
Operator Card when prompted.
KeySafe then takes you to Set Softcard Protection Pass Phrase
pane:

6. Set a pass phrase for the softcard by entering the same pass
phrase in both text fields.
A pass phrase can contain any characters you can type except for
tabs or carriage returns (because these keys are used to move
between data fields) and can be up to 1024 characters long. You
can change a pass phrase at any time.
7. After entering your desired pass phrase in both text fields, click
the OK button.
KeySafe displays a dialog box indicating that the softcard has
been successfully created.

nShield/payShield Operator Guide Windows v5.5 70

4 Managing cards and softcards Erasing Operator Cards and softcards

8. Click the OK button.

KeySafe returns you to the Create Softcard panel, where you can
create another softcard or choose a different operation by
clicking one of the menu buttons.

Erasing Operator Cards and softcards

Erasing a card or softcard removes all the secret information from the
card or softcard and deletes information about the card or softcard
from the host. (For information about security world data and the
remote file system, see the appropriate Administrator Guide for your
module type.)
If you do not erase the smart cards that you have used as Operator
Cards before you reinitialize your module, you must discard them
because they cannot be used, erased, or reformatted without the old
security world key.

You can erase Operator Cards using KeySafe or the createocs utility.
You can also use these methods to erase Administrator Cards other
than those in the current Administrator Card Set, for example, the
remaining Administrator Cards from an incomplete set that has been
replaced or Administrator Cards from another security world.
Note None of these methods erases cards from the current Administrator
Card Set.

If you erase an Operator Card that is the only card in an Operator Card
Set, information about the card set is deleted. However, if you erase
one card from an Operator Card Set of multiple cards, you must
remove the card information after you have erased the last card.

FIPS 140-2 level 3-compliant security worlds

When you attempt to erase cards for a security world that complies
with FIPS 140-2 level 3, you are prompted to insert an Administrator
Card or Operator Card from an existing set. You may need to specify

nShield/payShield Operator Guide Windows v5.5 71

4 Managing cards and softcards Erasing Operator Cards and softcards

to the application the slot you are going to use to insert the card. You
need to insert the card only once in a session. You can therefore use
one of the cards that you are about to erase.

Erasing card sets with KeySafe

To erase a card set using KeySafe use the following procedure:
1. Start KeySafe.
2. Click the Cards menu button. KeySafe takes you to the Card
Operations panel.
3. Click the Examine/Change Card navigation button. KeySafe takes
you to the Examine/Change Card panel
4. Insert the Operator Card that you want to erase into the reader.
5. Click the Erase Card! button. You do not need to supply the pass
phrase (if there is one) to erase an Operator Card.
6. KeySafe asks you to confirm that you want to erase this card. If
you are sure that you want to erase it, click the Yes button.
Note Erasing a card does not erase the keys protected by that card. The keys
are still listed on the keys panel but are unusable.
If you erase an Operator Card that is the only card in an Operator
Card Set, KeySafe deletes information about that card set.
However, if you erase one card from an Operator Card Set of
nCipher multiple cards, you must remove the card information
after you have erased the last card.
7. After erasing an card, KeySafe displays a dialog box to confirm
that the card has been erased. Click OK to continue using
KeySafe.

nShield/payShield Operator Guide Windows v5.5 72

4 Managing cards and softcards Erasing Operator Cards and softcards

Erasing card sets on the command line

To erase a card set from the command line, open a command window,
and run the command:

createocs -m|--module=MODULE -e|--erase

This command uses the following options:

-m|--module=MODULE

These options specify the module number of the module. If

you only have one module, MODULE is 1.

-e, --erase

These options indicate that you want to erase the card.

Note If you have more than one card reader and there is more than one card
available, createocs prompts you to confirm which card you wish to
erase. Use Cntrl - X to switch between cards.

If you have created a FIPS 140-2 level 3 compliant security world,

you must provide authorization in order to erase or create Operator
Cards.

You must first insert a card containing this authorization. Then

createocs prompts you to insert the card to be erased. You can obtain
this authorization from any card in the Administrator Card Set or from
any Operator Card in the current security world, including cards that
are to be erased.

See createocs on page 153 for more information about this command-
line utility.

nShield/payShield Operator Guide Windows v5.5 73

4 Managing cards and softcards Erasing Operator Cards and softcards

Erasing softcards
Erasing a softcard deletes all information about the softcard from the
host. (For information about security world data and the remote file
system, see the appropriate Administrator Guide for your module
type.) You can erase softcards using Keysafe or with the ppmk
command-line utility.

Erasing softcards with Keysafe

1. Stary Keysafe.
2. Click the Softcards menu button. KeySafe takes you to the
Softcard Operations panel.
3. Click the List Softcards navigation button. KeySafe takes you to
the List Softcards panel.
4. Select the softcard you want to erase from the list.
5. Click the Remove Softcard! button.
6. KeySafe asks you to confirm that you want to erase this card.
Click Yes to confirm.
7. After erasing a softcard, KeySafe displays a dialog box to
confirm that the card has been erased. Click OK to continue using
Keysafe.

Erasing softcards with ppmk

To erase a softcard with ppmk, open a command window, and give the
command:

C:\nfast\bin\ppmk.exe --delete NAME|IDENT

In this command, you can identify the softcard to be erased either by

its name (NAME) or by its logical token hash as listed by nfkminfo
(IDENT).

nShield/payShield Operator Guide Windows v5.5 74

4 Managing cards and softcards Viewing cards and softcards

If you are working within a FIPS 140-2 level 3 compliant security

world, you must provide authorization to erase softcards; ppmk
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. If you insert an Administrator Card from
another security world or an Operator Card that you have just created,
ppmk displays an error message and prompts you to insert a card with
valid authorization. When ppmk has obtained the authorization from
a valid card or if no authorization is required, it completes the process
of erasing the softcard.

Viewing cards and softcards

It is often necessary to obtain information from card sets, usually
because for security reasons they are left without any identifying
markings.

To view details of all the Operator Cards in a security world or details

of an individual Operator Card, you can use KeySafe or the nfkminfo
command-line utility. To check which pass phrase is associated with
a card, you can use the cardpp command-line utility.

To list all softcards in a security world or to show details of an

individual softcard, you can use the ppmk or nfkminfo command-line
utilities. To check which pass phrase is associated with a softcard, you
can use the ppmk command-line utility.

Viewing card sets with KeySafe

You can use KeySafe to view details of all the Operator Cards in a
security world, details of individual Operator Card Sets or details of
an individual Operator Card.

Examining a Card
In order to view information about individual cards with KeySafe,
follow these steps:

nShield/payShield Operator Guide Windows v5.5 75

4 Managing cards and softcards Viewing cards and softcards

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

on starting the software, see Chapter 3: Using KeySafe.)
2. Click the Cards menu button. KeySafe takes you to the Card
Operations panel.
3. Click the Examine/Change Card navigation button. KeySafe
takes you to the Examine/Change Card panel.
4. Insert a card into the appropriate smart card slot. KeySafe
displays information about the smart card currently in the slot. If
there is no smart card in the slot, KeySafe displays a message
Card slot empty - please insert the card that you want to examine.

From the Examine/Change Card panel, you can also:

• change a card’s pass phrase (if it has one)
• give a pass phrase to a card that does not already have one
• remove a pass phrase from a card that currently has one.

List an Operator Card Set

In order to view information about whole Operator Card Sets with
KeySafe, follow these steps:
1. Start KeySafe. (For an introduction to KeySafe and information
on starting the software, see Chapter 3: Using KeySafe.)
2. Click the Cards menu button. KeySafe takes you to the Card
Operations panel.
3. Click the List OCS navigation button. KeySafe takes you to the
List Operator Card Sets panel, which displays information about
all Operator Card Sets in the current security world.

From the List Operator Card Sets panel, you can also choose to
remove an Operator Card Set from the security world by clicking the
Remove OCS! button. (See Erasing card sets with KeySafe on page
72).

nShield/payShield Operator Guide Windows v5.5 76

4 Managing cards and softcards Viewing cards and softcards

Viewing card sets from the command line

You can use the nfkminfo command-line utility to view details of
either all the Operator Cards in a security world or of an individual
Operator Card.

To list the Operator Card Sets in the current security world from the
command line, open a command window, and give the command:

nfkminfo --cardset-list

In this command, --cardset-list specifies that you want to list the

operator card sets in the current security world.

nfkminfo displays output information similar to the following:

Cardset summary - 1 cardsets: (in timeout, P=persistent, N=not)

Operator logical token hash k/n timeout name
hash 1/1 none-N name

To list information for a specific card, use the command:

nfkminfo TOKENHASH

In this command, TOKENHASH is the Operator logical token hash of

the card (as listed when the command nfkminfo --cardset-list is run).

nShield/payShield Operator Guide Windows v5.5 77

4 Managing cards and softcards Viewing cards and softcards

This command displays output information similar to the following:

name "name"
k-out-of-n 1/1
flags NotPersistent
timeout none
card names ""
hkltu 794ada39038fa8c4e9ea46a24136bbb2b8b337f2

Note In the current release, not all software can give names to individual
cards.

See nfkminfo on page 249 for more information on using this utility.

Viewing softcards
Softcards can be viewed using Keysafe or from the command line. On
the command line there are several ways of viewing information
about them.

Viewing softcards with Keysafe

To view a softcard with Keysafe, follow these steps:
1. Start Keysafe.
2. Click the Softcards menu button. Keysafe takes you to the
Softcard Operations panel.
3. Click the List Softcards navigation button. Keysafe takes you to
the List Softcards panel, which displays information about all
softcards in the current security world.
From the List Softcards panel, you can also choose to remove a
softcard from the security world. See Erasing Operator Cards and
softcards on page 71 for more information about this procedure.

nShield/payShield Operator Guide Windows v5.5 78

4 Managing cards and softcards Viewing cards and softcards

Viewing softcards with nfkminfo

To list the softcards in the current security world using the nfkminfo
command-line utility, give the command:

nfkminfo --softcard-list

In this command --softcard-list specifies that you want to list the

softcards in the current security world.

To show information for a specific softcard using the nfkminfo

command-line utility, give the command:

nfkminfo --softcard-list IDENT

In this command IDENT is the softcard’s logical token hash (as given
by running the command nfkminfo --softcard-list). This command
displays output information similar to the following:

SoftCard
name "mysoftcard"
hkltu 7fb95888ea2850d4e3ffcc8f0c22100937344308
Keys protected by softcard 7fb95888ea2850d4e3ffcc8f0c22100937344308:
AppName simple Ident mykey
AppName simple Ident myotherkey

See nfkminfo on page 249 for more information on using this utility.

Viewing softcards with ppmk

To list the softcards in the current security world using the ppmk
command-line utility, use the command:

C:\nfast\bin\ppmk.exe --list

nShield/payShield Operator Guide Windows v5.5 79

4 Managing cards and softcards Viewing cards and softcards

In this command --list specifies that you want to list the softcards in
the current security world.

In order to view the details of a particular softcard using the ppmk

command-line utility, give the command:

C:\nfast\bin\ppmk.exe --info NAME|IDENT

In this command, you can identify the softcard whose details you
want to view either by its name (NAME) or by its logical token hash
(as given by running the command nfkminfo --softcard-list).

See ppmk on page 274 for more information on using this utility.

Verifying a card’s or softcard’s pass phrase

Verifying a card’s pass phrase with cardpp

To verify the pass phrase associated with a card using the cardpp
command-line utility, use the command:

cardpp --check [-m|--module=MODULE]

This command uses the following options:

--check

This option tells cardpp to check the pass phrase.

--module=MODULE

This option specifies 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 Operator Guide Windows v5.5 80

4 Managing cards and softcards Changing card and softcard pass phrases

The cardpp utility polls all available slots; if there is no card inserted,
it prompts you to insert one. If the card belongs to this security world,
cardpp either tells you if no pass phrase is set or prompts you to enter
the pass phrase and checks to see if it is correct.

Verifying a softcard’s pass phrase with ppmk

In order to verify the pass phrase of a particular softcard, open a
command window, and give the command:

C:\nfast\bin\ppmk.exe --check NAME|IDENT

In this command, you can identify the softcard whose pass phrase you
want to verify either by its name (NAME) or by its logical token hash
(as given by running the command nfkminfo --softcard-list).

ppmk prompts you to enter the pass phrase and then tells you whether
the pass phrase you entered is correct for the specified softcard.

See ppmk on page 274 for more information on using this utility.

Changing card and softcard pass phrases

In order to change pass phrase of a card or softcard, you need the card
or softcard and the old pass phrase. Card pass phrases can be changed
using KeySafe or the cardpp command-line utility; softcard pass
phrases can be changed using Keysafe or the ppmk command-line
utility.

If you have generated your security world with pass phrase recovery,
you can also replace the pass phrase for an Operator Card or softcard
even if you do not know the existing pass phrase.This operation,
however, requires authorization from the Administrator Card Set; see
the Administrator Guide for more information.

nShield/payShield Operator Guide Windows v5.5 81

4 Managing cards and softcards Changing card and softcard pass phrases

Each softcard or card of a card set can have its own individual pass
phrase: you can even have a card set in which some cards have pass
phrases and others do not, and you can have distinct softcards that
nevertheless use the same pass phrase. A pass phrase can be of any
length and can contain any characters that you can type.

Changing pass phrases with KeySafe

To change a card pass phrase, you need the card and the old pass
phrase.

If you have generated your security world with pass phrase recovery,
you can also replace the pass phrase for an Operator Card even if you
do not know the existing pass phrase.This operation, however,
requires authorization from the Administrator Card Set.

Each card in a 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.
Note 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.

Changing a card pass phrase with KeySafe

To change a pass phrase for an Operator Card using KeySafe:
1. Start KeySafe.
2. Click Cards. the Examine/Change panel is displayed.
3. Click Change Pass Phrase. The Set Card Protection Pass Phrase
panel is displayed.
4. Enter the old pass phrase, and click the OK button.

nShield/payShield Operator Guide Windows v5.5 82

4 Managing cards and softcards Changing card and softcard pass phrases

5. A screen is displayed asking Do you want to set a pass phrase?.

Selected Yes.
6. Enter your new pass phrase, and enter it again in the second box
as confirmation of the change.
7. Click OK.

Changing a softcard pass phrase with KeySafe

TO change a pass phrase for a softcard using KeySafe:
1. Start KeySafe.
2. Click the Softcards menu button. KeySafe takes you to the
Softcard Operations panel.
3. Click the Change Passphrase navigation button. KeySafe takes
you to the Change/Recover Softcard Passphrase panel.
4. Select the softcard whose pass phrase you want to change, and
click the Change Passphrase button. KeySafe takes you to the Get
Softcard Protection Pass Phrase panel.
5. Enter the old pass phrase and click OK. KeySafe either displays
an error dialog (if the pass phrase is not correct) or takes you to
the Set Softcard Protection Pass Phrase panel.
6. Enter your new pass phrase, and enter it again in the second box
to confirm the pass phrase is correct.
7. Click OK.
8. After changing a pass phrase, KeySafe displays a dialog box to
confirm that the pass phrase has been successfully changes. Click
OK to continue using KeySafe.

Changing a card’s pass phrase with cardpp

To change a card’s pass phrase with the cardpp command-line utility
when you know the pass phrase, take the following steps:

nShield/payShield Operator Guide Windows v5.5 83

4 Managing cards and softcards Changing card and softcard pass phrases

1. Run the cardpp utility using the command:

cardpp --change [-m|--module=MODULE]

If you only have one module, MODULE is 1. If you do not specify

a module number, cardpp uses all modules by default.
2. If prompted, insert the card whose pass phrase you want to
change. (If there is a card already in the slot, you are not
prompted.)
3. If prompted, enter the existing pass phrase for the card (If the card
has no current pass phrase you are not prompted.) If you enter the
pass phrase correctly, cardpp prompts you to enter the new pass
phrase.
4. Enter a new pass phrase, and then enter it again to confirm it.
After you have confirmed the new pass phrase, cardpp changes
the card’s pass phrase.

Changing softcard pass phrases with ppmk

To change a softcard’s pass phrase when you know the pass phrase,
follow these steps:
1. Give the following command:

C:\nfast\bin\ppmk.exe --change NAME|IDENT

In this command, you can identify the softcard whose pass phrase
you want to change either by its name (NAME) or by its logical
token hash as listed by nfkminfo (IDENT).
ppmk.exe prompts you to enter the old pass phrase.
2. Type the old pass phrase, and press Enter . If you enter the old
pass phrase correctly, ppmk.exe prompts you to enter the new
pass phrase.

nShield/payShield Operator Guide Windows v5.5 84

4 Managing cards and softcards Lost cards

3. Type the old pass phrase, and press Enter . Type the new pass
phrase again, and press Enter to confirm it.
After you have confirmed the new pass phrase, ppmk.exe then
changes the softcard’s pass phrase.

Lost cards
If you have lost a card from a card set, you can replace the card set
using the rocs utility or KeySafe’s Replace Operator Card Set option
(reached from the Card Operations panel). See the Administrator
Guide for more information about replacing operator card sets.

nCipher recommends that after you have replaced an Operator Card

Set, you then erase the remaining cards in the old card set (see Erasing
Operator Cards and softcards on page 71) and remove the old card set
from the security world (see the Administrator Guide).

Deleting an Operator Card Set’s information from the host does not
remove the data for keys protected by that card set. On KeySafe’s List
Keys panel (reachable from the Key Operations panel), such keys are
listed as being protected by Deleted Card Set.

nShield/payShield Operator Guide Windows v5.5 85

Chapter 5: Working with keys
This chapter describes how to use the facilities provided by nCipher
to work with keys. There is often more than one way of performing a
particular task. The methods available for working with keys are:
• KeySafe
• generatekey and related utilities

If you have purchased a payShield module, you can also load existing
keys from other media. See the Key-loading Solution Guide for
details.

Where commands are described in this chapter, it is assumed that you

have installed the nCipher software in the default location, C:\nfast\.
If you chose to install the nCipher software in another directory,
replace references to C:\nfast\ with the name of the directory in which
you installed the software.

Generating keys
Generating a key creates both a key and a certificate request for the
following application types:
• embed (OpenSSL)
• ssleay
• iis34

This request is a PKCS #10 format request in base-64 encoding.

Whenever possible, generate a new key instead of importing an

existing key. Because existing keys have been stored in a known
format on your hard disk, there is a risk that the existing key has been
compromised. Key material can also persist on backup media.
Note Some applications can generate keys directly.

nShield/payShield Operator Guide Windows v5.5 86

5 Working with keys Generating keys

When you attempt to generate keys for a security world that complies
with FIPS 140-2 level 3, you are prompted to insert an Administrator
Card or Operator Card. You may need to specify to the application,
the slot you are going to use to insert the card. You need to insert the
card only once in a session.

Generating keys on the command line

Keys are generated on the command line with the generatekey utility.
The --generate option creates a new key on the host computer that is
protected either by the module or by an Operator Card set from the
security world. No key material is stored in an unencrypted form on
the host computer.

When you generate a key with generatekey, choose a new identifier for
the key and use whichever application type is appropriate; see
generatekey on page 200 for more information about application
types. The key identifier can only contain digits and lowercase letters;
it cannot contain spaces, underscores (_), or hyphens (-).

You can use generatekey in two ways:

• in interactive mode, by issuing commands without parameters
and supplying the required information when prompted by the
utility
• in batch mode, by supplying some or all of the required
parameters on the command line (generatekey prompts
interactively for any missing but required parameters).

In interactive mode, you can input abort at any prompt to terminate

the process.

Batch mode is useful for scripting. In batch mode, if any required

parameters are omitted, generatekey does not prompt for the missing
information but instead will either use available defaults or fail. If you
specify one or more parameters incorrectly, an error is displayed and
the command fails.

nShield/payShield Operator Guide Windows v5.5 87

5 Working with keys Generating keys

To generate a key, use the command:

generatekey --generate [OPTIONS] APPNAME [NAME=VALUE ...]

This command use the following options:

--generate

This option specifies key generation.

OPTIONS

You can specify particular options when running generatekey

that control details of key generation. See generatekey on
page 200 for details of available options.

APPNAME

This option specifies the name of the application for which

the key is to be generated. This must be an application for
which generatekey can generate keys.

NAME=VALUE

This specifies a list of parameters for the application. See

generatekey on page 200 for details of available parameters.

In interactive mode, generatekey prompts you for any required

parameters or actions that have not been included in the command.
When you give the command:
1. Enter parameters for the command, as requested. If you enter a
parameter incorrectly, the request for that information is repeated
and you can re-enter the parameter.
2. For jcecsp keys, you must input the key store password. In
interactive mode, this is not echoed to the screen. When all the
parameters have been collected, generatekey displays the final
settings. In a FIPS 140-2 level 3 compliant security world, you
are prompted to insert a card for FIPS authorization if no such
card is present.

nShield/payShield Operator Guide Windows v5.5 88

5 Working with keys Generating keys

3. If prompted, insert an Administrator Card or an Operator Card

from the current security world.
4. If you want to protect the key with an Operator Card Set, you are
prompted to insert the relevant cards and input pass phrases, as
required.

Example of key generation with generatekey

To generate in batch mode an RSA key protected by an Operator Card
Set named operatorone and for an application that uses the
Cryptographic Hardware Interface Library (CHIL), use the
command:

generatekey --generate --batch --cardset=operatorone hwcrhk protect=token type=rsa

size=1024 plainname=keya ident=abc

The generatekey utility prompts you to insert a quorum of Operator

Cards from the operatorone Operator Card Set. After you have
inserted the appropriate number of cards, generatekey generates the
key.

Although it is not explicitly specified, the created key is recoverable

by default if recovery is enabled for the security world.

See generatekey on page 200 for more details about using the
generatekey command-line utility.

Generating keys with KeySafe

In order to generate a key with KeySafe, follow these steps:
1. Start KeySafe. (For an introduction to KeySafe and for
information on starting the software, see Chapter 3: Using
KeySafe.)
2. Click the Keys menu button. KeySafe takes you to the Key
Operations panel.

nShield/payShield Operator Guide Windows v5.5 89

5 Working with keys Generating keys

3. Click the Generate Key navigation button. KeySafe takes you to

the Generate Key panel:

4. Select an application with which you want to use your key from
the list, and then click the Next button. KeySafe takes you to the
Key Generation Parameters panel.

nShield/payShield Operator Guide Windows v5.5 90

5 Working with keys Generating keys

5. Select and enter your desired parameters for key generation.

The types of information that you need to provide on the Key
Generation Parameters panel differs slightly depending on the
application you selected on the Generate Key panel. Below, as an
example, is the Key Generation Parameters panel associated with
nCipher native applications:

6. When you have supplied your desired key generation parameters,

click the Next button.
Note In order to generate a key protected by a FIPS 140-2 level 3 compliant
security world, you need authorization from an Operator Card or
Administrator Card from the current security world. Follow the
onscreen instructions.
7. If you choose to generate a key that is protected by a smart card
or softcard, KeySafe takes you to a panel from which you can
load the protecting card or softcard. Follow the onscreen
instructions, inserting any necessary Operator Cards and
supplying any pass phrases as needed.

nShield/payShield Operator Guide Windows v5.5 91

5 Working with keys Generating keys

8. KeySafe displays a message indicating that the key has been

successfully generated. Click the OK button.
9. KeySafe returns you to the Generate Key panel, from which you
can generate another key or choose another operation.

Generating NVRAM-stored keys

NVRAM key storage provides a mechanism for generating keys
stored in a module’s nonvolatile memory and hence within the
physical boundary of an nCipher module. You can store only a few
keys in this way: the number depends on the memory capacity of the
module, the size of the key and whether the key has recovery data
associated with it.
nCipher recommends that you do not store keys in NVRAM unless you
must do so to satisfy regulatory requirements. 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 load
balancing and recovery capabilities. Because of these factors,
nCipher recommends you always use standard security world keys
unless explicitly required to use NVRAM-stored keys.

Before you can generate an NVRAM-stored key you must:

• ensure that you have installed version 2.6.8 or greater of the
nCipher server software. You can use the enquiry command-line
utility to identify the installed version number.
• ensure that your module has module firmware version 2.12.0 or
later installed. See the Administrator Guide for information on
upgrading your module firmware.
• create a new security world.

nShield/payShield Operator Guide Windows v5.5 92

5 Working with keys Importing keys

When you generate an NVRAM-stored key, you must have sufficient

nonvolatile memory available in the module or the command fails.
You need backup and recovery procedures to protect your NVRAM-
stored keys.

Note An NVRAM-stored key can only be loaded successfully by using the

with-nfast command-line utility on the generating module. Attempts to
load such a key on other modules that have NVRAM fail with
UnknownID errors.

nCipher provides the nvram-backup utility to enable the copying of

files, including NVRAM-stored keys, between a module’s nonvolatile
memory and a smart card. See nvram-backup on page 260 for
examples of how to use the nvram-backup command-line utility.

Importing keys
Importing a key takes an unprotected key stored on the host and stores
it in the security world in encrypted form.
nCipher recommends generating a new key (or retargeting a key from
within the security world) instead of importing an existing key
whenever possible. The import operation does not delete any copies
of the key material from the host, and because existing keys have been
stored in a known format on your hard disk (and key material can
persist on backup media), there is a risk that an existing key has been
compromised. It is your responsibility to ensure any unprotected key
material is deleted. If a key was compromised before importation,
then importing it does not make it secure again.

The following key types can be imported by the tools nCipher

provides:
• RSA keys in PEM-encoded PKCS #1 format (from a file). The
PEM key that contains the key to import must not require a pass
phrase.
• DES and 3DES keys (entered in hex).

nShield/payShield Operator Guide Windows v5.5 93

5 Working with keys Importing keys

Importing a key, like generating a key, creates both a key and a

certificate request for the following application types:
• embed (OpenSSL)
• ssleay
• iis34

This request is a PKCS #10 format request in base-64 encoding.

When you attempt to import keys into a security world that complies
with FIPS 140-2 level 3, you are prompted to insert an Administrator
Card or Operator Card. You may need to specify the slot you are going
to use to insert the card. You need to insert the card only once in a
session.

Importing keys from the command line

You can import keys using the generatekey command-line utility. To
import a key, give the command:

generatekey --import [OPTIONS] APPNAME [NAME=VALUE ...]

This command uses the following options:

--import

This option specifies key importation.

OPTIONS

You can specify particular options when running generatekey

that control details of key importation. See generatekey on
page 200 for details of available options.

APPNAME

This option specifies the name of the application for which

the key is to be imported. This must be an application for
which generatekey can generate keys.

nShield/payShield Operator Guide Windows v5.5 94

5 Working with keys Importing keys

NAME=VALUE

This specifies a list of parameters for the application. See

generatekey on page 200 for details of available parameters.

For RSA keys, you can include pemreadfile=filename on the command

line to specify the file name of the PEM file that contains the key.
Otherwise, you are prompted for this information during import.

In interactive mode, you are prompted for any required parameters or

actions that have not been included in the command:
• Enter parameters, as requested. If you enter a parameter
incorrectly, the request for that information is repeated and you
can re-enter the parameter.
• If you want to protect the key with an Operator Card Set, you are
prompted to insert the relevant cards and input pass phrases, as
required.
• If prompted, insert an Administrator Card or an Operator Card
from the current security world.

Example of key importation with generatekey

To import an RSA key stored in C:\projects\key.pem for use with an
nCipher native application and protect it with the security world, use
the command:

generatekey --import simple pemreadfile=C:\projects\key.pem plainname=importedkey

ident=abc protect=module

In this example, generatekey requires you to input RSA for the key
type.

Although not explicitly specified, this key is, by default, recoverable

if recovery is enabled for the security world.

See generatekey on page 200 for more details about using the
generatekey command-line utility.

nShield/payShield Operator Guide Windows v5.5 95

5 Working with keys Importing keys

Importing keys with KeySafe

Any user who has write access to the directory that contains the
security world can import a key.

In order to import a key with KeySafe, follow these steps:

1. Start KeySafe. (For an introduction to KeySafe and for
information on starting the software, see Chapter 3: Using
KeySafe.)
2. Click the Keys menu button. KeySafe takes you to the Key
Operations panel.
3. Click the Import Key navigation button. KeySafe takes you to the
Import Key panel:

4. Select the application associated with the key that you want to
import, and then click the Next button. KeySafe takes you to the
Key Import Parameters panel.

nShield/payShield Operator Guide Windows v5.5 96

5 Working with keys Importing keys

5. Select and enter the desired parameters for the key that you want
to import.
The types of information that you need to provide on the Key
Import Parameters panel will differ slightly depending on the
application you selected on the Import Key panel. Below, as an
example, is the Key Import Parameters panel associated with
nCipher native applications:

6. When you have supplied parameters for the key that you want to
import, click the Next button.
7. If you choose to import a key that is protected by a smart card,
KeySafe takes you to the Load Operator Card Set panel. Follow
the onscreen instructions, inserting the required number of
Operator Cards and supplying any pass phrases as needed.
8. KeySafe displays a message indicating that the key has been
successfully imported. Click the OK button.
9. KeySafe returns you to the Import Key panel, from which you can
import another key or choose another operation.

nShield/payShield Operator Guide Windows v5.5 97

5 Working with keys Listing supported applications with generatekey

Listing supported applications with generatekey

To list supported applications, use the command:

C:\nfast\bin\generatekey --list-apps

Retargeting keys with generatekey

The --retarget option to takes an existing key in the security world and
makes it available for use by another application as if it had been
expressly generated for use by that application. Because no key
material is exposed during retargeting, this operation is as secure as
generating a new key.
Note When you retarget a key, generatekey does not remove the original key
from the security world. If required, you can use KeySafe to discard
the original key.

When you retarget a key, you cannot change its protection method.
You cannot change the key from module-protected to card-protected,
or from card-protected to module-protected.

To retarget a key, use the command:

C:\nfast\bin\generatekey --retarget [OPTIONS] APPNAME [from-application=appname]

[from-ident=keyident]

In this command:

--retarget

specifies key importation.

OPTIONS

specifies any options to include when the command is run.

See Options on page 201 for details of available options.

nShield/payShield Operator Guide Windows v5.5 98

5 Working with keys Viewing keys

APPNAME

specifies the name of the application for which the key is to

be generated. This must be an application for which
generatekey can generate keys.

from-application=appname

specifies the name of the application with which the key is

currently associated.
Note You can retarget a key from any application, even those for which
generatekey cannot generate or import keys.

from-ident=keyident

specifies the identifier of the key to be retargeted. You can

find this identifier by using the nfkminfo command-line
utility.

If generatekey cannot identify the key type for retargeting, you are
prompted to specify the key type. Input the key type and press Enter .

Viewing keys
You can view existing keys in the security world using KeySafe or the
nfkminfo command-line utility.

Viewing keys with KeySafe

In order to view a list of keys with KeySafe, follow these steps:
1. Start KeySafe. (For an introduction to KeySafe and for
information on starting the software, see Chapter 3: Using
KeySafe.)
2. Click the Keys menu button. KeySafe takes you to the Key
Operations panel.

nShield/payShield Operator Guide Windows v5.5 99

5 Working with keys Viewing keys

3. Click the List Keys navigation button. KeySafe takes you to the
Key Listing panel:

The Key Listing panel displays all the keys that have been created in
(or imported in to) the current security world. It displays the name of
the key, the application for which it was created, the protection
method that was used and whether the key is stored in NVRAM.

If you click a key’s listing, KeySafe displays additional information

about that key, for example, the application with which the key is
used, whether or not the key is recoverable, and the key’s name,
creation date, hash, instance, and copy ID.

From the Key Listing panel, you can choose to discard a key from the
security world by clicking the Discard Key button. (See Discarding
keys on page 103 ).

nShield/payShield Operator Guide Windows v5.5 100

5 Working with keys Viewing keys

Viewing keys on the command line

Keys are listed on the command line using the nfkminfo utility. To list
the keys that have been created in the current security world, use one
of the following commands:

nfkminfo -k [APPNAME[IDENT]]

nfkminfo -l [APPNAME[APPNAME...]]

The --key-list (-k) option lists keys only. The --name-list (-l) option lists
keys and their names.

With either option, APPNAME is an optional application name. If you

specify an application name, nfkminfo lists only the keys for that
application. In general, APPNAME is one of:
• custom
• embed
• hwcrhk
• iis34
• nses35
• simple
• ssleay .

With the --name-list option, IDENT is the key identifier.

Note Other, user-defined application names may have been created (for
example, by using the nfkm library to generate arbitrary keys).

nfkminfo --key-list displays information in a format similar to this:

Key summary - 4 keys:

AppName appname Ident ident AppName appname Ident ident
AppName appname Ident ident AppName appname Ident ident

nShield/payShield Operator Guide Windows v5.5 101

5 Working with keys Viewing keys

To list information about a specific key, use the --key-list and specify
an application and key identifier:

C:\\nfast\bin\nfkminfo --key-list appname ident

nfkminfo then displays information in a format similar to this:

Key AppName appname Ident ident BlobKA length 752

BlobPubKA length 316
BlobRecoveryKA length 868
name "name"
hash hash recovery Enabled
protection CardSet
other flags PublicKey +0x0
cardset hash_ktBlobKA
format 6 Token
other flags 0x0
hkm hash_km hkt hash_kt hkr none
BlobRecoveryKA
format 8 Indirect
other flags 0x0
hkm none
hkt none
hkr hash_krBlobPubKA
format 5 Module
other flags 0x0
hkm hash_km hkt none
hkr none
No extra entries

To list keys and names, use the --name-list option.

nShield/payShield Operator Guide Windows v5.5 102

5 Working with keys Discarding keys

nfkminfo --name-list displays information in a format similar to this:

Key summary - 30 keys

in format key_<appname>_<ident> '<name>')
key_appname_ident 'name '
key_appname_ident 'name '
key_appname_ident 'name '
key_appname_ident 'name '
key_appname_ident 'name '
key_appname_ident 'name '
key_appname_ident 'name '

Discarding keys
Discarding a key deletes the information about the key from the host
disk. This option is only available in KeySafe.

If you have backup media, you can restore the information and the key
will become usable again. Likewise, if you have copies of the security
world data on several computers, erasing the data on one computer
does not remove it from any other computer.

To destroy a key permanently you must either erase the Operator Card
Set that is used to protect it or erase the security world completely.
There are no other ways to destroy a key permanently.

Restoring keys
nCipher does not supply tools for restoring a key that has been
discarded. However if you have kept a backup of the host data for the
security world, you can restore a key from the backup data.
Note If you have NVRAM-stored keys, you must additionally ensure you
have a backup of the key data stored on the relevant modules.

nShield/payShield Operator Guide Windows v5.5 103

Chapter 6: nCipher application interfaces
This chapter describes how to use an nCipher module with the
following types of application:
• Cryptographic Hardware Interface Library (CHIL) applications
• nCipherKM JCA/JCE CSP
• PKCS #11 applications
• nCipher native applications
• Custom external applications.

You can use KeySafe or the generatekey command-line utility to

generate or import keys for use with your applications (see Chapter 5:
Working with keys). By default, KeySafe uses the same mechanisms
and supports the same applications as the generatekey command-line
utility.
Note By default, any user is allowed to use any application that uses a
module.

Where commands are described in this chapter, it is assumed that you

have installed the nCipher software in the default location, C:\nfast\.
If you chose to install the nCipher software in another directory,
replace references to C:\nfast\ with the name of the directory in which
you installed the software.

Cryptographic Hardware Interface Library (CHIL)

The Cryptographic Hardware Interface Library (CHIL) is a simple
programming interface for accelerating modulo exponentiation and
accessing the RSA/DSA keys that are used by some application
software. The Cryptographic Hardware Interface Library supports
only RSA/DSA and Diffie-Hellman keys.

nShield/payShield Operator Guide Windows v5.5 104

6 nCipher application interfaces nCipherKM JCA/JCE CSP

If your application offers RSA/DSA keys in hardware support through

the Cryptographic Hardware Interface Library, use the hwcrhk key
type.

Some Cryptographic Hardware Interface Library applications that do

not support the hwcrhk key can still be configured for key storage by
using the embed key type (provided that they can read PEM (Privacy
Enhanced Mail) format key files and use the Cryptographic Hardware
Interface Library for all cryptographic operations).

Using keys
Configure the application to load the nCipher Cryptographic
Hardware Interface Library plug-in:
C:\\nfast\toolkits\nfhwcrhk\nfhwcrhk.dll

Refer to the documentation for your application.

Generating keys
Generate the key with KeySafe or generatekey, choosing a new
identifier for the key; see Generating keys on page 86. Use the hwcrhk
or embed key type, as appropriate.

The key identifier can only contain digits and lowercase letters; it
cannot contain spaces, underscores (_), or hyphens (-).

nCipherKM JCA/JCE CSP

nCipher supplies the nCipherKM JCA/JCE cryptographic service
provider. It requires JDK 1.4.x.

Use of the nCipherKM JCA/JCE cryptographic service provider

classes requires the presence of:
• the nCipher Java Key Management classes
• the nFast Java Generic stub classes.

nShield/payShield Operator Guide Windows v5.5 105

6 nCipher application interfaces nCipherKM JCA/JCE CSP

These components are found on the nCipher CD-ROM. The

Developer’s CD-ROM additionally provides associated Javadocs and
example code. For information about the installation of these
components, see the Administrator Guide.

The nCipherKM JCA/JCE cryptographic service provider can be used

with FIPS 140-2 level 3 compliant security worlds.
Note In a FIPS 140-2 level 3 compliant security world, it is neither possible
to import keys generated by other JCE providers nor to generate
module-protected keys.

The nCipherKM JCA/JCE cryptographic service provider supports

load sharing for keys that are stored in the nCipherKM keystore. The
load sharing feature provides support for multiple modules that are
connected to a single server, spreading the load of cryptographic
operations between the modules in order to provide scalability in
terms of performance.
Note nCipher recommends that you use load sharing unless you have
existing code that is designed to run with multiple modules.

In order to share keys with load sharing, you must create a 1-of-N
Operator Card Set with at least as many cards as you have modules.
All the cards on the Operator Card Set must have the same pass
phrase.

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 as follows:

security.provider.1=com.ncipher.fixup.provider.nCipherRSAPrivateEncrypt
security.provider.2=com.ncipher.provider.km.nCipherKM

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.

nShield/payShield Operator Guide Windows v5.5 106

6 nCipher application interfaces nCipherKM JCA/JCE CSP

Adding the nCipher Java classes to your class path

Before you can use the nCipherKM JCA/JCE cryptographic service
provider, you must ensure that you have added the nCipher Java
classes required by the CSP to your class path.

Add the required classes to your class path as follows:

jceclasspath;C:\nfast\java\classes\nfjava.jar;C:\nfast\java\classes\kmjava.jar;C:\\nfas
t\java\classes\kmcsp.jar;.

In this class path, jceclasspath is the path to your JCE framework .jar
file.
Note There is a dot, “.”, at the end of the first line of example code.
Note nCipher recommends that you use the Sun JCE framework which can
be downloaded from http://java.sun.com/products/jce/.

Setting the nCipherKM engine classes as the preferred provider

Before you can use the nCipherKM JCA/JCE cryptographic service
provider, you must ensure that you have edited the following Java
configuration file:

JDK_HOME\jre\lib\security\java.security

This ensures that the nCipherKM engine classes are used in

preference to any other providers that may be installed on your
system. Edit the file java.security in such a way as to make the

nShield/payShield Operator Guide Windows v5.5 107

6 nCipher application interfaces nCipherKM JCA/JCE CSP

nCipherKM JCA/JCE cryptographic service provider your

security.provider.1 by changing, for example, lines in the file
java.security that resemble:

#
# List of providers and their preference orders (see above):
#
security.provider.1=sun.security.provider.Sun

to lines that resemble:

#
# List of providers and their preference orders (see above):
#
security.provider.1=com.ncipher.provider.km.nCipherKM
security.provider.2=sun.security.provider.Sun

Choosing functions
The nCipherKM JCA/JCE provider implements the engine classes
described below.

KeyPairGenerator
• RSA
- OID.1.2.840.113549.1.1.1
- 1.2.840.113549.1.1.1
• DSA
- OID.1.2.840.10040.4.1
- 1.2.840.10040.4.1
- 1.3.14.3.2.12
• DH
- Diffie-Hellman

nShield/payShield Operator Guide Windows v5.5 108

6 nCipher application interfaces nCipherKM JCA/JCE CSP

- DiffieHellman

KeyGenerator
• DESede
- TripleDES
- Triple-DES
- DES3
• Rijndael
- AES
• CAST
- CAST128
- CAST256
• Blowfish
• Serpent
• Twofish
• ArcFour
• HmacSHA1
• HmacSHA256
• HmacSHA384
• HmacSHA512
• HmacTiger
• HmacRIPEMD160
• HmacMD5

Signature
• MD5withRSA
- MD5/RSA

nShield/payShield Operator Guide Windows v5.5 109

6 nCipher application interfaces nCipherKM JCA/JCE CSP

- OID.1.2.840.113549.1.1.4
- 1.2.840.113549.1.1.4
- 1.3.14.3.2.25
• SHA1withRSA
• SHA1withDSA
- DSA
- DSS
- SHA/DSA
- SHA-1/DSA
- SHA1/DSA
- SHAwithDSA
- DSAWithSHA1
- OID.1.2.840.10040.4.3
- 1.2.840.10040.4.3
- 1.3.14.3.2.13
- 1.3.14.3.2.27

Cipher
• RSA
- Mode: ECB
- Padding: PKCS1Padding (PKCS1, PKCS#1)
• OID.1.2.840.113549.1.1.1
• DESede
- Mode: ECB, CBC
- NoPadding, PKCS5Padding (PKCS5, PKCS#5)
• TripleDES
• Triple-DES

nShield/payShield Operator Guide Windows v5.5 110

6 nCipher application interfaces nCipherKM JCA/JCE CSP

• DES3
• Rijndael
- Mode: ECB, CBC
- NoPadding, PKCS5Padding (PKCS5, PKCS#5)
• AES
• CAST
- Mode: ECB, CBC
- NoPadding, PKCS5Padding (PKCS5, PKCS#5)
• CAST128
• CAST256
• Blowfish
- Mode: ECB, CBC
- NoPadding, PKCS5Padding (PKCS5, PKCS#5)
• Serpent
- Mode: ECB, CBC
- NoPadding, PKCS5Padding (PKCS5, PKCS#5)
• Twofish
- Mode: ECB, CBC
- NoPadding, PKCS5Padding (PKCS5, PKCS#5)
• ArcFour
- Mode: None
- Padding: None

KeyStore
• nCipher.sworld
- jks

nShield/payShield Operator Guide Windows v5.5 111

6 nCipher application interfaces nCipherKM JCA/JCE CSP

SecureRandom
• RND
- SHA1PRNG

KeyAgreement
• DH
- Diffie-Hellman
- DiffieHellman

KeyFactory
• DH
- Diffie-Hellman
- DiffieHellman
• RSA
- OID.1.2.840.113549.1.1.1
- 1.2.840.113549.1.1.1
• DSA
- OID.1.2.840.10040.4.1
- 1.2.840.10040.4.1, 1.3.14.3.2.12

Mac
• HmacSHA1
• HmacMD5
• HmacTiger
• HmacRIPEMD160
• HmacSHA256
• HmacSHA384

nShield/payShield Operator Guide Windows v5.5 112

6 nCipher application interfaces nCipherKM JCA/JCE CSP

• HmacSHA512

Java system properties

The nCipherKM JCA/JCE cryptographic service provider uses the
following Java system properties:
• JCECSP_DEBUG
• JCECSP_DEBUGFILE
• protect

These properties can be set on the command line when the Java
program is run. Normally, however, it is not necessary to change these
properties from their default values.

JCECSP_DEBUG
In order to specify the debugging level, set this property with a
command of the form:

java -DJCECSP_DEBUG=debuglevel myApp.

In this command, debuglevel is the numeral associated with the desired

level of debugging.

By default, the debuglevel of JCECSP_DEBUG is set to 0. You should

not have to reset JCECSP_DEBUG unless so directed by Support at
nCipher.

JCECSP_DEBUGFILE
In order to specify to which file debugging output is sent, set this
property with a command of the form:

java -DJCECSP_DEBUGFILE=debugfile myApp.

nShield/payShield Operator Guide Windows v5.5 113

6 nCipher application interfaces nCipherKM JCA/JCE CSP

In this command, debugfile is the name of the file that you wish
debugging output to be sent.

It is not necessary to set JCECSP_DEBUGFILE unless you have set

JCECSP_DEBUG to a value other than its default of 0.

protect
The nCipherKM key generation classes always generate secure
private keys that cannot be exported outside the module. This means
that private keys generated by the nCipherKM provider can only be
used by nCipherKM engine classes. Public keys generated by the
nCipherKM provider can be exported as an X.509 encoding.

Keys generated by the nCipherKM provider can be stored in an

nCipher security world using the nCipherKM KeyStore. It is also
possible to store keys that were generated by another JCE provider
(but not world infrastructure. It is up to the application to attempt to
destroy all software backups of the old key.

If the Java system property seeintegname is set, the generated key is

an SEE application key. The key will only be usable by an SEE
application signed with the seeinteg key specified by seeintegname.

The generated key is not recorded in the security world unless the key
is stored in an nCipher KeyStore. In such a case, the pass phrase
supplied must equal the pass phrase for the card of the card set that
protects the key.

Checking the installation of the nCipherKM JCA/JCE CSP

In order to check that the nCipherKM JCA/JCE CSP has been
installed correctly, run the KmcspTest utility as follows:

cd C:\nfast\java\classes
java -classpath "%CLASSPATH%;." KmcspTest

nShield/payShield Operator Guide Windows v5.5 114

6 nCipher application interfaces PKCS #11

KmcspTest displays a message, similar to the following, showing the

providers that are installed on your system:

1 - nCipherKM version version2 - SUN version 1.2

This message indicates that the nCipherKM provider is installed as

the default provider.

PKCS #11
In order to use the nCipher PKCS #11 library, you must tell the
application the name and location of the library. The exact method for
doing this depends on the application.

There are detailed instructions for using the nCipher PKCS #11
library with specific applications available from the nCipher web site,
http://www.ncipher.com/, or from [email protected].

Depending on the application, you may need to set the path and
library name C:\nfast\toolkits\pkcs11\cknfast.dll in a dialog box or
configuration file.

The PKCS #11 library supplied by nCipher has security options

which you must configure before you use the PKCS #11 library. For
full details, see PKCS #11 library with Security Assurance
Mechanism on page 118.

From version 1.7, the nCipher PKCS #11 library can be used with
FIPS 140-2 level 3 compliant security worlds. This version of the
library also introduces load sharing. This feature provides support for
multiple modules that are connected to a single server, spreading the
load of cryptographic operations between the modules in order to
provide scalability in terms of performance.
Note nCipher recommends that you use load sharing unless you have
existing code that is designed to run with multiple modules.

nShield/payShield Operator Guide Windows v5.5 115

6 nCipher application interfaces PKCS #11

In order to share keys with load sharing, you must create a 1-of-N
Operator Card Set that contains at least as many cards as you have
modules. All the cards on the Operator Card Set must have the same
pass phrase.
Note If you are using the preload utility in conjunction with the nCipher
PKCS #11 library, you can create K-of-N Operator Card Sets (see
preload on page 277).

Choosing functions
Some PKCS #11 applications enable you to choose which functions
you want to perform on the PKCS #11 token and which functions you
want to perform in your application.

The following paragraphs describe the functions that an nCipher

module can provide.

Generating random numbers and keys

The nCipher module includes a hardware random number generator.
A hardware random number generator provides greater security than
the pseudo-random number generators provided by host computers.
Therefore, you should always use the nCipher module to generate
random numbers and keys.

Digital signatures
The nCipher PKCS #11 library can use the nCipher module to sign
and verify messages using the following algorithms:
• DSA
• RSA
• DES3_MAC
• AES
• CAST128_MAC.

nShield/payShield Operator Guide Windows v5.5 116

6 nCipher application interfaces PKCS #11

The nCipher module is specifically optimized for public key

algorithms, and therefore it will provide significant acceleration for
DSA and RSA signature generation and verification. You should
always choose to perform asymmetric signature generation and
verification with the nCipher module (that is, RSA and DSA).

Asymmetric encryption
The nCipher PKCS #11 library can use the nCipher module to
perform asymmetric encryption and decryption with the RSA
algorithm.

The nCipher module is specifically optimized for asymmetric

algorithms, so you should always choose to perform asymmetric
operations with the nCipher module.

Symmetric encryption
The nCipher PKCS #11 library can use the nCipher module to
perform symmetric encryption with the following algorithms:
• DES
• Triple DES
• CAST128
• AES.

Because of limitations on throughput, these operations can be slower

on the nCipher module than on the host computer. However, although
the nCipher module may be slower than the host under a light load,
you may find that under a heavy load the advantage gained from off-
loading the symmetric cryptography (which frees the host CPU for
other tasks) means that you achieve better overall performance.

nShield/payShield Operator Guide Windows v5.5 117

6 nCipher application interfaces PKCS #11

Message digest
The nCipher PKCS #11 library can perform message digest
operations with MD2, MD5, SHA-1, SHA-256, SHA-384, and
SHA-512 algorithms. However, for reasons of throughput, the library
performs these operations on the host computer.

PKCS #11 library with Security Assurance Mechanism

It is possible for an application to use the PKCS #11 API in ways that
do not necessarily provide the expected security benefits, or which
might introduce additional weaknesses. For example, the PKCS #11
standard requires the nCipher library to be able to generate keys that
are extractable from the module in plaintext. An application could use
this ability in error, when a secure key would be more appropriate.

The PKCS #11 library with the Security Assurance Mechanism

(SAM), libcknfast, can help users to identify potential weaknesses,
and help developers create secure PKCS #11 applications more easily.

The SAM in the PKCS #11 library is intended to detect operations

that reveal questionable behavior by the application. If these occur,
the application fails with an explanation of the cause of failure.

After a review of your security policy and the way the application uses
the PKCS #11 library with the SAM, if there are questionable
operations that are considered to be acceptable and pose no security
risk, the PKCS #11 library can be configured to permit some, or all,
of them by means of the
CKNFAST_OVERRIDE_SECURITY_ASSURANCES environment
variable (described in
CKNFAST_OVERRIDE_SECURITY_ASSURANCES on page
126).
Note To ensure the security of your keys, you must review any messages
returned by the PKCS #11 library before changing the settings of the
CKNFAST_OVERRIDE_SECURITY_ASSURANCES environment
variable.

nShield/payShield Operator Guide Windows v5.5 118

6 nCipher application interfaces PKCS #11

The CKNFAST_OVERRIDE_SECURITY_ASSURANCES
environment variable uses a semicolon separated list of parameters,
with associated values, to explicitly allow operations that could
compromise the security of cryptographic keys if the operations are
not well understood.

If no parameters, or the none parameter, are supplied to the

CKNFAST_OVERRIDE_SECURITY_ASSURANCES #11 library fails
to perform the operation in question, and issues a warning, when the
following operations are detected:
• creating short term session keys as long term objects
• creating keys that can be exported as plain text
• importing keys from external sources
• creating or importing wrapping keys
• creating or importing unwrapping keys
• creating keys with weak algorithms (such as DES)
• creating keys with short key lengths.

See CKNFAST_OVERRIDE_SECURITY_ASSURANCES on page

126 for more information about parameters and diagnostic warnings.

Key security
The questionable operations largely relate to the concept of a key
being secure. A private or secret key is considered insecure if there is
some reason for believing that its value may be available outside the
module. Public keys are never considered insecure; by definition they
are intended to be public.

An explicitly insecure PKCS #11 key is one where CKA_SENSITIVE

is set to false. If an application uses a key that is insecure but
CKA_SENSITIVE is not set to false, it is possible that the application
is using an inadequate concept of key security, and that the library

nShield/payShield Operator Guide Windows v5.5 119

6 nCipher application interfaces PKCS #11

disallows use of that key by default. Use of insecure keys should, by

default, be restricted to short term session keys, and applications
should explicitly recognize the insecurity.

Using the nCipher PKCS #11 library

After you have loaded the nCipher PKCS #11 library, it is added to
your application's list of cryptographic modules or PKCS #11 slots.

Whether or not the library uses load sharing depends on the value of
the CKNFAST_LOADSHARING environment variable, described in
CKNFAST_LOADSHARING on page 124.

nCipher PKCS #11 library with load sharing

The nCipher PKCS #11 library creates a virtual slot for every
Operator Card Set in the security world (returning the name of the
card set) unless you have set CKNFAST_CARDSET_HASH (as
described in CKNFAST_CARDSET_HASH on page 125).

An additional virtual slot may be returned (with the label of

accelerator ), depending on the value given to the variable
CKNFAST_NO_ACCELERATOR_SLOTS (described in
CKNFAST_NO_ACCELERATOR_SLOTS on page 125).
Accelerator slots can:
• be used to support session objects
• be used to create module protected keys
• not be used to create private objects.

When you insert a smart card from an Operator Card Set in the current
security world, the nCipher PKCS #11 library treats this card as a
PKCS #11 token that is present in the virtual slot for that Operator
Card Set.

After the PKCS #11 token is present, you can open a session to that
token. Until you log in, a session can only access public objects that
belongs to that PKCS #11 token.

nShield/payShield Operator Guide Windows v5.5 120

6 nCipher application interfaces PKCS #11

The PKCS #11 token is present until you remove the last card
belonging to the Operator Card Set. When you remove the token, the
nCipher PKCS #11 library closes any open sessions.

Logging in gives access to the private objects that are protected by the
PKCS #11 token. Logging in requires the pass phrase for the Operator
Card Set. The exact mechanism for supplying the pass phrase depends
on the application that you are running.

The PKCS #11 token is shared across all the modules that have a
smart card from the Operator Card Set in the reader at the point that
you log in. After you have logged in, inserting additional cards from
this Operator Card Set has no effect.

If you remove a smart card that belongs to a logged-in token, the

nCipher PKCS #11 library closes any open sessions and marks the
token as being not present (unless the Operator Card Set is persistent).
Removing a card from a persistent Operator Card Set has no effect,
and the PKCS #11 token remains present until you log out.

nCipher PKCS #11 library without load sharing

There will be two entries for each module, unless you have set
CKNFAST_NO_ACCELERATOR_SLOTS .
Note The entry called accelerator cannot be used to create private objects.
It can be used to create module-protected keys.

Use the second of the two entries (which has the same name as the
Operator Card that is currently in the smart card reader) to protect
your keys or token objects.

PKCS #11 does not allow two tokens to be present in the same slot.
Therefore, when you insert a smart card into a reader, the nCipher
PKCS #11 library logs out any previously logged-in token from the
slot and closes any open sessions.

nShield/payShield Operator Guide Windows v5.5 121

6 nCipher application interfaces PKCS #11

nCipher PKCS #11 library with the preload utility

You can use the preload utility to pre-load K-of-N #11 card sets for
applications that cannot otherwise use them. preload loads the logical
token and then passes it to the PKCS #11 utilities.

You must provide any required pass phrase for the tokens when using
preload to load the card set. However, because the application is not
aware that the card set has been pre-loaded, the application operates
normally when handling the login activity (including prompting for a
pass phrase), but the PKCS #11 library will not actually check the
supplied pass phrase.

Normally, preload uses environment variables to pass information to

the program using the pre-loaded objects, including the PKCS #11
library. Therefore, if the application you are using is one that clears its
environment before the PKCS #11 library is loaded, you must set the
appropriate values in the cknfastrc file (see nCipher PKCS #11 library
environment variables on page 123). The current environment
variables remain usable. The default setting for the
CKNFAST_LOADSHARING environment variable changes from
specifying load sharing as disabled to specifying load sharing as
enabled. Moreover, in load-sharing mode, the loaded card set is used
to set the environment variable CKNFAST_CARDSET_HASH so that
only the loaded card set is visible as a slot.

The NFAST_NFKM_TOKENSFILE environment variable must also

be set in the cknfastrc file to the location of the pre-load file. See the
Administrator Guide for information about environment variables.

A logical token pre-loaded by preload for use with nCipher’s

PKCS #11 library is the only such token available to the application
for the complete invocation of the library. You can use more than one
module with the same card set.

If the loaded card set is non-persistent, then a card must be left in each
module on which the set has been loaded during the start-up sequence.
After a non-persistent card has been removed, the token is not present
even if the card is reinserted.

nShield/payShield Operator Guide Windows v5.5 122

6 nCipher application interfaces PKCS #11

If load sharing has been specifically switched off, you see multiple
slots with the same label.

nCipher PKCS #11 library environment variables

The nCipher PKCS #11 library uses the following environment
variables:
• CKNFAST_TOKENS_PERSISTENT
• CKNFAST_LOADSHARING
• CKNFAST_CARDSET_HASH
• CKNFAST_NO_ACCELERATOR_SLOTS
• CKNFAST_NO_SYMMETRIC
• CKNFAST_FAKE_ACCELERATOR_LOGIN
• CKNFAST_DEBUGDIR
• CKNFAST_ASSUME_SINGLE_PROCESS
• CKNFAST_OVERRIDE_SECURITY_ASSURANCES
• CKNFAST_USE_THREAD_UPCALLS
• CKNFAST_NVRAM_KEY_STORAGE

If you use the default values in the installation script, you should not
need to change any of these environment variables.

You can set environment variables in the file cknfastrc. This file must
be in the directory $NFAST_HOME. If NFAST_HOME is not set, or if
environment variables are cleared by your application, the file must be
in C:\nfast\bin\.

Each line of this file must be of the form:

variable=value

Note Variables set in the environment are used in preference to those set in
the resource file.

nShield/payShield Operator Guide Windows v5.5 123

6 nCipher application interfaces PKCS #11

Changing the values of these variables after you start your application
has no effect until you restart the application.

CKNFAST_TOKENS_PERSISTENT
This variable controls whether Operator Cards that are created by
your PKCS #11 application are persistent (see Persistent Operator
Card Sets on page 50 for a description of persistence). If this variable
is set when your application calls the PKCS #11 function that creates
tokens, the Operator Card created is persistent.
Note Use of the nCipher PKCS #11 library to create tokens is deprecated,
because it can only create 1-of-1 tokens in FIPS 140-2 level 2
security worlds. Use KeySafe or one of the command-line utilities to
create Operator Card Sets.

CKNFAST_LOADSHARING
In order to enable load-sharing mode, set the environment variable
CKNFAST_LOADSHARING to a value that starts with something
other than 0, N, or n. The virtual slot behavior described in nCipher
PKCS #11 library with load sharing on page 120 then operates. When
this variable is not set (or is set to a value that starts with 0, N, or n),
you see two slots for every module connected (as described in nCipher
PKCS #11 library without load sharing on page 121).

Applications that enable the user to select the slot, or that dynamically
select a slot based on its capabilities, should work without requiring
the backward capability mode.

Note To use softcards with PKCS #11, you must have

CKNFAST_LOADSHARING set to a nonzero value. When using pre-
loaded softcards or other objects, the PKCS #11 library automatically
sets CKNFAST_LOADSHARING=1 (load-sharing mode on) unless it
has been explicitly set to 0 (load-sharing mode off).

nShield/payShield Operator Guide Windows v5.5 124

6 nCipher application interfaces PKCS #11

CKNFAST_CARDSET_HASH
This variable enables you to specify a specific card set to be used in
load sharing mode. If this variable is set, only the virtual smart card
slot that matches the specified hash is present (plus the accelerator
slot). The hash that you use to identify the card set in
CKNFAST_CARDSET_HASH is the SHA-1 hash of the secret on the
card. Use the nfkminfo command-line utility to identify this hash for
the card set that you want to use: it is listed as hkltu. See the
Administrator Guide for further information on using nfkminfo.

CKNFAST_NO_ACCELERATOR_SLOTS
If this variable is set, the nCipher PKCS #11 library does not create
the accelerator slot, and thus the library only presents the smart card
slots (real or virtual, depending on whether load sharing is in use).

Do not set this environment variable if you want to use the accelerator
slot to create or load module protected keys.
Note Setting this environment variable has no effect on ckcheckinst because
ckcheckinst needs to list accelerator slots.

CKNFAST_NO_SYMMETRIC
If this variable is set, the nCipher PKCS #11 library does not advertise
any symmetric key operations.

CKNFAST_NO_UNWRAP
If this variable is set, the nCipher PKCS #11 library does not advertise
the c_wrap and c_unwrap commands. You should set this variable if
you are using iPlanet or Netscape Certificate Management Server as
it ensures that a standard SSL handshake is carried out. If not set
iPlanet or Netscape Certificate Management Server makes extra calls
which reduces the speed of the library.

nShield/payShield Operator Guide Windows v5.5 125

6 nCipher application interfaces PKCS #11

CKNFAST_FAKE_ACCELERATOR_LOGIN
If this variable is set, the nCipher PKCS #11 library accepts a PIN for
a module-protected key, as required by iPlanet, but then discards it.
This means that an iPlanet user requesting a certificate protected by a
loadshared module can enter an arbitrary PIN and obtain the
certificate.
Note The variable CKNFAST_FAKE_ACCELERATOR_LOGIN is only
available for iPlanet Enterprise Edition 6.

CKNFAST_DEBUGDIR
If this variable is set to the name of a writeable directory, log files are
written to the specified directory. The name of each log file contains
a process ID. This can make debugging easier for applications that
fork a lot of child processes.

CKNFAST_ASSUME_SINGLE_PROCESS
This variable is set by default to 1. This means that only token objects
that are loaded when C_Initialize is called are visible. Setting this
variable to 0 means that token objects created in one process become
visible in another process when it call C_FindObjects. Setting the
variable to 0 slows the library down.

CKNFAST_ASSURANCES_LOG
This variable is used to direct warnings about questionable security to
a specific log file. Do not change this variable without advice from
your application vendor.

CKNFAST_OVERRIDE_SECURITY_ASSURANCES
This variable can be assigned one or more of the following
parameters, with an associated value where appropriate, to override
the specified security assurances in key operations where this is
deemed acceptable:

nShield/payShield Operator Guide Windows v5.5 126

6 nCipher application interfaces PKCS #11

• all
• none
• tokenkeys
• longterm [=days]
• explicitness
• import
• unwrap_mech
• unwrap_kek
• weak_algorithm
• shortkey_algorithm=bitlength
• silent

Each parameter specified is separated by a semicolon. On the

command line, enter the following to set the variable:

CKNFAST_OVERRIDE_SECURITY_ASSURANCES="token1;token2=value3"

In the configuration file, enter the following to set the variable:

CKNFAST_OVERRIDE_SECURITY_ASSURANCES=token1;token2=value3

Unknown parameters generate a warning; see Diagnostic warnings

about questionable operations on page 133.

The meaning of these parameters is described in the rest of this

section.

nShield/payShield Operator Guide Windows v5.5 127

6 nCipher application interfaces PKCS #11

all

This parameter overrides all the security checks. It has the same effect
as setting all the other parameters, except none. The library does not
perform any of the security checks and allows the library to perform
potentially insecure operations. This parameter cannot be used with
any other parameters.

none

This parameter does not override any of the security checks. It has the
same effect as setting none of the other parameters. The library
performs all security checks and warns about potentially insecure
operations without performing them. This parameter cannot be used
with any other parameters.

tokenkeys

This parameter permits applications to request that insecure keys are

stored long-term by the cryptographic hardware and library.

Some PKCS #11 applications create short-term session keys as

longterm objects in the cryptographic provider, for which strong
protection by the module is not important. It is therefore not
necessarily a problem if this token needs to be set, provided the keys
are intended to be long term, as the longterm keys restriction will
trigger automatically. If you set the tokenkeys parameter, ensure that
your Quality Assurance process will test all of your installation’s
functionality at least 48 hours after the system was set up to check that
the lifetime of keys is as expected.

When this parameter is set, the effect on the PKCS #11 library is to
permit insecure Token keys. By default, any attempts to create,
generate, or unwrap insecure keys with CKA_TOKEN=true fails with
CKR_TEMPLATE_INCONSISTENT and a log message that explains
the insecurity. When tokenkeys is included as a parameter for

nShield/payShield Operator Guide Windows v5.5 128

6 nCipher application interfaces PKCS #11

CKNFAST_OVERRIDE_SECURITY_ASSURANCES, attempts to
create, generate, or unwrap insecure keys with CKA_TOKEN=true
are allowed.

longterm[=days]

This parameter permits an insecure key to be used days days after it

was created. Usually insecure keys may not be used more than 48
hours after their creation. If days is not specified, there is no time limit.

Needing to set this variable usually means that some important keys,
which should be protected by the module’s security, are not secure.

When longterm is set, the PKCS #11 API permits the use of the
following functions with an insecure key up to the specified number
of days after its creation:
• C_Sign and C_SignUpdate
• C_Verify and C_VerifyUpdate
• C_Encrypt and C_EncryptUpdate
• C_Decrypt and C_DecryptUpdate

By default these functions fail with CKR_FUNCTION_FAILED, or

CKR_KEY_FUNCTION_NOT_PERMITTED, and a log message that
explains the insecurity of these functions when used with an insecure
private or secret key more than 48 hours after the creation of the key
as indicated by time() on the host.

When the longterm[=days] parameter is set, C_SignInit, C_VerifyInit,

C_EncryptInit , C_DecryptInit, and a new read-only
CKA_VENDOR_DEFINED attribute, CKA_CREATION_DATE are
added to the key.

nShield/payShield Operator Guide Windows v5.5 129

6 nCipher application interfaces PKCS #11

explicitness

This parameter permits applications to create insecure keys without

explicitly recognizing that they are insecure, by setting the flag that
allows export as plain text. An insecure key is one whose plain text is
available to an attacker on the host, so it makes no sense to restrict
legitimate users’ access to the plain text of the key value.
Note Needing to set this variable usually indicates that the application
designers were not familiar with the security properties of the PKCS
#11 interface. It is not necessarily always a problem in itself, but it
does indicate that a review of the application’s security policies and
use of the PKCS #11 API should be carried out.

When this parameter is set, the effect on the PKCS #11 library is to
allow applications to create or import insecure keys which have
CKA_SENSITIVE set true. By default attempts to create, generate, or
unwrap insecure keys with CKA_SENSITIVE=true, or to set
CKA_SENSITIVE=true on an existing key, fails with
CKR_TEMPLATE_INCONSISTENT and a log message explaining
the insecurity.

When explicitness is supplied as a parameter for the

CKNFAST_OVERRIDE_SECURITY_ASSURANCES environment
variable, attempts to create, generate, or unwrap insecure keys with
CKA_SENSITIVE=true , or to set CKA_SENSITIVE=true on an
existing key, are allowed.

import

This parameter treats keys to be imported into the module’s protection

from insecure external sources as secure, provided that the application
requests security for them. Usually the library treats imported keys as
insecure for the purposes of checking the application's security policy,
because even though the imported copy may be secure, insecure
copies of the key may still exist on the host and elsewhere.

nShield/payShield Operator Guide Windows v5.5 130

6 nCipher application interfaces PKCS #11

If you are migrating from software storage to hardware protection of

keys you must enable this option once at the time of migration. You
should then disable it.
Note Needing to set this variable at other times indicates either that the
application designers thought that the key would be secure or that the
library thinks the key is supposed to be secure even though it is not
continuously kept in a secure environment.

When this parameter is set, the PKCS #11 API treats keys that are
imported through C_CreateObject or C_UnwrapKey as secure
(provided there is no other reason to treat them as insecure). By
default, keys which are imported through C_CreateObject or
C_UnwrapKey without this option in effect are marked as being
insecure. Only the setting of the parameter at the time of import is
relevant.

unwrap_mech

This parameter treats keys transferred into the module in an insecurely

encrypted form as if the encryption was secure. Strictly speaking, this
parameter allows key-decryption-keys to be used for insecure
decryption mechanisms as well as raw decryption.

Because there are no key decryption mechanisms, sometimes called

wrapping mechanisms, specified in PKCS #11 version v2.01 that are
both secure and suitable for long keys, any use of PKCS #11 unwrap
to create keys that are treated as secure requires the unwrap_mech
parameter of the
CKNFAST_OVERRIDE_SECURITY_ASSURANCES environment
variable to be set.

Setting the unwrap_mech parameter is necessary at the time the

wrapping key is created or imported.

When this parameter is set, the PKCS #11 API adds the
CKA_DECRYPT permission on decryption, even if the template has
CKA_DECRYPT=false. By default, trying to create a key with
CKA_UNWRAP=true and CKA_DECRYPT=false fails with

nShield/payShield Operator Guide Windows v5.5 131

6 nCipher application interfaces PKCS #11

CKR_TEMPLATE_INCONSISTENT . If unwrap_mech is supplied as

a parameter for CKNFAST_OVERRIDE_SECURITY_ASSURANCES
, then when the CKA_UNWRAP permission is requested on a key, the
library automatically adds the CKA_DECRYPT permission, even if
the template has CKA_DECRYPT false, because abuse of the
decryption mechanisms would allow a program to use the library to
decrypt with the key.

unwrap_kek

When a key is transferred into the module in encrypted form, the key
is usually treated as insecure unless the key that was used for the
decryption, the key-encrypting key (or unwrapping key), only allows
the import and export of keys and not decryption of arbitrary
messages. This behavior is necessary to prevent an unauthorized
application from simply decrypting the encrypted key instead of
importing it. However, because PKCS #11 wrapping mechanisms are
insecure, all unwrapping keys have CKA_DECRYPT=true.

When this parameter is set, the PKCS #11 API considers keys that are
unwrapped with a key that also has CKA_DECRYPT permission as
secure (provided there is no other reason to treat them as insecure). By
default, keys that are unwrapped with a key that has CKA_DECRYPT
permission are considered insecure.

weak_algorithm

This parameter treats keys for the specified weak algorithm as if they
were secure. For example, DES is not secure, but weak_des allows
such keys to be considered secure anyway. This applies to all keys
which have a short fixed key length or whose algorithms have other
security problems (as a guide, weak algorithms are ones whose work
factor to break is less than approximately 80 bits).

nShield/payShield Operator Guide Windows v5.5 132

6 nCipher application interfaces PKCS #11

shortkey_algorithm=bitlength

This parameter treats excessively short keys for the specified

algorithm as if they were secure. The length is the minimum length,
in bits, that will be considered secure. For example, RSA keys must
usually be at least 1024 bits to be considered secure, but
shortkey_rsa=768 would allow 768-bit RSA keys to be considered
secure.

silent

This parameter turns off the warning output. Checking is still

performed, and the check still returns failures correctly according to
the other variables that are set.

Diagnostic warnings about questionable operations

When the CKNFAST_OVERRIDE_SECURITY_ASSURANCES

environment variable is set to a value other than all, diagnostic
messages are always generated for questionable operations. Each
message contains the following elements:
• the PKCS #11 label of the key, if available
• the PKCS #11 identifier of the key, if available
• the hash of the key
• a summary of the problem. This may be a questionable operation
that has been permitted because of a setting in
CKNFAST_OVERRIDE_SECURITY_ASSURANCES or an
operation that has failed. In this case, the setting required to
authorize the operation is noted.

By default, these messages are sent to stderr. On Windows platforms,

they are also always sent to the Event Viewer.

If a file is also specified in the CKNFAST_ASSURANCE_LOG

environment variable, these messages are written to this file.

nShield/payShield Operator Guide Windows v5.5 133

6 nCipher application interfaces PKCS #11

If CKNFAST_DEBUG is 1 or greater and a file is specified in

CKNFAST_DEBUGFILE #11 library Security Assurance Mechanism
log information is sent to the specified file. These variables must be
set whenever generatekey or KeySafe are used.
Note If a file is specified in CKNFAST_ASSURANCES_LOG and no file is
specified in CKNFAST_DEBUGFILE (or if CKNFAST_DEBUG is 0),
diagnostic messages are send to stderr as well as to the file specified
in CKNFAST_ASSURANCES_LOG.

CKNFAST_USE_THREAD_UPCALLS
If this variable is set and CKF_OS_LOCKING_OK is passed to
C_Initialize,NFastApp_SetThreadUpcalls is called via
nfast_usencthreads, and only a single NFastApp_Connection is used,
shared between all threads.

If this variable is set and mutex callbacks are passed to C_Initialize but
CKF_OS_LOCKING_OK is not passed, C_Initialize fails
withCKR_FUNCTION_FAILED. (NFastApp_SetThreadUpcalls
requires more callbacks than just the mutex ones that PKCS #11
supports.)

If neither mutex callbacks nor CKF_OS_LOCKING_OK is passed,

this variable is ignored. Only a single connection is used because the
application must be single threaded in this case.

CKNFAST_NVRAM_KEY_STORAGE
When this environment variable is set, the PKCS #11 library
generates only keys in nonvolatile memory (NVRAM). You must also
ensure this environment variable is set in order to delete NVRAM-
stored keys.

nShield/payShield Operator Guide Windows v5.5 134

6 nCipher application interfaces PKCS #11

Checking the installation of the nCipher PKCS #11 library

After you have created a security world, ensure that the nCipher
PKCS #11 library has been successfully installed by using the
ckcheckinst command-line utility. In a FIPS 140-2 level 3 compliant
security world, you need an Operator Card from the security world to
run this utility. If you did not install your security world in FIPS 140-
2 level 3 mode, you can run the utility by using either an Operator
Card or a fixed token.

To verify the installation of the nCipher PKCS #11 library, follow

these steps:

nShield/payShield Operator Guide Windows v5.5 135

6 nCipher application interfaces PKCS #11

1. Give the command ckcheckinst.

If you have an invalid security world (for example, if all your
modules are in the initialization state), ckcheckinst quits with the
following error message:

ckcheckinst: C_Initialize failed rv = 00000006

Is the security world initialized? (Use nfkminfo to check)

If your security world is valid, ckcheckinst displays information

similar to the following:

PKCS#11 library interface version 2.01

flags 0
manufacturerID "nCipher Corp. Ltd "
libraryDescription "nFast PKCS#11 1.#.# "
implementation version 1.##
Strictfips 140 enabled
Load sharing and Failover enabled

slot Status Label

===== ====== =====
1 Operator card "card2 "
2 Operator card "card3 "
Select slot Number to run library test or 'R'etry or to 'E'xit:

In this output:
PKCS#11 library interface version 2.01
refers to the version of the PKCS #11 specification
supported
implementation version 1.##
refers to the version of the nCipher PKCS #11 library
Loadsharing and Failover enabled
is shown if load sharing has been enabled.
Slots that contain a valid Operator Card are indicated by the
status Operator card and the card’s label. In a FIPS 140-2 level 2
compliant security world, the available fixed tokens are also

nShield/payShield Operator Guide Windows v5.5 136

6 nCipher application interfaces PKCS #11

listed for selection.

If you insert a blank card or an unrecognized card (for example,
an Operator Card from a different security world or an
Administrator Card), this is indicated in the Status column. The
corresponding slot number is not available.
Note If you are using the preload utility in conjunction with the nCipher
PKCS #11 library, you can only see the token that you loaded with the
preload utility. In load-sharing mode, the loaded card set is used to set
the environment variable CKNFAST_CARDSET_HASH, so only this
card set is visible as a slot.
If you have no available slots, ckcheckinst displays No token
present beside the relevant slot numbers.
ckcheckinst gives you the following choices:

No removable tokens present.

Please insert an operator card into at least one available slot and
enter 'R' retry.
If you have not created a an operator card, enter a fixed token slot
number (if available)
Or 'E' to exit this program and create a card set before continuing.

2. If there are no available slots with cards in them, you can do one
of the following:
- insert a valid Operator Card, and press R
- choose a fixed token slot
- press E to quit, then create an Operator Card Set, and run
ckcheckinst again.
When there is at least one slot with a valid token, input a slot
number, and press Enter . In a FIPS 140-2 level 3 compliant
security world, ckcheckinst prompts you to enter the pass phrase
for the selected Operator Card.

nShield/payShield Operator Guide Windows v5.5 137

6 nCipher application interfaces PKCS #11

3. Type the pass phrase, and press Enter .

ckcheckinst displays the results of the tests:

Test Pass/Failed
---- -----------
1 Generate RSA key pair Pass
2 Generate DSA key pair Pass
3 Encryption/Decryption Pass
4 Signing/Verify Pass
Deleted test keys ok
PKCS11 Library test successful.

If any tests fail, ckcheckinst displays a message indicating the failure

and quits. It does not run any subsequent tests.

If ckcheckinst fails:
• check that the nCipher server is running
• use the enquiry and nfkminfo world.

If all seems in order, reinstall the nCipher library.

How the nCipher PKCS #11 library protects keys

Session objects are created on a module and never leave that module.
The following table lists the protection for different types of
PKCS #11 token objects:

Smart card Slot Accelerator Slot

Private Token Object Operator Card Set not supported
Public Token Object security world security world
Public key well known module key well known module key

nShield/payShield Operator Guide Windows v5.5 138

6 nCipher application interfaces PKCS #11

Operator Card Set

The object is stored as an nCipher key blob encrypted by the

Operator Card Set key. You must log in to this Operator Card
Set before you can load this object.

security world

The object is stored as an nCipher key blob encrypted by the

security world key. This object can be loaded on to any
module in the security world. The nCipher PKCS #11
library only allows access if a card from this Operator Card
Set is present.

well-known module key

Public keys are encrypted under a well-known module key.

This encryption is for programming convenience only and
does not provide security. These keys can be loaded on any
nCipher module.

API restrictions in FIPS mode

C_InitToken is not supported by the nCipher PKCS #11 library in
FIPS 140-2 level 3 mode.

CKA_EXTRACTABLE must be false for all keys. CKA_Private must

be true for all private keys and all secret keys.

Vendor specific error codes

nCipher defines the following vendor specific error codes:

CKR_FIPS_FUNCTION_NOT_SUPPORTED

This error code indicates that the function is not supported in

FIPS 140-2 level 3 mode, although it is supported in the FIPS
140-2 level 2 mode.

nShield/payShield Operator Guide Windows v5.5 139

6 nCipher application interfaces Check Point VPN-1/Firewall-1

CKR_FIPS_TOKEN_NOT_PRESENT

This error code indicates that an Operator Card is required

even though the card slot is not in use.

CKR_FIPS_MECHANISM_INVALID

This error code indicates that the current mechanism is not

allowed in FIPS 140-2 level 3 mode.

Check Point VPN-1/Firewall-1

nCipher supplies a Check Point configuration tool that configures a
Check Point VPN-1/Firewall-1 installation to use the nCipher module
for secure key storage.

Before you use the Check Point configuration tool, you must have:
• installed nCipher hardware
• installed nCipher software
• set up an nCipher security world with an Operator Card Set
• installed the Check Point VPN-1/Firewall-1 software

The Check Point configuration tool, ConfigPKCS11onCP, is installed

in the directory C:\nfast\toolkits\PKCS11\. The ConfigPKCS11onCP
tool has no command line options. Simply executing it configures the
Check Point installation to use the nCipher module for secure key
storage. The tool creates or amends the cknfastrc file to create a
suitable setup for Check Point to use the nCipher PKCS #11 library.

nCipher native and Custom applications

Use the nCipher native option for applications that were written using
nCipher key management and that expect keys to be both protected by
the security world and stored in the security world data structure.

nShield/payShield Operator Guide Windows v5.5 140

6 nCipher application interfaces Microsoft Cryptographic API

Use the Custom external application option for applications that were
written using nCipher key management and that expect their keys to
be in stand-alone files.
Note KeySafe does not place any restrictions on the Operator Card Set that
is used to protect nCipher native or Custom application keys. You
must make sure that your application is capable of loading the card
set.

Microsoft Cryptographic API

For information about using the Microsoft Cryptographic API, see the
Integration Guide.

nShield/payShield Operator Guide Windows v5.5 141

Chapter 7: nShield Operator Utilities
This chapter contains reference information about the utilities
referred to in this manual. See the Administrator Guide 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 Operator Guide Windows v5.5 142

7 nShield Operator Utilities bulkerase

bulkerase
The bulkerase utility is used to erase large numbers of cards in the
same session. You must be careful because the utility can erase any
FEM activation cards. The bulkerase utility can only erase Operator
Cards from a security world of which the module is a member.
bulkerase is a very powerful tool. You must be absolutely certain that
the cards you intend to erase, particularly FEM enabling cards, are
definitely no longer needed.

Usage

bulkerase [-v|--verbose] [-m|--module=MODULE [-m|--module=MODULE ...]]

--module= MODULE

This option specifies that the module MODULE is to be used

for erasing cards. Multiple modules can be specified. The
default is to use all modules.

--verbose

This option specifies that verbose output is required.

nShield/payShield Operator Guide Windows v5.5 143

7 nShield Operator Utilities cardpp

cardpp
The cardpp changes the pass phrase on a card when you know the
current pass phrase.

Usage

cardpp -e|--examine -c| --change -k|--check -r|--recover [-m|--module=MODULE]

The cardpp command-line utility polls all available slots. If there is no

card inserted, it prompts you to insert one.

If the card belongs to the current security world, cardpp prompts you
to enter the old pass phrase (if one is set).

If you enter the old pass phrase correctly, cardpp prompts you to enter
the new pass phrase and then to confirm it. After you have confirmed
the new pass phrase, cardpp then changes the card’s pass phrase.

Options
-e, --examine

These options tell cardpp to examine inserted cards.

-c, --change

These options tell cardpp to change the pass phrase of a card.

-k, --check

These options tell cardpp to check the pass phrase of a card.

-r, --recover

These options tell cardpp to recover the pass phrase from an

Operator Card.

nShield/payShield Operator Guide Windows v5.5 144

7 nShield Operator Utilities cardpp

-m, --module=MODULE

This option specifies 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 Operator Guide Windows v5.5 145

7 nShield Operator Utilities ckcerttool

ckcerttool
This utility allows you to import a certificate as a PKCS #11
CKO_CERTIFICATE object of type CKC_X_509 and associate it with
a corresponding RSA private key.

When ckcerttool imports a certificate, it correctly fills in the following

CKC_X_509 certificate object attributes:
• CKA_SUBJECT
• CKA_ISSUER
• CKA_SERIAL_NUMBER
• CKA_LABEL.

CKA_SUBJECT, CKA_ISSUER, and CKA_SERIAL_NUMBER are

extracted from the imported file. You must supply a value for
CKA_LABEL on the command line (otherwise, the default value
ncipher-cert is used).

CKA_LABEL and CKA_SUBJECT are applied to the corresponding

private key specified on the command line.

Usage
To import a card-set-protected or softcard-protected certificate, give a
command of the form:

ckcerttool -c|--cardset=CARDNAME -f|--certfile=FILENAME -k|--keyident=KMDATAKEYID [-L|-

-certname=NAME]

To import a module-protected certificate (without a pass phrase or

card-set name), give a command of the form:

ckcerttool -n|--nopin -f|--certfile=FILENAME -k|--keyident=KMDATAKEYID [-L|--

certname=NAME]

nShield/payShield Operator Guide Windows v5.5 146

7 nShield Operator Utilities ckcerttool

-c, --cardset=CARDNAME

These options specify the name (CARDNAME) of the card set

or softcard that protects the certificate.

-f, --certfile FILENAME

These options specify the name (FILENAME) of the .pem

format file containing the certificate.

-k, --keyident KMDATAKEYID

These options specify the NFKM key ident

(KMDATAKEYID) of the corresponding key.

-n, --nopin

These options specify that the object is to be a public object

(C_Login is not called).

-L, --certname NAME

These options specify a name (NAME) for the certificate that

is stored as CKA_LABEL. If you do not specify
CKA_LABEL, the default label is ncipher-cert.

Help options
-h, --help

These options display help for ckcerttool.

-V, --version

These options display the version number of ckcerttool.

-u, --usage

These options display a brief usage summary for ckcerttool.

nShield/payShield Operator Guide Windows v5.5 147

7 nShield Operator Utilities checkmod

checkmod
The checkmod utility checks modulo exponentiations performed on
the module against test data.

checkmod does not work with the testdata-crt-* files.

Usage

C:\nfast\bin\checkmod.exe [testfile [testfile ...]]

In this command, testfile is the name of a test file. The test file consists
of lines that contain values for the modexp command: variables A, P,
and N, as well as the result R .

Several example test data files are provided in the C:\nfast\testdata

directory. The name of each file starts with testdata.

Output
checkmod counts the number of successful commands, for example:

C:\nfast\bin\checkmod C:\nfast\testdata\testdata-s1024-n100
File C:\nfast\testdata\testdata-s1024-n100:
100 completed OK

If any command fails or if the value returned does not match the value
supplied in the test file, checkmod prints an error message and then
terminates.

nShield/payShield Operator Guide Windows v5.5 148

7 nShield Operator Utilities cksigtest

cksigtest
The cksigtest utility is supplied with the nCipher PKCS #11 library. It
measures the module signing or encryption speed when used with
nCipher PKCS #11 library calls.

The default is 1024-bit RSA signature generation with a buffered

output stream to stdout using 30 threads running for 60 seconds.

Usage

C:\nfast\bin\cksigtest [-s|--sign] [-v|--verify] [-d|--decrypt] [-e|--encrypt] [-S|--

sig-type=TYPE] [-l|--key-size=BITS] [-m|--mech=MECH] [-c|--cardsets=NAME] [-j|--
threads=COUNT] [-B|--unbuffered-stdout] [-t|--stop-after=TIME] [-p|--pin-for-
testing=PIN] [-n|--nopin]

Options

Help options

-h, --help

These options display help for cksigtest

-V, --version

These options display the version number of cksigtest

-u, --usage

These options display a brief usage summary for cksigtest

nShield/payShield Operator Guide Windows v5.5 149

7 nShield Operator Utilities cksigtest

Program options

-s, --sign

This option tests the sign operation. This action is performed

by default.

-v, --verify

This option tests the verify operation.

-d, --decrypt

This option tests the decrypt operation.

-e, --encrypt

This option tests the encrypt operation.

Key options

-S, --sig-type=TYPE

This option specifies the signature type to use. TYPE is one

of RSA, DSA, EC (if available), and KCDSA (if available).
The default is RSA.
Note The EC signature type is only available if you have enabled the
Elliptic Curve feature. See the Administrator Guide for information
about feature enabling.

-l, --key-size=BITS

This option specifies the length of the key in bits. The default
is 1024. This parameter is not required for a DSA key, which
is always 1024 bits long.
Note The module may run out of memory if you run cksigtest with sizes
greater than 2048, especially if the module has any other keys or
tokens loaded.

nShield/payShield Operator Guide Windows v5.5 150

7 nShield Operator Utilities cksigtest

-M, --mech=MECH

This option specifies the mechanism to use. MECH is one of

DSA, DSA_SHA1, SHA1_RSA_PKCS, RSA_X_509,
RSA_PKCS, EC_SHA1 (if available), and KCDSA_HAS160
(if available). The default is RSA_PKCS.
Note The EC_SHA1 mechanism is only available if you have enabled the
Elliptic Curve feature. See the Administrator Guide for information
about feature enabling.

Other options
-c, --cardset=NAME

This option specifies specifies the token label to use. The

token label is usually the name of the cardset in the slot, but
may be a label associated directly with the slot. If you use
this option on a slot with the label accelerator, you must also
specify the --nopin option.

-j, --threads=COUNT

This option specifies specifies the maximum number of

threads. The default is 30.

-B, --unbuffered-stdout

This option turns off buffering for stdout.

-t, --stop-after=TIME

This option specifies the maximum time in seconds to run

the command. The command quits after the first results
announcement after TIME seconds The minimum is 1
second. The default is 60 seconds.

nShield/payShield Operator Guide Windows v5.5 151

7 nShield Operator Utilities cksigtest

-p, --pin-for-testing=PIN

This option specifies the PIN to use for C_Login. If this

option is specified, the PIN is exposed in the clear. This
option is appropriate only for testing. This option is required
if you are working in FIPS 140-2 level 3 mode.

-n, --nopin

This option specifies not to call C_Login. The object created

will be a public object.

Output
cksigtest produces output similar to this:

Using slot[0] (label "accelerator ")

Using slot[1] (label "fred ")
Generating 1024-bit RSA key
testing signing
starting timing, timelimit 60s
total 2604, 260/s
total 5244, 264/s
total 7869, 262/s
total 10499, 263/s
total 13091, 259/s
timing done
15720 operations in 60 seconds, average 262 operations per second
OK

Totals and averages are returned once every 10 seconds for short runs
and every minute for long runs.

The first numeric column shows the total number of operations

achieved so far.

The second numeric column shows the average number of operations

achieved each second over the course of the previous minute.

nShield/payShield Operator Guide Windows v5.5 152

7 nShield Operator Utilities createocs

createocs
The createocs creates an Operator Card Set.

Usage

createocs -m|--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]

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.

createocs prompts you to insert and remove cards as required.

Options
-m, --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, N is the total number of cards and K is the

minimum required number of cards. You can either specify
K/N together or specify nothing, in which case the default of
1/1 is used.
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.

nShield/payShield Operator Guide Windows v5.5 153

7 nShield Operator Utilities createocs

-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 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 means 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
the Administrator Guide.

-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 use is not blank.
You can only employ --force to reuse Operator Cards from
the current security world, or cards containing unknown

nShield/payShield Operator Guide Windows v5.5 154

7 nShield Operator Utilities createocs

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 Card never times
out. Otherwise, the module automatically unloads the
Operator Card Set TIME after the Operator Card was loaded.

nShield/payShield Operator Guide Windows v5.5 155

7 nShield Operator Utilities cryptest

cryptest
The cryptest utility tests all defined symmetric cryptographic
mechanisms. cryptest can test encryption and signature mechanisms.

Although defined, some mechanisms may not be supported on a

particular module because of licensing restrictions. See Appendix A:
Cryptographic algorithms for the list of supported algorithms in this
release. If the mechanism is supported, cryptest reports the sizes for
which it successfully encrypts and decrypts a message.

If a mechanism is defined but not supported by the module, cryptest

reports Unknown Mechanism.

Usage

C:\nfast\bin\cryptest.exe [-M|--module=MODULE][-e|--encryption] [-s|--signature] [-

E|--channel-encrypt]
[-S|--channel-decrypt] [-m|--max-size=BYTES] [-b|--channel-block-size=BYTES]

Test options
-M, --module=MODULE

These options specify the module on which to perform tests.

-e, --encryption

These options test encryption mechanisms

-s, --signature

These options test signature mechanisms

-E, --channel-encrypt

This option specifies the use of channel commands to

encrypt or sign

nShield/payShield Operator Guide Windows v5.5 156

7 nShield Operator Utilities cryptest

-S, --channel-decrypt

This option specifies the use of channel commands to

decrypt or verify

-m, --max-size=BYTES

This option limits the size of the block to be encrypted to the

number of bytes specified in BYTES

-b, --channel-block-size=BYTES

This option uses an update size for channels that is less than
or equal to the number of bytes specified in BYTES.

If neither the --encryption nor the --signature option is given, cryptest

tests both encryption and signature mechanisms.

Output
cryptest returns output similar to this:

KeyType_DES:
Mech_Any:
encrypt 0 1 7 8 9 15 16 17 20 36 64 256 1025 2048 4096 8192 16384 65536
sign 0 1 7 8 9 15 16 17 20 36 64 256 1025 2048 4096 8192 16384 65536
Mech_DESmCBCi64pPKCS5:
encrypt 0 1 7 8 9 15 16 17 20 36 64 256 1025 2048 4096 8192 16384 65536
Mech_DESmECBpPKCS5:
encrypt 0 1 7 8 9 15 16 17 20 36 64 256 1025 2048 4096 8192 16384 65536
Mech_DESmECBpNONE:
encrypt 0 8 16 64 256 2048 4096 8192 16384 65536
Mech_DESmCBCpNONE:
encrypt 0 8 16 64 256 2048 4096 8192 16384 65536
Mech_DESmCBCMACi64pPKCS5:
sign 0 1 7 8 9 15 16 17 20 36 64 256 1025 2048 4096 8192 16384 65536
...

nShield/payShield Operator Guide Windows v5.5 157

7 nShield Operator Utilities cspcheck

cspcheck
This utility checks that CSP container files are intact and uncorrupted,
that referenced key files exist, and that any key counters are intact and
readable. You can use cspcheck in conjunction with nfkmcheck, but
ensure that you run nfkmcheck first in order to test the integrity of your
security world files.

Usage

C:\nfast\bin\cspcheck [-h]

There are no arguments for this utility.

Output from a sample cspcheck session looks something like:

cspcheck: warning: File key_mscapi_231cef632cf81a43e25eea7723235b91356f2db3 is a CSP key

that isn't used in any container
cspcheck: warning: File key_mscapi_user_name-ncsp-user-exchange is a CSP key that isn't
used in any container
cspcheck: information: 88 containers and 7 keys found.
cspcheck: warned about 2 problems

nShield/payShield Operator Guide Windows v5.5 158

7 nShield Operator Utilities cspimport

cspimport
This utility allows you to insert keys manually into existing CSP
containers.

Usage

C:\nfast\bin\cspimport -i|--import -k|--key=IDENT -a|--appname=APPNAME TARGET_ID TYPE

C:\nfast\bin\cspimport -m|--migrate -c|--container=SOURCE_ID --source-type=TYPE

TARGET_ID TYPE

If, when you import or migrate a key, the operation replaces an

existing key, the old key file is retained. The cspimport utility prints
out the name of the old key file. This can be deleted if you do not
require it.

Key migration does not remove the migrated key from the source
container.

Import options
-i, --import

These options change a container’s key association to that of

an arbitrary nCipher security world key (for example,
allowing migration from a different application). The IDENT
of the key to import is specified by -k or --key . The source
application name is specified by -a or --appname.

-k, --key=IDENT

These options specify the IDENT of the key to import.

-i, --import

These options specify the source application name .

nShield/payShield Operator Guide Windows v5.5 159

7 nShield Operator Utilities cspimport

Migrate options
-m, --migrate

These options copy CSP keys between containers (for

example, allowing you to move keys between different
users). The source container is specified with the -c or --
container option. If the source key is of a different type to the
target type, the source type is specified using the --source-
type option.

-c, --container=SOURCE_ID

These options specify the source container from which to

import the key.

--source-type=TYPE

This options specify the type of the source key.

The following examples show forms that the cspimport command can
take:

cspimport --migrate --container 0d34b6 --target 896b0 --type signature

cspimport --import --key 346b89 --appname mscapi --target 35b124 --type exchange

Note It is very important that you do not import the wrong type of key for
the CSP with which you wish to use it. The nCipher RSA CSP (ncsp.dll)
works only with RSA keys, and the nCipher DSA/DH CSP (ncspdd.dll)
works only with DSA and DH keys.

If the key file contains a symmetric key (or does not have a public blob
stored), then cspimport disallows its use with nCipher CSPs.
However, the cspimport utility cannot determine what type of
asymmetric key is contained in an arbitrary key file without loading
the key, which is impractical as it may require operator card sets.

nShield/payShield Operator Guide Windows v5.5 160

7 nShield Operator Utilities cspimport

You must ensure that you import asymmetric keys of the appropriate
type for your destination CSP. In particular, you must not migrate keys
between containers that belong to different CSPs. Attempts to use
such keys fail with an NTE_FAIL error code as well as other
miscellaneous errors in the CSP log file.

If you import or migrate a key, the original key file is copied so that
the key is not lost if the original application deletes it. The new key
copy has appname=mscapi and ident=cloned-key- xxx (where xxx is a
3-digit integer).

Example - importing an NFKM key

Note All outputs are examples only. Hashes and similar will be different to
those shown.

In order to import an NFKM key using cspimport --import , take the

following steps:
1. Generate a key in some external program (for example, KeySafe
or another developer library, or from a command-line utility).
Make sure you know what the KM file name of the new key is.
For example, to generate a new RSA private key pair with file
name key_simple_rsa-test, run the following command:

mkaclx --module=1 --type=RSAPrivate --module-protected --recovery --name=rsa-test

2. If it does not already exist, generate the container into which you
want to import the key. You can use the API or the keytst utility.
For example, to generate a new container called import-test that
belongs to the current user, you can issue the following keytst
command:

keytst -c import-test

nShield/payShield Operator Guide Windows v5.5 161

7 nShield Operator Utilities cspimport

3. Issue the csputils command to find the alphanumeric string that

identifies your target container:

csputils -n import-test

This command produces output similar to the following:

File ID Container name Container owner DLL name S X

========== ==================== ==================== ========== = =
83ebe19c7a import-test DOMAIN\fred ncsp
1 container and 0 keys found.

In this example, the alphanumeric string 83ebe19c7a identifies the

container import-test .

nShield/payShield Operator Guide Windows v5.5 162

7 nShield Operator Utilities cspimport

4. Issue the cspimport command in order to import the key.

a. The following command imports the key created in step 1
into the new container identified in step <Undefined Cross-
Reference> as a signature key:

cspimport --import --key=rsa-test --appname=simple --target=83ebe19c7a --type=signature

This command produces output similar to:

Source key:
Key file: key_simple_rsa-test
Key name: 'rsa-test'
Key hash: 0xd01ddd6e6c1482d70bbcc17808d8d261b7bf129c
Key is module protected.
Target container:
Container ID: #83ebe19c7a35ae3cefd1fced3b9a0aaaa778d80a
Container name: 'import-test'
User name = 'DOMAIN\\fred', CSP name = 'ncsp.dll'
Are you sure you want to continue? (yes/no):

b. Replying yes completes the import operation and produces

output similar to:

New target key:

Key file: key_mscapi_cloned-key-0
Key name: 'rsa-test'
Key hash: 0xd01ddd6e6c1482d70bbcc17808d8d261b7bf129c
Key is module protected.

nShield/payShield Operator Guide Windows v5.5 163

7 nShield Operator Utilities cspimport

5. Issue the csputils command in order to verify that the target

container now has a key:

csputils -n import-test

This produces output is similar to:

File ID Container name Container owner DLL name S X

========== ==================== ==================== ========== = =
83ebe19c7a import-test DOMAIN\fred ncsp *

1 container and 1 key found.

Moving CSP keys between users ('cspimport --migrate'):

Example - moving CSP keys between users

The following example of using cspimport --migrate assumes that you
have a user named alice who has a key-exchange key in a container
named foo and that you want to migrate this key to a user called bob
with a container named bar .

nShield/payShield Operator Guide Windows v5.5 164

7 nShield Operator Utilities cspimport

1. Issue csputils commands in order to find the alphanumeric strings

that identify the two containers. For alice, the following
command:

csputils -U alice

produces output similar to the following:

File ID Container name Container owner DLL name S X

========== ==================== ==================== ========== = =
2526b6fb64 alice DOMAIN\alice ncsp

32a16394a3 test DOMAIN\alice ncsp * *

cbfb7b1190 foo DOMAIN\alice ncsp *
3 containers and 3 keys found

The alphanumeric string cbfb7b1190 identifies alice's source

container foo. Issuing a similar csputils command for bob reveals
559376b4a2 as the alphanumeric string that identifies the
destination container bar.

nShield/payShield Operator Guide Windows v5.5 165

7 nShield Operator Utilities cspimport

2. Issue the cspimport command in order to copy the key from

alice’s container foo to bob’s container bar :

cspimport --migrate --container=cbfb7b1190 --target=559376b4a2 --type=exchange

The output is similar to the following:

Source container:
Container ID: #cbfb7b1190653138bc660df491b5426c929034e5
Container name: 'foo'
User name = 'DOMAIN\alice', CSP name = 'ncsp.dll'

Source key:

Key file: key_mscapi_testencryption-ncsp-ujames-exchange

Key name: '(null)'
Key hash: 0x027ded7f23f4bf42248dc0cf9839e1c186c2fca5
Key is cardset protected
Cardset hash: 0x4eb80f966c13bd735cb50f29ef19e5ec730feb1f

Target container:
Container ID: #559376b4a2982f04fd1f7c9a1adacb192f5ac827
Container name: 'bar'
User name = 'DOMAIN\bob', CSP name = 'ncsp.dll'

Are you sure you want to continue? (yes/no):

3. Replying yes completes the import operation, producing output

similar to the following:

New target key:

Key file: key_mscapi_cloned-key-1
Key name: '(null)'
Key hash: 0x027ded7f23f4bf42248dc0cf9839e1c186c2fca5
Key is cardset protected
Cardset hash: 0x4eb80f966c13bd735cb50f29ef19e5ec730feb1f

nShield/payShield Operator Guide Windows v5.5 166

7 nShield Operator Utilities cspimport

4. Issue the csputils command to verify that bob’s target container

bar now has a key: csputils -U bob
The output is similar to the following:

File ID Container name Container owner DLL name S X

========== ==================== ==================== ========== = =
559376b4a2 bar DOMAIN\bob ncsp *
a76e313717 bob DOMAIN\bob ncsp *
da53753753 TestEncryption DOMAIN\bob ncsp *
3 containers and 3 keys found.

This output shows that the imported key is now present in bob’s
container bar.

nShield/payShield Operator Guide Windows v5.5 167

7 nShield Operator Utilities cspmigrate

cspmigrate
This utility migrates containers and keys from earlier versions of the
nCipher CSP to the new container storage system.

Permissions
Calling cspmigrate with the -m parameter transfers the security
information from the registry keys that stored the container
information in old versions of the CSP to the new container files; it
also transfers this security information to the key files owned by the
container.

Calling cspmigrate with the -c parameter checks that the new container
file’s owner, group, and auditing permissions match those in the old
registry key, if necessary. However, calling cspmigrate with the -c
parameter does not check the file’s ACL; registry key ACLs have no
easy mapping to file ACLs. If you want to ensure that container files
ACLs are correct, use csputils to find the desired file name and
manually examine the container file’s permissions.
Note The cspmigrate utility can only be used if you have rights as a local
administrator. It produces very wide output and also produces very
long output if you have many containers.

Usage

c:\nfast\bin\cspmigrate -m| -c [-dqvf] [-h]

-m

This option migrates containers from the old storage

mechanism to new one. This option is non-destructive; it
only creates new container files and never deletes any
information. It is always safe to use the -m option.

nShield/payShield Operator Guide Windows v5.5 168

7 nShield Operator Utilities cspmigrate

-c

This option cleans up old registry entries and key files. After
you have used this option, the old CSP no longer works
Do not use the -c option until you are confident that the new CSP is
working correctly with your old containers.

-d

This option specifies a "dry run" (that is, a run that does
nothing but report on what needs to be done).

-q

This option specifies a "quiet run" (that is, a run during

which the user is not prompted for anything). Under normal
circumstances, if a container needs its keys transferred from
an old CSP but an identical container already exists in the
new CSP with the same keys, the utility prompts the user to
specify which key should be used in the new container.
Passing the -q option always causes the key in the new
container to be used without any prompting.

-v

This option produces verbose status output during the

migration.

-f

This option forces new keys to be overwritten by old keys. If

this option is passed in with -q , it always causes the old key
to replace the new key in the container.
Note After using the -q option, some CSP-generated key files may exist
without an associated container. If this is the case, issuing a
cspmigrate -c command does not remove these key files; you must
remove them manually.

nShield/payShield Operator Guide Windows v5.5 169

7 nShield Operator Utilities cspmigrate

Output
The cspmigrate utility should be run in two stages. The first stage,
cspmigrate -m, creates any required container files (letting you know
if these already exist) and sets up links to existing key files if this
necessary.

If a container with a specific key exists in both systems, by default the

application asks you which you want to use.

Output from a sample session with cspmigrate -m looks something

like:

Searching for user keys, version 1 system...

Found user 'NT AUTHORITY\\LOCAL SERVICE' (sid = S-1-5-19)
Found user 'NT AUTHORITY\\NETWORK SERVICE' (sid = S-1-5-20)
Found user 'DOMAIN\\user_name' (sid = S-1-5-21-1594850079-719136693-34565100-1111)
Found DLL 'ncsp' under keys.
Creating container: { container_name, ncsp, user_name } New container already exists!
Found plausible key exchange key for container.
Existing key file name is 'mscapi_user_name-ncsp-user-exchange'
...new container has key ident: mscapi_user_name-ncsp-user-exchange,
...old container has key ident: mscapi_231cef632cf81a43e25eea7723235b91356f2db3.
Do you want to replace the key in the new container with the one in the old
container? (yes/no):

Entering yes returns output similar to:

...key ident mscapi_231cef632cf81a43e25eea7723235b91356f2db3 is being replaced in the

container
but the key file will not be deleted
....Creating substitute key, new key file name is
'mscapi_7208b58427f9a7ddfd4ff8bf8ea29e434e32a5aa'
Set new key up in the container.
Creating container: { oldtest, ncsp, user_name } New container already
exists!
Found DLL 'ncspbase' under keys.
Creating container: { CSP test, ncspbase, user_name } New container created
successfully.
Found user 'MACHINE_NAME\\testuser' (sid = S-1-5-21-448539723-1580818891-
839522115-1007)

nShield/payShield Operator Guide Windows v5.5 170

7 nShield Operator Utilities cspmigrate

Found user 'MACHINE_NAME\\Administrator' (sid = S-1-5-21-448539723-

1580818891-839522115-500)
Searching for user keys, version 2 system...
Found DLL 'ncsp' under user keys.
Found user 'user_name'.
Creating container: { CSP test, ncsp, user_name } New container created
successfully.
Creating container: { container_name, ncsp, user_name } New container already
exists!
Creating container: { test, ncsp, user_name } New container already
exists!
Found user 'SYSTEM'.
Creating container: { SYSTEM, ncsp, SYSTEM } New container already exists!
Found DLL 'ncspdd' under user keys.
Found user 'user_name'.
Creating container: { container_name, ncspdd, user_name } New container
already exists!
Found user 'SYSTEM'.
Creating container: { SYSTEM, ncspdd, SYSTEM } New container already exists!
Found DLL 'ncspsigdd' under user keys.
Searching for machine keys, both systems...
Found DLL 'ncsp' under keys.
Creating container: { ASIGN_1012, ncsp, [machine] } New container created
successfully.
Creating container: { ASIGN_996, ncsp, [machine] } New container
created successfully.
Creating container: { CSP test, ncsp, [machine] } New container
created successfully.
Creating container: { old-machine, ncsp, [machine] } New container
created successfully.
Found plausible signature key for container.
Existing key file name is 'mscapi_old---2dmachine-ncsp-machine-sign'
Set new key up in the container.
Creating container: { oldtest-machine, ncsp, [machine] } New container
already exists!
Found DLL 'ncspbase' under keys.
Creating container: { CSP test, ncspbase, [machine] } New container created
successfully.
Found DLL 'ncspdd' under keys.
Creating container: { CSP test, ncspdd, [machine] } New container created
successfully.
Found DLL 'ncspsigdd' under keys.

nShield/payShield Operator Guide Windows v5.5 171

7 nShield Operator Utilities cspmigrate

At this point in the process, check that your new containers exist (by
using csputils) and that the new CSPs have the same functionality as
the old CSPs.
Note If you are using the Microsoft CA or IIS 5, you must reboot the
machine in order to ensure that the newly installed CSPs are used by
the system services.
After you are satisfied that the new CSPs are working correctly, you
can clean up the container information from the registry; it is no
longer needed. However, because there is no utility that regenerates
old container information (registry-based) from new container
information (security-world-based), only remove the old CSPs if you
are sure they are no longer needed. It is not necessary to perform this
step in order for the computer to operate correctly.

Output from (the same) sample session as shown above, but with
cspmigrate -c set to clean up the Windows registry file, looks
something like:

Searching for user keys, version 1 system...

Found user 'NT AUTHORITY\\LOCAL SERVICE' (sid = S-1-5-19)
Found user 'NT AUTHORITY\\NETWORK SERVICE' (sid = S-1-5-20)
Found user 'DOMAIN\\user_name' (sid = S-1-5-21-1594850079-719136693-34565100-1111)
Found DLL 'ncsp' under keys.
Checking container: { container_name, ncsp, user_name } New container exists.
Checking existence of plausible key exchange key for container.
Existing key file name is 'mscapi_user_name-ncsp-user-exchange'
Container contains a suitable key.
Removing registry key Software\\nCipher\\Cryptography\\UserKeys\\ncsp\\user_name.
Removing registry key Software\\nCipher\\Cryptography\\UserKeys\\ncsp.
Removing registry key Software\\nCipher\\Cryptography\\UserKeys.
Removing registry entry Software\\nCipher\\Cryptography.
Removing registry entry Software\\nCipher.
Found user 'MACHINE_NAME\\testuser' (sid = S-1-5-21-448539723-1580818891-839522115-1007)
Searching for user keys, version 2 system...
Found DLL 'ncsp' under user keys.
Found user 'user_name'.
Checking container: { CSP test, ncsp, user_name } New container exists.
Removing registry key
Software\\nCipher\\Cryptography\\ncsp\\UserKeys\\user_name_CSP_test.
Checking container: { container_name, ncsp, user_name } New container exists.

nShield/payShield Operator Guide Windows v5.5 172

7 nShield Operator Utilities cspmigrate

Removing registry key

Software\\nCipher\\Cryptography\\ncsp\\UserKeys\\container_name_user_name.
Checking container: { test, ncsp, user_name } New container exists.
Removing registry key Software\\nCipher\\Cryptography\\ncsp\\UserKeys\\user_name_test.
Found user 'SYSTEM'.
Checking container: { SYSTEM, ncsp, SYSTEM } New container exists.
Removing registry key Software\\nCipher\\Cryptography\\ncsp\\UserKeys\\SYSTEM_SYSTEM.
Removing registry key Software\\nCipher\\Cryptography\\ncsp\\UserKeys.
Removing registry key Software\\nCipher\\Cryptography\\ncsp.
Found DLL 'ncspdd' under user keys.
Found user 'user_name'.
Checking container: { container_name, ncspdd, user_name } New container exists.
Removing registry key
Software\\nCipher\\Cryptography\\ncspdd\\UserKeys\\container_name_user_name.
Found user 'SYSTEM'.
Checking container: { SYSTEM, ncspdd, SYSTEM } New container exists.
Removing registry key Software\\nCipher\\Cryptography\\ncspdd\\UserKeys\\SYSTEM_SYSTEM.
Removing registry key Software\\nCipher\\Cryptography\\ncspdd\\UserKeys.
Removing registry key Software\\nCipher\\Cryptography\\ncspdd.
Searching for machine keys, both systems...
Found DLL 'ncsp' under keys.
Checking container: { ASIGN_1012, ncsp, [machine] } New container exists.
Removing registry key Software\\nCipher\\Cryptography\\MachineKeys\\ncsp\\ASIGN_1024.
Checking container: { ASIGN_996, ncsp, [machine] } New container exists.
Removing registry key Software\\nCipher\\Cryptography\\MachineKeys\\ncsp\\ASIGN_996.
Checking container: { CSP test, ncsp, [machine] } New container exists.
Removing registry key Software\\nCipher\\Cryptography\\MachineKeys\\ncsp\\CSP_test.
Checking container: { old-machine, ncsp, [machine] } New container exists.
Checking existence of plausible signature key for container.
Existing key file name is 'mscapi_old---2dmachine-ncsp-machine-sign'
Container contains a suitable key.
Removing registry key Software\\nCipher\\Cryptography\\MachineKeys\\ncsp\\old-machine.
Checking container: { oldtest-machine, ncsp, [machine] } New container exists.
Removing registry key Software\\nCipher\\Cryptography\\MachineKeys\\ncsp\\oldtest-
machine.
Removing registry key Software\\nCipher\\Cryptography\\MachineKeys\\ncsp.
Found DLL 'ncspdd' under keys.
Checking container: { CSP test, ncspdd, [machine] } New container exists.
Removing registry key Software\\nCipher\\Cryptography\\MachineKeys\\ncspdd\\CSP_test.
Removing registry key Software\\nCipher\\Cryptography\\MachineKeys\\ncspdd.
Removing registry key Software\\nCipher\\Cryptography\\MachineKeys

nShield/payShield Operator Guide Windows v5.5 173

7 nShield Operator Utilities cspnvfix

cspnvfix
This utility regenerates the NVRAM key counter area for a specified
nCipher CSP key.

Usage

C:\nfast\bin\cspnvfix -c|--container=HASH -t|--type=KEYTYPE -m|--module=MODULE

-c , --container=HASH

These options specify the hash of the target key container.

Use csputils to retrieve the hash for a container of a specified
name.

-t, --type=KEYTYPE

These options specify the key type. This must be one of

signature and exchange.

-m, --module=MODULE

These options specifies the module for NVRAM area

regeneration.

This utility resolves situations where key counting for the specified
key is disabled because the NVRAM file area is not present. This
could occur, for example, because the NVRAM file has been erased
by module initialization or because a module has been replaced. Key
counting can be enabled again by regenerating the required NVRAM
file area. A quorum of the ACS is required to authorize regeneration
of the NVRAM file.

nShield/payShield Operator Guide Windows v5.5 174

7 nShield Operator Utilities csptest

csptest
The csptest utility tests the Cryptographic Service Providers that are
installed on the computer. csptest tests nCipher or Microsoft CSP
provider arrangements, whereas most utilities test nCore-APIs.

Usage

C:\nfast\bin\csptest [-f|--flood [-d|--dsa] [-m|--ms] [-C|--counters] [-K|--kitb] ] [-

n|--number=NUM ] [-m] [-d] [-l|--length=LEN] [-k|--keys=KEYS] [-s|--sigs=SIGS] [-t|--
time=TIME]]

-f, --flood

These options perform a continuous signature test, similar to

floodtest or sigtest.

-d, --dsa

These options specify the use of DSA signatures rather than

RSA signatures.

-m, --ms

These options specify the use of the Microsoft provider

(possibly with nCipher modexp offload) rather than the
nCipher provider.

-C, --counters

These options specify that keys generated for a flood will use
counters.

nShield/payShield Operator Guide Windows v5.5 175

7 nShield Operator Utilities csptest

-K, --kitb

These options generate module-protected keys.

Note If you use --counters or --kitb, you must insert your Administrator
Cards twice; first for generation and then again at exit for every key
generated.

-n, --number=NUM

These options specify NUM number of simultaneous threads

(the default is 100).

-l, length=LEN

These options specify the use of a key num -bits long. The
default is 1024.
Note csptest reports errors if you attempt to generate keys whose length is
not a multiple of 8 bits. This is because the CSP does not support
lengths that are not a multiple of 8 bits. This behavior is consistent
with that of the Microsoft CSP, although the error returned is
different.

-k, --keys=KEYS

This option specifies the use of num number of keys

simultaneously to soak (the default is 1).
Note The keys used to soak are shared between threads. Therefore, the
number of keys must be less than or equal to the number of threads.
Note If the value you specify for keys or length is too large, the module runs
out of memory and the command fails with the message:

nFastKM: error: MakeBlob (private key) failed; NoMemory unable to generate signature key
for context #16, last error was 0x80090020.

Note The maximum permitted value depends on the amount of memory on

the module. If the command fails with the out of memory message, run
the command again with a smaller number of keys.

nShield/payShield Operator Guide Windows v5.5 176

7 nShield Operator Utilities csptest

-s, sigs=SIGS

This option floods for num number of signatures and then

stops.

-t, --time=TIME

These options run for TIME seconds and then stops.

Output
When run without the --flood option csptest returns output similar to
this:

nCipher CSP test software

=========================
Found the nCipher domestic CSP named 'nCipher Enhanced Cryptographic Provider'
Provider name: nCipher Enhanced Cryptographic Provider
Version number: 1.9
Supported hash algorithms:
SHA-1 - hash length : 160 bits (supports SSL3 and TLS)
MD2 - hash length : 128 bits
MD5 - hash length : 128 bits (supports SSL3 and TLS)
SSL3 SHAMD5 - hash length : 288 bits (supports SSL3 and TLS)
MAC - hash length : 64 bits (supports SSL3 and TLS)
HMAC - hash length : 0 bits (supports SSL3 and TLS)
Supported data encryption algorithms:
RC2 - key lengths: 40-128 bits, default 128 bits. (supports SSL3 and TLS)
RC4 - key lengths: 40-128 bits, default 128 bits. (supports SSL3 and TLS)
DES - key length : 56-64 bits, default 64 bits. (supports SSL3 and TLS)
3DES - key length : 168-192 bits, default 192 bits. (supports SSL3 and TLS)
3DES_112 - key length : 112-128 bits, default 128 bits. (supports SSL3 and TLS)
Supported signature algorithms:
RSA_SIGN - key lengths: 384-16384 bits, default 1024 bits, in increments of 8 bits.
(supports SSL3 and TLS)
Supported key exchange algorithms:
RSA_KEYX - key lengths: 384-16384 bits, default 1024 bits, in increments of 8 bits.
(supports SSL3 and TLS)
User key containers:
Container 'fred' has a 1024-bit key exchange key.
Machine key containers:
Container 'fred\xd5 s computer' has no stored keys.
Container 'fred' has a 512-bit signature key.

nShield/payShield Operator Guide Windows v5.5 177

7 nShield Operator Utilities csptest

Testing signature operations:

Hashing data for signing - OK
Signing hash - OK
Exporting public key - OK
Importing public key - OK
Hashing data for verifying - OK
Verifying signature - OK
Testing key exchange operations:
Generating symmetric key - OK
Encrypting data - OK
Exporting symmetric key - OK
Getting salt value - OK
Importing symmetric key - OK
Encrypting data with imported key - OK
Checking two buffers are identical - OK
Timing signature operations (for 10 seconds): 41.1429 1024-bit signature operations per
second, averaged over 7 seconds.

csptest returns output for all loaded CSPs, including the standard
Microsoft CSPs.

If you specify the --flood option, csptest returns output similar to this:

1, 60 60, 60 overall
2, 130 70, 65 overall
3, 192 62, 64 overall
4, 263 71, 65.75 overall
5, 333 70, 66.6 overall
6, 396 63, 66 overall

nShield/payShield Operator Guide Windows v5.5 178

7 nShield Operator Utilities csputils

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.

Usage

c:\nfast\bin\csputils [-l|--list] | [-d | --detail] [-x|--delete] [-c | -- -m dllname -

U username | ALL -H hash_prefix -n name_prefix -h

-l, --list

These options display a table of the selected containers using

one line for each container

-d, detail

These options display detailed information about the

selected containers.

-x, delete

These options delete the selected containers after prompting

the user.

-c, --csp=CSP

These options select containers from the CSP named CSP

-U, --username=USER

These options select containers from the user named USER.

If USER is specified as ALL, containers are selected from all
users.
Note The -U ALL option does not display machine containers unless you
also specify --machine.

nShield/payShield Operator Guide Windows v5.5 179

7 nShield Operator Utilities csputils

-m, --machine

These options select all machine containers.

-H, --hash=HASH

These options select containers with the hash HASH

-n, --name=NAME

These options select containers with the name NAME.

Note The hash and container name are treated as substrings.

Selection options ( -c , --username , --machine , --hash , and --name )

are additive. The output displays the union of all sets created by the
selected options (for example, the command csputils --hash 3c4d --
username bert lists both containers whose hash starts 3c4d and also
those belonging to the user with user name bert). You cannot pass
more than one of each option on the command line at a time. For
example, attempting to issue a command likecsputils --username bert
--username erniedoes not work.
Note You need administrative privileges in order to use the --delete , the -
username , or the --machine options. Any other chosen selection
options list only the containers that belong to the current user.

If you do not specify any of -l , -d , or -x , then -l is assumed. If you do

not specify any selection options, csputils displays all containers from
the current user.

Output
In order to list all containers on the system concisely, issue the
command:

csputils --username ALL --machine

nShield/payShield Operator Guide Windows v5.5 180

7 nShield Operator Utilities csputils

This returns output similar to:

File ID Container name Container owner DLL name S X

===================================================================
05950465c5 CSP test DOMAIN\user_name ncsp *
1e6ff7b617 oldtest-machine MACHINE ncsp
2a27a30ff6 bd2769c6-403f-423... MACHINE ncsp
32a16394a3 container_name DOMAIN\user_name ncsp *
35f5fb00a3 oldtest DOMAIN\user_name ncsp
374b42557b CSP test MACHINE ncsp
4234b80bfc SYSTEM NT AUTHORITY\SYSTEM ncsp
6c400deafc SYSTEM NT AUTHORITY\SYSTEM ncspdd
748e8f42d3 CSP test MACHINE ncspbase
74cc603f6c CSP test MACHINE ncspdd
9c478d3429 container_name DOMAIN\user_name ncspdd
cccb69f1ab test DOMAIN\user_name ncsp
da493a4f56 CSP test DOMAIN\user_name ncspbase
13 containers and 1 key found.

In order to list all containers whose name contains CSP and also those
containers that were created by ncspbase.dll , issue the
command:csputils --name CSP --csp ncspbasewhich returns output
similar to:

File ID Container name Container owner DLL name S X

===================================================================
05950465c5 CSP test DOMAIN\user_name ncsp *
374b42557b CSP test MACHINE ncsp
748e8f42d3 CSP test MACHINE ncspbase
74cc603f6c CSP test MACHINE ncspdd
da493a4f56 CSP test DOMAIN\user_name nspbase
5 containers and 0 keys found.

nShield/payShield Operator Guide Windows v5.5 181

7 nShield Operator Utilities csputils

In order to display details about all containers whose hash contains 32

, issue the command:csputils --detail --hash 32which returns output
similar to:

Detailed report for container ID #32a16394a3ffe52eb4db1127d87865ce6a42fa7c

Filename: key_mscapi_container-32a16394a3ffe52eb4db1127d87865ce6a42fa7c
Container name: container_name
User name: DOMAIN\user_name
User SID: s-1-5-21-1594850079-719136693-34565100-1111
CSP DLL name: ncsp.dll
No signature key.
Filename for key exchange key is key_mscapi_231cef632cf81a43e25eea7723235b91356f2db3
Key was generated by the CSP
Key hash: 231cef632cf81a43e25eea7723235b91356f2db3
Key is recoverable.
Key is module protected.
1 container and 1 key found.

In order to delete all containers whose name contains CSP test , issue
the command:csputils --delete -name "CSP test"which returns output
similar to:

File ID Container name Container owner DLL name S X

===================================================================
05950465c5 CSP test DOMAIN\user_name ncsp *
374b42557b CSP test MACHINE ncsp
748e8f42d3 CSP test MACHINE ncspbase
74cc603f6c CSP test MACHINE ncspdd
da493a4f56 CSP test DOMAIN\user_name ncspbase
5 containers and 1 key found.
This action cannot be undone - are you sure you want to delete
all these containers and their associated key files? (yes/no):

nShield/payShield Operator Guide Windows v5.5 182

7 nShield Operator Utilities csputils

Type yes and press Enter . The returned output is similar to:

Deleting container file mscapi_container-05950465c57b34bf82a5a6316f6726944091baf7

Deleting key file mscapi_bb7202b7f4f4224a6281ee0f3b679b03139704ac
Deleting container file mscapi_container-374b42557b912d5bdce885193d174969427b0e4d
Deleting container file mscapi_container-748e8f42d39c1058ce1444d71fc055ef168546b7
Deleting container file mscapi_container-74cc603f6c606accd82ec0cf2cb9e711737c13fc
Deleting container file mscapi_container-da493a4f56fea6ca35f2ff40e61b98756ed2b71f
5 containers and 1 key deleted.

nShield/payShield Operator Guide Windows v5.5 183

7 nShield Operator Utilities des_kat

des_kat
The des_kat utility performs DES known-answer tests and indicates if
any of them fail.

Usage

C:\nfast\bin\des_kat [-m|--module=MODULE]

The options -m and --module=MODULE specify the module on which

to perform the test. The default is the first module available.

Output
des_kat should return output:

DES known answer tests

Tests passed

If any tests fail, des_kat returns the number of the failed test. Please
inform Support at nCipher.

nShield/payShield Operator Guide Windows v5.5 184

7 nShield Operator 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 Operator Guide Windows v5.5 185

7 nShield Operator 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 Operator Guide Windows v5.5 186

7 nShield Operator 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 Operator Guide Windows v5.5 187

7 nShield Operator 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 Real-

Time 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 Operator Guide Windows v5.5 188

7 nShield Operator 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 long-

term 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 the
Administrator Guide 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 Operator Guide Windows v5.5 189

7 nShield Operator 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 Operator Guide Windows v5.5 190

7 nShield Operator 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 Operator Guide Windows v5.5 191

7 nShield Operator 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 Korean Algorithms.

(KCDSA, SEED, HAS160 hash
function)
GeneralSEE Allows any SEE machine to be SEE Activation (EU+10)
loaded. Available only within CGEA
locations.
EllipticCurve Allows small key sizes to provide Elliptic Curve
improved levels of security.

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 Operator Guide Windows v5.5 192

7 nShield Operator 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 Developer’s Guide for more
information).

nShield/payShield Operator Guide Windows v5.5 193

7 nShield Operator 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 Operator Guide Windows v5.5 194

7 nShield Operator 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 Operator Guide Windows v5.5 195

7 nShield Operator 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_ave±SKEW.
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 Operator Guide Windows v5.5 196

7 nShield Operator 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 Operator Guide Windows v5.5 197

7 nShield Operator Utilities fwcheck

fwcheck
The fwcheck utility verifies a firmware image by using one of several
files that contain verification data.

Usage

C:\nfast\bin\fwcheck.exe [-v|--verbose] [-m|--module=MODULE] [-c|--challenge=HEX] NFF-

file

Help options
-h, --help

This option displays help for fwcheck.

-V, --version

This option displays the version number of fwcheck.

-u, --usage

This option displays a brief usage summary for fwcheck.

-v, --verbose

This option displays all possible output for fwcheck.

Checking options
-m, --module=MODULE

This option checks the module number MODULE.

-c, --challenge=HEX

This option uses HEX as the challenge. If not specified, the

challenge is a random value.

nShield/payShield Operator Guide Windows v5.5 198

7 nShield Operator Utilities fwcheck

The --challenge option supplies a random value that is used in the

challenge-response protocol. If this is not supplied, fwcheck creates a
value by hashing various system environment values together with
random bytes generated by the module. When used with the --verbose
option, it displays challenges and responses. This might be useful, for
example, to compare the behavior of two modules.

fwcheck can be used with the following types of file:

fw_platform.nff

the regular application firmware file as supplied to loadrom

fw_platform.ftv

performs a “pseudo-random sequence generation” test on

the application

In these file names, platform is the version number of the module,

beginning with nC.

The pseudo-random sequence generation test asks the module to

generate a fixed pseudorandom byte sequence that is a number of
megabytes long. This is generated according to an algorithm kept
secret inside the firmware and not present in the fwcheck application,
which simply computes the hash of this sequence and compares it to
a value in the .ftv file.

nShield/payShield Operator Guide Windows v5.5 199

7 nShield Operator Utilities generatekey

generatekey
You can use the generatekey utility to:
• generate new keys
• import existing keys into a security world
• retarget a key used by one application for use with a different
application
• list supported applications.

You can use generatekey interactively by:

• issuing commands without parameters and supplying the
required information when prompted by the utility
• supplying some or all of the required parameters on the command
line. generatekey prompts for any missing parameters.

In interactive mode, you can input abort at any prompt to terminate

the process.

You can also use generatekey in batch mode, which is useful for
scripting.
Note Because of changes to options and parameters in the current version
of generatekey, scripts you run that use a previous version of
generatekey may require changes before you can run them
successfully.

In batch mode, you supply parameters in the command line. If you

omit parameters, generatekey does not prompt for the missing
information. Instead it uses available defaults or fails. If you specify
one or more parameters incorrectly, an error is displayed and the
command fails.
Note If a parameter’s argument contains spaces, you must enclose the
argument within quotation marks (" ").

nShield/payShield Operator Guide Windows v5.5 200

7 nShield Operator Utilities generatekey

The generatekey utility takes the following form:

generatekey [OPTIONS] APPNAME [NAME=VALUE ...]

In this command:

OPTIONS

This represents the command-line options that determine

how generatekey behaves. OPTIONS must always precede
the application name (APPNAME) and parameters.

APPNAME

This represents the application with which you want to use

the key. Specifying an application can restrict your choice of
key type. APPNAME must follow any OPTIONS and precede
any parameters specified for the key.

NAME=VALUE

This is a list of parameters that determine the properties of a

key. In interactive mode, you can specify any or all of the
parameters and generatekey prompts you for unspecified
parameters. In batch mode, you specify parameters on the
command line; none are prompted for. Where you do not
specify parameters, generatekey uses available defaults or
terminates with an error message.

The options, applications, and parameters for use with generatekey are
described in the following sections.

Options
--generate

This option generates a new key. This is the default action if

none of --generate, --import, or --retarget is specified.

nShield/payShield Operator Guide Windows v5.5 201

7 nShield Operator Utilities generatekey

--import

This option imports a key.

--retarget

This option transfers an existing key to another application.

--batch

This option runs generatekey in batch mode. If you specify

--batch, you specify parameters as NAME=VALUE pairs on
the command line; no parameters are prompted for. Where
you do not specify parameters, generatekey uses available
defaults or terminates with an error message. If you specify
one or more parameters incorrectly, an error is displayed and
the command fails.
For jcecsp keys, you must specify the key store’s pass phrase, and this
is displayed on the command line. This risks revealing the password.
Therefore, nCipher recommends that you do not use batch mode with
jcecsp keys.

--interactive

This option runs generatekey in interactive mode. This is the

default mode. During operation, generatekey prompts you to
supply any required parameter not included on the command
line. Incorrect input is requested again.

--check, --check-props

These options tell generatekey to check parameters for

validity only, without generating, importing, or retargeting
the key.

--list-params, --list-props

These options list the parameters associated with a specific

application.

nShield/payShield Operator Guide Windows v5.5 202

7 nShield Operator Utilities generatekey

--list-apps

This option lists the supported applications. Unlike other

options, it is not necessary to specify an APPNAME with
--list-apps.

--list-key-types

This option lists the supported key types for the specified
APPNAME. You can specify --import to see what key types
are supported for import.

--module MODULE

This option specifies the module to use. If no module is

specified:
• in batch mode, the only available or first usable module
is used
• in interactive mode, the only available module is used or
you are prompted to specify a module.
Note A module is usable if it is in the current security world and in the
operational state.

The module may alternatively be specified with the module

parameter.

--cardset NAME, --cardset HASH

For a token protected key, these options specify the Operator

Card Set to use to protect the key, by its name or hash value,
as returned by nfkminfo. If you do not specify one of these
options and you specify Operator Card protection for the
key:
• in batch mode, generatekey uses the Operator Card Set
to which the Operator Card currently in the module
belongs (or the first returned by nfkminfo)

nShield/payShield Operator Guide Windows v5.5 203

7 nShield Operator Utilities generatekey

• in interactive mode, if there is more than one Operator

Card Set, you will be prompted to select the Operator
Card Set to use at card-loading time.

generatekey only generates or imports the key if the smart

card in the module is from this card set.

--verify

This option verifies the security of the generated, imported

or retargeted key. This is the default mode of operation. If
you specify --verify, only the following key types are
available:
• DES2
• DES3
• DH
• DSA
• ECDH
• ECDSA
• HMACRIPEMD160
• HMACSHA1
• HMACSHA256
• HMACSHA384
• HMACSHA512
• HMACTiger
• KCDSA (if enabled)
• RSA

nShield/payShield Operator Guide Windows v5.5 204

7 nShield Operator Utilities generatekey

• Rijndael (AES)

--no-verify

This option disables the security check on the key. If you

specify --no-verify, additional key types to those supported
with --verify are available:
• ArcFour
• Blowfish
• CAST
• CAST256
• DES
• HMACMD2
• HMACMD5
• IDEA
• SEED
• Serpent
• Twofish
Because there are no checks on the security of any key generated in
this manner and therefore no guarantee of its security, and because
incorrectly constructed Access Controls Lists (ACLs) are not
detected, nCipher recommends that you do not use the --no-verify
option.

--debug

This option enables the display of debugging messages.

nCipher recommends you do not use the option unless asked
to do so by Support at nCipher.

--quiet

This option suppresses the display of all non-vital messages

during operation.

nShield/payShield Operator Guide Windows v5.5 205

7 nShield Operator Utilities generatekey

--verbose

This option displays all messages during operation. This is

the default.

Applications
With generatekey, APPNAME can be:

simple

for nCipher native keys. No special action is taken after the

key is generated.

custom

This option generate a key for custom applications that

require the key blob to be saved in a separate file. Specifiying
custom also causes a certificate request and self-signed
certificate to be generated. However, nCipher recommends
that you use the APPNAME simple (instead of custom) where
possible.

pkcs11

These keys are formatted suitably for use with PKCS #11
applications and are given a suitable identifier. The set of key
types supported is currently limited to:
• DES
• DES2
• DES3
• DH
• DSA
• ECDH
• ECDSA
• HMACSHA1

nShield/payShield Operator Guide Windows v5.5 206

7 nShield Operator Utilities generatekey

• RSA
• KCDSA
• CAST
• HMACMD5
• Rijndael (AES)

embed

This option is for use with CHIL applications that do not

support hwcrhk key storage but that do have a key
importation facility that can read PEM-format RSA key
files. Use the hwcrhk option for CHIL applications that
support hwcrhk key storage.

hwcrhk

This option generates a key for Cryptographic Hardware

Interface Library (CHIL) applications that do not require the
APPNAME embed. Only RSA, DSA, and DH key types are
supported

jcecsp

for Java Cryptography architecture support. These keys are

automatically added to an nCipher.sworld keystore.

kpm

for keys to be delivered by the nForce Ultra key server. The

generatekey command-line utility automatically creates a
special ACL entry that permits a kpm to be delivered to an
nForce Ultra’s enrolled internal hardware security module.

nShield/payShield Operator Guide Windows v5.5 207

7 nShield Operator Utilities generatekey

Parameters
The following table lists available parameters with the actions
(generate, import, and retarget) and applications to which they apply:

nShield/payShield Operator Guide Windows v5.5 208

7 nShield Operator Utilities generatekey

Parameter Purpose Action Application

generate
import
retarget
custom
embed
hwcrhk
jcecsp
pkcs11
seeconf
seeinteg
simple
kpm
alias This determines the alias to X X X X
assign to the key.
blobsavefile When using the custom X X X X
application type, this
specifies a file name of the
form the form
FILENAME.EXT to which
to save the key blob.
Additionally, text file
containing information
about the key is saved to a
file whose name has the
form ROOT_inf.txt; for
asymmetric key types, the
public key blob is also
saved to a file whose name
has the form
ROOT_pub.EXT.

cardset This specifies the Operator X X X X X X X X X

Card Set that is to protect
the key, if protect is set to
token. In interactive mode,
if you do not specify a
cardset, you will be
prompted to select one at
card-loading time. The
default is the Operator
Card Set to which the card
currently inserted in the
slot belongs (or the first
one returned by nfkminfo).

nShield/payShield Operator Guide Windows v5.5 209

7 nShield Operator Utilities generatekey

Parameter Purpose Action Application

generate
import
retarget
custom
embed
hwcrhk
jcecsp
pkcs11
seeconf
seeinteg
simple
kpm
certreq This parameter enables you X
to generate a certificate
request when generating a
PKCS #11 key (RSA keys
only); the default behavior
is to not generate a
certificate request. To
generate a certificate
request you must set
certreq to yes, which makes
generatekey prompt you to
fill in the extra fields
required to generate a key
with a certificate request.
The resultant certificate
request is saved to the
current working directory
with a file name of the
form filename_req.ext
where filename is a name of
your choice. An extra file
with a name of the form
filename.ext is also
generated to be used as a
pseudo- key-header; this
file can be removed after
the certificate request has
been generated. You can
use this paramater with the
--retarget option to
generated a self-signed
certificate for an existing
key.

nShield/payShield Operator Guide Windows v5.5 210

7 nShield Operator Utilities generatekey

Parameter Purpose Action Application

generate
import
retarget
custom
embed
hwcrhk
jcecsp
pkcs11
seeconf
seeinteg
simple
kpm
checks For RSA key generation X X X X X X X X
only, this specifies the
number of checks to be
performed. Normally, you
should leave this blank to
let the module pick an
appropriate default.
curve For ECDH and ECDSA X X X X X X X X X
key generation only. This
option specifies which of
the range of supported
curves to use. Supported
curves are: NISTP192,
NISTP224, NISTP256,
NISTP384, NISTP521,
NISTB163, NISTB233,
NISTB283, NISTB409,
NISTB571, NISTK163,
NISTK233, NISTK283,
NISTK409, NISTK571,
ANSIB163v1,
ANSIB191v1, SECP160r1
embedconvfile This specifies the name of X X
the PEM file that contains
the RSA key to be
converted.

nShield/payShield Operator Guide Windows v5.5 211

7 nShield Operator Utilities generatekey

Parameter Purpose Action Application

generate
import
retarget
custom
embed
hwcrhk
jcecsp
pkcs11
seeconf
seeinteg
simple
kpm
embedsavefile When using the embed X X X X X
application type, this
specifies the name for the
file where the fake RSA
private key is to be saved.
The file has the same
syntax as an RSA private
key file, but actually
contains the key identifier
rather than the key itself,
which remains protected.
A certificate request and a
self-signed certificate are
also written. If the
filename is ROOT.EXT
then the request is saved to
ROOT_req.EXT and the
self-signed certificate is
saved to
ROOT_selfcert.EXT.

from-application For retargeting, this X X X X X X X X

parameter specifies the
application name of the
key to be retargeted. Only
applications for which at
least one key exists are
acceptable.
from-ident This specifies the identifier X X X X X X X X
of the key to be retargeted,
as displayed by nfkminfo.

nShield/payShield Operator Guide Windows v5.5 212

7 nShield Operator Utilities generatekey

Parameter Purpose Action Application

generate
import
retarget
custom
embed
hwcrhk
jcecsp
pkcs11
seeconf
seeinteg
simple
kpm
hexdata This specifies the hex value X X X X X X X
of DES/DES3 key to
import. Note that the hex
digits are echoed to the
screen and are may be
visible in process listings if
specified on the command
line.
ident This specifies a unique X X X X X
identifier for the key in the
security world. For simple
or hwcrhk applications,
this is the key identifier to
use (the exact identifier for
simple, for hwcrhk the key
type is implicitly
included). For other
application types, keys are
assigned an automatically
generated identifier and
accessed by means of some
application-specific name.
keystore This specifies the filename X X X X
of the keystore to use. This
must be an nCipher
keystore.

keystorepass This specifies the password X X X X

to the keystore to use.

nShield/payShield Operator Guide Windows v5.5 213

7 nShield Operator Utilities generatekey

Parameter Purpose Action Application

generate
import
retarget
custom
embed
hwcrhk
jcecsp
pkcs11
seeconf
seeinteg
simple
kpm
module This specifies the module X X X X X X X X X
to use for generating the
key. If there is more than
one usable module, this is
prompted for. The module
can also be specified with
the --module option. The
default is the first usable
module (one in the current
security world and in the
operational state).
nvram This determines whether X X X X X X X X
the key is stored in the
kmdata directory of the
host computer or in the
module’s NVRAM. If set
to yes, the key is stored in
the module's NVRAM. If
set to no, the key is stored
on the host. The default is
no. This parameter only
works if your module's
firmware supports it and if
there is sufficient space in
your module’s NVRAM.
See Generating NVRAM-
stored keys on page 92.
paramsreadfile This specifies the name of X X X X X X X X X
the group parameters file
that contains the discrete
log group parameters for
Diffie-Hellman keys only.
This should be a PEM-
formatted PKCS#3 file. If
this parameter is omitted,
the module uses a default
file.

nShield/payShield Operator Guide Windows v5.5 214

7 nShield Operator Utilities generatekey

Parameter Purpose Action Application

generate
import
retarget
custom
embed
hwcrhk
jcecsp
pkcs11
seeconf
seeinteg
simple
kpm
pemreadfile This specifies the name of X X X X X
the PEM file that contains
the key to be imported.
When importing an RSA
key, this is the name of the
PEM-encoded PKCS #1
file to read it from.
Password-protected PEM
files are not supported.
plainname This specifies the key X X X X X X X X X
name within the security
world. For some
applications, the key
identifier is derived from
the name, but for others the
name is just recorded in
kmdata and not used
otherwise.
protect This specifies the X X X X X X X X X X X
protection method, which
can be module for security-
world protection, softcard
for softcard protection or
token for Operator Card Set
protection. The default is
token, except for seeconf
keys, where the default is
module. seeinteg keys are
always token-protected.
The softcard option is only
available when your
system has at least one
softcard present.

nShield/payShield Operator Guide Windows v5.5 215

7 nShield Operator Utilities generatekey

Parameter Purpose Action Application

generate
import
retarget
custom
embed
hwcrhk
jcecsp
pkcs11
seeconf
seeinteg
simple
kpm
pubexp For RSA key generation X X X X X X X X
only, this specifies in
hexadecimal format the
public exponent to use
when generating RSA
keys. it is normally left
blank. nCipher
recommends you do not
use this parameter unless
asked to by Support at
nCipher.
qsize This specifies the size in X X X X X X X X
bits of Q when generating
KCDSA keys (if this
feature is enabled). This
parameter is normally
invisible because it must
always be set to 160
(which is therefore the
default value). For
information about enabling
features, see the
Administrator Guide
appropriate to your module
type.
recovery This parameter enables X X X X X X X X X X X
recovery for this key and is
only available for card-set
protected keys in a
recovery-enabled world. If
set to yes, the key is
recoverable. If set to no,
key is not recoverable. The
default is yes. Non-
recoverable module-
protected keys are not
supported.

nShield/payShield Operator Guide Windows v5.5 216

7 nShield Operator Utilities generatekey

Parameter Purpose Action Application

generate
import
retarget
custom
embed
hwcrhk
jcecsp
pkcs11
seeconf
seeinteg
simple
kpm
seeintegname If present, this parameter X X
identifies a seeinteg key.
The ACL of the newly
generated private key is
modified to require a
certificate from the seeinteg
key for its main operational
permissions, such Decrypt
and Sign (DuplicateHandle,
ReduceACL, and GetACL
are still permitted without
certification.)
selfcert This parameter enables you X
to generate a self-signed
certificate when generating
a PKCS #11 key (RSA
keys only). To generate a
self-signed certificate
request you must set
selfcert to yes, which makes
generatekey prompt you to
fill in the extra fields
required to generate a key
with a self-signed
certificate. The resultant
certificatesaved to the
current working directory
with a file name of the
form filename.ext. You can
use this paramater with the
--retarget option to
generated a self-signed
certificate for an existing
key.

nShield/payShield Operator Guide Windows v5.5 217

7 nShield Operator Utilities generatekey

Parameter Purpose Action Application

generate
import
retarget
custom
embed
hwcrhk
jcecsp
pkcs11
seeconf
seeinteg
simple
kpm
size For key types with X X X X X X X X X X
variable-sized keys, this
specifies the key size in
bits. The range of
allowable sizes depends on
key type and whether
--no-verify was used. The
default depends on the key
type. See Appendix A:
Cryptographic algorithms
for information on
available key types and
sizes. This parameter does
not exist for fixed-size
keys, nor for ECDH and
ECDSA keys which are
specified using curve.
strict For DSA key generation X X X X X X X
only, if set to yes this
parameter enables strict
verification, which also
limits the size to exactly
1024 bits. The default is
no.

nShield/payShield Operator Guide Windows v5.5 218

7 nShield Operator Utilities generatekey

Parameter Purpose Action Application

generate
import
retarget
custom
embed
hwcrhk
jcecsp
pkcs11
seeconf
seeinteg
simple
kpm
type This specifies the type of X X X X X X X X X X
key. You must usually
specify the key type for
generation and import
(though some applications
only support one key type,
in which case you are not
asked to choose).
Sometimes the type must
also be specified for
retargetting. See Appendix
A: Cryptographic
algorithms for information
on available key types. The
--verify option limits the
available key types.
x509country This specifies a country X X X X X
code, which must be a
valid 2-letter code, for the
certificate request.
x509dnscommon This specifies a site X X X X X
domain name, which can
be any valid domain name,
for the certificate request.
x509email This specifies an email X X X X X
address for the certificate
request.
x509locality This specifies a city or X X X X X
locality for the certificate
request.

nShield/payShield Operator Guide Windows v5.5 219

7 nShield Operator Utilities generatekey

Parameter Purpose Action Application

generate
import
retarget
custom
embed
hwcrhk
jcecsp
pkcs11
seeconf
seeinteg
simple
kpm
x509org This specifies an X X X X X
organization for the
certificate request.
x509orgunit This specifies an X X X X X
organizational unit for the
certificate request.
x509province This specifies a province X X X X X
for the certificate request.
xsize This specifies the private X X X X X X X
key size in bits when
generating Diffie-Hellman
keys. The default is 256
bits for a key size of 1500
bits or more and otherwise
160 bits.

Note If a parameter’s argument contains spaces, you must enclose the

argument within quotation marks (" ").

nShield/payShield Operator Guide Windows v5.5 220

7 nShield Operator 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 the

appropriate Administrator Guide for you module type.

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

%NFAST_HOME%\scripts\hardserver.d directory and executes them as
follows:
• 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 Operator Guide Windows v5.5 221

7 nShield Operator 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 Operator Guide Windows v5.5 222

7 nShield Operator 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.For information about starting the module in
the pre-initialization state, see the appropriate Administrator Guide
for your module type.

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

-n, --ntoken

These options specify the initialization of a module as an

nToken.

nShield/payShield Operator Guide Windows v5.5 223

7 nShield Operator 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 Operator Guide Windows v5.5 224

7 nShield Operator Utilities keytst

keytst
The keytst utility displays information about existing CSP key
containers. If you have the appropriate permissions, keytst allows you
to create containers and their keys, and to delete containers.
Note The contents of a CSP key container do not necessarily reflect the key
information that is held in the kmdata directory. However, all key
container data that is held in the nCipher CSP is present in the kmdata
directory. See the Administrator Guide for more details about the
contents of these container files.

The keytst command-line utility works with the Microsoft CryptoAPI

in conjunction with either the Microsoft or the nCipher CSPs, whereas
most utilities (including csputils, cspmigrate, and cspcheck) work
directly with the nCipher APIs.

Usage
The following options are available for the keytst utility:

C:\nfast\bin\keytst.exe [-l|--list] [[-c|--create=containername] |

[-d|--delete=containername]] [-p|--public] [-M|--mscsp] [-m|--machine] [-S|--schannel]
[-D|--dsa] [-V|--verify] [-x|--exchange] [-s|--signature] [-e|--export]
[-L|--length=bitlen] [-C|--counter] [-K|--kitb]

Operational options
-l, --list

These options list available container names. The default

container must be present. If necessary, use the --create
option without a container name to create the default
container.

nShield/payShield Operator Guide Windows v5.5 225

7 nShield Operator Utilities keytst

-c, --create=containername

These options either create a container named

containername or create one or both keys for this container

-d, --delete=containername

These options delete the container named containername.

-p, --public

These options shows public key material and counters (if

they exist) for either or both keys.

CSP choice options

-M, --mscsp

These options use the Microsoft CSP instead of the nCipher

CSP

-m, --machine

These options specify the use of a machine container instead

of a user container. You must have administrative privileges
to list machine keys.

-s, --schannel

These options specify the use of the SChannel provider

instead of the normal provider.

-D, --dsa

These options specify the use of the DSA provider instead of

the default RSA provider.

-V, --verify

These options specify the use of a

CRYPT_VERIFYCONTEXT context

nShield/payShield Operator Guide Windows v5.5 226

7 nShield Operator Utilities keytst

Key creation options

-x, --exchange

These options can be set in combination with the --create or

--public options to create or show the key-exchange key.

-s, --signature

These options specify the use of a machine container instead

of a user container. You must have administrative privileges
to list machine keys.

-s, --schannel

These options specify the use of the SChannel provider

instead of the RSA provider.

-e, --export

These options can be set in combination with the --create

option to create keys with the bit set that specifies the key as
exportable. Selecting this option has no effect with the
nCipher CSP, as keys are never exportable in plain text.

-L, --length=bitlen

These options can be set in combination with the --create

option to create keys with the bit set that specifies the key as
exportable. Selecting this option has no effect with the
nCipher CSP, as keys are never exportable in plain text.

-C, --counter

These options can be set in combination with the --create

option plus one of the --signature or --exchange options to
create keys with key counters, if these are supported. You
must have the use of a quorum of the Administrator Card Set
in order to use this option.

nShield/payShield Operator Guide Windows v5.5 227

7 nShield Operator Utilities keytst

-K, --kitb

This option can be set in combination with the --create to

create NVRAM protected keys, if these are supported. You
must have the use of a quorum of the Administrator Card Set
in order to use this option.

Output
In order to list the available containers, issue the command:

C:\nfast\bin\keytst --list --machine

This produces output similar to the following:

Available key containers:

oldtest-machine
bd2769c6-403f-4232-86e6-7fe47dcec690
CSP test
csrv-test
old-machine
container_nameAdministrator

To generate an exchange key and signature key in the container

Administrator, issue the following command:

C:\nfast\bin\keytst --create --machine --exchange --signature Administrator

nShield/payShield Operator Guide Windows v5.5 228

7 nShield Operator Utilities keytst

This produces output similar to the following:

Generating key(s) for the 'Administrator' container.

New key exchange key generated OK.
New signature key generated OK.
C:\nfast\bin\keytst ---create --machine --exchange --signature Administrator
Container 'Administrator':
Public half of key exchange key is:
06 02 00 00 00 A4 00 00 52 53 41 31 00 04 00 00
01 00 01 00 F3 77 04 B8 90 73 B5 3F 04 3A F3 9E
A4 72 08 55 A1 74 15 FD 7F 80 3D 0F 16 BA 22 F9
BE 30 7C E5 3C 44 B0 E9 53 53 8F 69 30 F7 E8 B3
52 F6 43 5F 5D 13 05 04 03 4C 55 17 91 FE 10 74
B3 48 72 1E 64 28 6B 62 24 04 C0 74 42 BD 67 91
44 EB 51 2D E3 B8 D5 37 DB 3C 02 AD 7C 2B F7 50
B4 0D 25 31 E0 00 AB 6C B0 1E 4E FB 65 4E 01 4E
AD FE 5E 66 84 23 19 A5 04 3C B2 95 ED 3D DE 2E
7D 60 98 B6
Public half of signature key is:
06 02 00 00 00 24 00 00 52 53 41 31 00 04 00 00
01 00 01 00 D3 D2 10 A1 C4 A8 AC 5A 29 97 D1 37
8E F6 E0 D7 FF 08 34 F1 73 1A 1A 54 4D 4B 8E 69
B4 2D 7B C7 9F F7 7B D1 D1 EE BB 9E 73 69 48 CF
04 83 BA 36 7F 70 A1 73 DA 25 47 94 D5 4B F6 F7
75 C1 50 1D 96 7D 73 70 33 D8 EE 1A 53 D5 ED 56
22 8E FF 39 B3 70 8A 98 13 02 3F EE 22 71 FC 29
F2 A8 FD 5A 48 47 5D 2D A8 88 B0 B6 99 41 F3 85
AE E0 C7 D4 9A F0 D1 66 34 A1 6C D1 E3 00 AE 37
F5 AE A6 D7

To delete a container Administrator, issue the command:

C:\nfast\bin\keytst --create --machine Administrator

nShield/payShield Operator Guide Windows v5.5 229

7 nShield Operator Utilities keytst

This produces output similar to the following:

****************************************
* WARNING *
* You are about to delete a container! *
* This is a non-recoverable option. *
* *
****************************************
Do you wish to continue? (yes/no):

Answering yes produces the output:

Container 'Administrator' deleted

nShield/payShield Operator Guide Windows v5.5 230

7 nShield Operator Utilities kmfile-dump

kmfile-dump
The kmfile-dump utility displays detailed key-management
information from a security world’s key-management data file. You
can also display information about the status of your security world
with the nfkminfo command-line utility.

Usage

kmfile-dump.exe [-b|--binary] [-p|--plain] [-v|--verbose] file [file ...]

In this command, file is the name of the file from which data is
dumped. The key-management data files from which you can display
data are located in the kmdata directory. They are:

Filename Contains data for...

module_ESN Module whose ESN is ESN
world Security world
card_HASH_NUM Card number NUMfrom card
set whose hash is HASH
card_HASH Card set whose hash is HASH
key_APPNAME_IDENT Key of type APPNAME whose
identifier is IDENT

Program options
-b, --binary

This entry displays all entries in binary.

-p, --plain

This option uses plain format for binary output with no

offsets or ASCII.

nShield/payShield Operator Guide Windows v5.5 231

7 nShield Operator Utilities kmfile-dump

-v, --verbose

This option shows binary dumps of key blobs.

nShield/payShield Operator Guide Windows v5.5 232

7 nShield Operator Utilities kptest

kptest
The kptest utility tests the consistency of encryption and decryption,
or signature and verification, with the RSA and DSA algorithms. It
can also test key generation by regenerating the key pair used every
given number of checks. kptest is not intended as a speed test.

Usage

C:\nfast\bin\kptest [-s|--sign-verify] [-e|--encrypt-decrypt] [-k|--key-

regenerate=CHECKS] [-i|--plain-size=SIZE] [-m|--module=MODULE] [-t|--stop-after=TIME] [-
c|--curve CURVE] [-n|--jobs-count=COUNT] [-S|--key-type=TYPE] [-l|--key-size=BITS] [-M|-
-mechanism=MECH] [-p|--plain-type=TYPE] [--strong] [--pairwise-check] [[[-K|--skew-
check=SKEW ]| [-T|--min-check=COUNT ]] [-C|--check-start=TIME]] [--overprint][-o|--
output=FILE] [-r|--report-interval=TIME]

Program options
-s, --sign-verify

These options test the sign/verify operation. This is the

default for DSA, ECDSA and KCDSA.

-e, --encrypt-decrypt

These options test the encrypt/decrypt operation. This is the

default for RSA.

-k, --key-regenerate=CHECKS

These options regenerate the key every CHECKS number of

checks.

-i, --plain-size=SIZE

These options use a plain text of SIZE bytes.

nShield/payShield Operator Guide Windows v5.5 233

7 nShield Operator Utilities kptest

-m, --module=MODULE

These options use module number MODULE. The default is

1.

-t, --stop-after=TIME

These options 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 infinite (that is, there is no
limit to the maximum number of jobs to run).

Key options
-S, --key-type=TYPE

These options test the sign/verify operation. This is the

default for DSA and KCDSA.

-l, --key-size=BITS

These options set the key size in bits. The default is 1024.
This option will be ignored if the key type is ECDSA - for
ECDSA keys use -c, --curve with one of the supported curves
as the argument.

-c, --curve CURVE

These options specify which of the range of supported

curves to use for testing with ECDSA. Supported curves are
any of: NISTP192, NISTP224, NISTP256, NISTP384,
NISTP521, NISTB163, NISTB233, NISTB283, NISTB409,

nShield/payShield Operator Guide Windows v5.5 234

7 nShield Operator Utilities kptest

NISTB571, NISTK163, NISTK233, NISTK283,

NISTK409, NISTK571, ANSIB163v1, ANSIB191v1,
SECP160r1.
Note The ECDSA algorithm is only available if you have enabled the
Elliptic Curve feature. See the Administrator Guide for details of
feature enabling.

-M, --mechanism=MECH

These options use plaintext of SIZE bytes.

-p, --plain-type=TYPE

These options use the plaintext type TYPE. Valid values are
Bignum, Hash and Bytes.

--strong

For RSA, this option uses strong (ANSI X9.31) primes. For
DSA, it uses the strict flag.

--pairwise-check

This option sets the PairwiseCheck flag in the key-generate

option.

Automatic checking options

-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 average. Subsequently, when
floodtest writes an output line, it quits with an error message
if the average is outside the range average ±SKEW.
Note The --min-check and --skew-check options are mutually exclusive.

nShield/payShield Operator Guide Windows v5.5 235

7 nShield Operator Utilities kptest

-T, --min-check=COUNT

These options perform threshold checking, starting after

either 15 seconds or the time specified by --check-start.
Subsequently, when kptest writes an output line, it quits with
an error message if the overall average number of modular
exponentiations each second drops below COUNT.

-C, --check-start=TIME

These options specify 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

These options specify that results be written to FILE in

addition to stdout.

-r, --report-interval=TIME

These options display, 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 Operator Guide Windows v5.5 236

7 nShield Operator Utilities kptest

Output
kptest displays a message similar to this:

Using default RSA key type

Using default keysize=1024
Using default Bytes plaintext type
Using default plaintext size=160
Using default RSApPKCS1 mechanism
Making 1024-bit RSAPrivate key on module #2
1 : 40
2 : 97
3 : 155
...

Subsequent lines show the time the test has been running and the total
number of operations performed.

nShield/payShield Operator Guide Windows v5.5 237

7 nShield Operator Utilities mkaclx

mkaclx
The mkaclx utility generates a key with specified attributes on a one-
off basis. It is useful for testing.

Usage

mkaclx [-m|--module=MODULE]
[-t|--type=KEYTYPE] [-b|--bits=BITS][-g|--group-size=BITS] [-k|--keygen-cert] [-K|--no-
keygen-cert] [-O|--deny-oppermissions=OPPERMS] [-C|--cardset-protected]
[-M|--module-protected] [-r|--recovery] [-R|--no-recovery] [-i|--kitb] [-a|--see-app-
key=IDENT[:MECH]]
[-N|--name=NAME] [-S|--softcard-protected=NAME] [-T|--timeout=SECS] [-U|--use-
limit=N] [-q|--quiet] [-v|--verbose] [-n|--name=NAME]
[--confirm]

Module selection options

-m, --module=MODULE

These options specify the module to generate the key. The

default is the first available module.

Key generation parameters

-t, --type=KEYTYPE

These options specify the type of the generated key. The

default is RSA.

nShield/payShield Operator Guide Windows v5.5 238

7 nShield Operator Utilities mkaclx

-b, --bits=BITS

These options specify the length in bits of the key to

generate. The default for each key type is as follows:

Key type Default

RSA, DH, DSA 1024 bits
DES, DES3, Skipjack Key size fixed by
algorithm
HMAC-MD5, HMAC-MD2, RC2, RC4, RC5, CAST128 128 bits
HMAC-SHA1, HMAC-RIPEMD160 160 bits
HMAC-SHA256, Serpent, Rijndael, Twofish, CAST256, 256 bits
Blowfish
HMAC-SHA384 384 bits
HMAC-SHA512 512 bits
HMAC-Tiger 192 bits

-g, --group-size=BITS

These options specify the group size for Diffie-Hellman keys

in bits. The default depends on the key type.

-k, --keygen-cert

These options specify that a key-generation certificate is

stored. This is the default.

-K, --no-keygen-cert

These options specify that no key-generation certificate is

stored.

-O, --deny-oppermissions=OPFLAGS

These options specify that the OpPermissions specified in

OPFLAGS are disabled. OPFLAGS must be a comma
separated list of OpPermissions.

nShield/payShield Operator Guide Windows v5.5 239

7 nShield Operator Utilities mkaclx

Key protection options

-C, --cardset-protected

These options specify that a card-set protected key is

generated.

-M, --module-protected

These options specify that a module protected key is

generated. This is the default.

-S, --softcard-protected=NAME

The options generate a softcard-protected module key using

the softcard named NAME.

-r, --recovery

These options specify that the generated key is recoverable.

This is the default.

-R, --no-recovery

These options specify that the generated key is not

recoverable.

-i, --kitb

Write the encrypted data to the module’s NVRAM.

-a, --see-app-key=IDENT[:MECH]

These options specify that use of the generated key is

restricted to SEE signed by the SEE integrity key IDENT,
optionally with the mechanism MECH.

-T, --timeout=TIME

These options specify the time limit for main-use operations.

Use the suffix s to specify seconds, m for minutes, h for
hours, and d for days.

nShield/payShield Operator Guide Windows v5.5 240

7 nShield Operator Utilities mkaclx

-U, --use-limit=N

These options specify the per-authorization limit for main-

use operations.

Other options
-q, --quiet

These options produce fewer messages on successful runs.

-v, --verbose

These options produce more messages on successful runs.

-N, --name=NAME

These options specify the name of the key. The default is that
the key has no name.

--confirm

This option shows the command and requests confirmation.

nShield/payShield Operator Guide Windows v5.5 241

7 nShield Operator Utilities modstate

modstate
The modstate utility displays the signed module state.

Usage

C:\nfast\bin\modstate [-m|--module MODULE] [--kml|--klf]

Module options
-m, --module=MODULE

These options specify the module number.The default is 1.

--kml

This option specifies SignerType_KML. This is the default.

--klf

This option specifies SignerType_KLF.

nShield/payShield Operator Guide Windows v5.5 242

7 nShield Operator Utilities ncdate

ncdate
The ncdate example utility views, sets and adjusts the real-time clock
in a module.

Usage

C:\nfast\bin\ncdate [-d|--display] [-m|--module=MODULE]

C:\nfast\bin\ncdate -a|--adjust [-m|--module=MODULE] hh:mm:ss [yyyy:mm:dd]
C:\nfast\bin\ncdate -s|--set [-m|--module=MODULE] hh:mm:ss [yyyy:mm:dd]

Action selection options

-d, --display

These options display the current module time.

-m, --module=MODULE

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

--set

This option sets the module time to the time specified

--adjust

This option adjusts the module time to the time specified.

To show the current time and date on module 1:

C:\nfast\bin\ncdate

nShield/payShield Operator Guide Windows v5.5 243

7 nShield Operator Utilities ncdate

To set the time and optionally the date on the module MODULE to the
given time and date:

C:\nfast\bin\ncdate --module=MODULE --set hh:mm:ss [yyyy:mm:dd]

To update the time and optionally the date on the module MODULE
to the given time and date:

C:\nfast\bin\ncdate --module=MODULE --adjust hh:mm:ss [yyyy:mm:dd]

Using the --adjust option makes the module compute the drift rate of
the internal clock based on the interval between the present time and
the time when the clock was last set or adjusted. The module
remembers this rate and uses it to correct future readings. It is
therefore important that the time is obtained from the same source as
it was previously.
Note The --set and --adjust options do not work on a module that is included
in a security world. Use the rtc utility for modules in a security world.
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) 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.

nShield/payShield Operator Guide Windows v5.5 244

7 nShield Operator Utilities ncthread-test

ncthread-test
The ncthread-test utility stress tests modules and tests nCore API
concurrent connection support.

Usage

C:\nfast\bin\ncthread-test [-d|--des-threads=THREADS] [-r|--rsa-threads=THREADS] [-s|--

check-every=PERIOD] [-c|--block-size=SIZE] [-b|--rsa-size=SIZE] [-q|--quiet]

Module options
-d, --des-threads=THREADS

These options create THREADS DES3 threads for symmetric

encryption. The default is 4.

-r, --rsa-threads=THREADS

These options create THREADS RSA threads for digital

signing. The default is 4.

-s, --check-every=PERIOD

These options check threads every PERIOD seconds. The

default is 10.

Other options
-c, --block-size=SIZE

These options encrypt blocks of up to SIZE characters long.

The default is 16384.

nShield/payShield Operator Guide Windows v5.5 245

7 nShield Operator Utilities ncthread-test

-b, --rsa-size=SIZE

These options use RSA key of size SIZE bits. The default is
1024.

-q, --quiet

These options run quietly, outputting only errors and

warnings.
Note If any threads have not returned a value since the last thread check, a
warning is generated. However, this may simply indicate that the
interval between checks is too short. If a thread persistently fails to
return a value, this indicates that an error has occurred.

nShield/payShield Operator Guide Windows v5.5 246

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

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 Operator Guide Windows v5.5 247

7 nShield Operator 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 Operator Guide Windows v5.5 248

7 nShield Operator Utilities nfkminfo

nfkminfo
The nfkminfo utility displays information about the security world and
the keys and card sets associated with it.

Usage

C:\nfast\bin\nfkminfo --cardset-list
[TOKENHASH] -key-list
[APPNAME[APPNAME]] |
-name-list
[APPNAME[IDENT...]]

Options
-c, --cardset-list [TOKENHASH]

If TOKENHASH is not specified, these options list the card

sets associated with the security world.

The output is similar to this:

Cardset summary - 1 cardsets:

(in timeout, P=persistent, N=not) Operator logical token hash k/n
timeout name
hash 1/1 none-N
name

If TOKENHASH is specified, these options list the details of

the card identified by hash.

nShield/payShield Operator Guide Windows v5.5 249

7 nShield Operator Utilities nfkminfo

The output is similar to this:

name
"name" k-out-of-n 1/1 flags NotPersistent timeout
none card names "" hkltu
794ada39038fa8c4e9ea46a24136bbb2b8b337f2

-k, --key-list [APPNAME[APPNAME]]

These options list keys without key names. If APPNAME is

specified, only keys for these applications are listed.

-l, --name--list [APPNAME[IDENT]]

These options list keys with their names. If APPNAME is

specified, only keys for these applications are listed. If
IDENT is listed, only the keys with the specified identifier
are listed.

nShield/payShield Operator Guide Windows v5.5 250

7 nShield Operator Utilities nfkmverify

nfkmverify
The nfkmverify utility verifies key generation certificates, and so
allows you to confirm how a particular security world and key are
protected. It also returns some information about the security world
and key.

nfkmverify only works for:

• keys that were generated by generatekey or nfkmcmdadp from
nftcl component version 1.81.0 or later
• security worlds generated by new-world from sworld component
version 1.4.0 or later later, and keys generated by application
programs and libraries that use the certificate storage features
available from sworld component version 1.4.0 or later
• keys and security worlds generated on modules using firmware
version 1.67.15 or later.

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

A key that has been recovered to a different card set shows a

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

A key that has been transferred from another security world will show
discrepancies and fail to be verified. nCipher recommend that keys are
verified in the original security world at the time of generation.

If you need to replace your security world or card set, nCipher

recommend that new keys are generated where possible. If you need
to transfer a key, verification should be performed immediately prior
to transfer as verification after the change of protection to a new
security world, or card set, is troublesome.

nShield/payShield Operator Guide Windows v5.5 251

7 nShield Operator Utilities nfkmverify

Usage

nfkmverify.exe [-f|--force] [-v|--verbose] [-U|--unverifiable] [-m|--module=MODULE]

[appname] [ident]

Help options
-h, --help

These options display help for nfkmverify.exe.

-V, --version

These options display the version number for nfkmverify.exe.

-u, --usage

These options display a brief usage summary for

nfkmverify.exe.

Program options
-m, --module=MODULE

These options perform checks with module MODULE.

-f, --force

These options forces display of an output report that might

be wrong.

-U, --unverifiable

These options proceed even if the security world is

unverifiable.
Note If you need the --unverifiable option, there may be some serious
problems with your security world.

nShield/payShield Operator Guide Windows v5.5 252

7 nShield Operator Utilities nfkmverify

-v, --verbose

These options proceed even if the security world is

unverifiable.

-C, --certificate

These options check the original ACL for the key using the
key generation certificate. This is the default.

-L, --loaded

These options check the ACL of a loaded key instead of the

generation certificate.

-R, --recov

These options check the ACL of the key loaded from the
recovery blob.

--allow-dh-unknown-sg-group

This option allows an operation to proceed even if a Diffie-

Hellman key is using an unrecognized Sophie-Germain
group.

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

Under normal circumstances, issuing a command of the form:

nfkmverify --verbose --unverifiable myapp o20010621a13h25m02

nShield/payShield Operator Guide Windows v5.5 253

7 nShield Operator Utilities nfkmverify

returns output of the form:

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

Generating module ESN 0A42-E645-7A75 currently #1 (in same incarnation)

nCore hash 23a901f3329aa9e29cd79d3bb7b32d549b725fc3
public_half.type= RSAPublic 1
.data.rsapublic.e= 4 bytes
00010001

.n= 128 bytes

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

Verification successful, check details above.

Output of the form shown above indicates successful verification of

the relevant key generation certificate.

nShield/payShield Operator Guide Windows v5.5 254

7 nShield Operator Utilities nfkmverify

The following examples indicate forms of output that could be

returned if you try to verify the generation certificate of a key
generated in a security world that was created with an insufficiently
up-to-date version of nCipher software.

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

nfkmverify --verbose myapp spong

returns output of the form:

PROBLEM: no world generation certificates

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

Adding the --unverifiable tag to the same command:

nfkmverify --verbose --unverifiable myapp spong

returns output of the form:

PROBLEM: application key myapp spong: no key generation signature

1 issues found, NOT VERIFIED

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

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

nShield/payShield Operator Guide Windows v5.5 255

7 nShield Operator Utilities nfkmverify

returns output of the form:

PROBLEM: application key myapp spong: no key generation signature

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

1 issues found, NOT VERIFIED

nShield/payShield Operator Guide Windows v5.5 256

7 nShield Operator Utilities nopclearfail

nopclearfail
The nopclearfail utility clears a module, puts a module into the error
state, or retries a failed module.
Note In order to recover a module from the error state, you must turn the
power to the module off and then on. For internal modules, this may
mean shutting down and then rebooting your computer.

Retrying a module causes the nCipher server to attempt reconnecting

to a module to which the connection has previously failed. Retrying a
module may cure some bus errors. You cannot attempt to reconnect to
a module if it is in the error state.

Usage

C:\nfast\bin\nopclearfail.exe [[-n|--no-op]|[ -c|--clear]|[-f|--fail]|[-r|--retry]]

[[-a|--all]| [-m|--module=MODULE]]

Action selection options

-n, --no-op

These options send the NoOp command

-c, --clear

These options send the ClearUnit command. To use this

option, you must be logged in as a user who is permitted to
create privileged connections.

-f, --fail

These options send the Fail command. To use this option,

you must be logged in as a user who is permitted to create
privileged connections.

nShield/payShield Operator Guide Windows v5.5 257

7 nShield Operator Utilities nopclearfail

-r, --retry

These options send the RetryFailedModule command. To use

this option, you must be logged in as a user who is permitted
to create privileged connections.

Module selection options

-a, --all

These options send the command to all modules

-m, --module=MODULE

These options send the command to module MODULE.

Output
If you select the --no-op, --retry, or --clear option, nopclearfail returns
the following for each selected module:

Module 1, command NoOp: OK

If you select the --fail option and logged in as a user who is permitted
to create privileged connections, the Fail command causes the module
to enter the error state. The status LED will flash SOS D (... --- ... -..) .
In order to reset the module, you must turn the power to the module
off and then on again. If you are not logged in as a user who is
permitted to create privileged connections and you select the --fail
option, the Fail command will fail and the module will itself continue
as normal.
Note When your machine is connected to a remote slot, if you clear all the
modules using nopclearfail --clear --all, the remote slot temporarily
becomes unavailable. The slot is unavailable for about 5 minutes,
after which it becomes available again automatically. There may be a

nShield/payShield Operator Guide Windows v5.5 258

7 nShield Operator Utilities nopclearfail

short delay before a message informs you of this. However, when the
problem occurs the following message may appear after you run
slotinfo:

bash-2.04$ slotinfo.exe 1 Module 1:

Slot Type Token IC Flags Details
#0 Smartcard - 0 A
#1 Software Tkn - 0
#2 Unconnected - 0 R RemoteServerFailed, <us >
(CrossModule,#1-ServerUnitReset,#2-ExplicitRequest,#3-ExplicitRequest)

nShield/payShield Operator Guide Windows v5.5 259

7 nShield Operator Utilities nvram-backup

nvram-backup
The nvram-backup utility copies files between a module’s 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 Generating NVRAM-stored keys on page 92 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 load-
balancing 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 module’s
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 module’s 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 module’s NVRAM.

When you copy files to a module’s NVRAM or delete files from

NVRAM, you are required to insert a quorum of Administrator Cards
for NVRAM authentication.

nShield/payShield Operator Guide Windows v5.5 260

7 nShield Operator 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 nvram-

backup.exe.

-u, --usage

These options display a brief usage summary for nvram-

backup.exe.

Action selection options

-l, --list

These options list files either on a module’s NVRAM or on

a smart card. By default nvram-backuplists the contents of
the module’s NVRAM.

nShield/payShield Operator Guide Windows v5.5 261

7 nShield Operator Utilities nvram-backup

-c, --copy

These options copy files between a module’s NVRAM and a

smart card.

You cannot copy from a module’s 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 266.

-d, --delete

These options delete files from a module’s 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 module’s NVRAM for

copying to a smart card or for listing, or deletes files from the
module’s NVRAM.

-S, --from-smartcard

These options reads files from a smart card for copying to a

module’s 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 Operator Guide Windows v5.5 262

7 nShield Operator 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 module’s 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 266.

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 Operator Guide Windows v5.5 263

7 nShield Operator Utilities nvram-backup

Output
To list the contents of the default module’s NVRAM, use the
command:

C:\nfast\bin\nvram-backup.exe --list

nvram-backup displays file information in the following format:

File ID (hex) File ID (ASCII) File Length

------------- --------------- -----------
725178c71ba5cf959318fc
625178c71ba5cf959318fc
72d2fb7c9d0c58f6424855
62d2fb7c9d0c58f6424855

In this example, four files are stored in the module’s 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 266.

To obtain a listing of the contents of a module’s 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. nvram-
backup prompts you to insert a smart card from this security world for
authorization.

nShield/payShield Operator Guide Windows v5.5 264

7 nShield Operator Utilities nvram-backup

1. 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 nvram-
backup 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 module’s 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 module’s 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 Operator Guide Windows v5.5 265

7 nShield Operator 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 Operator Guide Windows v5.5 266

7 nShield Operator 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 nvram-

sw.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 Operator Guide Windows v5.5 267

7 nShield Operator 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 Operator Guide Windows v5.5 268

7 nShield Operator 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 Operator Guide Windows v5.5 269

7 nShield Operator 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 128-
255 (top bit set).

nCipher also uses the following specific FileIDs:

nShield/payShield Operator Guide Windows v5.5 270

7 nShield Operator 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 Operator Guide Windows v5.5 271

7 nShield Operator Utilities pollbare

pollbare
Note This utility is deisgned as a test utility only, although it can also be
used by nCipher support to obtain more information about your
system. Unless you are a developer you are unlikely to need to
understand it in detail; developers can find more complete
information in the nCipher Developer Reference.

The pollbare example utility returns information about state changes.

Its functionality depends on whether the server or any module
supports nCore API poll commands. You can discover whether this is
the case by using the enquiry utility, described in enquiry on page 185.

Usage

C:\nfast\bin\pollbare.exe [-q|--quiet] [-t|--time=TIME] [-m|--module=MODULE]

-q. --quiet

These options specify that pollbare run only once.

-t. --time=TIME

These options specify an update every TIME number of

seconds. If you do not specify a value, the default is 1.

-m. --module=MODULE

These options specify that pollbare be applied only to a given

module MODULE. If you do not specify a module, the
default is all modules.

nShield/payShield Operator Guide Windows v5.5 272

7 nShield Operator 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 Operator Guide Windows v5.5 273

7 nShield Operator 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 softcard’s pass phrase
• recovering a softcard’s 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 Operator Guide Windows v5.5 274

7 nShield Operator 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 Operator Guide Windows v5.5 275

7 nShield Operator 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 Operator Guide Windows v5.5 276

7 nShield Operator 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|--require-
fips] [-N|--no-fips] [-f PRELOADFILE|--preload-file=PRELOADFILE] [-R|--reload-
everything] | 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 Operator Guide Windows v5.5 277

7 nShield Operator 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 274). However, the preload command can load
softcard-protected keys; see Key selection options on page 279.

-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. See Viewing cards and softcards on page 75 for
further information. 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 Operator Guide Windows v5.5 278

7 nShield Operator 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 module-
protected 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 Operator Guide Windows v5.5 279

7 nShield Operator Utilities preload

nfkminfo command-line utility in order to identify keys that

are used by particular applications. See Viewing cards and
softcards on page 75 for further information.

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

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.
See Viewing cards and softcards on page 75 for further
information. Softcard patterns or names are treated as
substrings.

nShield/payShield Operator Guide Windows v5.5 280

7 nShield Operator 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 274.

Use the ppmk or nfkminfo command-line utilities to identify

keys and softcards that are used by particular applications.
See Viewing cards and softcards on page 75 for further
information. 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 Operator Guide Windows v5.5 281

7 nShield Operator 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 Operator Guide Windows v5.5 282

7 nShield Operator 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 Operator Guide Windows v5.5 283

7 nShield Operator 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 Operator Guide Windows v5.5 284

7 nShield Operator 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 Operator Guide Windows v5.5 285

7 nShield Operator 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 Operator Guide Windows v5.5 286

7 nShield Operator 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 Operator Guide Windows v5.5 287

7 nShield Operator Utilities pubkey-find

pubkey-find
The pubkey-find utility returns information about the contents of a
.pem file, which may be a private key, a certificate, or a certificate
request.

Usage

C:\nfast\bin\pubkey-find.exe [--cert|--certreq|--privkey|--auto] [--summary] [--hash]

[--fingerprint] [--thumbprint] [--identify] [--verify] [--info] [--augment]
[--match-appname PATTERN] [--match-ident PATTERN] [--all|--latest|--earliest] [--module
MODULE] [--verbose][--nfkmverify-options OPTIONS]CERT-OR-KEY-FILE

In this command CERT-OR-KEY-FILE specifies a .pem file.

This utility has the help option -h. It does not have other help options.

Input format options

--cert

This option specifies that the input file is a certificate.

--certreq

This option specifies that the input file is a certificate

request.

--privkey

This option specifies that the input file is a private key.

--auto

This option specifies that the type of the input file is not
known. pubkey-find attempts to identify the input format.
This is the default if no input file type option is specified.

The input file type should be specified if it is known.

nShield/payShield Operator Guide Windows v5.5 288

7 nShield Operator Utilities pubkey-find

Output format options

--summary

This option generates summary output in human-readable

format. Summary information includes the nCore hash and
the identities of any matching key files in the kmdata area. If
the file is in private key format but is actually an embed key
indicator (or ssleay encapsulated blob), this is also reported.

The information displayed by the --summary option is the

default if no output format options are specified. Summary
information is not printed if another output format option is
specified and --summary is not.

--hash

This option prints the nCore key-pair hash.

--fingerprint

This option prints the certificate’s MD5 hash (its

fingerprint).

--thumbprint

This option prints the certificate’s SHA-1 hash (its

thumbprint).

The --hash, --fingerprint, and --thumbprint options print not

just the key, but the cryptographic checksum of the entire
certificate.

--identify

This option prints the key’s security world appname and

idents.

nShield/payShield Operator Guide Windows v5.5 289

7 nShield Operator Utilities pubkey-find

Further processing options

--verify

This option uses nfkmverify to verify that the key was

securely generated.

--info

This option displays extensive general information about the

key (nfkminfo -k)

--augment

This option augments the kmdata file with the public key
blob from the imported key. You can only augment a single
key at a time.

Other options
--match-appname PATTERN

This option limits processing to the application name that

matches the specified PATTERN. (The default is no
restriction).

--match-ident PATTERN

This option limits processing to the idents that match the

specified PATTERN. (The default is no restriction).
Note Pattern matching in --match-appname and --match-ident uses the syntax
of the UNIX glob command.

--all

This option reports and processes all key files in the kmdata
directory that match CERT-OR-KEY-FILE. This is the default
if none of --all, --latest or --earliest is specified.

nShield/payShield Operator Guide Windows v5.5 290

7 nShield Operator Utilities pubkey-find

--latest

This option reports and processes the most recently modified

file.

--earliest

This option reports and processes the file that has the earliest
modification time.

--module MODULE

This option selects the module to use.

--verbose

This option reports more details if the input cannot be

parsed.

--nfkmverify-option OPTIONS

This option passes OPTIONS to nfkmverify. OPTIONS must

be a Tcl list. See nfkmverify on page 251.

If several kmdata files match, for example if the key has been
retargeted, pubkey-find processes all of them. The --latest and --earliest
options can be used to select one file only to process. The --earliest
option is likely to work best with nfkmverify (that is, the --verify
option). --latest is likely to work best otherwise.

nShield/payShield Operator Guide Windows v5.5 291

7 nShield Operator Utilities pubkey-find

Output
pubkey-find returns information similar to the following:

$ C:\nfast\bin\pubkey-find cert.pem
input format cert
nCore hash 7e259da3d7e78d8ad0b9375e5b99d2d4ad0de7a8
no matching key in current security world host data area
$ C:\nfast\bin\pubkey-find embed.pem
PEM 'key' file really contains only key indicator
input format privkey
nCore hash 750749f62b640132c4b05fa552f49fea3785d01a
name 'plainname'
appname embed
ident 1038030e0e3f21d709817e049eec575a33faa2f2
$ C:\nfast\bin\pubkey-find embed_req.pem
input format certreq
nCore hash 750749f62b640132c4b05fa552f49fea3785d01a
name 'plainname'
appname embed
ident foo
name 'plainname'
appname embed
ident 1038030e0e3f21d709817e049eec575a33faa2f2
$ C:\nfast\bin\pubkey-find --fingerprint embed_selfcert.pem
47:3d:8f:f8:2c:7a:64:23:f9:5a:53:c4:1c:39:3b:2c
$ C:\nfast\bin\pubkey-find --thumbprint embed_selfcert.pem
52:ab:8c:fa:13:a6:ce:43:69:70:87:36:d1:eb:73:71:3e:ba:98:e8
$

nShield/payShield Operator Guide Windows v5.5 292

7 nShield Operator Utilities randchk

randchk
The randchk utility runs an n-bit, or an n-to-m-bit, Maurer’s Universal
Statistical Test on random numbers returned by the module.

Maurer’s Universal Statistical Test is documented in “A universal

statistical test for random bit generations”, Advances in Cryptology—
CRYPTO ’90 (LNCS) 408-420, 1991.

Usage

C:\nfast\bin\randchk.exe [L-min [L-max]]

If specified, the value of L-min is the number of the lowest bit to be

used in the test and L-max is the number of the upper bit to be used in
the test. These numbers must be between 1 and 16. If you do not enter
a number, randchk performs a 6-bit test.

You can specify a single number, L-min, or a range of numbers, L-min

to L-max. If you specify numbers from L-min to L-max inclusive,
randchk performs statistical tests for a range of random numbers with
these lengths. The second number, L-max, must be larger than the first
number, L-min.

Output
randchk displays a message similar to this:

Initialising 6-bit Universal Statistical Test Processing... 46K 6-bit test results:
5.221070 = 0.003365 from mean (0.507348 s.d.'s)

nShield/payShield Operator Guide Windows v5.5 293

7 nShield Operator 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 the Administrator
Guide for details of client configuration.

Usage

C:\nfast\bin\rfs-setup.exe [-c|--configfile=FILENAME] [-f|--force]

C:\nfast\bin\rfs-setup.exe <ADDRESS> module_ESN keyhash
C:\nfast\bin\rfs-setup.exe --gang-client module_ip_address module_ESN keyhash
C:\nfast\bin\rfs-setup.exe --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 Operator Guide Windows v5.5 294

7 nShield Operator 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 module’s
front panel. You can also obtain it with the anonkneti utility. See
bulkerase on page 143 for details.

nShield/payShield Operator Guide Windows v5.5 295

7 nShield Operator 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 the Administrator Guide 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 Operator Guide Windows v5.5 296

7 nShield Operator 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 Operator Guide Windows v5.5 297

7 nShield Operator 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 --kill-
lock option forcibly removes the lock file.

nShield/payShield Operator Guide Windows v5.5 298

7 nShield Operator Utilities sigtest

sigtest
The sigtest utility measures the module speed using RSA, DSA or
ECDSA signatures or signature verifications.

Usage

sigtest [[-s|--sign]|[-v|--verify]|[-d|--decrypt][-m|--module=MODULE][-c|--curve
CURVE][-j|--outstanding-jobs=COUNT]-t|--stop-after=TIME][[-n|--jobs-count=COUNT][-S|--
key-type=TYPE][-l|--key-size=BITS][-M|--mechanism=MECH][-p|--plain-type=TYPE] [--
strong] [--pairwise-check] [-K|--skew-check=SKEW][-T|--min-check=COUNT][-C|--check-
start=TIME][--overprint] [-o|--output=FILE][-r|--report-interval=TIME]

Help options
-h, --help

These options display help for sigtest.

-V, --version

These options display the version number for sigtest.

-u, --usage

These options display a brief usage summary for sigtest.

Program options
-s, --sign

These options test the Sign operation. This is the default if no

program option is specified.

-v, --verify

These options test the Verify operation.

nShield/payShield Operator Guide Windows v5.5 299

7 nShield Operator Utilities sigtest

-d, --decrypt

These options test the Decrypt operation.

-m, --module=MODULE

These options specify the module number. Multiple modules

may be specified, for example, --module=1 --module=2. If no
module is specified, all module are tested by default.

-j, --outstanding-jobs=COUNT

These options set the maximum number of outstanding jobs.

The default value of COUNT is the maximum number of jobs
recommended for the hardserver, plus one. If -m is used to
limit the testing to a single module when using ECDSA,
limit the maximum number of jobs to 100 using -j 100 as the
algorithm is currently slower than RSA or DSA and single
modules may become overloaded by the test.

-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 hours, and d
for days. The default value of TIME is infinity, that is, the test
runs forever.

-n, --jobs-count=COUNT

These options specify the maximum number of jobs to run.

The default value of COUNT is infinity, that is, there is no
limit to the number of jobs run.

Key options
-S, --key-type=TYPE

These options select the signature type to use. Valid values

are RSA, DSA, ECDSA and KCDSA. The default is RSA.

nShield/payShield Operator Guide Windows v5.5 300

7 nShield Operator Utilities sigtest

-l, --key-size=BITS

These options set the key size in bits. The default is 1024.
This option is ignored if the key type is ECDSA; for elliptic
curve keys. use the -c or --curve options with one of the
supported curves as the argument.

-c, --curve CURVE

These options specify which of the range of supported

curves to use for testing with ECDH and ECDSA. Supported
curves are any of: NISTP192, NISTP224, NISTP256,
NISTP384, NISTP521, NISTB163, NISTB233, NISTB283,
NISTB409, NISTB571, NISTK163, NISTK233,
NISTK283, NISTK409, NISTK571, ANSIB163v1,
ANSIB191v1, SECP160r1 .

-M, --mech=MECH

These options specify the mechanism to use. Valid values are

RSApPKCS1, DSA, ECDSA and KCDSAHAS160.
Note The KCDSA algorithm and the KCDSAHAS160 mechanisms are
available only if you have enabled the KCDSA feature. See the
Administrator Guide for details of feature enabling. Similarly, the
ECDSA mechanism is only available if you have enabled the Elliptic
Curve feature.

-p, --plain-type=TYPE

These options use the plaintext type TYPE. Valid values are
Bignum, Hash and Bytes.

--strong

For RSA, this option uses strong (ANSI X9.31) primes. For
DSA, it uses the strict flag.

--pairwise-check

This option sets the PairwiseCheck flag during key

generation.

nShield/payShield Operator Guide Windows v5.5 301

7 nShield Operator Utilities sigtest

Automatic checking options

-T, --min-check=COUNT

These options perform threshold checking, starting after

either 15 seconds or the time specified by --min-check.
Subsequently, when sigtest writes an output line, it quits with
an error message if the overall average number of modular
exponentiations each second drops below COUNT.

-K, --skew-check=SKEW

These options perform skew checking, after either 15

seconds or the time specified by --min-check. sigtest records
the overall average number of modular exponentiations each
second as average. Subsequently, when sigtest writes an
output line, it quits with an error message if the average is
outside the range average SKEW.
Note The --min-check and --skew-check options are mutually exclusive.

-C, --check-start=TIME

These options specify 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

These options specify that results be written to FILE in

addition to stdout.

nShield/payShield Operator Guide Windows v5.5 302

7 nShield Operator Utilities sigtest

-r, --report-interval=TIME

These options display, 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.

Output
sigtest produces output similar to this:

number of modules: 1
Making 1024-bit RSA Private key on module #1...
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 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 Operator Guide Windows v5.5 303

7 nShield Operator 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 Operator Guide Windows v5.5 304

7 nShield Operator Utilities slotinfo

• Use createocs to format Operator Cards

• Use KeySafe or createocs to erase cards.

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 Operator Guide Windows v5.5 305

7 nShield Operator 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
308.
• 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 Operator Guide Windows v5.5 306

7 nShield Operator 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 Operator Guide Windows v5.5 307

7 nShield Operator 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
client’s 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 Operator Guide Windows v5.5 308

7 nShield Operator Utilities stattree

Category Contains
ModuleJobStats Statistics for the commands (jobs) processed by a
module. Appears under the PerModule category.
ModulePCIStats Statistics from the module’s PCI host interface. Appears
only on PCI-interfaced modules.
ModuleObjStats Statistics for the module’s Object Store, which contains
keys and other resources. These statistics may be useful
in debugging applications that leak key handles, for
example.
ModuleEnvStats General statistics for the module’s 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 Operator Guide Windows v5.5 309

7 nShield Operator 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 Operator Guide Windows v5.5 310

7 nShield Operator 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
module’s 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 Operator Guide Windows v5.5 311

7 nShield Operator 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 Operator Guide Windows v5.5 312

7 nShield Operator 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 non-
RSA tasks the main CPU or another resource (such as the
random number generator) can be saturated without this
statistic reaching 100%.
HostIRQs On PCI 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 module’s
ModuleObjStats node.
ObjectsDestroyed The number of items in the module’s object store that
have been deleted and their corresponding memory
released.
ObjectCount The current number of objects (keys, logical tokens,
buffers, SEE Worlds) in the object store. This is equal to
ObjectsCreated minus ObjectsDestroyed. An empty
module contains a small number of objects that are
always present.

nShield/payShield Operator Guide Windows v5.5 313

7 nShield Operator 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 module’s
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 module’s
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 module’s kernel does
not know (and does not report in the statistics) how much
of the user-mode’s heap is currently free, and how much
is in use.

nShield/payShield Operator Guide Windows v5.5 314

Appendix A: Cryptographic algorithms
This appendix describes the algorithms supported by nCipher
modules.

In the following tables, the column labelled nfkmverify documents the

implemented behaviour of the nfkmverify command-line utility (and
its underlying library). An entry N in this column means that
nfkmverify always rejects the algorithm, while Y means that
nfkmverify always accepts the algorithm. A constraint on the number
of bits means that nfkmverify only accepts keys of at least that many
bits.

Symmetric Algorithms
FIPS approval

nfkmverify
Algorithm Key length in bits Use for ...
Authorization
Digital Signatures
Encryption
Other

AES Y 128, 192, 256 Y Y Y

Arcfour 192 Y N
Blowfish 8 to 448 Y Y N
CAST 5 up to 128 Y Y N
CAST 6 up to 256 Y Y N
DES 56 Y Y N
MD2 HMAC 8 to 2048 Y N
MD5 HMAC 8 to 2048 Y N
RIPEMD160 8 to 2048 Y ≥80 bits
HMAC
SEED 128 Y Y N
Serpent up to 256 Y Y N

nShield/payShield Operator Guide Windows v5.5 315

A Cryptographic algorithms Cryptographic algorithms

Symmetric Algorithms

FIPS approval

nfkmverify
Algorithm Key length in bits Use for ...

Authorization
Digital Signatures
Encryption
Other
SHA-1 HMAC Y 8 to 2048 Y ≥80 bits
SHA-256 HMAC Y 8 to 2048 Y ≥80 bits
SHA-384 HMAC Y 8 to 2048 Y ≥80 bits
SHA-512 HMAC Y 8 to 2048 Y ≥80 bits
Tiger HMAC 8 to 2048 Y ≥80 bits
Triple DES Y 112, 168 Y Y Y
Twofish up to 256 Y Y N

nShield/payShield Operator Guide Windows v5.5 316

A Cryptographic algorithms FIPS Information

Asymmetric Algorithms

FIPS approval

nfkmverify
Algorithm Key length in bits Use for ...

Authorization
Digital Signatures
Encryption
Other
RSA Y ≥512 Y Y Y ≥1024 bits
≥1024 ≥1024 bits

Key exchange
Diffie-Hellman Y

DSA Y 512 to 1024 ≥1024 bits

Y Y
El-Gamal ≥1024
Y
KCDSA ≥1024 ≥1024 bits
Y Y
ECDSA Y ≥224 ≥1024 bits
Y Y
ECDH Y ≥224 ≥1024 bits
Y Y

Note The RSA algorithm is based on the factorization of integers.

Note The Diffie-Hellman, DSA, El-Gamal, ECDSA, ECDH, and KCDSA
algorithms are all based on discrete logarithms in a multiplicative
group of a finite field.

FIPS Information
The latest guidance from the National Institute of Standards and
Technology (NIST) is that

nShield/payShield Operator Guide Windows v5.5 317

A Cryptographic algorithms FIPS Information

• a module is only operating in FIPS mode when it uses NIST-

approved algorithms
• a module operating at FIPS 140-2 level 3 must not only indicate
whether it is in FIPS mode but also actively prevent use of
algorithms not approved by NIST in FIPS-approved mode.

Thus, with the current release of firmware, when a module is

initialized into FIPS 140-2 level 3 mode, you are only offered NIST-
approved algorithms. If you have a security world created to comply
with FIPS 140-2 level 3 and have any protocols that use algorithms
not approved by NIST, you must either migrate to a FIPS 140-2 level
2 security world or change your protocols. If you have a security
world created to comply with FIPS 140-2 level 3 and have existing
long-term keys for non-approved algorithms, then these keys cannot
be used with the current firmware. In such a case, nCipher
recommends that you either migrate your security world to a FIPS
140-2 level 2 security word or replace these keys with approved keys
before upgrading to the current firmware.

These changes do not affect security worlds that were created to

comply with FIPS 140-2 level 2, nor do they affect systems that use
the nCipher module to protect long-term keys but perform encryption
with session keys on the host (as is the case with nCipher’s MSCAPI,
CHIL, and PKCS #11 libraries).

The NIST-approved algorithms that nCipher modules offer are:

• DSA
• ECDSA
• RSA
• Diffie-Hellman
• Triple DES
• AES
• SHA-1
• SHA-256

nShield/payShield Operator Guide Windows v5.5 318

A Cryptographic algorithms FIPS Information

• SHA-384
• SHA-512
• TLS key derivation
• HMAC (SHA-1, SHA-256, SHA-384, SHA-512)

The algorithms not approved by NIST that nCipher modules offer are:
• KCDSA
• ECDH
• Arc Four
• Blowfish
• CAST 5
• CAST 6
• DES
• Serpent
• SEED
• Twofish
• SHA-160
• MD2
• MD5
• RIPEMD 160
• HMAC (MD2, MD5, RIPEMD160)

nShield/payShield Operator Guide Windows v5.5 319

nCipher addresses
nCipher Corporation Ltd. nCipher Inc.
Cambridge, UK Boston Metro Region, USA

Jupiter House 92 Montvale Avenue, Suite 4500

Station Road Stoneham, MA 02180
Cambridge USA
CB1 2JD
UK
Tel: +44 (0) 1223 723600 Tel: 800-NCIPHER
Fax: +44 (0) 1223 723601 800-6247437
+1 (781) 994 4000
Fax: +1 (781) 994 4001
E-mail: E-mail:
[email protected] [email protected]
[email protected] [email protected]

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.