nShield/payShield Administrator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher...

nShield/payShield Administrator

Guide Windows

nShield/payShield Administrator Guide Windows v5.5 2

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 orreproduced 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 aretrademarks 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. nCipherCorporation Limited shall not be liable for errors contained herein or for incidental or consequentialdamages 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 SoftwareDocumentation, as defined in sub-paragraphs (a)(1) and (a)(5) of DFAR § 252.227-7014, "Rights inNoncommercial Computer Software and Noncommercial Computer Software Documentation". Use,duplication or disclosure by the Government is subject to nCipher's standard US Terms And Conditionsfor the Product.

Patents

UK Patent GB9714757.3. Corresponding patents/applications in USA, Canada, South Africa, Japan andInternational Patent Application PCT/GB98/00142.


Contents

Chapter 1: Introduction 10

General information 10

Audience 11

Contents of this guide 11

Conventions 13

Additional Documentation 16

Further information 16

Chapter 2: nCipher security worlds 18

Security 20

Application independence 24

Platform independence 25

Flexibility 25

Robustness 31

Scalability 34

KeySafe and security worlds 35

Applications and the security world 37

The nCipher PKCS #11 library and security worlds 37

Risks 38

Chapter 3: Getting the module working 39

Determining module requirements 39


Prerequisites to software installation 40

Software installation procedure 43

After software installation 46

Configuring the module 51

Creating and configuring a security world 56

Creating and configuring a payShield installation 64

Creating the Operator Card Set 71

Chapter 4: Changing the module state 76

Entering the pre-maintenance state 76

Entering the pre-initialization state 78

Entering the operational state 79

Chapter 5: Uninstalling 82

Uninstalling the nCipher support software 82

Chapter 6: Configuring the hardserver 83

Remote module connections 83

Hardserver settings 84

Hardserver start-up settings 84

Remote slots 84

SEE machines 85

Hardserver configuration file 85

Payments configuration file 96

Chapter 7: Using multiple modules 98

Identifying modules 98

Multiple modules and Remote Operator 99

Adding a module 100


Module fail over 100

Chapter 8: Feature Enabling nCipher Modules 101

Available Features 101

payShield features 103

Ordering features for your module 104

Enabling features 105

Chapter 9: Using CodeSafe Applications 108

CodeSafe/C applications 108

Chapter 10: Using KeySafe 109

Starting KeySafe 109

The KeySafe window 111

Errors 120

Chapter 11: Managing security worlds 123

Security world files 123

Security world options 125

Creating a security world 129

After you have created a security world 154

Adding or restoring a module to the security world 155

Erasing a module from a security world 162

Deleting the security world 165

Displaying information about your security world 166

Windows Cryptographic Services Provider (CSP) 179

Transferring keys between security worlds 185


Chapter 12: About payShield installations 187

About payShield Card Sets 187

Supported payShield Key Types 190

payShield security world properties 191

Chapter 13: Remote Operator Card Sets 193

About Remote Operator 193

Configuring Remote Operator 194

Chapter 14: Administration tasks with cards and softcards 200

Replacing an Operator Card’s pass phrase 200

Replacing Operator Card Sets 202

Changing pass phrases with cardpp 218

Changing pass phrases with ppmk 220

Replacing the Administrator Card Set 221

Chapter 15: nShield Administrator Utilities 226

Help options 226

anonkneti 227

cfg-reread 228

enquiry 229

floodtest 238

hardserver 242

initunit 244

loadkeys 246

key-xfer-im 250

loadrom 253

mk-reprogram 255


ncversions 257

new-world 259

nvram-backup 266

nvram-sw 272

payshield-config 278

payshield-info 280

payshield-install 283

postrocs 286

ppmk 287

preload 290

racs 301

rfs-setup 302

rfs-sync 304

rtc 307

slotinfo 310

sppupgradekeys 312

stattree 314

Appendix A: Upgrading module firmware 323

Version Security Number 323

Firmware on the CD-ROM 324

What must I do? 325

Key data 325

Firmware installation overview 326

PCI modules 327

After firmware installation 329


Appendix B: Components on nCipher CD-ROMs 330

nCipher component bundles 330

nCSS User CD-ROM 335

CipherTools CD-ROM 335

CodeSafe CD-ROM 336

Components Required for Particular Functionality 337

PKCS #11 applications 338

Cryptographic Hardware Interface Library applications 338

nCipherKM JCA/JCE cryptographic service provider 338

nCipher SNMP monitoring agent 339

Appendix C: Environment variables 340

Appendix D: Logging and debugging 343

Environment variables to control logging 343

Logging from the nCipher CSP 348

Logging and debugging information for PKCS #11 349

Hardserver debugging 350

Debugging information for payShield 350

Debugging information for Java 352

Appendix E: Installed Utilities 354

Appendix F: The nCipher SNMP monitoring agent 361

Activating the nCipher SNMP agent 362

Default settings 363

Do you already have an SNMP agent running? 363

Activation of the SNMP agent 363

Further Information 364


Using the nCipher SNMP agent with a manager application 367

Useful nCipher SNMP agent command-line switches 382

Using the SNMP command line tools 385


Chapter 1: Introduction

General information

This guide describes how to use an nShield, payShield or payShield Ultra hardware security module (or HSM) to protect and accelerate the performance of the longterm cryptographic keys that are used by your applications, including payment and related applications on payShield modules.

In this guide, the term nShield refers to any of the nShield, payShield or payShield Ultra modules. Information specific to the payShield and payShield Ultra modules is clearly marked.

nCipher modules use the security world paradigm to provide a secure environment with both application independence and platform independence for all your module and key management operations. Security worlds have the flexibility and scalability to suit your needs, while also providing the robustness that is needed for every day operation as a key component in your IT infrastructure.

Standard nCipher security worlds need to be prepared for use with payShield applications. Although it is possible to convert an existing security world for use with payShield, nCipher recommends that you create a new security world and then follow the instructions in payShield security world properties on page 191. Be sure to create back up copies of any existing data in your kmdata directory before creating a new security world, or attempting to convert an existing security world.

All nCipher modules support standard cryptography frameworks and can be quickly integrated with many standards based products.


1 Introduction Audience

Audience

Read this guide if you need to configure or administer an nShield or payShield module, and you use or require an nCipher security world to protect your keys.

This guide assumes that you are familiar with the basic concepts of cryptography and Public Key Infrastructure (PKI).

This guide assumes that you have read the Hardware Installation Guide and that you have installed your nShield or payShield module.

Contents of this guide

Chapter 1: Introduction, this chapter, describes the purpose and intended audience of this guide.

Chapter 2: nCipher security worlds describes the concept of security worlds.

Chapter 3: Getting the module working describes the steps involved in getting the module working.

Chapter 4: Changing the module state describes how to change the state of the module.

Chapter 5: Uninstalling describes how to uninstall nCipher software.

Chapter 6: Configuring the hardserver describes how to configure the hardserver software, which controls communication between applications and nCipher modules.

Chapter 7: Using multiple modules describes how to install additional modules on a system where at least one module and the server software have already been installed.

Chapter 8: Feature Enabling nCipher Modules describes how to order and enable new features purchased from nCipher.


1 Introduction Contents of this guide

Chapter 9: Using CodeSafe Applications describes CodeSafe applications.

Chapter 10: Using KeySafe introduces KeySafe, nCipher’s security world management tool.

Chapter 11: Managing security worlds contains detailed information about working with security worlds, including adding a module to an existing security world.

Chapter 12: About payShield installations describes how to configure a payShield installation.

Chapter 13: Remote Operator Card Sets describes the use of Remote Operator card sets.

Chapter 14: Administration tasks with cards and softcards describes how to perform card-management tasks that require an Administrator Card Set.

Chapter 15: nShield Administrator Utilities describes the utilities that are used in this manual.

Appendix B: Components on nCipher CD-ROMs lists the contents of the standard bundles and the additional software supplied on your nCipher CD-ROM.

Appendix A: Upgrading module firmware describes how to upgrade your nCipher module if nCipher has supplied updated firmware.

Appendix E: Installed Utilities lists all the utilities installed with the nCipher software.

Appendix F: The nCipher SNMP monitoring agent describes how to use the supplied Simple Network Management Protocol (SNMP) agent with your nCipher module.


1 Introduction Conventions

Conventions

nCipher modules

The following terms are used to distinguish different module versions:

In this table, n is any integer.

Term Model number Used for

nCipher PCI module nCnnnnP-nnn Any nCipher module with a PCI interface.

nCipher nToken module nC2022p-000 or nC2023p-000

an nCipher nToken module (PCI interface).

nCipher netHSM module nHnnnn Any nCipher netHSM module (netHSM 300/800/1600, payShield net, or payShield Ultra net).

acceleration-only module nC10nnX-nnn Any nCipher module that does not support key management (nFast module).

key-management module nC30nnX-nnn,nC40nnX-nnn, ornHnnnn

Any nCipher module that supports key management (nForce, nShield, payShield, netHSM 300/800/1600, payShield net, or payShield Ultra net).

OEM PCI 1600 key-management module

nC3033P-1600 The OEM PCI 1600 modules are supplied to OEM customers only.



Version numbers

The version number shown on the copyright page and at the bottom of each page in this guide is the version number of this document. Please quote this version number if you contact Support at nCipher with queries about nCipher documentation.

nCipher software

The hardserver software controls communication between applications and nCipher modules, which may be installed locally or remotely. It runs as a service on the host computer.

The nCipher support software is a collection of programs and utilities, including the hardserver, supplied by nCipher to install and maintain your nCipher security system.

Default directory

By default, nCipher software is installed in the /opt/nfast/ (Unix) or C:\nfast (Windows) directory, referred to as the nCipher directory. Instructions in this guide are given on the assumption that nCipher software was installed in this location. If you install the software in another directory, you must set the environment variable NFAST_HOME to point to the directory where the software is installed. You can choose to install nCipher software in another location, in which case you must substitute your location accordingly. An environment variable, NFAST_HOME, is used to specify the default location for nCipher software. For further information on setting environment variables, refer to Setting the environment variables on page 49.



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

EnterCtrl C


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:

Further information

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

Guide PDF file

Hardware Installation Guide, for information on hardware installation and troubleshooting; a printed copy is also supplied with nCipher modules (part number N-001027).

Hardware_Installation.pdf

nShield/payShield Operator Guide, for information on managing keys and other tasks with an nShield/payShield module that do not require an Administrator Card.

nShield_Operator.pdf

CodeSafe/C Developer’s Guide, for reference material about developing in C for the Secure Execution Environment.

CodeSafe_C_Developer.pdf

Integration Guide, for information on developing applications with an nCipher module using industry standard interfaces.

Integration_Guide.pdf

nCore Developer’s Guide, for information on developing applications with an nCipher module using the nCipher API and NFKM library.

nCore_Developer_Guide.pdf

nCore Developer’s Reference, for reference material covering nCipher API, C generic stub, and NFKM libraries.

nCore_Developer_Ref.pdf

payShield Developer Reference, for payShield developer reference material

payShield_Developer_Ref.pdf

Key-loading Solution Guide, for information about nCipher’s key-loading solution.

Key-loading_Solution.pdf


1 Introduction Further information

The Java Generic Stub classes, nCipher KM JCA/JCE provider classes, and Java Key Management classes are supplied with HTML documentation in standard Javadoc format, which is installed in the appropriate nfast/java directory when you install these classes.

nCipher also supplies a performance tool that you can use to test Web server performance both with and without an nCipher module in order to confirm performance. This tool is supplied separately. If you require a copy, contact your nCipher sales representative.

All nCipher product documentation, including a range of guides that describe how to configure popular third-party applications, is available from the nCipher web site: http://active.ncipher.com/documentation/.

If you would like to receive security advisories from nCipher, please subscribe to the low volume nCipher security-announce mailing list. To do this, send a mail with the single word subscribe in the message body to [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].

http://active.ncipher.com/documentation/

mailto:[email protected]



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


2 nCipher security worlds nCipher security worlds

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

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

• some cryptographic key and certificate data that is encrypted using the security world key and stored on a host computer or computers.

Figure 1 shows how these components are related to one another. Cards, keys, and even modules can be added or removed at any time. These elements are linked by the security world key, which is unique to each world.

Distributing the keys used for different tasks within the security world over different storage media means that a security world can recover from the loss of any one element. It also increases the difficulties faced by an attacker, who needs to obtain all the elements before gaining any information.


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.



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.



Security worlds and Remote Operator

The Remote Operator feature makes it possible for the contents of a smart card inserted into the slot of one module, the attended module, to be securely transmitted and loaded onto another module, the unattended module. Only Operator Cards can be loaded to remote slots in this way. Both the attended module and the unattended module must be in the same security world.

The Remote Operator feature is useful such circumstances as when you need to load a key protected by an Operator Card Set onto a machine to which you do not have physical access (for example, because it is in secure area).

Secure communication channels between the attended and unattended modules are achieved using an impath (an abbreviation of intermodule path), which is the secure protocol that nCipher modules use for communication over IP networks. An impath is a cryptographically secure channel between two nCipher nC-series hardware security modules. Data sent through such a channel is secure against both eavesdroppers and active adversaries. The channel can carry arbitrary user data as well as module-protected secrets, such as share data, to be passed directly between modules.

Security worlds shared with netHSM modules

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



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

http://csrc.nist.gov/cryptval/140-2.htm


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


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.


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



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



working card fails, retrieve the spare card from the safe and use it until you re-create a new set of two cards, as described in Replacing an Operator Card Set or recovering keys to softcards on page 32.

Note You can only recover card sets that were created with the recovery option explicitly set.

Using pass phrases

Each Operator Card can be given a pass phrase. The pass phrases are independent. You can choose to give only some cards in a card set pass phrases.

You can change the pass phrase on a card at any time. For information on changing pass phrases, see Changing pass phrases with cardpp on page 218 or the appropriate Operator Guide for your module. This requires the card, the existing pass phrase, and a module that belongs to the security world.

Note Some applications do not support the use of pass phrases.

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

Using persistent Operator Card Sets

If you create a standard Operator Card Set, the keys protected by a card can only be used while that card, or the last card loaded in the case of card sets, is in the nCipher 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.

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.

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.


2 nCipher security worlds Robustness

Robustness

If you are using cryptography in a production environment, you need to know that it will work 24 hours a day, 7 days a week. If something goes wrong, you must be able to recover without compromising your security. An nCipher security world offers all of these features.

Backup and recovery

The nCipher security world data stored on the host is encrypted using your choice of either Triple DES or AES encryption.

You should regularly back up the data stored in the kmdata directory safely with your normal backup procedures.

It would not matter if an attacker were to obtain this data because it is worthless without the encryption keys, stored in your module, and the Administrator cards for that security world.

When you create a security world, it automatically creates recovery data for the security world key. As with all host data, this is encrypted with Triple DES. The cryptographic keys that protect this data are stored on a set of smart cards called the Administrator Card Set. The keys are split among the cards in the Administrator Card Set using the same K-of-N mechanism as for an Operator Card Set. The Administrator Card Set protects several keys that are used for different operations.

The cards in the Administrator Card Set are only used for recovery operations and adding extra modules to a security world. At all other times, these cards should be stored in a safe.

Note In strict FIPS 140-2 Level 3 security worlds, the Administrator Card Set or an Operator Card Set is needed to control many operations, including the creation of keys and Operator Card Sets.



Replacing a module

If you have a problem with a module, you can replace it with a new module by using the Administrator Card Set and the recovery data to load the security world key securely. Use the same mechanism to reload the security world key if you need to upgrade the firmware in the module or if you need to add extra modules to the security world.

Replacing the Administrator Card Set

If you lose one of the smart cards from the Administrator Card Set, or if the card fails, you must immediately create a replacement set using the KeySafe Replace Administrator Card Set option or the racs utility. The module does not store recovery data for the Administrator Card Set. It relies on the fact that K is less than N; therefore, it can re-create all the keys on the module even if the information from one of the cards is missing.

You cannot replace the Administrator Card Set unless you have the required number of current cards and access to their pass phrases. Therefore, as soon as you lose one card, or as soon as one card fails, you should replace the set.

Although replacing the Administrator Card Set deletes the copy of the recovery data on your host, the old Administrator Card Set can still be used with the old host data, which may be on backup tapes and other hosts. To protect against this risk, you must immediately erase the old Administrator Cards after you create a new Administrator Card Set.

Replacing an Operator Card Set or recovering keys to softcards

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



Similarly, you can recover keys protected by one softcard to another softcard.

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

Note Keys protected by an Operator Card Set can only be recovered to another Operator Card Set, and not to a softcard. Likewise, 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.


2 nCipher security worlds Scalability

Similarly, if you choose to create recovery data when you generate the security world or key, it cannot be removed later in a secure manner.

The recovery data for application keys is kept separate from the recovery data for the security world key. The security world always creates recovery data for the security world key. It is only the recovery of application keys that is optional.

Scalability

A security world is scalable. You can add multiple modules to a server and share a security world across multiple servers. You can also add Operator Card Sets and application keys at any time. You do not need to make any decisions about the size of the security world when you create it.

To share a security world across multiple servers:

• ensure each server has at least one module fitted

• copy the host data to each server or make it available on a shared disk

• use the recovery data and the Administrator Card Set to load the required cryptographic keys securely onto every module.

If you want to have access to the same keys on every server, you must ensure that all changes to the data are propagated to the remaining servers. If your are part of a cluster, then the tools provided by the cluster should synchronize the data. If the servers are connected by a network, then they could all access the same copy of the data. There is no risk of an attacker obtaining information by snooping on the network, as the data is only ever decrypted inside a module. Alternatively, you can maintain copies of the data on different servers.

It is now possible to allow non-netHSM modules to automatically access the remote file system (RFS) used by netHSM and payShield NET modules and to share security world and key data stored in the


2 nCipher security worlds KeySafe and security worlds

kmdata directory. Client modules that access data in this way are described as cooperating clients. See Setting up client cooperation on page 53 for more information.

Load sharing

If you have more than one module on your system and you load the same key onto each module, your nCipher-aware applications can make use of the load sharing features in the nCipher server to share the cryptography between them.

Note It is up to the application to implement load sharing. Some applications may not be able to make use of this feature.

KeySafe and security worlds

KeySafe provides an intuitive and easy-to-use graphical interface for managing security worlds. KeySafe manages the security world and the keys protected by it. See the Operator Guide for full information about KeySafe.

Note Most applications store only their long-term keys in the security world. Session keys are short term keys generated by the application which are not normally loaded into the security world.

Although you use KeySafe to generate keys, it is your chosen application that actually uses them. You do not need KeySafe to make use of the keys that are protected by the security world. For example, if you share a security world across several host computers, you do not need to install KeySafe on every computer. If you want to manage the security world from a single computer, you can install KeySafe on just that one computer even though you are using the security world data on other machines.

KeySafe enables you to:


2 nCipher security worlds KeySafe and security worlds

• 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

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


2 nCipher security worlds Applications and the security world

Applications and the security world

The security world can protect keys for a range of industry standard applications. See the nCipher web site (http://www.ncipher.com) for details of applications that are currently supported.

nCipher has produced Application Guides for many supported applications. These Application Guides contain information about installing and configuring the application to work with nCipher modules and security worlds.

For information on the range of Application Guides available, either visit the nCipher web site (http://www.ncipher.com) or contact Support at nCipher ([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.

http://www.ncipher.com




2 nCipher security worlds Risks

Risks

Even the best-designed tools cannot offer security against every risk. Although a security world can control which user has access to which keys, it cannot prevent a user from using a key fraudulently. For example, a security world can only determine whether a user is authorized to use a particular key; it cannot determine whether the message being sent with that key is accurate.

A security world can only manage keys that were created inside the security world; keys created outside a security world, even if imported into the security world, may remain exposed to a security risk.

Most failures of security systems are not the result of inherent flaws in the system, but result from carelessness on the part of the users. The following basic rules apply to any security system:

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


Chapter 3: Getting the module working

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

1. Determine the requirements for the module, as described in Determining module requirements on page 39.

2. Complete any prerequisites to installing nCipher support software, as described in Prerequisites to software installation on page 40.

3. Install the software, as described in Software installation procedure on page 43.

4. Perform post-installation tests and software environment configurations, as described in After software installation on page 46.

5. Configure the hardserver, as described in Configuring the hardserver on page 51. Also, if necessary, set up client configuration, as described in Setting up client cooperation on page 53

6. Create and configure the security world, as described in Creating and configuring a security world on page 56.

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

8. Create the Operator Card Set, as described in Creating the Operator Card Set on page 71.

Determining module requirements

Before you start to set up the module, you must identify the specific requirements of your installation. You (or your security policy officer) should have determined the following:


3 Getting the module working Prerequisites to software installation

• which optional components of the nCipher software you need to install. To do this you need to know:

- the applications that are to use the module.

- any constraints on installing software on your computer.

• the security requirements for the security world (see Determining module requirements on page 39 for details of these options).

• if you want to use payShield, the requirements for the payShield installation, including the functions to be enabled (see About payShield Card Sets on page 187 for details of these options).

Do not start the installation procedure until you have this information.

Prerequisites to software installation

This section describes various steps you may need to take before installing the nCipher support software. These are:

• Installing and connecting the module on page 40

• Removing existing installations on page 41

• Installing Java patches on page 41

• Identifying which components to install on page 42.

Installing and connecting the module

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



Removing existing installations

nCipher recommends that you uninstall older versions of support software before you install new support software. If the installer detects an existing nCipher installation, it asks you if you want to install the new components. These components replace your existing installation.

Instructions for uninstalling nCipher support software are provided in Chapter 5: Uninstalling.

The automated nCipher installers do not delete other components or any key data and security world data that you have created.

Note Because the nCipher server is installed as a service, it is only possible to have one nCipher installation on any given computer.

Installing Java patches

nCipher currently supports JRE/JDK version 1.4.x.

If you intend to use KeySafe, Sun’s Java run-time environment version 1.4.x or the equivalent developer kit must be installed. It is recommended that you install Java before you install the nCipher components. The Java executable must be on your path.

The DSE200’s Web-based interface requires JRE/JDK version 1.3.x, which is installed with the DSE200 support software.

Java software is available from http://java.sun.com/products/. If your security policy does not allow the use of downloaded software, these components can be obtained on CD-ROM from Sun or your operating system vendor.

In order to use nCipher Java components, you may need to install patches supplied by your operating system manufacturer. Refer to the Sun documentation supplied with your Java installation.

http://java.sun.com/products/



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

Identifying which components to install

nCipher supplies standard component bundles that contain many of the necessary components for your installation and, in addition, individual components for use with supported applications. To be sure that all component dependencies are satisfied, you can install all the software components supplied, or you can choose to install only those you need.

During the installation process, you are asked to choose which bundles and components to install. Your choice depends on a number of considerations, among them the following:

• the types of application that will be using the module

• the amount of disk space available for the installation

• your company’s policy on installing software. For example, although it may be simpler to choose all software components, your company might have a policy of not installing any software that is not required.

You must install the hwsp Hardware Support bundle. If the hwsp Hardware Support bundle is not installed, your module cannot function.

Note The nfdrv Windows device drivers component, required if you are using an nCipher PCI card, is installed as part of the hwsp Hardware Support bundle.


3 Getting the module working Software installation procedure

Additionally, nCipher recommends that you always install the ctls Core Tools bundle, which contains all the nCipher command-line utilities, including generatekey, low level utilities, and test programs.

Note The Core Tools bundle includes the tclsrc Tcl run time component that installs a run-time Tcl installation within the nCipher directories. This is used by nCipher’s tools for creating the security world, by KeySafe, and by the new-world utility. This does not affect any other installation of Tcl on your computer.

See Appendix B: Components on nCipher CD-ROMs for details of the optional components. Ensure that you have identified those that you require before you start the installation.

Software installation procedure

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

Note Because the nCipher server is installed as a service, it is only possible to have one nCipher installation on any given computer.

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

Note Visit the nCipher Web site support section to download Application Guides that give advice on installing nCipher modules with a range of third party applications.



nCipher supplies Windows 2000 Plug and Play drivers for the nCipher module. These drivers have also been tested with Windows 2003 Server.

Take the following steps to install the nCipher server and associated software:

1. Log in as Administrator or as a user with local administrator rights.

2. Place the CD-ROM in the CD-ROM drive. If Autorun is enabled, the installer runs automatically, detecting the version of Windows and launching the appropriate installation program. You can launch the installer (setup.exe, on the top level of the CD-ROM) manually if Autorun is not enabled.

The installer displays the version number of the nCipher support software that is to be installed.

Note If you have an earlier installation of nCipher support software, the installer detects this and gives you the option to uninstall the earlier installation or quit the installer. The installer cannot install the current release of nCipher support software unless any earlier installation has been uninstalled. Uninstalling requires a reboot before a new installation of the current software can commence.

Follow the onscreen instructions.

3. The installer displays the nCipher license agreement. Accept the license terms by clicking the Yes button for the installation to continue.

4. The installer displays a list of installable components. You must install the hwsp Hardware Support bundle, and nCipher strongly recommends installing the ctls Core Tools bundle. Otherwise, choose to install all components, or select the components that



you require. See Appendix B: Components on nCipher CD-ROMs for more information about choosing which components to install.

By default, the installer places files in the C:\nfast directory, but you are given the option of selecting a different directory. If the installer detects an existing installation in a different directory, it offers this other directory as the default.

5. Click the Next button, and the installer installs and performs basic configuration of the selected components.

Note If the installer detects an existing installation of the current release of support software, it advises you of this. Click the Yes button to continue.

6. The installer advises you that it will create an icon on your desktop for the nCipher CSP installation wizard.

Note Do not run the nCipher CSP installation wizard before you have successfully installed the module.

When run, this wizard:

a. installs the correct nCipher CSP

b. makes the nCipher CSP the default SChannel provider, if requested.

After you have completed the rest of the module installation process, double click the nCipher CSP installation wizard icon to install the nCipher CSP.

Note You must install this version of the nCipher CSP to work with this version of the nCipher software, even if you have a previous version of the nCipher CSP installed.

For more information on using the nCipher CSP with IIS (Internet Information Service) and Microsoft Certificate Server, see the appropriate Operator Guide for your module and the relevant application guide.

Click the Next button to continue the installation.


3 Getting the module working After software installation

7. If you chose to install the nCipher SNMP agent, the installer advises you that it does not run by default. Click the Next button to continue.

8. If you chose to install the nCipher PKCS #11 library and have an existing PKCS #11 installation, the installer advises you of this. The installer asks whether you want to configure the PKCS #11 library for use with Check Point VPN-1/Firewall-1. You can choose to do one of the following:

a. Select Yes, and then follow the steps in the Check Point configuration dialog. See Check Point’s product documentation for further information.

b. Select No to continue the installation process without configuring Check Point VPN-1/Firewall-1. You can configure the PKCS #11 library for use with Check Point VPN 1/Firewall 1 later by running the ConfigPKCS11onCP.exe utility in the C:\nfast\toolkits\\pkcs11 directory.

Note If you choose to configure the PKCS #11 library for use with Check Point VPN-1/Firewall-1, install the PKCS #11 module only after Check Point VPN-1/Firewall-1 is installed.

9. When the installation is complete, click the Finish button.

After you have installed the software, perform post-installation tests and software environment configurations as described in After software installation on page 46.

After software installation

Testing the installation

To check that the software has been installed correctly:

1. Log in as a normal user.

2. Open a command window.



3. Verify that the server is running by using the following test command (assuming that you installed the nCipher server in the default directory):

C:\nfast\bin\enquiry

A successfully completed enquiry command returns output of a form similar to the following:

server:

enquiry reply flags none

enquiry reply level Four

serial number ####-####-####

mode operational

version #.#.#

speed index ###

rec. queue ##..##

...

module #1:

...

mode operational

version #.#.#

...

connection status OK

The enquiry utility returns information on the nCipher server and on each module.

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

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

- The version number for the module is the nCipher internal release number of the firmware.

If the enquiry utility returns an error message, refer to the troubleshooting chapter in the Hardware Installation Guide.



Testing the smart card reader

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

Note The LED is triggered by a mechanical switch that indicates only that the card is inserted. It does not indicate that the card is a valid smart card or that it is the correct way up.

The LED flashes briefly when you reset the module and when the module changes state.

Note Always insert the smart card with the contacts facing up.

You can check that the card reader of any module is working correctly by inserting an nCipher smart card and using the following test command (assuming that you installed the server in the default directory):

C:\nfast\bin slotinfo -m MODULE [-s SLOT]

In this command, MODULE is the number of the module and SLOT is the number of the slot. If you have only one module, MODULE is 1, and if you do not specify a slot number, slotinfo returns information about all slots.

This command should return either:

Module n slot 0:

Token not formatted



or

Module n slot 0:

Authentication key: 00000000-00000000-00000000-00000000-00000000

No data on token

3698 bytes free

Note The authentication key and data size may vary.

Monitoring the module using Performance Monitor

You can monitor the performance of the nCipher modules that are connected to a Windows host by using Microsoft’s Performance Monitor.

When you install the nCipher server software it adds three new objects to the Performance Monitor:

nCipher Connections

This provides statistics for each connection to the server with an instance for each connection.

nCipher PerModule

This provides statistics for each nCipher module with an instance for each module, identified by ModuleID.

nCipher ServerGlobals

This provides statistics for the nCipher server.

Note To preserve security, connection instances are identified by a number. This number is a simple counter and is not related to the ClientID .

Setting the environment variables

You can set nCipher specific environment variables as follows:

1. Open the System dialog box by clicking the System icon in the Control Panel.



2. Select the Advanced tab and click the Environment Variables button.

3. To add a variable, click New. Alternatively, to edit an existing variable select an entry in the System Variables list and click Edit.

4. In the Variable Name text box, type or edit the name of the environment variable (for example, NFAST_HOME).

5. In the Variable Value text box, type or edit the value to use.

6. Click the OK button to set the value, and then click the OK button to close the dialog box.

7. Restart the nFast Server service.

See Appendix C: Environment variables for detailed information on the environment variables used by nCipher software.

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

Logging and debugging

Note The current release of nCipher support software uses controls for logging and log files, as well as debugging, that differ from those used in previous releases. However, settings you made in previous releases to control logging, log files, and debugging are still generally supported in the current release, although in some situations the output is now formatted differently.

The nCipher Support Software generates logging information that is configured through a set of four environment variables:

• NFLOG_FILE


3 Getting the module working Configuring the module

• NFLOG_SEVERITY

• NFLOG_DETAIL

• NFLOG_CATEGORIES

Note If none of these logging environment variables are set, the default behaviour is to log nothing, unless this is overridden by any individual library. If any of the four logging variables are set, all unset variables are given default values.

Some components of the nCipher Support Software generate separate debugging information which you can manage differently. If you are setting up the module in order to develop software that uses it, you should configure debugging at this point. Otherwise, you should proceed to Creating and configuring a security world on page 56.

Detailed information about controlling logging information by means of these environment variables is supplied in Appendix D: Logging and debugging.

Configuring Java support for KeySafe

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

Configuring the module

Configuring the hardserver

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



The hardserver can handle transactions for multiple modules. This does not require configuration of the hardserver; see Chapter 7: Using multiple modules for information.

The hardserver must be configured to control:

• the way the hardserver communicates with remote modules

• the way the hardserver communicates with local modules

• the import and export of remote slots

• the loading of SEE machines on to the module when the hardserver starts up.

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

Note In some previous releases of nCipher support software, hardserver configuration was controlled by environment variables. The use of these variables has been deprecated. If any of these environment variables are still set, they override the settings in the configuration file.

You must load the configuration file for the changes to the configuration to take effect.

To configure the hardserver, follow these steps:

1. Save a copy of the configuration file C:\nfast\kmdata\config\config so that the configuration can be restored if necessary.

2. Edit the configuration file C:\nfast\kmdata\config\config to contain the required configuration. (See Hardserver configuration file on page 85 for descriptions of the options in the configuration file.)



3. Run the cfg-reread command-line utility to load the new configuration. See cfg-reread on page 228 for details.

4. Test that the hardserver is configured correctly by running the enquiry command-line utility. (See enquiry on page 229 for full details of the enquiry command-line utility and its output.)

Check that a module with the correct characteristics appears in the output.

5. Test that the client has access to the security world data. To do this, run the nfkminfo command-line utility.

Check that a module with the correct ESN appears in the output and has the state 0x2 Usable.

Setting up client cooperation

It is now possible to allow non-netHSM modules to automatically access the remote file system (RFS) used by netHSM and payShield NET modules and to share security world and key data stored in the kmdata directory. Client modules that access data in this way are described as cooperating clients.

To configure client cooperation for modules that are not netHSM or payShield modules, complete the following steps:

1. Configure the remote file system used by your netHSM module to accept access by cooperating clients. For information about how to do this see the netHSM Administrator Guide.

2. On each client that is to be a cooperating client (that is, that is to access the remote file system in order to share key data), you must run the rfs-sync command with appropriate options:



- For clients that use a local KNETI (the nCipher integrity key, which is installed when the module is shipped) for authorization and which are to be given write access to the remote file system, run the command:

rfs-sync --setup rfs.rfs.rfs.rfs

- For clients that do not have a local KNETI and require write access, run the command:

rfs-sync --setup --no-authenticate rfs.rfs.rfs.rfs

In these commands, rfs.rfs.rfs.rfs is the IP address of the machine where the remote file system is located.

Note The rfs-sync utility uses lock files to ensure that updates are made in a consistent fashion. If a rfs-sync --commit operation (the operation that writes data to the remote file system) fails due to a crash or other problem, it is possible for a lock file to be left behind. This would cause all subsequent operations to fail with a lock timeout error.rfs-sync has options for querying the current state of the lock file, and for deleting the lock file; however, these should only be used if necessary to resolve this problem. Clients without write access cannot delete the lock file.

To remove a cooperating client so the remote file system no longer recognizes it, you must:

• know the IP address of cooperating client you want to remove



• manually update the remote_file_system section of the hardserver configuration file by removing the following entries for that particular client:

remote_ip=ccc.ccc.ccc.cccremote_esn=

keyhash=0000000000000000000000000000000000000000

native_path=c:\nfast\kmdata\local

volume=kmdata-local

allow_read=yes

allow_write=yes

allow_list=yes

is_directory=yes

is_text=no

and

remote_ip=ccc.ccc.ccc.cccremote_esn=

keyhash=0000000000000000000000000000000000000000

native_path=c:\nfast\kmdata\localsync-store

volume=kmdata-backup

allow_read=yes

allow_write=yes

allow_list=yes

is_directory=yes

is_text=no

In these commands, ccc.ccc.ccc.ccc is the IP address of the client.

Useful utilities

To find out the ESN and the hash of the KNETI key for a given IP address, use the anonkneti command-line utility. A manual double-check is recommended for security.

A client can use rfs-sync --show to display the current configuration, or rfs-sync --remove to revert to a stand-alone configuration. Reverting to a stand-alone configuration leaves the current contents of the kmdata directory in place. See rfs-sync on page 304 for more information.


3 Getting the module working Creating and configuring a security world

Creating and configuring a security world

Before you can use the module to manage keys, you must create a security world. A security world can only be created with a single module. If you have more than one module, you must choose one with which to create the new security world. You can add additional modules to an existing security world later (as described in Adding or restoring a module to the security world on page 155).

Before you start to create a security world:

• The modules that you wish to add to the security world must be in pre-initialization state, as described in Entering the pre-initialization state on page 78.

• You must be logged in to the host computer as a user who is permitted to create privileged connections. See hardserver on page 242.

You must have set the NFAST_HOME environment variable.

• You should know what the security policy for the module is, and in particular the number and quorum of administrator and operator cards to be used.

• You must have enough smart cards to form the security world’s card sets.

On some internal modules, you must access the initialization link or switch on the module. With such modules, always shut down your computer and turn off the power before opening the case. Replace the case before reconnecting the power.

You normally create a security world when you first install the module. If you wish use the module to protect a different set of keys, you can replace the security world with another one.

The process of creating a security world:

• erases the module

• creates a new module key for this security world

• creates a new Administrator Card Set to protect this module key



• stores the security world information on the computer’s hard disk, or in the case of netHSM, the operating system’s filesystem and the remote filesystem. The information is encrypted using the secrets stored on the Administrator Card Set.

Any Operator Cards created in a previous security world cannot be used in the new security world. If you are replacing a security world, you must erase all the Operator Cards created in the previous security world before you create the new world.

You can create a security world from the command line with the new-world utility, as described here. Alternatively, you can use KeySafe (as described in Creating a security world with KeySafe on page 131), or the nCipher CSP wizard, as described in Creating the security world using the CSP wizard on page 139.

Creating a security world by using new-world

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

Running the new-world command-line utility

Open a command window and type the command:

new-world [-i|--initialize] [-S|--no-remoteshare-cert] [-o|--overwrite] [-F|--strict-

fips-140-2-level-3] [-R|--no-recovery] [-tTIMEOUT|--nso-timeout=TIMEOUT] [-m|--

module=MODULE] [-Q|--acs-quorum=K/N] [FEATURES]

In this command:



-i, --initialize

These options tell new-world to initialize a new security world, replacing any existing kmdata directory.

Note Replacing an existing security world in this way does not delete the security world’s host and recovery data, but renames the existing kmdata directory in which these reside as kmdata_nn (where nn is an integer, 0 or greater, depending on how many security worlds have been previously saved during overwrites).

-S, --no-remoteshare-cert

These options tell new-world to not to make the module a target for remote shares.

-o, --overwrite

These options tell new-world to overwrite smart cards without prompting. Any existing data will be erased. If a value for this flag is not specified, new-world will prompt you if a card contains data. This option does not enable you to reuse Operator Cards from other security worlds.

-F, --strict-fips-140-2-level-3

These options tell new-world to create a security world that conforms to the FIPS 140-2 requirements for roles and services at level 3. If you do not specify this flag, new-world creates a security world that complies with FIPS 140-2 requirements for level 2.

Note This option provides compliance with the roles and services of the FIPS 140-2 level 3 standard. It is included for those customers who have a regulatory requirement for compliance.

-R, --no-recovery

These options tell new-world to disable Operator Card Set recovery. The effect of setting this flag is the same as for specifying the feature !r.



By default, new-world creates key-recovery material that is protected by the cryptographic keys on the Administrator Card Set. This option does not give nCipher or any other third party access to your keys. Keys can only be recovered by using the Administrator Cards. nCipher recommends that you leave Operator Card Set recovery enabled.

If you set the --no-recovery option, you will not be able to replace lost or damaged Operator Card Sets and therefore will not be able to access the keys that are protected by such cards. Key recovery cannot be enabled later without reinitializing your security world and discarding all your existing keys.

Note All keys are recoverable unless otherwise specified at key generation, even PKCS #11 keys that have the sensitive flag set to TRUE or extractable flag set to FALSE.

-tTIMEOUT, --nso-timeout=TIMEOUT

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

-m, --module=MODULE

These options specify the ModuleID to use. new-world initializes only one module at a time. If you have multiple modules, you must run new-world with --initialize for the first module, and then run new-world with --program for the other modules; see new-world on page 259.

-Q, --acs-quorum=K/N

In these options, K specifies the minimum number of smart cards needed from the Administrator Card Set in order to authorize a feature. You can specify lower K values for a particular feature. All the K values must be less than or equal



to the total number of cards in the set. If a value for K is not specified, new-world creates an Administrator Card Set that requires a single card for authorization.

Note Some applications do not have mechanisms for requesting that cards be inserted. Therefore any Operator Card Sets that you create for use with these applications must have K=1.

Note If you are creating an Administrator Card Set for a payShield installation, K must be greater than 1. N must therefore be greater than 2.

N specifies the total number of smart cards to be used in the Administrator Card Set. This value must be less than or equal to 64. If a value for this option is not specified, new-world creates an Administrator Card Set that contains a single card.

Note You should not create an Administrator Card Set for which the required number of cards is equal to the total number of cards because you will not be able to replace the Administrator Card Set if even a single card is lost or damaged.

This option only takes effect if you are creating a new security world.

new-world command-line utility features

Security world features can be specified on the command line.



You can specify multiple features as a comma-separated list of terms. Each term consists of a feature name, optionally preceded by either a dash (-) or an exclamation point (!) to turn off the feature and can optionally be followed by an equals sign (=) and the threshold for this feature.

Note The ! character is interpreted by some shells as history expansion and must be escaped with a backslash, \\!. The dash may be interpreted as being the start of an command-line option unless you have used the -f option or specified a module without including the -m flag.

Note If you set the !fto flag, that is, turn off FTO, you will not be able to use smart cards to import keys even if you set the --allow-smartcard-imports option in the payshield-install utility.

Note If you want to use extended debugging from the module, you must set the dseeall flag.

The following feature names are available:

m

This feature specifies module programming (and cannot be disabled).

r

This feature specifies Operator Card Set recovery (see Replacing an Operator Card Set or recovering keys to softcards on page 32).

p

This feature specifies PIN recovery. For information on changing pass phrases, see Changing pass phrases with cardpp on page 218 or the appropriate Operator Guide for your module.

nv

This feature specifies that the Administrator Card Set is needed to enable non-volatile memory allocation.



rtc

This feature specifies that the Administrator Card Set is needed to enable real-time clock setting (see Real-time clock (RTC) options on page 128).

dsee

This feature specifies that the Administrator Card Set is needed to enable SEE World debugging.

dseeall

This feature specifies that SEE World debugging is enabled for all users, without certificates.

fto

This feature specifies that the Administrator Card Set is needed to enable foreign token operations.

If the threshold of a feature is set to 0, it may still be available using the standard Administrator Card Set quorum.

The pass phrase recovery (p) and dseeall features are turned off by default; the other options are turned on by default.

Note The non-volatile memory and SEE world debugging options are relevant only if you are using the Secure Execution Engine. If you have bought the CodeSafe Developer Kit, refer to the CodeSafe Developer Guide for more information.

Note If you want to use extended debugging from the module, you must set the dseeall flag.

The dseeall option is designed for testing purposes only. Do not enable this feature on production security worlds as it may enable SEE applications to leak security information.



For example, the following features:

m=1,r,!p, nv2, rtc1

create a security world for which:

• a single card from the Administrator Card Set is required to add a new module

• the default number is required to replace an Operator Card Set

• pass phrase recovery is not enabled

• two cards are required to allocate nonvolatile memory

• one card is required to set the real-time clock (applies to SEE only).

new-world command-line utility output

If new-world cannot interpret the command line, it displays its usage message and exits.

If you attempt to set a threshold for a feature that you have disabled or if you attempt to set a threshold too high, new-world displays an error and exits.

If the module is not in the pre-initialization state, new-world displays and error and exits. See Entering the pre-maintenance state on page 76

new-world may give the following reasons why the module is not ready for programming:

• Initialization link not fitted

Internal PCI modules

In this case, move the mode switch to the initialization position, and run the command again.

External modules

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


3 Getting the module working Creating and configuring a payShield installation

• Maintenance link fitted


In this case, move the mode switch to the initialization position, and run the command again.

External modules

In this case, remove the maintenance link, fit the initialization link, and run the command again.

If the module is in the pre-initialization state, new-world prompts you for smart cards and pass phrases as required.

When new-world has initialized the module, restart the module in the operational state, as described in Entering the operational state on page 79.

Creating and configuring a payShield installation

If you have a payShield net module, you must configure a payShield installation as an environment for its payments functionality and enable the features required for payments functionality.

The SEE activation feature, the payShield feature, and the payShield acceleration feature must be enabled as described in Chapter 8: Feature Enabling nCipher Modules before you can configure a payShield installation. If the payShield feature is configured, the CodeSafe feature is not available.

Before you start to configure a payShield installation:

• You must have created a security world that has the following options:

- key recovery enabled.

- use of an FTO Delegate key with a required number of cards (and not with KNSO).



- the number of cards required for the Administrator Card Set set to a value greater than 1.

See About payShield Card Sets on page 187 for important advice about the choice of a value for K.

- the SEE debugging for all option enabled, if you wish to make use of the extended payShield module debugging option. (You must have configured the security world’s card requirements separately to enable this option.)

This option is designed for testing purposes only. Do not enable it on production security worlds as it may enable SEE applications to leak security information.

• You must know what the security policy and the associated card sets for the payShield installation are. If this is not already decided, see About payShield Card Sets on page 187.


• You must know which payShield functions are required.

Creating the payShield installation from the command line

This procedure involves Administrator cards, the payShield Master Card Set and the Key Establishment Card Set. It must be performed on a trusted host. See About payShield Card Sets on page 187 for full details of the card sets created during this procedure.

You must be logged in as a user who is permitted to create privileged connections. See hardserver on page 242 for more information.

The payshield-install utility creates a payShield installation in the current security world. It fixes the installation’s operating properties and creates both the Master Card Set and the Key Establishment Card Set. It is extremely important that you choose the settings carefully since you cannot change the properties of a payShield installation after you have created it.



See payshield-install on page 283 for full details of the payshield-install utility.

To run the payshield-install utility, type the following command, specifying the options required for your installation:

payshield-install [options] psiname keyhash

In this command:

psiname

This is the name of the payShield installation to be created.

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

keyhash

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

25d0dfc32e980c7ab8f0fd7647db7fc2252f9851

Do not type a hash that differs from this value unless you are certain that the new hash is from a valid payShield signing key. If you are in any doubt as to the origin of the hash value you have been given, do not create a payShield installation: contact Support at nCipher for confirmation of the correct signing key hash.

As a minimum, specify the following:

payshield-install -S psiname keyhash

If you do not set the -S (--allow-smartcard-imports) option at this point, your payShield installation can never import keys from smart cards, but can only generate new keys.



The payshield-install utility performs or prompts for the following operations in the order specified:

• If you have set the --totally-insecure option, the payshield-install utility issues the following warning:

WARNING: Creating an insecure payShield installation.

You must not set the --totally-insecure option, the -I (--allow-insecureimports) option, or the -D (--allow-insecure-debug) option when creating a live commercial payShield installation. If this warning is displayed, the payShield installation you create is suitable only for testing environments.

No sensitive keys or data should ever be allowed to pass through a payShield installation created with the -I (--allow-insecure-imports) option set.

• The payshield-install utility prompts for a KFTO quorum of security world Administrator cards. This quorum is the K value that you specified for FTO when you created the security world.

The payshield-install utility prompts for a KFTO quorum of security world Administrator Cards. This quorum is the K value that you specified for FTO when you created the security world. The payshield-install install utility loads the security world’s KFTO and displays the following message:

payShield Master Cardset creation ...

It then prompts for new operator cards.



• Following the onscreen prompts, each Master Card Set card holder inserts a blank card and enters a name and pass phrase for this card.

The payshield-install utility displays the following message:

payShield Key Establishment Cardset creation ...

It then prompts for new operator cards.

• Following the onscreen prompts, each Key Establishment Card Set card holder inserts a blank card and enters a name and pass phrase for this card.

The payshield-install utility displays a success message and exits.

A successful operation might have output similar to the following:

payshield-install.exe: no card in module 1 slot 0

Insert an administrator card into module 1 slot 0 and press return...

Passphrase for administrator card 1:

payShield Master key generation ...

payShield Master key generated

Making FTO delegation certificate ...

payShield Master Cardset creation ...

Insert new operator card 1 into module 1 slot 0 and press return...

Passphrase for new operator card 1:

Name for card 1: master

payShield Master Cardset created

payShield Key Establishment key generation ...

payShield Key Establishment key generated

payShield Key Establishment Cardset creation ...

Insert new operator card 1 into module 1 slot 0 and press return...

Passphrase for new operator card 1:

Name for card 1: kec

payShield Key Establishment Cardset created

Successfully created new payShield Installaton psi

In the interests of brevity, the above output transcript shows the creation of 1-of-1 card sets. Such a card set selection is not suitable for a live, commercial payShield installation.



Configuring the payShield installation options

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

Enabling payments functions

When you have configured the payShield installation, you must enable payments functions.

Be very careful when deciding which payments functions are to be enabled. Some functions (particularly the IBM PIN function) can interact negatively with others, causing a reduction in the overall security of the installation. Only enable functions that you will use.

To enable the required payments functions, run the following command on the machine that is designated as the remote file system, and then follow the onscreen instructions:

payshield-config psiname

In this command, psiname is the name that you supplied when you created the payShield installation.

Configuring modules to use payShield

For each module you must create an entry in the load_seemachine section of the hardserver configuration file. Make each entry of the following form:

...

module module

machine_file=c:\nfast\nc-seemachines\payshield\version\emvsmtype1.sar

postload_prog=payshield

postload args=-n psiname [-d]

...



Separate the flags for each module by a dash on its own line, as in the following example:

postload args=-n psiname [-d]

-

module MODULE

In this example:

MODULE

This represents the module number (for example, 1)

version

This represents the payShield SEE machine version and has the format X.Y.Z.camA

psiname

This represents the name of the payShield installation that the hardware security module is to host. This is the same as the psiname passed to SPP_init() in any application that wishes to use the payShield hardware security module.

-d

This flag specifies that the operating SEE World has the dseeall feature set and that the operating payShield installation has the -D option set. Both of these conditions must have been specified at the time of SEE World creation time, and their status can be checked using, respectively, the nfkminfo and payshield-info command-line utilities. If either of these conditions is not satisfied, then specifying -d in postload_args inhibits SEE machine loading.

For further information on the hardserver configuration file, see Chapter 6: Configuring the hardserver.


3 Getting the module working Creating the Operator Card Set

Creating the Operator Card Set

The Operator Card Set provides access to application keys. Operator Card Sets are optional, but if you require one, create it before you start to use the module with applications.

You can create Operator Card Sets with:

• names for individual cards, as well as for the card set

• K-of-N policies

• optional pass phrases for any card within a given set

• formal FIPS 140-2 level 3 compliance.

Some applications do not have a mechanism for requesting that cards are inserted. If you create a card set for one of these applications, you must set K to 1:

You can create an Operator Card Set from the command line with the createocs utility (as described here). Alternatively, you can use KeySafe, or the nCipher CSP wizard. For more information about creating Operator Card Sets, see the Operator Guide appropriate to your module type.

Creating the Operator Card Set from the command line

To create an Operator Card Set:

Application Pass phrase

ISS Not permitted

iPlanet Required

Netscape Certificate Server

Required



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



option. createocs prompts for the names of the cards as they are created. Not all applications can display individual card names.

-p, --persist

These options create a persistent card set.

-P, --no-persist

These options create a non-persistent card set.

-R, --no-pprecovery

These options mean that the pass phrase for this card set cannot be recovered. The pass phrase for the card set is recoverable by default. You can specify this explicitly with --pprecovery.

-q, --remotely-readable

These options allow this card set to be read remotely. For information on configuring Remote Operator Card Sets, see Chapter 13: Remote Operator Card Sets.

-f, --force

These options allow createocs to overwrite smart cards without prompting. If you do not specify the --force option, createocs prompts you if any smart card to be used is not blank. You can only employ --force to reuse Operator Cards from the current security world, or cards containing unknown data. You cannot use the --force option either to force the reuse of Administrator Cards from the current security world without first erasing them or to force the reuse of Operator Cards from other security worlds.

-T, --timeout=TIME

These options set the time-out for the card set. Use the suffix s to specify seconds, m for minutes, h for hours, and d for days. If the timeout is set to 0, the Operator



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.



3. Type a pass phrase and press . Alternatively, press 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 .

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.

Enter Enter

Enter


Chapter 4: Changing the module state

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

Entering the pre-maintenance state

This section describes how to place nCipher modules in the pre-maintenance state. A module must be in the pre-maintenance state before you can perform maintenance tasks like upgrading firmware.

Follow the directions for your particular model of module as described in this section.


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

Figure 3 PCI module back panel

2. Reset the module by pressing the clear button.

Status LED

Clear switch

Mode switch

Smart cardconnector

DC power

MOI

Maintenance


4 Changing the module state Entering the pre-maintenance state

When the self tests are complete, the unit should enter the pre-maintenance state. In this state, the Status LED emits repeated single long flashes. Refer to the table below if the Status LED does not emit repeated single long flashes:

Note If the Status LED remains continuously on or off for more than a minute, it indicates that the self tests have failed terminally. Contact Support at nCipher.

You can use the enquiry command-line utility to check that the module is in the pre-initialization state. See enquiry on page 229 for information about using this utility.

LED State Reason and remedy

Mainly on but regularly blinks off(The exact timing depends on the nCipher module.The longer the LED stays on the less the load. At 100% load the LED is off for as long as it is on.)

Operational The override switch is on. Refer to the installation instructions in the Hardware Installation Guide for information on accessing and setting the override switch to off.

Emits repeated single short flashes

Pre-initialization The mode switch is in the initialization position. Repeat steps 1 to 2, positioning the mode switch in the maintenance position.

Flashes the Morse SOS pattern followed by a code

Error The module has encountered an unrecoverable error. There is a list of these errors and the actions to take in the Hardware Installation Guide.


4 Changing the module state Entering the pre-initialization state

Entering the pre-initialization state

This section describes how to put nCipher modules in the pre-initialization state. You must have at least one module in the pre-initialization state before you can create a security world. A module must be in the pre-initialization state before you can add it to an existing security world.

On some internal modules, you must access the initialization link or switch on the module. With such modules, always shut down your computer and turn off the power before opening the case. Replace the case before reconnecting the power.

Follow the directions for your particular model of module as described in this section.


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



Status LED

Clear switch

Mode switch

Smart cardconnector

DC power

MOI Initialization


4 Changing the module state Entering the operational state

The module performs self tests, during which the Status LED is on.

When the self tests are complete, the unit should enter the pre-initialization state. In this state, the Status LED emits repeated single short flashes. Refer to the table below if the Status LED does not emit repeated single short flashes:

Note If the Status LED remains continuously on for more than a minute, it indicates that the self tests have failed terminally. Contact Support at nCipher.

You can use the enquiry command-line utility to check that the module is in the pre-initialization state. See enquiry on page 229 for information about using this utility.

Entering the operational state

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


Mainly on but regularly blinks off(The exact timing depends on the nCipher module.The longer the LED stays on the less the load. At 100% load the LED is off for as long as it is on.)

Operational The override switch is on. Refer to the installation instructions in the Hardware Installation Guide for information on accessing and setting the override switch to off.

Emits repeated single long flashes

Pre-maintenance The mode switch is in the maintenance position. Repeat steps 1 to 2, positioning the mode switch in the initialization position.





Internal PCI modules nC3022P-xxx

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

Figure 5 nCipher PCI module back panel and switches


The module performs self tests, during which the Status LED is on.

When the self tests are complete, the unit should enter the operational state. In this state the Status LED is mainly on, but blinks off regularly. As the load on the unit increases, the length of time that the Status

Status LED

Clear switch

Mode switch

Smart cardconnector

DC power

MOI

Operational



LED is off increases. If the module is fully loaded, the Status LED is off for as long as it is on. Refer to the table below if the Status LED is not mainly on and blinking off regularly:

Note If the Status LED remains continuously on for more than a minute, it indicates that the self tests have failed terminally. Contact Support at nCipher.

You can use the enquiry utility to discover whether the module is in the operational state. (See enquiry on page 229 for information on using this utility.)

Note To prevent the chance of accidentally resetting the module into the pre-initialization or pre-maintenance mode, you can turn on the override switch. Refer to the Hardware Installation Guide for information on accessing and setting the override switch.


Emits repeated single short flashes

Pre-initialization The mode switch was in the initialization position when you pressed the clear button. Repeat the process described in this section to set the mode switch in the operational position.

Emits repeated single long flashes

Pre-maintenance The mode switch is in the maintenance position. Repeat the process described in this section to set the mode switch in the operational position.




Chapter 5: Uninstalling

This chapter provides information on uninstalling nCipher software.

Uninstalling the nCipher support software

Note Do not uninstall the nCipher software unless either you are certain it is no longer required or you are going to upgrade it.

1. Log on to the host computer as Administrator or as a user with local administrator rights.

2. Select Add/Remove Programs from the Windows Control Panel.

3. Select the nCipher support software entry, and click the Add/Remove button to uninstall the support software.

Note The uninstall process restores the Microsoft CSP as the default SChannel CSP.

If required, you can safely remove the nCipher module after shutting down all connected hardware.


Chapter 6: Configuring the hardserver

The hardserver handles secure transactions between the modules connected to the host computer and applications that run on the host computer. In addition, the hardserver controls any remote slots that the module uses and loads any SEE machines that are to run on the module.

The hardserver can handle transactions for multiple modules. This does not require configuration of the hardserver. See Chapter 7: Using multiple modules.

The hardserver must be configured to control:

• the way the hardserver communicates with remote modules

• the way the hardserver communicates with local modules

• the import and export of remote slots

• the loading of SEE machines on to the module when the hardserver starts up.

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

Remote module connections

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

• a network-connected nCipher module that is configured to use the host computer as a client computer. For information about configuring network-connected modules, see the netHSM/payShield net Administrator Guide.


6 Configuring the hardserver Hardserver settings

• a module to which an attended remote slot is imported for the hardserver’s unattended local module.

You configure the hardserver’s communications with remote modules in the server_remotecomms section of the hardserver configuration file. This section defines the port on which the hardserver listens for communications from remote modules. You should need to edit this section only if the default port (9004) is not available.

See slot_imports for information about configuring remote slots.

Hardserver settings

You configure the hardserver’s settings in the server_settings section of the configuration file.

This section defines how connections and hardserver logging are handled. These settings can be changed while the hardserver is running.

Hardserver start-up settings

You configure the hardserver’s start-up settings in the server_startup section of the configuration file.

This section defines the sockets and ports used by the hardserver. You should need to change this section only if the default ports for privileged or unprivileged connections (9000 and 9001) are not available.

Remote slots

You configure remote slots in the slot_imports and slot_exports sections of the configuration file. The Remote Operator feature must be enabled on the module, as described in Chapter 8: Feature Enabling nCipher Modules.


6 Configuring the hardserver SEE machines

These sections define the slots that are imported to or exported from the module.

See Chapter 13: Remote Operator Card Sets for full information about remote slots.

SEE machines

You configure the hardserver to load SEE machines on start-up in the load_seemachine section of the configuration file. The SEE Activation feature must be enabled on the module, as described in Chapter 8: Feature Enabling nCipher Modules.

This section defines the SEE machines and optional user data to be loaded, as well any other applications to be run in order to initalize the machine after it is loaded.

See Chapter 9: Using CodeSafe Applications for information about SEE machines.

Hardserver configuration file

The hardserver configuration file has the following sections that you can update to configure the hardserver on an nShield module. If a section is not present, it is assumed to have no entries.

server_settings

The server_settings section defines the settings for the client hardserver that can be modified while the hardserver is running. The section contains the following fields:

loglevel

This field specifies the level of logging performed by the hardserver. It takes a value that is one of:

• info


6 Configuring the hardserver Hardserver configuration file

• notice

• client

• remoteserver

• error

• serious

• internal

• startup

• fatal

• fatalinternal

The default is info.

See Logging and debugging on page 343.

If NFAST_SERVERLOGLEVEL is set, it overrides the value in the configuration file.

logdetail

This field specifies the level of detail logged by the hardserver. You can supply one or more of the following flags in a space-separated list:

external_time

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

external_date

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



external_pid

This flag specifies showing the external process ID with the log entry.

external_tid

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

external_time_t

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

stack_backtrace

This flag specifies showing the stack backtrace with the log entry.

stack_file

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

stack_line

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

msg_severity

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

msg_categories

This flag specifies showing the message category (a category as used by the NFLOG_CATEGORY environment variable) with the log entry.



msg_writeable

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

msg_file

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

msg_line

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

options_utc

This flag specifies showing the date and time in UTC (Coordinated Universal Time) instead of local time.

connect_retry

The number of seconds to wait before retrying a remote connection to a client hardserver. The default is 10.

connect_broken

The number of seconds of inactivity allowed before a connection to a client hardserver is declared broken. The default is 90.



connect_keepalive

The number of seconds between keepalive packets for remote connections to a client hardserver. The default is 10.

connect_command_block

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

max_pci_if_vers

The maximum PCI interface version number. If this is set to 0 (the default) there is no limit.

These flags are those used by the NFLOG_DETAIL environment variable (see Environment variables to control logging on page 343).

module_settings

The module_settings section defines the settings for the module that can be changed while the hardserver is running. The section contains the following fields:

esn

The electronic serial number of the module.

priority

The priority of the module. This is an integer from 1 (highest) to 100 (lowest). The default is 100.



server_remotecomms

The server_remotecomms section defines the remote communication settings for the client hardserver. These are read only at hardserver start-up. This section contains the following fields:

impath_port

The port on which the hardserver listens for incoming impath connections. The default is 9004. Setting this field to 0 specifies that the hardserver does not listen for incoming connections.

server_startup

The server_startup section defines the settings for the hardserver that are loaded at startup. The section contains the following fields:

unix_socket_name

This field is not used on Windows systems.

unix_privsocket_name

This field is not used on Windows systems.

nt_pipe_name

The name of the pipe to use for non-privileged connections on Windows. An empty string specifies none. The default is \\.\pipe\crypto.

If the NFAST_SERVER environment variable is set, it overrides the value in the configuration file.

nt_pipe_users

A list of users allowed to issue non-privileged connections on Windows. If empty, any user can issue non-privileged connections. This is the default.



nt_privpipe_name

The name of the pipe to use for privileged connections on Windows. An empty string specifies none. The default is \\.\pipe\privcrypto.

If the NFAST_PRIVSERVER environment variable is set, it overrides the value in the configuration file.

nt_privpipe_users

A list of users allowed to issue privileged connections on Windows. If empty, any user can issue non-privileged connections. This is the default.

If the NFAST_SERVER environment variable is set, it overrides the value in the configuration file.

nonpriv_port

The port on which the hardserver listens for local non-privileged TCP connections. 0 specifies none. Java clients default to connecting to 9000. The default is 0.

If the NFAST_SERVER_PORT environment variable is set, it overrides the value in the configuration file.

priv_port

The port on which the hardserver listens for local privileged TCP connections. 0 specifies none. Java clients default to connecting to 9001. The default is 0.

If the NFAST_SERVER_PRIVPORT environment variable is set, it overrides the value in the configuration file.

load_seemachine

The load_seemachine section defines SEE machines that the module should load and, if required, start for use by other clients. Each SEE machine is defined by an entry as follows:



module

The module on to which to load the SEE machine. The value must be an integer. A module with this ID must be configured on the client computer.

machine_file

The file name of the SEE machine. (For payShield, the correct version and path are found in the release notes on the current nCipher CD-ROM.)

userdata

The file name of the userdata to pass to the SEE machine on startup. If this field is blank (" "), the SEE machine is loaded but not started. If this module is a payShield net module, this field must be blank. The default is blank.

worldid_pubname

The PublishedObject name to use for publishing the KeyID of the started SEE machine. If this field is blank (" "), the KeyID is not published. This field is ignored if the value of userdata is blank. If this module is a payShield net module, this field must be blank.

postload_prog

The program to run after loading the SEE machine to perform any initialization required by the SEE machine or its clients. This program must accept an argument of the form '-m module#'. If this module is a payShield net module, this field must be set to payshield.



postload_args

Arguments to pass to the program specified in postload_prog. The argument '-m module#' is automatically passed as the first argument. This field is ignored if postload_prog is not specified or is blank. If this module is a payShield net module, this field must be set to -n psiname [-d].

slot_imports

The slot_imports section defines the remote slots that the client hardserver on an unattended module should import from remote modules for use by modules connected directly to that local computer. Each slot is defined by an entry as follows:

local_esn

The ESN of the local module to which to import the slot.

local_slotid

The SlotID to use to refer to the slot when it is imported on the local module. The default is 2.

remote_ip

The IP address of the machine that hosts the slot to import

remote_port

The port number on which the remote hardserver is listening.

remote_esn

The ESN of the remote module from which to import the slot,

remote_slotid

The SlotID of the slot to import on the remote module. The value must be an integer. The default is 0.



slot_exports

The slot_exports section defines the slots on local modules that the local hardserver should allow network modules to import. Each local slot has an entry for each remote module that can import it, as follows:

local_esn

The ESN of the local module whose slot can be imported by a network module.

local_slotid

The SlotID of the slot that is to be imported. The value must be an integer. The default is 0.

remote_ip

The IP address of the network module that is allowed to import the slot. The default is to allow all modules in the security world to import the slot.

The IP address of the machine that is allowed to import the slot.

remote_esn

The ESN of the module allowed to import the slot.

remote_file_system

This section is updated automatically when the rfs-setup utility is run. You should not edit it manually.

The remote_file_system section defines a remote file system on the client, by listing the modules allowed to access the filesystem on this client. Each module is defined by an entry as follows:



remote_ip

The IP address of the network module that is allowed to access the filesystem on this client.

remote_esn

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

keyhash

The hash of the key with which the client must authenticate itself to the module. The default is 40 zeros, which means that no key authentication is required.

native_path

The local file name for the volume to which this entry corresponds.

volume

The volume which the remote host would access to use this entry.

allow_read

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

allow_write

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

allow_list

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


6 Configuring the hardserver Payments configuration file

is_directory

If this is set to yes, this entry represents a directory. The default is no.

is_text

If this is set to yes, line endings should be converted to and from the Unix convention for transfers

Payments configuration file

The payments configuration file is a temporary file used when enabling payments functions. (See Enabling payments functions on page 69.) The file has the following sections.

PINBlock formats

This section determines which PINBlock formats can be used in specific situations. If a format is not listed, then it is disabled and any attempt to use the format results in the message AccessDenied.

Role i/o permissions

This section determines the types of keys that can be imported or exported. Here you can specify which key block formats are acceptable for each import or export operation.

Listing no formats for an operation means that the operation is disabled. For example the following entry would mean that TPKs:

• Can be generated in attended operations (using the VeriFone solution)

• Cannot be generated automatically

• Can (in principle) be exported as components or wrapped in attended operations


6 Configuring the hardserver Payments configuration file

• Cannot be imported from components or wrapped in attended operations

• Can be imported automatically from a wrapped key.

role=KeyRole_TPK

gen_a=allow

gen_u=

ex_a=ExportFormat_XORComponents,ExportFormat_ECBWrapped

ex_u=

im_a=ExportFormat_XORComponents,ExportFormat_ECBWrapped

im_u=ExportFormat_ECBWrapped

nCipher does not recommend unattended key operations, since no currently supported key block formats carry sufficient role or integrity information.


Chapter 7: Using multiple modules

The hardserver can communicate with multiple nShield payShield modules connected to the host. By default, the server accepts requests from applications and submits each request to the first available module. The server can share load across buses, which includes the ability to share load across a mixture of modules.

If your application is multi-threaded, you can add additional modules and expect performance to increase proportionally until you reach the point where cryptography no longer forms a bottleneck in the system.

Identifying modules

Modules are identified in two ways:

• by serial number

• by ModuleID.

You can obtain the ModuleIDs and serial numbers of all your modules by running enquiry. See enquiry on page 229.

Serial Number

The serial number is a unique 12-digit number that is permanently encoded into each module. You should quote this number in any correspondence with Support at nCipher.

ModuleID

The ModuleID is an integer assigned to the module by the server when it starts. The first module it finds is given ModuleID 1, the next is given ModuleID 2, and so on.


7 Using multiple modules Multiple modules and Remote Operator

The order in which buses are searched and order of modules on a bus depends on the exact configuration of the host. If you add or remove a module, this can change the allocation of ModuleIDs to all the modules on your system.

You can use the enquiry command-line utility to identify the PCI bus and slot number associated with a module. See enquiry on page 229 for further information.

All commands sent to nShield payShield modules require a ModuleID. Many nCipher commands, including all acceleration-only commands, can be called with a ModuleID of 0. Such a call causes the hardserver to send the command to the first available module. If you purchased a developer kit, you can refer to the relevant developer documentation for information about the commands that are available on nCipher modules.

In general, the hardserver determines which modules can perform a given command. If no module contains all the objects that are referred to in a given command, the server returns an error status.

There are, however, some key-management operations that must be performed together on the same module. In such cases, your application must specify the ModuleID.

If you want to be able to share Operator Card Sets and keys between modules, the modules must be in the same security world.

Multiple modules and Remote Operator

On standard installations, Operator Card Sets and keys are only available for the specific module on which you have loaded them. If you want to load an Operator Card Set on more than one module, you need to physically insert the smart cards that make up the Operator Card Set into each module in turn.


7 Using multiple modules Adding a module

With Remote Operator enabled, you can load keys protected by an Operator Card Set onto an unattended module by inserting the relevant cards into a slot in an attended module. See Chapter 13: Remote Operator Card Sets for information on configuring modules to work in this way.

Adding a module

If you have a module installed, you can add further modules without reinstalling the server software.

However, nCipher recommends that you always upgrade to the latest server software and upgrade the firmware in existing modules to the latest firmware.

Note Before you install new hardware, check the release notes on the CD-ROM supplied with your new module for information about specific compatibility issues, new features, and bug fixes.

1. Install the module hardware. Refer to the Hardware Installation Guide for information on installing nCipher hardware.

2. Reboot your computer.

3. Add the module to the security world. Refer to Adding or restoring a module to the security world on page 155.

Module fail over

The nCipher support software supports fail over; that is, if a module fails, the processing can be transferred automatically to another module provided the necessary keys have been loaded. Depending on the mode of failure, however, the underlying bus and Operating System may not be able to recover and continue operating with the remaining devices.

In order to maximize uptime, nCipher recommends that you fit the redundant nCipher devices on a bus that is physically separate from the primary devices.


Chapter 8: Feature Enabling nCipher Modules

nCipher modules support a range of optional features. Optional features must be enabled with a certificate that you order from nCipher. You can order the features when you purchase a module, or you can obtain the certificate at a later date and use the Feature Enable Tool to enable the features. See Ordering features for your module on page 104 for details of ordering optional features. See Enabling features on page 105 for details of enabling features.

The module firmware checks to confirm whether any features that it attempts to use are enabled. It normally does this when it authorizes the commands, or command options, that relate to a specific feature.

Most features are static; that is, they are enabled by means of a switch in the module’s EEPROM. A static feature remains enabled when the module is reinitialized.

Some optional features are dynamic, that is, they are enabled by means of a software switch in the module’s volatile memory. A dynamic feature must be enabled again if the module is reinitialized.

Once you have enabled features on a module, you must clear the module to make them available.

Available Features

This section lists the features that can be added to modules.

Contact [email protected] for full details of all available features.

Elliptic Curve

Elliptic curves allow small key sizes to provide improved levels of security and are commonly used in embedded devices.

See Developer’s Reference for full details of the elliptic curve feature.



8 Feature Enabling nCipher Modules Available Features

Secure Execution Engine (SEE)

The SEE is a unique secure execution environment. The SEE features available to you are:

See the CodeSafe/C Developer Guide for full details of the SEE.

Remote Operator support

Many nCipher customers keep critical servers in a physically secure and remote position. The nCipher security world infrastructure, however, often requires the physical presence of an operator to perform tasks such as inserting cards. Remote Operator enables these customers to manage nCipher enabled servers remotely using a secure nCipher communications protocol over IP networks.

The Remote Operator feature must be ordered for and enabled on the module installed in the remote server. Remote Operator cannot be enabled remotely on an unattended module.

See Chapter 13: Remote Operator Card Sets for full details of using Remote Operator.

SEE Activation (EU+10)

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

SEE Activation (Restricted)

Provided with specific products that include an SEE application. This feature enables you to run your specific SEE application, and is available to customers in any part of the world.


8 Feature Enabling nCipher Modules payShield features

ISO smart card Support (ISS)

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

Korean Certificate-based Digital Signature Algorithm (KCDSA)

This algorithm is used extensively in Korea as part of compliance with local regulations specified by the Korean government.

See Developer’s Reference for full details of the KCDSA algorithm.

Client licenses

You can purchase additional client licenses that allow you to run multiple clients for the module. Three clients are always enabled on each module.

payShield features

If you have purchased payShield, the module is always supplied with the following feature enabling tokens:

• SEE Activation (Restricted), to allow software to run inside your module

• payShield Activation, to allow payShield software to run inside your module.

• payShield Rnumber, to set the performance variant of the payShield module to the number number

• ISO smart card support (ISS), also called Foreign Token Open (FTO), to allow the use of non-nCipher smart cards.


8 Feature Enabling nCipher Modules Ordering features for your module

For payShield applications you must enable these features using the Feature Enable Tool, described in The Feature Enable Tool on page 105, before you can use the secure payment application.

Ordering features for your module

When you have decided that you require a new feature, you can order it for your module from nCipher Sales over the phone.

Before you call nCipher Sales, you should collect information about your module as follows:

• If possible, make a note of the module serial number.

• Run the enquiry command and note down the Electronic Serial Number of the module.

You must provide the ESN number to order a new feature.

If you prefer, you can include this information in an E-mail to [email protected]. You can use the Feature Enable Tool to save the ESN details to a file. See The Feature Enable Tool on page 105.

When your order has been processed, you receive a Feature Enabling Certificate in one of the following ways:

• nCipher E-mails you the Feature Enabling Certificate.

• nCipher sends you a smart card that contains the Feature Enabling Certificate.

The Feature Enabling Certificate contains the information that you need to enable the features you have ordered.

For more information, including pricing of features, telephone or Email your nearest nCipher sales representative using the contact details from this guide, or the nCipher web site (http://www.ncipher.com).




8 Feature Enabling nCipher Modules Enabling features

Enabling features

The Feature Enable Tool

The Feature Enable Tool utility, by default, scans the smart card readers of all modules attached to the host, and enables any features found on inserted FEM cards.

To use the Feature Enable Tool, you must be logged in as a user who is permitted to create privileged connections.

You can enable a feature without having physical access to a module by exporting the slot on your local module, importing that slot into the remote module, and then running the Feature Enable utility on the remote host.

The Feature Enable Tool offers you the choice of clearing the module after it has enabled features. If you do not choose to clear the module then (for example, because you have another process running on the module), you must clear it later. You can use any appropriate method to do this (for example, the nopclearfail utility or the Clear button).

Usage

fet.exe

Help options

-h, --help

display help for fet.exe

-v, --version

display the version number of fet.exe



-u, --usage

display a brief usage summary for fet.exe.

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

Viewing features already enabled on a module

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

Enabling features with a smart card

When it is launched, the Feature Enable Tool automatically scans the smart card readers of all modules attached to a host computer for any Feature Enabling smart cards present in the smart card readers, including imported slots.

To enable a new feature:

1. Insert the Feature Enabling smart card from nCipher into a slot available to the module to be updated.

2. Run C:\nfast\bin\fet.exe to start the Feature Enable Tool.

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

Enabling new features on your module without a smart card

The Feature Enable Tool can also obtain the Feature Enabling Certificate information supplied by nCipher from a file or from the keyboard.



When you run the Feature Enable Tool without a Feature Enabling smart card in any module slot, a message similar to the following is displayed. There is a line for the features on each module, and a list of options. In this example, only one module (ESN 511D-DB15-D438) is attached to the host.

Feature Enable Tool

===================

ISO Smart Card Support

| Remote Operator

| | Korean Algorithms

| | | SEE Activation (EU+10)

Mod Electronic | | | | SEE Activation (Restricted)

No. Serial Number | | | | |

1 511D-DB15-D438 -- NO NO NO NO NO

1. Read FEM certificate(s) from a smart card or cards.

2. Read FEM certificate from a file.

3. Read FEM certificate from keyboard.

4. Write table to file.

Enter option :

If you select option 1, you are prompted to insert a Feature Enabling smart card into a module slot and then press . The Feature Enable Tool then behaves in exactly the same way as if it were run with the Feature Enabling cards already in the slots.

If you select option 2, you are prompted for the location and file name of the Feature Enabling certificate. When you supply these, you are prompted for the module number and the feature.

If you select option 3, you are prompted for the module number and the feature, and are then asked to enter the certificate one line at a time, followed by a period (“.”) on a line by itself. You can also cut and paste a Feature Enabling certificate from an E-mail.

If you select option 4, the table of enabled features is written to a file. You can include this file when you request new features from nCipher. See Ordering features for your module on page 104.

Enter


Chapter 9: Using CodeSafe Applications

If you have enabled the Secure Execution Engine (SEE), your system can run CodeSafe applications that implement special functionality.

Note If you wish to use the SEE to run applications, you must order and enable it as described in Chapter 8: Feature Enabling nCipher Modules.

An SEE application is typically a standalone SEE machine that is loaded automatically by the hardserver, for example, a CodeSafe C application.

Please check the documentation supplied by your application vendor for information about signatures that may be required to set up and use the application, and any other installation and configuration information.

CodeSafe/C applications

CodeSafe/C applications are standalone applications.

Each CodeSafe C application can consist of multiple parts, and its installation can include several configuration steps. Please see your application vendor’s documentation for instructions on installing and configuring each application.

You may need to use the hardserver, loadmache and tct2 utilities when configuring and loading an applicationl; see hardserver on page 242, and .


Chapter 10: 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:

• creating a security world

• adding a module to a security world

• removing a module from a security world

• replacing an Administrator Card Set

• creating Operator Card Sets

• replacing Operator Card Sets

Starting KeySafe

In order to use KeySafe, 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.

http://www.sun.com/


10 Using KeySafe Starting KeySafe

In order for KeySafe to work, you must set priv_port (the port on which the hardserver listens for local privileged TCP connections) to 9001 and nonpriv_port (the port on which the hardserver listens for local nonprivileged TCP connections) to 9000.

Note See Setting the environment variables on page 49 and server_settings on page 85 for information on setting these parameters.

Start KeySafe by selecting the KeySafe entry from the Programs folder on the Windows Start menu.

The Windows KeySafe launcher checks that the components required to run KeySafe are installed. Any missing components are listed in a dialog box similar to the following:


10 Using KeySafe The KeySafe window

When it starts, KeySafe displays a window similar to the one shown below:

Note nCipher recommends using a 16-bit or 24-bit color depth to ensure accurate color reproduction. In environments with 8-bit color depth, some colors may be represented incorrectly, although KeySafe still operates.

The KeySafe window

The KeySafe window is divided into two areas:

• the sidebar (on the left), subdivided into:

- the menu buttons (at the top of the sidebar)

- the Module Status tree (at the bottom of the sidebar)

• the main panel area (on the right).

This layout is consistent throughout the KeySafe application.



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



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

Enter



setting. Click the toggle to display expanded information about the security world or module. Click the toggle again to collapse this information.

Note For purposes of clarity, screen shots in this guide are shown with some of the Module Status tree toggles expanded.

Security world information

When you toggle the Module Status tree view of security world information to its expanded setting, KeySafe reports Yes or No for each of the following conditions:

• the security world is initialized

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

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

It also gives the following information:

• which type of key protects the security world (DES or AES/Rijndael)

• which FIPS 140-2 level the security world is operating at (level 2 or level 3)

The expanded security world information includes a folder labeled Advanced, which itself can be toggled into an expanded view. This folder displays advanced security world attributes related to 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



• 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



- 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 Entering the pre-initialization state on page 78. After you have initialized a security world, in order for a module to be usable, you must put it into the operational state (as described in Entering the operational state on page 79).

- for strict FIPS 140-2 level 3 security worlds, a FIPS Auth Loaded entry will show if an Administrator Card or Operator Card has been inserted to authorise a FIPS key required operation.

The Module status tree has an Advanced folder that shows the following details when expanded:

• the version of the module’s firmware

• whether the module has a Real Time Clock (RTC)

• whether the module has nonvolatile memory (NVRAM).



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.



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.



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


10 Using KeySafe Errors

you to the Module Operations panel, and clicking the Back button on the Examine/Change Card panel takes you to the Card Operations panel.

Navigating with the keyboard

The 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

key activates the currently selected button (as if you had clicked it). Pressing the - button combination takes you to the previous field (if any) or deselects an automatically selected button (if any).

Errors

If KeySafe detects an error from which it cannot recover, it may display a Fatal Error message, such as:

In this case, it could be that the nCipher server is unable to receive TCP connections for some reason. The server program communicates with clients by using named pipes or TCP sockets.

Note See Setting the environment variables on page 49 and Hardserver start-up settings on page 84 for information on setting these parameters.

The error message shown could also indicate that the nCipher server is not running (or that your module is physically disconnected). If the nCipher server is not running, take the following steps:

1. Exit KeySafe.

2. Restart the server as described in the section hardserver on page 242.

3. Restart KeySafe.

Tab

EnterShift Tab



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 Appendix A: Upgrading module firmware.

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.



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


Chapter 11: Managing security worlds

You normally create a security world when you install the module. This chapter contains detailed information about security worlds and instructions for alternative methods of creating them and other tasks that involve the security world.

Before you can use the nShieldpayShield module to manage keys, you must create a security world. If you are using payShield you must then configure the security world using the payshield-install utility as described in About payShield installations on page 187.

Security world files

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

Location of security world files

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

Note By default, the kmdata directory, and sub-directories, inherit permissions from the user that creates them. Installation of nCipher support software must be performed by a user with Administrator rights that allow read and write operations, and the starting and stopping of applications.


11 Managing security worlds Security world files

Files and operations

Security world operations create or modify files in the C:\nfast\kmdata\local directory as follows:

In this table:

• ESN is the electronic security number of the module on which the security world is created

• ident is the identifier given to the card set or key when it is created

• cardno is the number of the card in the card set

• appname is the name of the application by which the key was created.

The ident of a card set is a 40-character string that represents the hash of the card set’s logical token. The ident of a key is either user supplied or a hash of the key’s logical token, depending on the application that created the key.

Operation Creates/modifies Creates files...

Create a security world

creates worldmodule_ESN

Load a security world

creates or modifies module_ESN

Replace an Administrator Card Set

modifies world

Create an Operator Card Set

creates cards_ident card_ident_cardno (one per card)

Generate a key creates key_appname_ident

Create an Operator Card Set

modifies key_appname (for each key that has been recovered)

Recover a key modifies key_appname (for each key that has been recovered)


11 Managing security worlds Security world options

Required files

The following files must be present and up to date in the C:\nfast\kmdata\local directory, or the directory specified by the NFAST_KMLOCAL environment variable, for a host to use a security world:

• world

• a module_ESN file for each module that this host uses

• a cards_ident file for each cardset that is to be loaded from this host

• a card_ident_cardno file for each card in each cardset that is to be loaded from this host

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

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

Security world options

Decide what kind of security world you need before you create it. Depending on the kind of security world you need, you can choose different options at the time of creation. For convenience, security world options can be divided into the following groups:

• basic options, which must be configured for all security worlds

• recovery options, which must be configured if the security world, keys, or pass phrases are to be recoverable

• SEE options, which only need be configured if you are using nCipher’s Secure Execution Engine (SEE)

• options relating to the replacement of an existing security world with a new security world.



Security world options are highly configurable at the time of creation but, so that they remain secure, not afterwards. For this reason, nCipher recommends that you familiarize yourself with security world options, especially those required by your particular situation, before you begin to create a security world.

Security world basic options

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

Security world key type

You must decide whether to use a Triple DES or AES key as the security world key. The security world key is the key generated during security world creation that protects the application keys and Operator Card Sets in the created security world.

K and N

You must decide the total number of cards (N) in a security world’s ACS and must have that many blank cards available before you start to create the security world. You must also decide how many cards from the ACS must be present (K) when performing administrative functions on the security world.

Note nCipher recommends that you do not create Administrator Card Sets for which K is equal to N, because you cannot replace such an Administrator Card Set if even 1 card is lost or damaged.

Note If you are creating an Administrator Card Set for a payShield installation, Kmust be greater than 1. Therefore, nCipher recommends that in such casesN be greater than 2.

In many cases, it is desirable to make K greater than half the value ofN (for example, if N is 7, to make K 4 or more). Such a policy makes it harder for a potential attacker to obtain enough cards to access the security world. Choose values of K and N that are appropriate to your situation.



FIPS 140-2 level 3 compliance

By default, security worlds are created to comply with the roles and services, key management, and self-test sections of the FIPS 140-2 standard at level 2. However, you can choose to enable compliance with the FIPS 140-2 standard at level 3.

Note This option provides compliance with the roles and services of the FIPS 140- 2 level 3 standard. It is included for those customers who have a regulatory requirement for compliance.

If you enable compliance with FIPS 140-2 level 3 roles and services, authorization is required for the following actions:

• generating a new Operator Card Set

• generating or importing a key, including session keys

• erasing or formatting smart cards (although though you can obtain authorization from a card you are about to erase).

In addition, you cannot import or export private or symmetric keys in plain text.

Remote Operator

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

Security world recovery options

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



can choose to disable these recovery options when creating a security world. However, if you do so, all key recovery is impossible, even for keys generated as recoverable (which is the default for key generation).

If you do not enable recovery for a security world, you can never replace lost or damaged Operator Card Sets and, therefore, in such a case could never access the keys that are protected by such cards. Recovery cannot be enabled later without reinitializing your security world and discarding all your existing keys.

Security world SEE options

You must configure SEE options if you are using nCipher’s Secure Execution Engine (SEE). If you do not have SEE installed, the SEE options are irrelevant.

SEE debugging

SEE debugging is disabled by default, but you can choose whether to enable it for all users or whether to make it available only through use of an ACS. In many circumstances, it is useful to enable SEE debugging for all users in a development security world but to disable SEE debugging in a production security world. Choose the SEE debugging options that best suit your situation.

Real-time clock (RTC) options

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


11 Managing security worlds Creating a security world

Nonvolatile memory (NVRAM) options

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

Security world replacement options

Options relating to security world replacement are relevant only if you are replacing a security world.

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

Creating a security world

You normally create a security world when you first install the module (as described in Chapter 3: Getting the module working). If you want use the module to protect a different set of keys, you can replace the security world with another one.

In order to create a security world, the following must apply:

• Any modules that you wish to add to the security world must be started in pre-initialization state, as described in Entering the pre-initialization state on page 78.

• You must be logged in to the host computer as a user who is permitted to create privileged connections. See hardserver on page 242.

• The NFAST_HOME environment variable must be set.



• You should know what the security policy for the module is, and in particular the number and quorum of administrator and operator cards to be used. See Determining module requirements on page 39 for details.


When you have completed the operation and run the payshield-install utility if required, you must restart the module in the operational state.

The process of creating a security world:


• creates a new module key for this security world

• creates a new Administrator Card Set to protect this module key

• stores the security world information on the computer’s hard disk. The information is encrypted using the secrets stored on the Administrator Card Set.

Any Operator Cards created in a previous security world cannot be used in the new security world. If you are replacing a security world, you must erase all the Operator Cards created in the previous security world before you create the new world. See the Operator Guide.

You can create a security world from the command line with the new-world utility, as described in the section Creating a security world by using new-world on page 57 in Chapter 3: Getting the module working. Alternatively, you can create a security world with KeySafe, or the nCipher CSP wizard. The new-world utility can also be used to add a module to an existing security world.

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



Creating a security world with KeySafe

1. Start KeySafe. (For an introduction to KeySafe and information on starting the software, see the appropriate Operator Guide for your module.)

2. Check the Module Status tree to ensure that you have a module in the pre-initialization state (PreInitMode). See Entering the pre-maintenance state on page 76.

3. Click the Modules menu button, which takes you to the Module Operations panel.

4. Click the Initialize Security World navigation button.

5. If KeySafe finds existing security world data, it takes you to the Existing Security World panel in order to confirm that you want to delete this data by overwriting the existing security world:



Note Overwriting an existing security world in this way does not delete that security world’s host and recovery data, but renames the existing kmdata directory in which these reside as kmdata_nn (where nn is a 2-digit integer assigned depending on how many security worlds have been previously saved during overwrites up to a maximum of 99).

If you want to overwrite an existing security world, click the Overwrite Security World button on the Existing Security World panel. KeySafe then takes you to the Initialize Security World panel.

6. If KeySafe does not find existing security world data, it takes you to the Initialize Security World panel:

7. Enter the total number of cards (N) that you wish to have in the Administrator Card Set. This number must be less than or equal to 64.



8. Enter the number of Administrator Cards that are needed to authorize any action. This number (K) must be less than or equal to the total number of cards (N).

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

Note If you are creating an Administrator Card Set for a payShield installation, K must be greater than 1, and therefore N must be greater than 2.

9. Select the protection mode for the security world (that is, whether the security world key is to be a Triple DES key or an AES key).

10. Select whether or not you want the new security world to comply with the roles and services, key management, and self-test sections of the FIPS 140-2 standard at level 3.

Note This option provides compliance with the letter of the FIPS 140-2 level 3 standard, but does not improve the security of your keys. It is included for those customers who have a regulatory requirement for compliance.

11. To configure SEE options, proceed to the SEE options panel, and follow these steps:

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

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

c. Choose the parameters for SEE debugging and the number of Administrator Cards required to change SEE debugging settings. These are:



• Restricted

• Generate Authorization Key

• No Access Control. Click the Use these settings button to return to the Initialize

Security World panel.

Note If you wish to use SEE, you must have ordered and enabled it as described in Chapter 8: Feature Enabling nCipher Modules.

12. KeySafe always generates recovery data for the security world key. However, if you want to be able to recover Operator Cards and application keys, you must proceed to the Initialize Security World Advanced Options panel:



Use the Initialize Security World Advanced Options panel to create key and pass phrase recovery material that is protected by the cryptographic keys on the Administrator Card Set. This does not give nCipher, or any other third party, access to your keys. Keys can only be recovered by using the Administrator Cards.

Note nCipher recommends that you always select the recovery option.

a. Select whether or not you want to enable key recovery, and the number of Administrator Cards required to authorize key recovery.

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

c. Specify the number of Administrator Cards required to authorize loading this security world on to another module.

d. Select whether or not you want to enable generation of the FTO key and the number of Administrator Cards required to authorize the use of the FTO key.

Click the Use these settings button to return to the Initialize Security World panel.

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

Note If you disable FTO in the Initialize Security World Advanced Options panel, you cannot use smart cards to import keys even if you set the --allow-smartcard-imports option in the payshield-install utility.

Note If you want to use extended debugging from the module, you must set SEEDebugging to Unrestricted.



13. Click the Initialize Security World! button. This takes you to the Create Administrator Card Set panel:

14. KeySafe prompts you to insert the cards that are to form the Administrator Card Set.

Insert a blank card and click the OK button. If you insert a non-blank card that KeySafe can erase, the Erase Card! button is enabled, giving you the option of overwriting that card.

Note When creating a card set, KeySafe recognizes a card that belongs to the set before the card set is complete. If you accidentally insert a card to be written again after it has already been written, you see a warning.



15. KeySafe takes you to the Set Card Protection Pass Phrase panel:

If you want to set a pass phrase for this Administrator Card:

a. select the Yes option

b. enter the same pass phrase in both text fields

c. click the OK button.

A given pass phrase is associated with a specific card, so each card can have a different pass phrase. You can change these pass phrases at any time by using KeySafe’s Examine/Change Card option (available from the Card Operations panel) or the cardpassphrase command-line utility.

If you do not want to set a pass phrase for this Administrator Card:

d. select the No option

e. click the OK button.



16. KeySafe then prompts you for the next card (if any).

Note When creating a card set, KeySafe recognizes a card that belongs to the set before the card set is complete. If you accidentally insert a card to be written again after it has already been written, you see the following warning:

17. After you have created all the Administrator Cards, KeySafe creates a new module key.

When initialization is complete, KeySafe displays a message: Security world successfully initialized. Click the OK button, and KeySafe returns you to its introduction panel.

18. After you have added a module to the security world, restart the module in the operational state. (See Entering the pre-maintenance state on page 76).

If you have more than one module on this server, you can use KeySafe’s Reprogram Module option to incorporate a new module into your security world (or to restore an existing module after a firmware upgrade), as described in Adding or restoring a



module to the security world on page 155. Alternatively, you can also incorporate a new module into your security world by using the new-world command-line utility (see new-world on page 259).

Creating the security world using the CSP wizard

The nCipher CSP installation wizard can be used to:

• create a new security world

• add a module to an existing security world

• create Operator Card Sets, including K-of-N sets

• install nCipher’s Cryptographic Service Provider and/or acceleration-only offload.

To create a security world by using the nCipher CSP wizard, follow these steps:



1. Run the wizard by double-clicking the icon on your desktop.

The wizard displays this window:

If any module is in the pre-maintenance or maintenance state, the wizard displays a warning. In such a case, reset the module into the pre-initialization state, and rerun the wizard.

2. Click the Next button.

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



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



- If there is at least one module capable of key management and there is no existing security world, the wizard displays the following window:



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

3. Select one of the following options:

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

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

- to use the existing security world, select Use the existing security world, and click the Next button.



- to proceed without creating a security world, select Install cryptographic acceleration only and click the Next button. The wizard installs the acceleration-only hook. This option only provides acceleration and does not use the module to manage keys.

If you choose either to Create a new security world or to use an existing world, the following screen is displayed:


If you are replacing an existing security world, go to step 14.

If there are no modules in the pre-initialization state, the wizard prompts you to reset the modules as described in Entering the pre-initialization state on page 78.

Note If you need to shut down the computer in order to access the maintenance link or switch, rerun the wizard when you restart the computer. It continues from this point.



5. When all the modules are in the pre-initialization state, click the Next button. The wizard displays the following window:

6. Either accept the default 2-of-3 scheme for the Administrator Card Set or select the Use custom security policy option and enter your own parameters for the sharing scheme:

- the number of cards required (K) must be less than or equal to the total number of cards

- the total number of cards (N) must be at least 1 but no more than 64.

Note If you are creating an Administrator Card Set for a payShield installation, K must be greater than 1.

7. Select either DES3 or AES for the security world’s module key type.



8. Select the Configure advanced security world options option if you want to continue on to further configuration options for the security world when you have completed the selection of the options on the current screen. Select the SEE settings option to continue on to configure options for SEE.

Note You can select both the Advanced settings and the SEE settings option.

9. If you require compliance to level 3 of the roles and services section of the FIPS 140-2 standard, select the Create a FIPS 140-2 level 3 compatible security world option. If you select this option, you must insert a card from the Administrator Card Set or an existing Operator Card Set before you can create a new Operator Card Set.

Note The Create a FIPS 140-2 level 3 compatible security world option provides compliance with the letter of the FIPS 140-2 standard, but does not improve the security of your keys. It is included for those customers who have a regulatory requirement for compliance with this standard.




If you did not select the Configure advanced security world options option, continue from step 11.

If you selected the Advanced settings option, the World Advanced Options window is displayed:

Each tab in this window lets you specify the number of cards required to authorize specific tasks:

- On the Add module tab, select the number of cards required to add a module to the security world.

- On the Key rec. tab, disable or enable key recovery. If you enable key recovery, select the number of Administrator Cards required to recover a key.

Note If you require key recovery, you must enable it when you create the security world. If you do not enable key recovery now, it never will be possible to recover keys in this security world.



- On the PP rec. tab, disable or enable pass phrase recovery. If you enable pass phrase recovery, select the number of Administrator Cards required to recover a pass phrase.

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

- On the RTC tab, specify whether you require a key to authorize setting the modules real-time clock (RTC). If you require this key, select the number of Administrator Cards required to set the clock.

- On the DSEE tab, disable SEE debugging, enable SEE debugging for all users, or enable SEE debugging and create an associated key. If you enable debugging with this key, select the number of Administrator Cards required to authorize SEE debugging.

- On the FTO tab, specify whether you require a key to authorize foreign token operations (FTO). If you require this key, select the number of Administrator Cards required to perform foreign token operations.

Note FTO must be enabled to create a payShield installation.

11. Select Enable remote cardset support if required.



12. The wizard displays the following window:

If you want to protect this card with a pass phrase, select the Card requires a pass phrase option. The wizard prompts you to enter and confirm the pass phrase.

Note The Next button is only enabled when you have entered two matching pass phrases.

13. When you have entered the pass phrase, click the Next button.

14. Place the smart card in the module.




16. When the wizard successfully writes to this card, it prompts you to insert the next card and to enter a pass phrase for this card. Continue the process, following the onscreen instructions. When the wizard has written the number of cards you requested, it displays the following screen:

These smart cards form the Administrator Card Set for this security world. The security of your key data depends on the security of these smart cards.



17. If there are no more modules to add to the security world, go to step 18.

If there are further modules to add to the security world, the wizard prompts you to insert a card from the Administrator Card Set in the next module. Follow this process:

a. Insert one of the cards from the Administrator Card Set that you have just created, and click the Next button. If the card is not from the Administrator Card Set, the wizard prompts for another card.

b. If you defined a pass phrase for this smart card, the wizard prompts you to enter it. Enter the pass phrase, and click the Next button.

If the pass phrase is incorrect, the wizard displays an error message. If you type the pass phrase incorrectly three times, the wizard does not continue, and this module is returned to the factory state.

Note If the wizard stops because the incorrect pass phrase has been entered three times, the module is not be added to the security world. Run the wizard again in order to add this module to the security world.

c. When your correct pass phrase is entered successfully, the wizard prompts you for further smart cards and their pass phrase until you have loaded the required number of Administrator Cards and pass phrases, as defined in step 6.

If there are yet more modules to be programmed on this host, the wizard returns you to repeat the process of inserting Administrator Cards and entering their pass phrases for each additional module being added to the security world.



18. When all the modules have been added to the security world, the wizard displays this window:

19. Restart the module in the operational state (as described in Entering the operational state on page 79).



20. The wizard displays the following window:

This window enables you to create Operator Cards for the new security world. If you do not want to use Operator Card Sets to protect your keys, select the Module protection option. If this option is selected, the CSP only creates keys that are protected by


11 Managing security worlds After you have created a security world

the security world. This option is suited to applications where 24-hour operation is required, because no human intervention is required to use application keys.

If you want to use Operator Card Sets to protect your keys, select the Operator Card Set protection keys option.

If you are using Microsoft’s CA and you want the wizard to prompt you every time you create or import a key, turn on the Always use the wizard when creating or importing keys option. If you leave this option turned off, the wizard attempts to protect the new or imported key by using the card currently in the module.

You can change these settings by rerunning the wizard and selecting the Use the existing security world option.

If your security world is FIPS compliant, the option to use module-protected keys is not available.

Backing up the security world and CSP

In versions of the CSP after 1.11.0, the security world host data and CSP container information is stored in the directory to which the NFAST_KMDATA environment variable points (by default, C:\nfast\kmdata ). The data in this directory is encrypted.

The contents of the NFAST_KMDATA directory, together with the Administrator Card Set and Operator Card Sets, contain the entire state of the nCipher CSP.

After you have created a security world

Store the Administrator Card Set in a safe place.

If you lose more than N minus K of these Administrator Cards you cannot restore the security world or lost Operator Cards. For example, if you have a 2-of-3 Administrator Card Set and you lose


11 Managing security worlds Adding or restoring a module to the securityworld

more than one card, you cannot restore the security world. If you have created an Administrator card set where K equals N, then the loss of one card stops you from being able to restore the security world.

To prevent this situation from occurring, replace lost or damaged cards from the Administrator Card Set as soon as you discover the loss or damage. See Replacing the Administrator Card Set on page 221.

The security of the keys that you create within this security world is wholly dependent on the security of these smart cards.

The security world host data is stored in the directory to which the NFAST_KMLOCAL environment variable points. (See the section Security world files on page 123). The data in this directory is encrypted. Ensure that this directory is backed up regularly. Check the file permissions for this directory. Ensure that the nFast Administrator role, and any user that you want to be able to create Operator Cards or keys, has write permission for this directory. All other valid users must have read permission.

Note By default, the kmdata directory, and sub-directories, inherit permissions from the user that creates them. Installation of nCipher software must be performed by a user with Administrator rights that allow read and write operations, and the starting and stopping of applications.

The module can now be used to create Operator Cards and keys for the new security world.

Adding or restoring a module to the security world

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



You can also restore a module to a security world in order to continue using existing keys and Operator Cards:

• after you upgrade the firmware

• if you replace the module

The additional modules can be any nCipher modules. For information about adding a network-connected module to the security world, see the documentation for the appropriate module type.

In order to add a module to a security world, you must:

• have a copy of the security world data on this host. This is the host data written by KeySafe, the nCipher CSP wizard, or new-world when you created the security world. This data is stored in the directory to which the environment variable NFAST_KMDATA points (by default, C:\nfast\kmdata).

• set the environment variable NFAST_KMDATA (if the security world data is not in the default location).

• be logged in to the host computer as a user who is permitted to create privileged connections. See hardserver on page 242.

• have started the module in pre-initialization state (as described in Entering the pre-initialization state on page 78).

• possess a sufficient number of cards from the Administrator Card Set and the appropriate pass phrases.

Adding or restoring a module to a security world:


• reads the required number of cards (K) from the Administrator Card Set so that it can re-create the secret

• reads the security world data from the computer’s hard disk

• uses the secret from the Administrator Card Set to decrypt the security world key

• stores the security world key in the module’s nonvolatile memory.



When you have added a module to a security world, you cannot access any keys that were protected by a previous security world on the module.

Note It is not possible to program a module into two separate security worlds simultaneously.

Initialization removes any data stored in a module’s nonvolatile memory (for example, data for an SEE program or NVRAM-stored keys). To preserve this data, you must back it up before initializing the module and restore it after the module has been reprogrammed. nCipher provides the nvram-backup utility to enable data stored in nonvolatile memory to be backed up and restored. See nvram-backup on page 266 for details.

In order to continue using existing keys and Operator Cards, you must reprogram the module:

• after you upgrade the firmware

• if you replace the module

• if you need to add a module to an existing security world.

Adding a module to a security world with KeySafe

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


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

3. Click the Reprogram Module navigation button.



4. Select the module that you want to add to your security world by clicking its listing in the Module Status tree.

Note The module that you want to add to your security world must be in the pre-initialization state.

5. Click the Reprogram Module! command button. KeySafe takes you to the Load Administrator Card Set panel:

6. Insert a card from the Administrator Card Set that is required to authorize this action, and click the OK button. If a pass phrase is required, you must then enter it.

Note A pass phrase is associated with a specific card. If, for example, you insert card A but enter the pass phrase associated with card B, KeySafe does not accept the pass phrase and prompts you to type it again.

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



After you have added a module to the security world:

• Put the module into the operational state, as described in Entering the operational state on page 79.

• Return the Administrator Card Set to safe storage.

The newly added module can now be used with keys and cards from the existing security world.

Adding a module to a security world with the nCipher CSP wizard

To add a module to an existing security world:

1. Run the wizard by double-clicking the icon on your desktop.

2. The wizard displays the window:


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



If the wizard displays any of the other windows:

a. cancel the operation

b. check that you have correctly set the environment variable NFAST_KMDATA

c. copy the local sub-directory from the NFAST_KMDATA directory (that is, the directory to which the NFAST_KMDATA environment variable points) of another computer in the same security world or from a backup tape of this computer to the NFAST_KMDATA directory of this computer.

d. run the wizard again.

4. Ensure that the Use the existing security world option is selected, and click the Next button.

You can then proceed to add modules in the same manner that you add multiple modules when you create a security world. Follow the instructions for creating a security world in the section Creating the security world using the CSP wizard on page 139 from step 17.



Adding a module to a security world with new-world

1. Open a command window and type the command:

C:\nfast\bin\new-world [-l|--program] [-S|--no-remoteshare-cert] [-m|--module=MODULE]

In this command:

-l, --program

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


These options tell new-world not to make the module a target for remote shares.

-m, --module=MODULE

These options specifiy the ModuleID to use. new-world initializes only one module at a time. If you have multiple modules, you must run new-world once for every module that you want to add or restore.

If new-world cannot find the key-management data, it displays the message:

new-world: no existing world to load.

If you intend to initialize the module into a new security world, run new-world with the -i option.

If the module is not in the pre-initialization state, new-world displays and error and exits. See new-world on page 259.


2. After new-world has reprogrammed the module, restart the module in the operational state, as described in Entering the operational state on page 79.


11 Managing security worlds Erasing a module from a security world

3. Store the Administrator Card Set in a safe place.

Note If any error occurs (for example, if you do not enter the correct pass phrases), the module is reset to the factory state. The module does not form part of the security world unless you run new-world again.

Erasing a module from a security world

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

Erasing a module from a security world deletes from the module all of the secret information that is used to protect your security world. This returns the module to the factory state. Provided that you still have the Administrator Card Set and the host data, you can restore the secrets by adding the module to the security world.

In order to erase a module, you must:

• be logged in to your computer as a user who is permitted to create privileged connections. See hardserver on page 242.

• have started the module in the pre-initialization state, as described in Entering the pre-initialization state on page 78.

You do not need the Administrator Card Set in order to erase a module. However, unless you have a valid Administrator Card Set and the host data for this security world, you cannot restore the security world after you have erased it.



After you have erased a module, it is in the same state as when it left nCipher (that is, it has a random module key and a known KNSO).

Erasing a module with KeySafe

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


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

3. Click the Erase Module navigation button. KeySafe takes you to the Erase Module panel:

4. Select the module that you want to erase by clicking its listing on the Module Status tree. Then click the Erase Module! command button.



5. KeySafe erases all secrets from the module, returning it to its factory state.

Note If you have any keys that were protected by an erased module, you cannot access them unless you restore these secrets. You cannot restore these secrets unless you have the appropriate Administrator Card Set.

Erasing a module with new-world

new-world can erase any modules that are in the pre-initialization state.

Run new-world with the command:

new-world [-e|--factory] [-m|--module=MODULE]

In this command:

-e, --factory

These options tell new-world to restore a module to its factory state.

-m, --module=MODULE

These options specify the ModuleID to use. new-world erases only one module at a time. To erase multiple modules, you must run new-world once for every module that you want to erase.

Output

If new-world successfully erased a module, it does not display any messages. Otherwise, new-world returns an error message.


11 Managing security worlds Deleting the security world

Erasing a module with initunit

initunit erases any modules that are in the pre-initialization state.

Run initunit with the command:

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

In this command, --module=MODULE specifies the ModuleID of the module you want to erase. If --module=MODULE is not specified, all modules in the pre-initialization state are erased.

Output

If initunit is successful, for each module that is in the pre-initialization state, it returns a message similar to this:

Initialising Unit #

Setting dummy HKNSO

Module Key Info:

HKNSO ###################

HKM ###################

Otherwise, initunit returns an error message.

Deleting the security world

Occasionally, you may want to replace your security world (for example, if you believe that your existing world has been compromised). You can remove an existing security world and replace it with a new one. However:

• you will not be able to access any of the keys that you have previously used


11 Managing security worlds Displaying information about your securityworld

• before you remove an old security world, you must reformat any smart cards that were used previously as Operator Cards within this security world.

Note If you do not reformat the smart cards used as Operator Cards before you reinitialize your module, you must throw them away because they cannot be used, erased, or reformatted without the old security world key.

You can, and should, reuse the smart cards from the old Administrator Card Set. If you do not reuse or destroy these cards, then an attacker with these smart cards, a copy of your data (for example, a weekly backup) and access to any nCipher key management module can access your old keys.

There are two ways to delete an existing security world:

• Method 1:

a. Delete the files in the directory to which the NFAST_KMDATA environment variable points.

b. Create a new security world.

c. Add all your modules to this world.

• Method 2:

a. Remove all the modules from the security world.

b. Delete the files in the directory to which the NFAST_KMDATA environment variable points.

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

Displaying information about your security world

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



You can use KeySafe to view details of Operator Cards in a security world as described in the Operator Guide.

Displaying information about your security world with nfkminfo

To display information about the security world from the command line, issue the following command:

nfkminfo [-w|--world-info] [-r|--repeat] [-p|--preload-client-id]

In this command:

-w, --world-info

These options specify that you want to display general information about the security world. These options are the default and need not be included explicitly.

-r, --repeat

These options display the information repeatedly. There is a pause at the end of each set of information. The information is displayed again when you press .

-p, --preload-client-id

These options display the preloaded client ID value, if any.

The command also has the standard help options:

-h, --help

This option displays help for nfkminfo.

-v, --version

This option displays the version number of nfkminfo.

-u, --usage

This option displays a brief usage summary for nfkminfo.

Enter



Output

nfkminfo displays information similar to that shown in the following examples:

generation 1

state 0x70000 Initialised Usable Recovery !PINRecovery

!ExistingClient !RTC !NVRAM !FTO !SEEDebug

n_modules 1

hknso hash_knso

hkm hash_km

hkmwk hash_knwk

hkre hash_kre

hkra hash_kra

ex.client none

...

...

Module #1

generation 1

state 0x1 Useable

flags 0x10000 ShareTarget

n_slots 2

esn 34F3-9CB4-753B

hkml hash_kml

Module #1 Slot #0 IC 11

generation 1

phystype SmartCard

slotlistflags 0x2

state 0x4 Operator

flags 0x20000 RemoteEnabled

shareno 2

error OK

Cardset

name "fred"

k-out-of-n 1/2

flags NotPersistent

timeout none

card names "" ""

hkltu hash_kt


generation 1



phystype SoftToken

slotlistflags 0x0

state 0x1 Empty

flags 0x0

shareno 0

shares

error OK

No Cardset

No Pre-Loaded Objects

Security world

nfkminfo reports the following information about the security world:

generation

This indicates the nCipher internal number.

state

This indicates the status of the current world:

Initialised

indicates that the security world has been initialized

Usable

This indicates that there is at least one usable module in this security world on this host.

!Usable

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

Recovery

This indicates that the security world has the key recovery feature enabled.



!Recovery

This indicates that the security world has the key recovery feature disabled.

StrictFIPS140

This indicates that the security world is FIPS 140-2 level 3 compliant. If this is not shown, the security world is level 2 compliant only.

Note This indicates that your security world is compliant with the roles and services of the FIPS 140-2 level 3 standard. It is included for those customers who have a regulatory requirement for compliance.

ExistingClient

This indicates that there is a Client ID set, for example, by preload. This Client ID is given in the ex.client output if the --preload-client-id flag was supplied.

!ExistingClient

This indicates that no Client ID is set. The ex.client output will be empty.

!SEEDebug

This indicates the security world has no SEE Debugging delegation key.

SEEDebug

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

SEEDebugForAll

This indicates no authorization is required for SEE Debugging.



PINRecovery

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

!PINRecovery

This indicates that the security world has the PIN recovery feature disabled.

FTO

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

!FTO

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

NVRAM

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

!NVRAM

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

RTC

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

!RTC

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



n_modules

This indicates the number of nCipher modules connected to this computer.

hknso

This indicates the SHA-1 hash of the nCipher Security Officer’s key.

hkm

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

hkmwk

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

hkre

This indicates the SHA-1 hash of the recovery key pair.

hkra

This indicates the SHA-1 hash of the recovery authorization key.

ex.client

This indicates the ClientID required to use any pre-loaded keys and tokens.

k-out-of-n

This indicates the values of K and N for this security world.



other quora

This indicates the number (quora) of Administrator Cards (K) required to perform certain other functions as configured for this security world.

Module

For each module in the security world, nfkminfo reports:

generation

This indicates the version of the module data.

state

This indicates is one of the following:

PreInitMode

This indicates that the module is in the pre-initialization state.

InitMode

This indicates that the module is in the initialization state.

Unknown

This indicates that the module’s state could not be determined.

Usable

This indicates that the module is programmed in the current security world and can be used.



Uninitialized

This indicates that the module does not have the nCipher Security Officer’s key set and that the module must be initialized before use.

Factory

This indicates indicating that the module has module key zero only and that the nCipher Security Officer’s key is set to the factory default.

Foreign

This indicates that the module is from an unknown security world.

AccelOnly

This indicates that the module is acceleration only.

Unchecked

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

Failed

This indicates that the module has failed.

MaintMode

This indicates that the module is in the maintenance state.

flags

This displays ShareTarget if the module has been initialized to allow reading of remote card sets.



n_slots

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

esn

This indicates the electronic serial number of the module (if the module is not in the Usable state, the electronic serial number may not be available).

hkml

This indicates the hash of the module signing key (if the module is not in the Usable state, this value may not be available).

Slot

For each nCipher slot on the module, nfkminfo reports:

IC

This indicates the insertion count for this slot (which is 0 if there is no card in the slot).

generation

This indicates the version of the slotinfo structure.

phystype

This indicates the type of slot, which can be one of:

• SmartCard

• SoftToken.

slotlistflags

These are flags describing the capabilities of the slot:



0x1

This indicates that the slot uses a protected PIN path.

0x2

This indicates that the slot supports challenge-response authentication.

state

This can be one or more of the following flags:

Blank

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

Admin

This indicates that the smart card in the reader is part of the Administrator Card Set.

Empty

This indicates indicating that there is no smart card in the reader.

Error

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

Operator

This indicates that the smart card in the reader is an Operator Card.



flags

This displays Passphrase if the smart card requires a pass phrase.

shareno

This indicates the number of the card within the card set.

error

This indicates the error status encountered if the smart card could not be read:

OK

This indicates that there were no errors.

TokenAuthFailed

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

PhysTokenNotPresent

This indicates that there is no card in the reader.

If you purchased a developer kit, you can refer to the relevant developer documentation for a full list of error codes.

Card set

If there is an Operator Card in the reader, nfkminfo reports:

name

This indicates the name given to this card set.

k-out-of-n

This indicates the values of K and N for this card.



flags

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

NotPersistent

This indicates that the Operator Card is not persistent.

Persistent

This indicates that the Operator Card is persistent.

NotRemoteEnabled

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

RemoteEnabled

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

PINRecoveryForbidden(disabled)

This indicates that the card in the slot does not have PIN recovery enabled. This is always true if PIN recovery is disabled for the security world.

PINRecoveryRequired(enabled)

This indicates that the card in the slot does have PIN recovery enabled.

timeout

the period of time in seconds after which the module automatically removes the Operator Card Set. If timeout is set to none, the Operator Card Set does not time out.


11 Managing security worlds Windows Cryptographic Services Provider(CSP)

card

names the names of the cards in the set, not all software can give names to individual cards in a set.

hkltu

the SHA-1 hash of the secret on the card.

For more information about nfkminfo, see the appropriate Operator Guide for your module.

Windows Cryptographic Services Provider (CSP)

Container storage format

Note Versions of the CSP later than 1.11.0 have an updated container storage mechanism. CSP containers are now stored as part of the nCipher security world instead of in the Windows registry file.

Versions of the CSP later than 1.11.0 use a non-backwards-compatible container and key storage format. If you are installing version 1.11.0 or later of the CSP over older versions, you must run thecspmigrateutility in order to convert containers and keys from the old system to the new system.

CSP versions 1.11.0 and later have a number of advantages over older versions:

• The CSP state is easily mirrored between multiple machines simply by copying the contents of the kmdata directory or by sharing the kmdata directory across a network.

• The CSP key files can have arbitrary names (previously, the names of key files were linked to their key type and their container name). This new method facilitates the importation of existing nCipher security world keys into the CSP.



• Every different container is now guaranteed to have a distinct storage location. There were circumstances in CSP versions older than 1.11.0 in which two containers with similar names could have shared the same keys wrongly.

However, there are some points to bear in mind concerning CSP versions 1.11.10 and later:

• If you want to share the same key between multiple computers, nCipher supplies the cspimport utility for transferring keys between containers.

• Any existing containers with older versions of the CSP must be migrated to the new format. nCipher provides a utility, cspmigrate, to migrate containers from the old to the new system.



Setting up the Microsoft CA with an existing key

If you want to set up the Microsoft CA with an existing key, select the check box labelled Use an existing key in the Advanced Options section of the CA setup process. You are presented with a menu of suitable containers (machine containers that contain signature keys) from which to select:

If the key you select already has a certificate associated with it, you can choose to use the same certificate for the CA. Such a choice is typically used if you are reinstalling the CA and using the same key.

Setting up IIS 5 with an existing key

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



For example, in order to generate a suitable server certificate using the web interface of the Microsoft CA, make the following selections in order:

1. Request a certificate

2. Advanced request

3. Submit a certificate request to this CA using a form

At this point in the process, the advanced certificate request form is displayed. Ensure that the two following options are selected:

- the intended purpose must be Server Authentication Certificate

- the Use local machine store option must be enabled.

Note If you do not enable these options, the created certificate is not suitable for use as a Web server certificate and SSL does not work.

The selected CSP must also be a suitable nCipher CSP (typically, nCipher Enhanced SChannel Cryptographic Provider for an RSA key).

In order to use an existing key set, enable the Use existing key set’s name. The key size option is ignored in this case because the key size was decided at the original key creation time.



The portion of the advanced certificate request form used for the CSP and key setup is shown below, with all needed options selected correctly:

Migrating an existing security world to the new CSP format

There is a set of utilities supplied with CSP version 1.11.0 and later that help you migrate from the Windows registry-based CSP container storage to the new CSP format. The new CSP format stores all information about a security world in the kmdata directory.

These utilities are:

cspcheck

This utility checks that CSP container files are intact and uncorrupted, and also that referenced key files exist. Use cspcheck in conjunction with nfkmcheck, but run nfkmcheck first in order to test the integrity of your security world files.



cspimport

This utility allows you to insert keys manually into existing CSP containers. This utility has two modes that either allow you to change a container’s key association to that of an arbitrary nCipher security world key or to copy CSP keys between containers.

cspmigrate

This utility moves an existing security world’s CSP container information from the registry to the security world’s kmdata directory.

csputils

This utility lists CSP containers and provides detailed information about them. It can also be used to delete container files if the current user has administrative privileges.

keytst

This utility displays information about existing CSP key containers by using the Microsoft CryptoAPI. If you have the appropriate permissions, keytst also allows you to create containers and their keys, as well as delete containers.

A further CSP utility, cspimport, lets you insert keys manually into existing CSP containers. This utility has two modes that allow you either to change a container’s key association to that of an arbitrary nCipher security world key or to copy CSP keys between containers.

Each of these commands has an -h option that display the usage message for the command.


11 Managing security worlds Transferring keys between security worlds

Transferring keys between security worlds

The utilities mk-reprogam and key-xfer-im are used to transfer keys between security worlds. Before you can use these utilities to transfer keys, the following must be the case:

• the security world from which keys are being transferred must have recovery enabled (the destination security world can be non-recoverable).

• the key being transferred must have recovery enabled or be module-protected

• you must have the Administrator Card Sets for both the exporting module and the importing module.

• If one of the modules is a netHSM, it should be imported

To transfer keys:

1. Program the module to which you intend to transfer the key into one of the security worlds involved.

If one of the security worlds is FIPS 140-2 level 3 compliant and the other is not, then program the module into the security world that is not FIPS 140-2 level 3 compliant.

2. Run the mk-reprogram utility on the exporting security world in order to program a module key from that security world to a module in the importing security world. See mk-reprogram on page 255.

To authorize this operation, you must first present a quorum of Administrator Cards for KNSO for the exporting (current) security world, then a quorum of Administrator Cards for module programming from the importing security world.

Note If you change security worlds by using the command new-world -l, the programmed module key is lost.


11 Managing security worlds Transferring keys between security worlds

3. Run the key-xfer-im utility on the exporting security world in order to transfer the key to the importing security world. See key-xfer-im on page 250 for full details of the utility.

If you are transferring the key from a security world that is FIPS 140-2 level 3 compliant to one that is not, you must use the --export-add option. If you are transferring the key from a security world that is not FIPS 140-2 level 3 compliant to one that is, you must use the --export-delete option. These options must precede the key file name in the key-xfer-im command.

Also, remember that the default or current security world is set by the NFAST_KMDATA environment variable, which defaults to %NFAST_HOME%\kmdata. For more information about this environment variable, see Appendix C: Environment variables.

4. Initialize the importing security world.

To verify that module-protected keys have been imported:

a. Run the following command:

C:\nfast\bin\preload --module-prot exit

The output shows whether the key was imported successfully.

b. Check the C:\nfast\kmdata\local\ directory to see if the key has been exported.

You can use preload to load other types of keys to verify that they have been imported.See the Operator Guide for details.

5. If you have transferred keys that protect PKCS #11 objects, run postrocs on the target module once the key transfer is complete. See postrocs on page 286.


Chapter 12: About payShield installations

You must create security worlds specifically for use with the payShield module and then use the payshield-install utility to configure an associated payShield installation. Normally, you configure a payShield installation in this way when you set up the module; see Creating and configuring a payShield installation on page 64 for details.

This chapter contains reference information about payShield installations.

All installation activities which make use of the security world Administrator Card Set, the Key Establishment Card Set or the payShield Master Card Set must be performed on a trusted host. This host should not be connected to any network and should be stored and used in a physically secure location. Ideally the host’s software, including the operating system and the nCipher software, should be freshly installed from trusted media. The security and integrity of a payShield installation cannot be guaranteed if any of these card sets is compromised.

You can usually create a payShield installation with an existing security world, but nCipher strongly recommends creating a new security world for your payShield installation.

About payShield Card Sets

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


12 About payShield installations About payShield Card Sets

Administrator Card Set

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

payShield Master Card Set

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

payShield Key Establishment Card Set

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

Card Set Quorums

nCipher recommends that you give careful consideration to the choice of K and N for the ACS and Master Card Set. Any quorum of K Administrator Card holders or K Master Card holders can perform administrative functions, such as weakening or overriding the security protection of payShield keys. This means that any attacker who obtains a quorum of cards and pass phrases can do the same.

nCipher suggests as a minimum a quorum of 3 cards out of 5 (that is, a 3-of-5 card set) for the ACS and Master Card Set.


12 About payShield installations About payShield Card Sets

Additionally, the Administrator Card Set has a separate quorum for Foreign Token Open operations (FTO). An FTO quorum of Administrator Cards is required (and sufficient) to authorize the reading of data directly from non-nCore-format smart cards. Thus, the FTO quorum of Administrator Cards must be used to enable the payShield system to use the module smart-card reader to exchange key setup information with the VeriFone handset. Similarly, any attacker who can use the FTO quorum of Administrator Cards may be able to interfere with and subvert key establishment, including reading key components from transfer smart cards.

The quorum for FTO should be selected to prevent this. nCipher suggests as a minimum a quorum of 3.

nCipher recommends that you give careful consideration to the choice of K and N for the Key Establishment Card Set. Any quorum of K Key Establishment Card holders can introduce new keys, as can an attacker who is able to use K Key Establishment Cards with a module in the security world. If new keys are not authorized and secure, they may compromise the security of other payShield keys and PINS that are being processed.

nCipher suggests as a minimum a quorum of 2 cards out of 4 (that is, a 2-of-4 card set) for the Key Establishment Card Set.

Card Holders

The entire security of the keys you create within the payShield installation and of the data that they protect depends on the security of the security world and of the payShield installation card sets. You must ensure that all cards are stored securely and in the custody of trusted personnel. Cards should never be exposed needlessly.

No individual should ever have possession of more than one card from a particular card set, although an individual may hold one card from each of a number of different card sets.


12 About payShield installations Supported payShield Key Types

Supported payShield Key Types

lmku

This type is the Local Master Key for key and data encryption.

lmkr

This type is the Local Master Key for key encryption only.

zmk

This type is the Zone Master Key.

cvk

This type is for CVC generation and verification.

cvkv

This type is for CAVV generation and verification.

pvk

This type is the Pin Verification Key.

tpk

This type is the Terminal PIN Key.

zpk

This type is the Zone PIN Key.

mksmi

This type is for secure messaging for the integrity master key

mkidn

This type is the dynamic number master key


12 About payShield installations payShield security world properties

mkac

This type is the AC (ARQ, AAC, TC) master key

mkdac

This type is for the static data authentication master key.

A Local Master Key (lmk) can be used for the encryption both of key material and of data such as PINs. However, nCipher considers it useful to split and restrict the capabilities of certain key types. Therefore, the following two new types of lmk are provided for use with payShield:

• lmku for the encryption of keys and data

• lmkr for the encryption of keys only

When specifying an lmk in a payShield installation, you must select one of these types of lmk depending on your requirements. These are treated as strictly separate roles and cannot be changed after creation.

payShield security world properties

This section describes the properties required of a security world for payShield installations. For general information on creating security worlds, see Creating a security world on page 129. Security worlds for payShield must have FTO and key recovery enabled. You must set K for the Administrator Card Set to a value other than 1.

See Card Set Quorums on page 188 for important advice about the choice of a value for K.

If you wish to make use of the extended payShield module debugging option you must also select the dseeall feature. This option is designed for testing purposes only. Do not enable it on production security worlds as it may enable SEE applications to leak security information.


12 About payShield installations payShield security world properties

It is extremely important that you choose the settings carefully because you cannot change the properties of a security world after you have created it.


Chapter 13: Remote Operator Card Sets

This chapter describes:

• the concept of the Remote Operator functions

• how to configure Remote Operator.

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

About Remote Operator

The Remote Operator facility enables the contents of a smart card inserted into the slot of one module (the attended module, such a client module) to be securely transmitted and loaded onto another module (the unattended module, such as a netHSM). This is useful when you need to load a key protected by an Operator Card Set onto a machine to which you do not have physical access, for example, because it is in a secure area.

For Remote Operator to work, the modules must be in the same security world. The Operator Card Set is inserted into a slot in the attended module. From this module, the contents of the card set are transmitted over secure channels to another module. This module, the unattended module, loads the contents of the Operator Card Set. You do not need physical access to this module during the loading of the card set.

The following limitations apply to Remote Operator:

• Non-persistent card sets cannot be accessed remotely.

• The createocs utility cannot use remote slots to write new cards or card sets.


13 Remote Operator Card Sets Configuring Remote Operator

You can export a slot from an attended module and import a slot to any (unattended) module in the security world. The unattended module for import may be a local module connected to the host or a network-connected module such as a netHSM or payShield net module.. (You can import or export slots between netHSM or payShield net modules and local modules only if the local module uses a hardserver whose version is 2.6.10 or higher.) Before you can import a slot to one module, you must first export it from another module.

Configuring Remote Operator

This section describes how to configure Remote Operator.

Before you configure Remote Operator

Requirements for Remote Operator

Before you start to configure Remote Operator, you must do the following:

• Initialize two modules in the same security world, as described below.

• Initialize the unattended module as described below.

• Ensure both the attended and unattended module are in the operational state, as described in Entering the operational state on page 79.

• Create an Operator Card Set with the correct permissions, as described in Creating a Remote Operator Card Set on page 196.

• Configure each hardserver to allow communication between the modules.



Initializing modules for Remote Operator

Firmware version 2.6.10 or greater must be installed in both the attended and unattended module. Use the enquiry utility to determine the version of the firmware on the modules. For instructions on upgrading firmware, see Appendix A: Upgrading module firmware or the documentation for the appropriate module type.

After updating the firmware, the unattended module must be reinitialized into the security world by using KeySafe or new-world.

Note By default, a module is initialized with remote card set reading enabled. If you do not want a module to be able to read remote card sets, you must configure it accordingly. Use the command new-world -S MODULE (where MODULE is the module’s ModuleID number) if you do not want this module to be able to read remote card sets. See new-world on page 259

Note for full information.

The attended module does not need to be re-initialized.

If a module has been initialized to allow loading of remote card sets, nfkminfo displays a module section of the following form:

Module #1

generation 2

state 0x2 Usable

flags 0x10000 ShareTarget

n_slots 3

esn 8851-43DF-3795

hkml 391eb12cf98c112094c1d3ca06c54bfe3c07a103

The ShareTarget flag indicates that the module can be used as an attended module for the loading of Remote Operator Card Sets.



Creating a Remote Operator Card Set

You must create card sets that allow themselves to be loaded remotely for use with Remote Operator. A module with firmware 2.0.2 (PCI modules) or greater must be used to create the card sets.

Create each card set using Keysafe or the -q option for createocs. (For information on createocs, see the Operator Guide.). The cards must have been created to be persistent; see Creating the Operator Card Set on page 71.

Note All the modules must be included in the security world before you generate the Operator Card Set. If you are not using client cooperation, the kmdata directories must be manually synchronized after you generate the Operator Card Set.

If the card in the given slot is from a remotely enabled card set, nfkminfo displays a slot section similar to the following:


generation 1

phystype SmartCard

slotlistflags 0x2

state 0x5

Operator flags 0x20000 RemoteEnabled

shareno 1

shares LTU(Remote)

error OK

In this output, the RemoteEnabled flag indicates the card can be loaded remotely.

Importing and exporting slots

To import a slot from an attended module on to an unattended module:



1. Configure the host of the attended module to export the slot. To do this, add an entry for the slot to be imported to the slot_exports section of the configuration file

as described in slot_exports on page 94

.

2. Configure the host of the unattended module to import the slot. To do this, add an entry for the slot exported in step 1 to the slot_imports section of the configuration file on the host.

Exporting a remote slot

Import and export of slots is set up in the slot_exportssection of the hardserver configuration file for each module. The Remote Operator feature must be enabled on the module.

The slot_exports section defines the slots on local modules that the local hardserver should allow network modules to import. Each local slot has an entry for each remote module that can import it, as follows:

local_esn

The ESN of the local module whose slot can be imported by a network module.

local_slotid

The SlotID of the slot to be imported. The value must be an integer. The default is 0.

remote_ip

The IP address of the machine that is allowed to import the slot.

remote_esn

The ESN of the module allowed to import the slot.



Importing remote slots

Import and export of slots is set up in the hardserver configuration file for each module.

The slot_imports section in this file defines the remote slots that the local hardserver on an unattended module should import from remote modules for use by modules connected directly to the local computer.

Each slot is defined by an entry as follows:

local_esn

The ESN of the local module to which to import the slot.

remote_ip

The IP address of the machine that hosts the slot to import

remote_port

The port number on which the remote hardserver is listening.

remote_esn

The ESN of the remote module from which to import the slot,

remote_slotid

The SlotID of the slot to import on the remote module. The value must be an integer. The default is 0.



Loading Remote Operator Card Sets

After the hardserver has been configured, the remote slots can be used by all the standard nCipher libraries. A remote slot can be used to load any Operator Card Sets that have been created to allow remote loading. See the chapter in the Operator Guide that covers the application you wish to use with remote cards for more information.

Note After an Operator Card Set has been inserted into a remote slot, for each time a given card is inserted, the module only allows each share on that card to be read once. If there is a second attempt to read shares from that card before the card is reinserted, the operation fails with a UseLimitsUnavailable error.

Creating keys protected by Remote Operator Card Sets

After you have created card sets that can be loaded remotely, use generatekey and preload, or Keysafe, to create keys protected by them.

Note KeySafe can list the imported slot but cannot use it.

If you already have card-set protected keys that you want to use, but the card set is not remotely loadable, you can use Keysafe to protect the key under a new card set that is remotely loadable. This only succeeds if the key was initially generated with recovery enabled. If you created the key without enabling key recovery, you cannot protect the key under a different card set. In this case, you must generate a new key.


Chapter 14: Administration tasks with cards and softcards

This chapter describes tasks with card sets and softcards that require an Administrator Card Set to authorize them.

For other card and softcard tasks, see the appropriate Operator Guide for your module.

If you want to configure smart cards for use with a remote module, see Chapter 13: Remote Operator Card Sets.

This chapter describes the following operations:

• replacing an unknown pass phrase for an Operator Card

• replacing an Operator Card Set or recovering keys to a different softcard

• replacing the Administrator Card Set.

• changing a softcard pass phrase with ppmk (in security worlds where pass phrase recovery is enabled and the pass phrase is unknown).

Before you can perform any of these operations, you must first create a security world, as described in Chapter 11: Managing security worlds.

Replacing an Operator Card’s pass phrase

To replace a pass phrase for an Operator Card when you do not know the current pass phrase, you must:

• have created a security world with pass phrase recovery

• have the number of cards from the Administrator Card Set required to recover a pass phrase.


14 Administration tasks with cards and softcards Replacing an Operator Card’s pass phrase

Replacing a pass phrase with cardpp (on a client)

Take the following steps:

1. Run the cardpp utility using the command:

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

In this command:

--recover

This option tells cardpp to recover the pass phrase.

-m, --module=MODULE

These options specify the number of the module to use. If you only have one module, MODULE is 1. If you do not specify a module number, cardpp uses all modules by default.

2. At the prompt, supply the number of cards from the Administrator Card Set required to authorize pass phrase recovery.

3. At the prompt, insert the Operator Card whose pass phrase you want to replace.

4. At the prompt, type the pass phrase or press if you do not want to set a pass phrase.

5. If you have entered a pass phrase, at the prompt, confirm it.

cardpp sets the new pass phrase and prompts you for another Operator Card.

6. To change the pass phrase on further cards, repeat steps 3 though 5, or press to quit.

Administrator cards should only be inserted in a server you know is secure.

Enter

Q


14 Administration tasks with cards and softcards Replacing Operator Card Sets

Replacing Operator Card Sets

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

• KeySafe includes an option to replace Operator Card Sets on the Card Operations panel (click the Replace OCS navigation button).

• The rocs command-line utility provides an interactive method or a command-line only method to replace Operator Card Sets.

When you replace an Operator Card Set, the key material is not changed by the process. The process deletes the original host data (that is, the encrypted version of the key or keys and the smart card data file) and replaces this data with host data protected by the new Operator Card Set.

In order to replace an Operator Card Set, you must have:

• enabled key recovery when you created the security world

Note If you did not enable key recovery, or if you created the security world with an early version of pkcs-init that did not support key recovery, you cannot recover keys from lost or damaged smart cards.

• created the original Operator Card Set using createocs, createoc-simple, KeySafe, or the nCipher PKCS #11 library version 1.6 or later

If you initialized the token using ckinittoken from the nCipher PKCS #11 library version 1.5 or earlier, you must contact Support at nCipher to arrange for them to convert the token to the new format while you still possess a valid card.



• a sufficient number of cards from the Administrator Card Set to authorize recovery

Note All recovery options require authorization from the Administrator Card Set. If any of the smart cards in the Administrator Card Set are lost or damaged, immediately replace the entire Administrator Card Set.

• initialized a second Operator Card Set using createocs, createoc-simple, KeySafe, or the nCipher PKCS #11 library version 1.6 or later.

Note The new Operator Card Set need not have the same K-of-N policy as the old set.

If you are sharing the security world across several host computers, you must ensure that the changes to the host data are propagated to all your computers. One way to achieve this is to use client cooperation; see Setting up client cooperation on page 53.

Replacing Operator Card Sets with KeySafe

In order to replace an Operator Card Set, you must have another Operator Card Set onto which to copy the first set’s data. If you do not already have an existing second Operator Card Set, you must create a new one. See the Operator Guide for details.

When you have a second Operator Card Set ready, follow these steps in order to replace the first Operator Card Set:


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



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



This panel lists existing Operator Card Sets in tabular form. For each card set it displays:

Name

the name of the card set

Required (K)

the number of cards needed to re-create a key

Total (N)

the total number of cards in the set

Persistent

whether or not the card set is persistent

Recoverable Key Count

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

Nonrecoverable Key Count

the number of private keys protected by this card set that cannot be recovered.

You can click and drag with your mouse in order to resize this table's column widths and to rearrange the column order. Clicking a column heading sorts the rows in ascending order based on that column heading.

4. Select an Operator Card Set that you want to replace by clicking its list entry.

5. Click the Replace OCS! command button.

Note If the card set does not have any recoverable keys, it cannot be replaced.



6. KeySafe takes you to the Load Administrator Card Set panel, where it prompts you to insert cards from the Administrator Card Set in order to authorize the action. Each time you insert an Administrator Card into the module’s smart card slot, you must click the OK button to load the card.

Note Only insert your Administrator Card Set into a module that is connected to a trusted server.

7. When you have loaded enough cards from the Administrator Card Set to authorize the procedure, KeySafe takes you to the Load Operator Card Set panel, where it prompts you to insert the Operator Card Set that is to protect the recoverable keys (this is the Operator Card Set onto which you are copying data from the Operator Card Set you are replacing). Each time you insert an card from the new Operator Card Set into the module’s smart card slot, you must click the OK button.

When you have loaded enough cards from the new Operator Card Set, KeySafe creates new working versions of the recoverable keys that are protected by this card set.

KeySafe deletes the original host data for all recovered keys and replaces this data with host data that is protected by the new Operator Card Set. If there are no nonrecoverable keys protected by the card set, KeySafe also removes the old card set from the security world. However, if the Operator Card Set has nonrecoverable keys, the host data for the original card set and for the nonrecoverable keys is not deleted. These keys can only be accessed with the original Operator Card Set. If you want to delete these files, use the Remove OCS option.

8. When the process is complete, KeySafe displays a dialog box indicating that the Operator Card Set has been successfully replaced. Click the OK button. KeySafe returns you the Replace Operator Card Set panel, where you may replace another Operator Card Set or choose a different operation.



Recovering keys to Operator Card Sets or softcards with rocs

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

Using rocs interactively

Run the rocs utility using the command:

C:\nfast\bin\rocs

rocs displays the following prompt:

'rocs' key recovery tool

Useful commands: 'help', 'help intro', 'quit'.

rocs >

In order to use rocs to replace an Operator Card Set or recover keys to a softcard, take the following steps:

1. You must select a module to use by using the module command, which is described in the section module number on page 213.

2. List the Operator Card Sets and softcards in the current security world by using the list cardsets command, which is described in the section list cardsets on page 210.

3. Select the Operator Card Set or softcard to which you want to transfer the keys by using the target command, which is described in the section target cardset-spec on page 214.


4. List the keys in the current security world using the list keys command, which is described in the section list keys on page 212.



5. Select the keys that are to be recovered by using the mark command, which is described in the section mark key-spec on page 213.

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

7. After you have selected the keys that are to be recovered, transfer these keys by using the recover command, which is described in the section recover on page 214.

rocs prompts you to insert a card from the Administrator Card Set.

8. Insert a card from the Administrator Card Set.

rocs prompts you for the pass phrase for this card. This action is repeated until you have loaded the required number of cards from the Administrator Card Set.

If you do not have the required number of cards from the Administrator Card Set, press and then . The rocs utility returns you to the rocs > prompt without processing any keys.

Administrator cards should only be inserted in a server you know is secure.

Q Enter



9. If you are recovering keys to an Operator Card Set:

a. rocs prompts you to insert a card from the first Operator Card Set that you have selected as the target. Operator Card Sets are processed in ascending numerical order as listed by the list cardsets command.

b. Insert a card from this Operator Card Set.

c. rocs prompts you for the pass phrase for this card. This action is repeated until you have loaded the required number of cards from the Operator Card Set.

If you are recovering keys to a softcard, rocs prompts you for the pass phrase for the softcard that you have selected as the target.

If you decide that you do not want to transfer the keys to the selected card set or softcard, press and then (to quit).rocs returns you to the rocs > prompt and does not process any further Operator Card Sets or softcards.

When you have loaded the target softcard or the required number of cards from the target Operator Card Set, rocs transfers the selected keys to the target Operator Card Set or softcard.

If you have selected other target Operator Card Sets or softcards, rocs prompts for a card from the next Operator Card Set.

10. Repeat step 9 for each selected target.

11. If you have transferred the correct keys, write the key blobs to disk by using the save function (described in the section save key-spec on page 214). If you have transferred a key by mistake, you can restore it to its original protection by using the revert command (described in the section revert key-spec on page 214).

At the rocs prompt, you can use the following commands:

• help topic

• help intro

• list cardsets

• list keys

Q Enter



• mark key-spec

• module number

• quit

• recover

• rescan

• revert key-spec

• save key-spec

• status

• target cardset-spec

• unmark key-spec

Note You can specify a command by typing enough characters to identify the command uniquely. For example, for the status command, you can type st and then press .

help

With no arguments specified, help shows a list of available commands with brief usage messages and a list of other help topics. With an argument, help shows detailed help information about a given topic.

help intro displays a brief step-by-step guide to using rocs.

list cardsets

This command lists the Operator Card Sets and softcards in the current security world. For example:

No. Name Keys (recov) Sharing

1 test 6 (6) 3 of 5; 20 minute timeout

2 test2 3 (2) 2 of 3

3 test3 1 (1) 1 of 1; persistent

In this output:

Enter



No.

This is the card set or softcard number, which can be used to identify this card set in rocs commands.

Name

This is the Operator Card Set or softcard name

Keys

This is the number of keys protected by this Operator Card Set or softcard

(recov)

This is the number of recoverable keys

Sharing

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

persistent

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

### minute timeout

This indicates that the Operator Card Set is persistent and has a time-out set.



list keys

This command lists the keys in the current security world, as in the following example:

No. Name App Protected by

1 rsa-test hwcrhk module

2 Id: uc63e0ca3cb032d71c1c pkcs11 test2

R 3 Server-Cert pkcs11 test --> test2

4 Id: uc63e0ca3cb032d71c1c pkcs11 test --> test3

5 Server-Cert pkcs11 module (test ---> fred2)

where:

No.

This is the key number, which can be used in mark and unmark commands.

Name

This is the key name.

App

This is the application with which this key is associated.

Protected by

This indicates the protection method:

method description

module key protected by the security world

name key protected by the named Operator Card Set or softcard

name-->name2 key protected by the Operator Card Set or softcard name1 marked for recovery to Operator Card Set or softcard name2

module (name) PKCS #11 public object, which are protected by the security world but associated with a specific Operator Card Set or softcard

module (name-->name2) PKCS #11 public object marked for recovery



mark key-spec

This command marks the listed keys that are to be recovered to the target Operator Card Set or softcard. You can mark one or more keys by number, ident, Operator Card Set or softcard, or hash. See Specifying keys on page 217 for details. To mark more than one key at a time, ensure that each key-spec is separated from the other by spaces, as in the following example:

mark key-spec1 key-spec2 key-spec3

If you have not selected a target Operator Card Set or softcard, or if rocs cannot parse the key-spec, then rocs displays an error message.

You can mark and remark the keys to be recovered to various target Operator Card Sets or softcards. Remarking a key displaces the first target in favor of the second target.


module number

This command selects the module to be used. The module number must correspond to a module in the current security world. If the module does not exist, is not in the security world, or is otherwise unusable, then rocs displays an error message and does not change to the selected module.

quit

This command allows you to leave rocs. If you attempt to quit when you have recovered keys but have not saved them, rocs displays a warning.



recover

This command transfers the marked keys to their target Operator Card Sets or softcards. This operation is not permanent until you save these keys by using the save command.

rescan

This command updates the card set and key information.

revert key-spec

This command returns keys that have been recovered, but not saved, to being protected by the original protection method. If the selected keys have not been recovered, rocs displays an error message.

save key-spec

This command writes the new key blobs to disk. If you specify a key-spec, only those keys are saved. Otherwise, all recovered keys are saved.

status

This command lists the currently selected module and target Operator Card Set or softcard.

target cardset-spec

This command selects a given Operator Card Set or softcard as the target. You can specify the card set or softcard name, the number returned by list cardsets, or the hash.



unmark key-spec

This command unmarks the listed keys. Unmarked keys are not recovered.

Using rocs from the command line

You can select all the options on the command line using the command:

C:\nfast\bin\rocs -m|--module=MODULE [-t|--target=CARDSET-SPEC]

[-k|--keys=KEYS-SPEC] [-c|--cardset=CARDSET-SPEC] [-i|--interactive]

In this command:

-m, --module=MODULE

specify the module number of the module to use.

-t, --target=CARDSET-SPEC

specifies the Operator Card Set or softcard to be used to protect the keys. See Specifying card sets on page 217 for details.

-k, --keys=KEYS-SPEC

selects the keys to be recovered. See Specifying keys on page 217 for details.

-c, --cardset=CARDSET-SPEC

selects all keys that are protected by the given Operator Card Set or softcard. See Specifying card sets on page 217 for details.

-i, --interactive

forces rocs to start interactively even if you have already selected keys.



The rocs command also has the standard help options:

-h, --help

displays help for rocs

-v, --version

displays the version number of rocs

-u, --usage

displays a brief usage summary for rocs.

You must specify the target before you specify keys.

You can use multiple --keys=KEYS-SPEC and --cardset=CARDSET-SPEC options, if necessary.

You can specify multiple targets on one command line by including separate --keys=KEYS-SPEC or --cardset=CARDSET-SPEC options for each target. If a key is defined by --keys=KEYS-SPEC or --cardset=CARDSET-SPEC options for more than one target, it is transferred to the last target for which it is defined.

If you have selected a module, a target Operator Card Set or softcard, and keys to recover but have not specified the --interactive option, rocs automatically recovers the keys. rocs prompts you for the Administrator Card Set and Operator Card Set or softcard, as described in Using rocs interactively on page 207.

Note If you use rocs from the command line, all keys are recovered and saved automatically. You cannot revert the keys unless you still have cards from the original Operator Card Set.

If you do not specify the target and keys to recover, or if you specify the --interactive option, rocs starts in interactive mode with the selections you have made. You can then use further rocs commands to modify your selection before using the recover and save commands to transfer the keys.



Specifying card sets

The value of CARDSET-SPEC identifies one or more Operator Card Sets or softcards. It may have any of the following forms:

[number] cardset-number

selects the Operator Card Set or softcard with the given number from the list produced by the list cardsets command

[name] cardset-name

selects card sets or softcards by their names (the card set or softcard name may be a wildcard pattern in order to select all matching Operator Card Sets or softcards)

hash cardset-hash

selects the Operator Card Set or softcard with the given hash.

In order to specify multiple Operator Card Sets or softcards, include several CARDSET-SPECs on the command line.


Specifying keys

The --keys=KEYS-SPEC option identifies one or more keys. It may have any of the following forms:

mark key-number

This selects the key with the given number from the list produced by the list keys command. Examples of usage are:

rocs -t target_OCS -k key_number


14 Administration tasks with cards and softcards Changing pass phrases with cardpp

and

rocs -t target_OCS -k "mark 56"

appname:keyident

This selects keys by their internal application name and ident. You must supply at least one of appname or keyident, but you can use wildcard patterns for either or both in order to select all matching keys. An example of usage is:

rocs -t target_OCS --keys="simple:simplekey"

hash keyhash

This selects the key with the given key hash. An example of usage is:

rocs -t target_OCS --keys="hash e364[...]"

--cardset cardset-spec

This selects all keys protected by a given card set

Changing pass phrases with cardpp

If you have generated your security world with pass phrase recovery, the cardpp utility allows you to:

• change a pass phrase

• add a pass phrase to a card that currently does not have one

• remove a pass phrase from a card that currently has one


14 Administration tasks with cards and softcards Changing pass phrases with cardpp

• replace the pass phrase of an Operator Card even though you do not know the current pass phrase. This operation requires authorization from the Administrator Card Set. Changing a pass phrase with cardpp when you do know the current pass phrase does not require authorization from the Administrator Card Set; for more information see the Operator Guide appropriate for your module.

Each card in a card set can have its own individual pass phrase. You can even have a set in which some cards have pass phrases and others do not. A pass phrase can be of any length and can contain any characters that you can type.

Changing pass phrases with cardpp (pass phrase not known)

To change a pass phrase for an Operator Card using the cardpp command-line utility when you do not know the pass phrase, you must:


• have sufficient cards from the Administrator Card Set to authorize the action.

If these conditions are met, take the following steps:

1. Run the cardpp utility using the command:

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

In this command:

--recover

tells cardpp to recover the pass phrase.

-m, --module=MODULE

specify the number of the module to use. If you only have one module, MODULE is 1. If you do not specify a module number, cardpp uses all modules by default.


14 Administration tasks with cards and softcards Changing pass phrases with ppmk

2. When cardpp prompts you, insert sufficient cards from the Administrator Card Set to authorize pass phrase recovery.

3. When cardpp prompts you, insert the Operator Card whose pass phrase you want to replace.

4. When cardpp prompts you for the new pass phrase, type the pass phrase or press if you do not want to set a pass phrase.

5. If you have entered a pass phrase cardpp asks you to confirm it. After you confirm, cardpp sets the new pass phrase and prompts you for another Operator Card.

6. If you do not want to continue press to quit.

Changing pass phrases with ppmk

If you have generated your security world with pass phrase recovery, the ppmk utility allows you both to change a softcard’s pass phrase if you know the current pass phrase and recover a softcard’s pass phrase even if you do not know the current pass phrase.

Changing a pass phrase with ppmk when you do know the current pass phrase does not require authorization from the Administrator Card Set; for more information see the Operator Guide appropriate for your module.

Changing a pass phrase with ppmk when you do not know the current pass phrase requires authorization from the Administrator Card Set.

Changing pass phrases with ppmk (pass phrase not known)

To change a pass phrase for a softcard using the ppmk command-line utility when you do not know the pass phrase, you must:


• have sufficient cards from the Administrator Card Set to authorize the action.

If these conditions are met, take the following steps:

Enter

Q


14 Administration tasks with cards and softcards Replacing the Administrator Card Set

1. Run the ppmk utility using the command:

C:\nfast\bin\ppmk --recover NAME|IDENT

In this command, --recover tells ppmk to recover the pass phrase. You can identify the softcard whose pass phrase you want to recover by its name (NAME) or by its logical token hash as listed by nfkminfo (IDENT).

2. When ppmk prompts you, insert sufficient cards from the Administrator Card Set to authorize pass phrase recovery.

3. When prompted, type a pass phrase for the new softcard, and press . 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 .

If the pass phrases do not match, ppmk prompts you to input and confirm the pass phrase again.

Administrator Card Sets should only be inserted in a trusted server.

After you have confirmed the new pass phrase, ppmk finishes configuring the softcard to use the new pass phrase.

Replacing the Administrator Card Set

Replacing the Administrator Card Set uses K of the cards in the current Administrator Card Set in order to:

1. load the secret information that is to be used to protect the archived copy of the security world key.

2. create a new secret that is to be shared between a new set of cards

3. create a new archive that is to be protected by this secret.

Enter

Enter



If you discover that one of the cards in the current Administrator Card Set has been damaged or lost, use the command-line utility racs or the KeySafe Replace Administrator Card Set option to create a new set immediately. If further cards are damaged, you may not be able to re-create your security world.

nCipher recommends that you erase your old Administrator Cards as soon as you have created the new Administrator Card Set. An attacker with the old Administrator Card Set and a copy of the old host data could still re-create all your keys. With a copy of a current backup, they could even access keys that were created after you replaced the Administrator Card Set.

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

Replacing an Administrator Card Set with KeySafe

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


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

3. Click the Replace ACS navigation button, and KeySafe takes you to the Replace Administrator Card Set panel.

4. If you are sure that you want to replace the Administrator Card Set, click the Replace ACS! command button



5. KeySafe takes you to the Load Administrator Card Set panel, where it prompts you to insert cards from the Administrator Card Set in order to authorize the action. Each time you insert an Administrator Card into the module’s smart card slot, you must click the OK button to load the card.

Note Only insert your Administrator Card Set into a module that is connected to a trusted server.

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

Note When creating a card set, KeySafe recognizes cards that belongs to the set even before the card set is complete. If you accidentally insert a card to be written again after it has already been written, KeySafe displays a warning.



7. When you insert a blank card, KeySafe takes you to the Set Card Protection Pass Phrase panel:

8. If you want to set a pass phrase for this Administrator Card:

a. Select the Yes option.

b. Enter the same pass phrase in both text fields.

c. Click the OK button.

KeySafe then prompts you for the next card (if any). A given pass phrase is associated with a specific card, so each card can have a different pass phrase. You can change these pass phrases at any time by using KeySafe’s Examine/Change Card option (available from the Card Operations panel) or the cardpp command-line utility.

9. If you do not want to set a pass phrase for this Administrator Card:

a. Select the No option.

b. Click the OK button.



10. After you have created all the Administrator Cards, KeySafe displays a message:

ACS successfully replaced. Now consider erasing your old Administrator Cards

Click the OK button, and KeySafe returns you to its introduction panel.

11. When you have finished replacing the Administrator Card Set, erase the old Administrator Cards.

Replacing an Administrator Card Set with racs

Note Before you start to replace an Administrator Card Set, you must ensure you have enough cards to create a complete new Administrator Card Set. If you start the procedure without enough cards, you will have to cancel it part of the way through.

The racs utility creates a new Administrator Card Set to replace a set that was created with the new-world utility.

Use the command:

C:\nfast\bin\racs.exe [-m|--module=MODULE] [-f|--force]

In this command:

--module=MODULE

specifies the ModuleID of the module to use.

--force

tells racs to allow the use of smart cards that already contain data. Any existing data is erased. If a value for this flag is not specified, racs prompts you if a card contains data.

When you have finished replacing the Administrator Card Set, erase the old Administrator Cards.


Chapter 15: nShield Administrator Utilities

This chapter contains reference information about the utilities referred to in this manual. See Appendix E: Installed Utilities for a full list of all the utilities supplied with the nCipher software.

Help options

If a utility has the standard help options, these are not included in the synopsis or in the description. The standard help options are as follows:

• -h, --help displays help for the utility

• -v, --version displays the version number of the utility

• -u, --usage displays a brief usage summary for the utility

Some commands have alternative help options. These are described but are not included in the synopsis.


15 nShield Administrator Utilities anonkneti

anonkneti

This utility displays the ESN and HKNETI key hash from a netHSM module identified by its IP address. This information is required to configure your client hardserver to import the remote module.

This utility uses an anonymous host and is insecure. Use it only if you trust your network. Otherwise, obtain the ESN and HKNETI of the module from the welcome screen.

Usage

c:\nfast\bin\anonkneti [-m module] [-p port] IP_address

In this command:

-m module

This option specifies the module to query. The default is module 1.

-p port

This option specifies the port to use to communicate with the module.

IP_address

This option specifies the IP address of the module from which to obtain the ESN and HKNETI key hash.


15 nShield Administrator Utilities cfg-reread

cfg-reread

This utility loads the hardserver configuration from the configuration file.

Usage

C:\nfast\bin\cfg-reread.exe

This command has no options or parameters. It loads the file C:\nfast\kmdata\config\config as the client’s current configuration. See server_remotecomms on page 90 for details of the configuration file.

The cfg-reread utility calls a number of separate utilities, each of which loads one section of the configuration file. If you update only one section of the configuration file, you can reload just that section by running the corresponding command as follows:

Utility Configuration file section

Updates ...

hsc_loadseemachine.exe load_seemachine SEE machine settings

hsc_serverremotecomms.exe server_remotecomms Remote communications settings

hsc_serversettings.exe module_settingsserver_settings

Module settings and hardserver settings

hsc_slotimports.exe slot_imports Imported slot settings

hsc_slotexports.exe slot_exports Exported slot settings


15 nShield Administrator Utilities enquiry

enquiry

The enquiry utility returns information about the nCipher server and the modules connected to it.

Usage

enquiry -m|--module=MODULE

In this command, --module=MODULE is the module number of the module about which you want to receive information. If you do not specify a module, enquiry returns information about all modules.

Output

enquiry returns the following data for the server and each module:

enquiry reply flags

Failed indicates that the module has failed. This failure may be because the module is in the Error state or because there is a problem on the PCI bus.

enquiry reply level

This is the version of enquiry that the module (or hardserver) supports. For release 9.0 and later, this level is Six or higher.

serial number

This is the electronic serial number of the module. Please quote this number when contacting Support at nCipher. For the server, this field contains the electronic serial numbers for all attached modules.

mode

This is one of:



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



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.



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.



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 Chapter 8: Feature Enabling nCipher Modules for information on the features available and how to enable them.

HasFileOp

The HasFileOp flag is set if the module supports operations using nonvolatile memory.

HasPCIPush

The HasPCIPush flag is set by the module if it has PCI push functionality.



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



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



features enabled

For modules that support enquiry level Six version 1 or greater, this lists the features currently enabled. Possible values are as follows:

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.

Value Feature that is enabled Feature name

ForeignTokenOpen Foreign Token access features (ISS). ISO Smart Card Support

RemoteShare Remote Operator Card support Remote Operator

KISAAlgorithms Support for KISA algorithm suite (KCDSA, SEED, HAS160 hash function)

Korean Algorithms.

GeneralSEE Allows any SEE machine to be loaded. Available only within CGEA locations.

SEE Activation (EU+10)

EllipticCurve Allows small key sizes to provide improved levels of security.

Elliptic Curve



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


15 nShield Administrator Utilities floodtest

floodtest

The floodtest utility performs hardware speed testing using modular exponentiation with the Chinese Remainder Theorem.

Usage

C:\nfast\bin\floodtest.exe [--crt|--no-crt] [-Q|--query] [-R|--no-round-robin] [-l|--

job-size=BITS]

[-t|--stop-after=TIME] [-j|--outstanding-jobs=COUNT] [-n|--jobs-count=COUNT]

[[[-K|--skew-check=SKEW ]| [-T|--min-check=COUNT ]] [-C|--check-start=TIME ]]

[--overprint][-o|--output=FILE] [-r|--report-interval=TIME]

Program options

--crt

This option specifies use of CRT optimization. This is the default.

--no-crt

This option specifies no use of CRT optimization

-Q, --query

These options specify use Query mode (spinlock) rather than Wait mode

-R, --no-round-robin

These options specify that replies be accepted in any order. (The default is that replies are accepted on a round-robin basis.)



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



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



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.


15 nShield Administrator Utilities hardserver

hardserver

The hardserver is the communications service between applications and nCipher modules.

You must be logged in as Administrator to use the command-line options for this command.

Usage

hardserver.exe [-c|--command-line]

The hardserver is configured by means of configuration files. See Hardserver configuration file on page 85 for information.

The -c or --command-line options run the hardserver program as a command line program instead of as a service

Hardserver startup

The hardserver utility is the hardserver program. It is installed as a service and started automatically.

On startup, the hardserver looks for scripts in the %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.


15 nShield Administrator Utilities hardserver

Stopping the hardserver

1. Ensure that you are logged in as a user who is permitted to stop and that services (for example, a Local Administrator).

2. Open the Computer Management dialog. This is usually found by choosing Programs > Administrative Tools from the Start menu.

3. Highlight the Services entry under Services and Applications. nFast Server should be listed with the status Started.

4. Scroll down the list of services until you have highlighted the nFast Server entry, and click the Stop button in order to stop the server.

Restarting the nCipher server

1. Ensure that you are logged in as as a user who is permitted to create privileged connections.

2. Open the Computer Management dialog. This is usually found by choosing Programs > Administrative Tools > Computer Management from the Start menu.

3. Highlight the Services entry under Services and Applications. nFast Server should be listed with the status Stopped.

4. Scroll down the list of services until you have highlighted the nFast Server entry, and click the Start button in order to restart the server.


15 nShield Administrator Utilities initunit

initunit

The initunit utility initializes a unit with a random module key and a known KNSO. This utility makes a key-management module usable but does not enable any key archival or recovery.

Usage

In order to use initunit, you must be logged in to the host computer as root or as a user in the group nfast and must start the module in the pre-initialization state. See Entering the pre-maintenance state on page 76 for information on putting the module into a pre-initialization state.

C:\nfast\bin\initunit.exe [-m|--module=MODULE] [-n|--ntoken]

In this command:

-m, --module=MODULE

These options specify the module number (MODULE) of the module you want to initialize. If you do not specify a module, initunit initializes all modules that are in a pre-initialization state.

-n, --ntoken

These options specify the initialization of a module as an nToken.


15 nShield Administrator Utilities initunit

Output

If initunit is successful, it returns a message similar to this for each module that has been initialized:

Initialising Unit #

Setting dummy HKNSO

Module Key Info:

HKNSO ###################HKM ###################

Otherwise, it returns an error message that points to the reason for the initialization failure.


15 nShield Administrator Utilities loadkeys

loadkeys

The loadkeys utility is used with a payShield installation. It imports, generates or exports keys. Its use is described in full in the Keyloading Solution Guide.

Usage

C:\nfast\bin\loadkeys.exe [options] psiname

In this command, psiname is the name of the payShield installation that you are going to import the key into. psiname must consist of 16, or fewer, lower case alphanumeric characters.

Options

Modes of Operation

-I, --import

These options import a key (requires --format option).

-E, --export

These options export a key (requires --format option).

-G, --generate

These options generate a new key.

--batch

This option specifies that the application does not prompt for nonessential options that have not been specified on the command line. Non-essential options include key export options, rolespecific options and group memberships.



General options

-m, --module=MODULE

These options select the hardware security module to use. The default is 1.

-f, --format=FORMAT

These options specify the import or export format for the key. This can be wrapped or components.

--kcvf=CV_FORMAT

These options specify the key Check Value format. This can be one of none (for no check value), zero (for the encryptzeros method) or self (for the encrypt-self method).

-d, --debug

These options enable library debugging.

-k, --key-name=NAME

These options specify the name for the imported key. This can be either the name of the key to be exported or the name to give the newly imported key, depending upon the operation.

Import/Generate options

-l, --length=LENGTH

These options set the lengths for each component. LENGTH can be 8, 16 or 24 bytes.

This is equal to the length of the resulting derived key, or half the length of the derived key if you are importing cvk or cvkv keys.



You can omit this option if the key type specified in --role=ROLE has only one permitted length.

-r, --role=ROLE

These options specify the role for the imported key

-g, --group=NAME

These options add the key to group NAME. NAME can be a maximum of 16 characters. The option may be specified multiple times.

-a, --export-attended

These options makes the key exportable in attended operations.

-A, --no-export-attended

These options specify that the key is not to be exportable in attended operations.

Component options

--ccvf=CV_FORMAT

These options specify the component Check Value format. This can be one of none (for no check value), zero (for the encrypt zeros method) or self (for the encrypt-self method).

-n, --num=COMPONENTS

These options specify the total number of components. This can be an integer from 2 through 9.



Wrapped options

-w, --wrapper=NAME

These options specify the name of the wrapping key. key. If the payShield key that you specify cannot be loaded, the application prompts you for another name.

Reduced AC import options

-i, --iipb=MASK

These options specify the IIPB mask to be used with this reduced AC key operation. The default is ffff000000000000.

IBM PIN key options

--dtable=TABLE

This option specifies the decimalization table that is to be used with a new PVKIBM key.

--pan-n=PAN

This option specifies the number of PAN digits to be required for PIN generation with a new PVKIBM key. PAN can be an integer from 0 through 12: the default is 12.


15 nShield Administrator Utilities key-xfer-im

key-xfer-im

The key-xfer-im utility transfers a key into a second security world. The module must previously have had the second security world’s module key loaded using the mk-reprogram utility, described in mk-reprogram on page 255. (See Transferring keys between security worlds on page 185.)

Usage

key-xfer-im SOURCE-KMDATA-LOCAL DESTINATION-KMDATA-LOCAL NEW-PROTECT KEY-FILE [KEY-

FILE ...] [NEW-PROTECT KEY-FILE [KEY-FILE ...]]

Parameters

SOURCE-KMDATA-LOCAL

The full path name of the kmdata file for the source security world.

DESTINATION-KMDATA-LOCAL

The full path name of the kmdata file for the target security world.

NEW-PROTECT

The protection for the key in the target security world.

You must specify either --module or --cardset. If you specify --cardset, it must be followed by the key hash for the destination card set.

In addition, you can also specify options to configure the key protection further:



--export-leave

This option is used to leave the key’s list of operations requiring authorization from the Administrator Card Set (ACS)= the same. This is the default.

--export-add

This option is used to add export to the key’s list of operations requiring authorization from the ACS. This option is available only when exporting keys from a strict FIPS 140-2 level 3 security world into a non-strict FIPS 140-2 level 3 security world.

--export-delete

This option is used to remove export from the key’s list of operations requiring authorization from the ACS. This option is available only when exporting keys from a non-strict FIPS 140-2 level 3 security world into a strict FIPS 140-2 level 3 security world.

--aclbase-recovery

This option is used to base the Access Control List (ACL) of the exported key on the ACL in the recovery key blob. This is the default.

--aclbase-working

This option is used to base the ACL of the exported key on the ACL in the working key blob.

KEY-FILE

This is the full path of source kmdata file for the key. The module must have module keys from both worlds: program it into one world with new-world and use mk-reprogram to



add the other module key. If transferring between Strict FIPS-140 level 3 and non-strict worlds, the module’s owning world must be non-strict.

The following example command demonstrates the second step in moving a module from a security world that is not FIPS 140 2 level 3 compliant to one that is:

key-xfer-im C:\nfast\kmdata\local\ C:\nfast\kmdata-FIPS\local\ --module --export-delete

KEY-FILE


15 nShield Administrator Utilities loadrom

loadrom

The loadrom utility loads new firmware into a module. Firmware is supplied as an encrypted and signed file. See Upgrading module firmware on page 323 for information on upgrading firmware.

You can also use loadrom to obtain information about the firmware.

Usage

C:\nfast\bin\ [-v|--view] [-n|--notypecheck] [-m|--module=MODULE]

[-b|--maxblocksize=SIZE] NFF_file

In this command NFF_file is the name of the file that contains the firmware. This has the extension .nff. See Appendix A: Upgrading module firmware for information on the file name for your module.

Help options

-h, --help

These options display help for loadrom.exe.

-V, --version

These options display the version number of loadrom.exe.

-u, --usage

These options display a brief usage summary for loadrom.exe.

Programming options

-v, --view

These options only display information about the .nff file and do not load it.


15 nShield Administrator Utilities loadrom

-i, --ioboard

This option is for nCipher internal use only.

-m, --module=MODULE

These options load the firmware on the module MODULE.

-b, --maxblocksize=SIZE

These options set the maximum block size in bytes for module programming.

--notypecheck

This option omits the module type check.

Output

If you select the --view option, loadrom displays output similar to this:

File :..\..\module\firmware\2-18-13\ncx3p-21.nff

Firmware : PCI Type 3 firmware version 2.18.13cam1 (VSN 21)

for : nC1003P/nC3023P

Filetype : NFast3

Programming chunks: 12

Confidentiality key:

nC3023P confidentiality key (dorris #2)

Confidentiality mech:

DES3mCBCi64pPKCS5

Signatures:

#0: <unknown> integrity key

#1: nC3023P integrity key (dorris-1)

During installation and when upgrading module firmware you can compare the output of loadrom --view with the information provided by the enquiry command-line utility to ensure that the correct version of the firmware is present on the module. See enquiry on page 229.


15 nShield Administrator Utilities mk-reprogram

mk-reprogram

The mk-reprogram utility programs a security-world module key into a module to which it does not yet belong. A key that is to be transferred from one security world to another must be loaded into a module that:

• has been programmed into one of the security worlds

• has had the module key of the target security world loaded into it using mk-reprogram.

After the security-world module key has been loaded, you can use the key-xfer-im utility to transfer a key into the second security world. (See Transferring keys between security worlds on page 185.)

Usage

mk-reprogram.exe [[--module MODULE-NO----] CHANGES

In this command CHANGES specifies the parameters of the reprogrammed security world, as described in Keywords on page 256. kmdata must be from the security world that includes the module.

Options

--module=MODULE-NO

specifies the module on to which to program the security world. The default is the first available module.

--protocol

specifies the protocol to use.

--owner kmlocal-path

specifies the path to the source module's kmlocal directory.


15 nShield Administrator Utilities mk-reprogram

Keywords

CHANGES can be one of the following:

list

lists the details of the security world.

add kmdata-path

adds the path to the local kmdata directory. This directory must be from the security world that includes the specified module.

delete MODULE-KEY-HASH

deletes the specified module key hash.

Example

The following example command demonstrates the first step in moving a module-protected key from a security world that is not FIPS 140 1 level 3 or FIPS 140 2 level 3 compliant to one that is:

mk-reprogram --module 1 add C:\nfast\kmdata_FIPS\local


15 nShield Administrator Utilities ncversions

ncversions

The ncversions utility displays installed nCipher support software components and their versions. The utility lists all components, whether installed individually or as part of a component bundle, and also the component bundles themselves. See Components on nCipher CD-ROMs on page 330.

Usage

C:\nfast\bin\ncversions.exe

Output

The following in an example of a component list produced by ncversions:

Comp Output Version Repository/Build no.

----------------------------------------------------------------

convrt user 1.1.0 cam/1

csee armdev 0.10.5 cam/3

csee seedev 0.10.5 cam/3

ctd agg 0.0.12 cam/4

ctls agg 0.0.13 cam/3

cutils devel 1.4.2 cam/8

emvjni user 0.2.2 cam/36

emvspj user 0.2.6 cam/20

emvspj devel 0.2.6 cam/20

emvspp user 1.5.10 cam/14

emvspp devel 1.5.10 cam/14

gcchk user 1.1.1 cam/2

... ... ... ...

... ... ... ...

ncversions displays a line of information for each component:


15 nShield Administrator Utilities ncversions

Comp

This gives the component's identifying code

Output

This identifies the type of component, such as:

• user for a user component

• devel for a developer component

• agg for a component bundle

Version

This identifies the version of the component

Repository/Build no.

This identifies the repository and build number.


15 nShield Administrator Utilities new-world

new-world

The new-world utility creates a security world that supports SEE functions and remote Operator Card Set use. new-world also allows you to specify different thresholds for different operations, such as:

• adding a module

• replacing an Operator Card Set

• authorizing real-time clock operations

• authorizing nonvolatile memory operations.

new-world can also be used to add a module to an existing security world.

To use the new-world utility, you must be logged in to the host computer as Administrator or a user who is permitted to create privileged connections.

Note If you create a security world with new-world, this security world is created with only one module. If you use other modules, then you must add them to the security world with new-world or KeySafe.

Usage

new-world -i|initialize [-S|--no-remoteshare-cert][-o|--overwrite][-F|--strict-fips-

140-level-2-level-3] [-R|--no-recovery][-m|--module]MODULE] -Q|--acs-quorum=K/N FEATURES

-k|--km-type=KEY-TYPE [--reduced-features]

new-world -l|program [-S|--no-remoteshare-cert][-m|--module=MODULE]

new-world -e|--factory -m|--module=MODULE



Module selection option

-m, --module=MODULE

These options specify the module to use. new-world initializes only one module at a time. If you have multiple modules, you must run new-world once for every module. The default is 1.

Action selection options

-i, --initialize

These options tell new-world to initialize a new security world and program it into the module specified in --module=MODULE, replacing any existing kmdata directory.

-l, --program

These options tell new-world to load the existing security world from the kmdata directory into a module specified in --module=MODULE.

-e, --factory

These options tell new-world to erase a module, restoring it to factory state.

Note You must not include more than one of the --initialize, --program, and --factory options. If you do not specify any of these options and a kmdata directory already exists, new-world loads the security world found within the directory. If you do not specify any of these options and no kmdata directory exists, new-world creates a security world.



Module reprogramming options


These options tell new-world that the selected module is not a target for remote shares.

New security world options

-Q, --acs-quorum=K/N,

In these options K is the maximum number of smart cards required from the Administrator Card Set to authorize a feature. You can specify lower thresholds for a particular feature. Thresholds must be less than or equal to the total number of cards in the set.

N is the total number of smart cards to be used in the Administrator Card Set. This value must be less than or equal to 64.

Note You should not create an Administrator Card Set for which the required number of cards is equal to the total number of cards because you cannot replace the Administrator Card Set if even a single card is lost or damaged.

The --acs-quorum=K/N option only takes effect if you are creating a new security world.



-F, --strict-fips-140-2-level-3

These options create a security world that conforms to the FIPS 140-2 requirements for roles and services at level 3. If you do not specify this flag, new-world creates a security world that complies with FIPS 140-2 requirements for level 2.

Note This option provides compliance with the roles and services of the FIPS 140-2 level 3 standard. It is included for those customers who have a regulatory requirement for compliance.

The current release of the nCipher PKCS #11 library works with a FIPS 140-2 level 3 compliant security world. However, if you intend to use the security world with the PKCS #11 applications iPlanet Enterprise Server or iPlanet Proxy Server, do not specify this flag.

The --strict-fips-140-2-level-3 option only has any effect if you are creating a new security world.

-O, --overwrite

These options tell new-world to allow the use of smart cards that already contain data. Any existing data is erased. If a value for this flag is not specified, new-world prompts you if a card contains data.

-R, --no-recovery

These options tell new-world to disable Operator Card Set recovery. The effect of setting this flag is the same as for specifying the feature !r.

By default, new-world creates key-recovery material that is protected by the cryptographic keys on the Administrator Card Set. This option does not give nCipher or any other third party access to your keys. Keys can only be recovered by using the Administrator Cards. nCipher recommends that you leave Operator Card Set recovery enabled.



If you do not enable this option at the time of security world creation, you can never enable recovery for keys in the security world.

If you do not enable this option when you create the ACS, you can never enable recovery for any card sets protected by the ACS.

-k, --km-type=KEY-TYPE

These options specify the type of key that is to protect the new security world. KEY-TYPE can be des3 or rijndael).

Features

When initializing a security world, features may be specified as arguments after the module number. Some features are enabled by default, and you can give the command new-world --help-features to display a list of features indicating which are enabled by default when initializing a security world with new-world.

Features are specified as a comma-separated list of terms. Each term consists of a feature name, optionally preceded by either a dash (-) or an exclamation point (!) to turn off the feature and can optionally be followed by an equal sign (=) and the threshold for this feature.

However, the ! character, used to turn off a given feature, is interpreted by some shells (for example, the C shell and its derivatives, bash and zsh) as requesting a history expansion. In such cases, you must escape the ! character by preceding it with a \ character, as in the following example:

new-world 2 rtc,nv,\!r

Additionally, any feature entered on the command line with a leading hyphen (-) can be interpreted as an option. Attempting to pass a feature as a nonexistent option in this way returns an error (for example, unknown option). Prevent errors of this kind by using the



standard POSIX double hyphen (--) marker to indicate that any subsequent features on the command line are not to be interpreted as options, as in the following example:

new-world -m 2 -- -r

Currently understood feature names are:

• m, for module programming (this feature cannot be disabled)

• r, for Operator Card Set recovery

• p, for pass phrase recovery

• dsee, to make an SEE debugging key

• dseeall, enable SEE debugging without authorization

• nv, for nonvolatile memory allocation

• rtc, real-time clock setting

• fto, Foreign Token Open authorization. Use this feature with ISO Smartcard Support.

The dsee and dseeall options are not applicable unless you have purchased and installed nCipher’s CodeSafe Developer kit.

For example, the following features:

m=1,r,!p,nv=2,rtc=1

create a security world for which:

• a single card from the Administrator Card Set is required to add a new module

• the default number is required to replace an Operator Card Set

• pass phrase recovery is not enabled

• 2 cards are required to allocate nonvolatile memory



• 1 card is required to set the real-time clock.

Note Under most conditions, it is advisable to turn on such features as nv, rtc, dsee, and (if desired) p. There is usually no benefit in turning on both dsee and dseeall simultaneously.

Output

If new-world cannot interpret the command line, it displays its usage message and exits.

If you attempt to set a threshold for a feature that you have disabled or if you attempt to set a threshold too high, new-world displays an error and exits.

If the module is not in the pre-initialization state, new-world displays and error and exits. To put the module in the pre-initialization state, see Entering the pre-maintenance state on page 76.


When new-world has initialized the module, restart the module in the operational state.


15 nShield Administrator 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 the Operator Guide for more details.

Do not store keys in NVRAM unless you must do so to satisfy regulatory requirements.

Note nCipher introduced NVRAM key storage only for users who must store keys within the physical boundary of a module to comply with regulatory requirements. NVRAM-stored keys provide no additional security benefits and their use exposes your Administrator Card Set to increased risk. Storing keys in nonvolatile memory also reduces 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.



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.


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



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

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



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

General options

-f, --force

These options force nvram-backup to delete or overwrite a file without requesting confirmation.

-v, --verbose

These options provide verbose output.

-x, --hex

These options specify that hex notation is used for the file selection option.

--no-length

When used with the --list option, the --no-length option specifies that file lengths are not printed.



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

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.



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 .

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.

Enter


15 nShield Administrator Utilities nvram-sw

nvram-sw

The nvram-sw utility views and modifies NVRAM areas.

Usage

C:\nfast\bin\nvram-sw.exe -a|--alloc [-m|--module=MODULE] [-b|--bytes=BYTES] [-n|--

nvram-id=ID] [-k|--key=APPNAME,IDENT][--no-copy]

C:\nfast\bin\nvram-sw.exe -d|--delete [-m|--module=MODULE] [-n|--nvram-id=ID]

C:\nfast\bin\nvram-sw.exe -w|--write [-m|--module=MODULE] [-f|--file=FILE]

C:\nfast\bin\nvram-sw.exe -r|--read [-m|--module=MODULE] [-f|--file=FILE]

C:\nfast\bin\nvram-sw.exe -c|--delete-noadmin [-m|--module=MODULE] [-n|--nvram-id=ID]

C:\nfast\bin\nvram-sw.exe -i|--acl [-m|--module=MODULE] [-n|--nvram-id=ID]

C:\nfast\bin\nvram-sw.exe -l|--list [-m|--module=MODULE]

C:\nfast\bin\nvram-sw.exe -a|--alloc [-m|--module=MODULE] [-b|--bytes=BYTES] [-n|--

nvram-id=ID] [-k|--key=APPNAME,IDENT][--no-copy]

Help options

-h, --help

These options display help for nvram-sw.exe.



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


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



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



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



nCipher uses following identifying characters:

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:

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.



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.


15 nShield Administrator Utilities payshield-config

payshield-config

The payshield-config utility modifies the payShield installation’s settings. The utility must be run immediately after running payshield-install or payshield-install - -retarget to complete the setup or retargeting of the payShield installation.

This utility can be used to enable the AcquirePIN Clear PIN functionality. It uses its own key role which is incompatible with other payShield PIN functions (KeyRole_AWK). Use of this function is not recommended as best practice. You should only enable the AcquirePIN function if the payShield installation will be running in a physically secure location with trusted operators and network at all times.

Any PIN entered via the AcquirePIN function cannot be considered to be secured by the module. Using the same PIN and PAN combination for both AcquirePIN and PVV/Offset PIN operations may therefore negate the security of PVV/Offset.

This utility can also be used to enable IBM PIN functions and unattended key import and export. Enabling these functions may reduce the security of the system and is not recommended. If any of these functions are needed, the proper restrictions should be applied. If you are not sure whether you need these functions, or do not know what the proper restrictions are, please contact nCipher Support.

Usage

payshield-config.exe [-h|- -help][-v|- -version][-u|- -usage] [{-m|--module}=MODULE]

[{-s|- -slot}=SLOT] [{-c|--configfile}=FILENAME] [{-d|--dump-config}=FILE] [--

helpfeatures]PSINAME FEATURES

-m, --module=MODULE



15 nShield Administrator Utilities payshield-config

-s, --slot=SLOT

These options identify the slot to use. The default is 0.

-c, --configfile=FILENAME

These options specify the configuration file to insert into the PUD. If the option is not used, then a default configuration is written to the PUD, unless one is already present.

-d, --dump-config=FILENAME

These options dump the configuration file that is stored in the PUD.

--help-features

This option describes the syntax for non-interactive feature selection, including a list of features that can be specified in the comma-separated list FEATURES.

Altering the Installation Settings

The following settings can be changed using the payshield-config utility:

• which payments functions are enabled or disabled

• acceptable PINBlock formats for PIN operations

• acceptable import and export formats for key roles.


15 nShield Administrator Utilities payshield-info

payshield-info

The payshield-info utility displays information about a specified payShield installation.

Usage

payshield-info.exe [-i|--info][-k|--keys][-n|--name]=keynamePSINAME

General options

-V, --verbose

These options display verbose key details, where applicable.

-s, --sort=KEY

These options select the output sort mode for the --keys and --roles modes.

Operation mode options

-i, --info

These options display basic information about the PSI.

-k, --keys

These options display keys for the named PSI.

-f, --features

These options display the features enabled in the PUD.

-c, --config

These options dumpt the configuration files stored in the PUD.



-n, --name=keyname

These options display detailed information about the named key.

-r, --role=keyrole

These options display all the keys in the payShield installation named PSINAME that have the role specified in keyrole (for example, PVKP). To view keys for which role information is unavailable, use --role=unknown.

Keywords

PSINAME

The name of the payShield installation to provide information about.

Output

The following information is displayed:

• The name of the payShield installation

• The version of the SEE machine in use

• The K and N values of the Master Card Set

• The K and N values of the Key Establishment Card Set

• The hash of the Master key

• The hash of the Key Establishment Key

• The maximum possible number of loaded keys

• The flags that are set on the payShield installation



For example:

PSI Name: qapsi

EMVSM version: 1.0.6+ 2003-01-13 16:55:51. jgeater

Master Key Hash: d42e1791a4e5ea5021444e521bb2c650093efd4d

Estab Key Hash: a06fe51b52725b344dade13a59466bdb77400c1f

Max Keys: 1000

Flags (0x3e0000): TotallyInsecure InsecureImport InsecureDebug

SmartcardImport UnrestrictedImport

Cardsets:

allocated 0053BCD8

Estab CardSet: 1/1 (aaa002b568604e5bbc3a63dcdb0209cd478f317b)

Master CardSet: 1/1 (b9a595b21446ca82dee93a482d60848ec0f1b5dd)


15 nShield Administrator Utilities payshield-install

payshield-install

The payshield-install utility is used to configure a security world specifically for the requirements of your payShield installation.

Usage

payshield-install.exe [--master-quorum=K/N --estab-quorum=K/N[{-m|--module}=MODULE] [{-

s|- -slot}=SLOT] [{-A|- -adminslot}=ADMIN_SLOT] [{-L|--max-loaded-keys}=NUM] [--non-

fips-temporarykeys] [--totally-insecure] [--override-keyhash-check] [-D|- -allow-

insecure-debug] [-S|--allow-smartcard-import] [-I|- -allow-insecure-import] [-U|- -

allow-unrestricted-import] [--require-estab-always] [--retarget-see-machine] [--

acquirepin-wait=INT] PSINAME KEYHASH

Security options

--master-quorum=K/N

This option specifies the K-of-N sharing parameters for the Master card set. The default is 3 of 5 (3/5).

--estab-quorum=K/N

This option specifies the K-of-N sharing parameters for the Key Establishment card set. The default is 2 of 4 (2/4).

-m, --module=MODULE


-s, --slot=SLOT

These options specify the slot to use. The default is 0.

-A, --adminslot=SLOT

These options specify the slot to use for loading FIPS and FTO authorizations. The default is 0.



-L, --max-loaded-keys=NUM

These options specify the maximum number of keys the SEE machine is allowed to load (default=1000).

--non-fips-temporarykeys

This options prohibits the passing of temporary keys through the hardware security module’s firmware.

--totally-insecure

This option allows you to set the --allow-insecure-debug and --allow-insecure-imports options, which make the installation totally insecure.

--override-keyhash-check

This option overrides the key hash check against known payShield SEE machine signing key hashes.

-D, --allow-insecure-debug

These options allow the generation of insecure debug. They require you to have also set the --totally-insecure option.

-S, --allow-smartcard-imports

These options allow the import of keys from smart cards.

-L, --allow-insecure-imports

These options allow the importing of keys non-interactively. They require you to have also set the --totally-insecure option.

-L, --allow-insecure-imports

These options allow the importing of keys non-interactively. They require you to have also set the --totally-insecure option.



When these options are set, you can use the payShield/Verifone key import method to import non-payShield keys into your security world. These keys are described as unrestricted because they are imported as module protected and their encrypt/decrypt ACL permissions are not restricted by a certifier or SEE world.

-U, --allow-unrestricted-imports

These options allow the importing of keys with ACLs that allow unrestricted use.

--require-estab-always

This option requires establishment cards to be presented for unrestricted key imports.

This is not a security feature.

--acquirepin-wait=INT

This option forces at least INT centiseconds of elapsed time between AcquirePIN operations. The default is 0 (that is, no rate limiting).

The delay rate for AcquirePIN is enforced separately for each module. If you have two nShield modules, then two AcquirePIN operations are allowed in the specified time period.

Keywords

PSINAME

This is the payShield installation name, which must be of 16 or fewer lowercase alphanumeric characters.

KEYHASH

This is the hash of the nCipher SPP SEE machine signing key.


15 nShield Administrator Utilities postrocs

postrocs

The postrocs utility performs clean-up tasks after key-xfer-im has been used to transfer keys that protect PKCS #11 objects.

Usage

C:\nfast\bin\postrocs [-m|--module=MODULE] [-s|--slot=SLOT]

Help options

-h, --help

These options display help for postrocs.exe.

-V, --version

These options display the version number for postrocs.exe.

-u, --usage

These options display a brief usage summary for postrocs.exe.

Options

-m, --module=MODULE

These options specify the target module for the key transfer. The default is 1.

-s, --slot=SLOT

These options specify the target slot for the key transfer. The default is 0.


15 nShield Administrator Utilities ppmk

ppmk

This utility allows you to manage softcards. It can be used to perform the following tasks:

• listing softcards

• creating a new softcard

• checking or changing a 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.



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



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


15 nShield Administrator Utilities preload

preload

The preload command-line utility enables keys to be loaded onto a module before an application is run. The application can be run immediately in the same session or the first session can be paused and the application can be run in a separate session. Additional keys can be loaded while a session is running.

For applications that do not support K-of-N Operator Card Sets, preload enables K-of-N Operator Card Sets and module-protected keys to be loaded before the application is run. You can use the preload command to preload K-of-N Operator Card Sets before running PKCS #11 applications.

Some command-line options may cause preload to function interactively by prompting for Operator Cards.

Note Currently, preload can be used only with command-line utilities.

Usage

C:\nfast\bin\preload.exe [-m MODULE|--module=MODULE] [-c IDENT|--cardset=IDENT] [--

cardset-name=NAME] [-s IDENT|--softcard=IDENT] [-o|--any-one] [-i|--interactive] [-A

APP|--appname=APP] [-K PATTERN|--key-ident=PATTERN] [-n PATTERN| --name-pattern=PATTERN]

[--name-exact=NAME] [-M|--module-prot] [--no-cardset-keys] [--admin=NAME] [-F|--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.



Card set selection options

Note The current release of the preload command-line utility cannot load softcards; use the ppmk command-line utility to load softcards (see ppmk on page 287). However, the preload command can load softcard-protected keys; see Key selection options on page 292.

-c IDENT, --cardset=IDENT

These options specify that all Operator Card Sets that match IDENT are to be loaded. The IDENT variable can be the hash or the name of a card set; the preload command tries to guess whether IDENT is a hash or a name based on the form you supply.

If you definitely want to preload a named card set, use the --cardset-name=NAME option instead.

Use KeySafe or the nfkminfo command-line utility to identify keys and cards that are used by particular applications. For further information, see the appropriate Operator Guide for your module. Card set patterns or names are treated as substrings.

--cardset-name=NAME

This option specify an Operator Card Set with the given name NAME to be loaded.

-o, --any-one

This option loads a single Operator Card Set and then stops.

-i, --interactive

This option causes preload to load Operator Card Sets interactively until you tell it to stop.



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



nfkminfo command-line utility in order to identify keys that are used by particular applications. For further information, see the appropriate Operator Guide for your module.

-n PATTERN, --name-pattern=PATTERN

These options load all keys (for the APP specified by --appname) whose name includes or matches PATTERN. PATTERN is treated as a substring. You can set multiple instances of these options to load keys that match more than one pattern.

If you want to load a particular named key, use the --name-exact=NAME option instead.

--name-exact=NAME

This option loads the key whose name is specified by NAME for the APP specified by --appname.

-s IDENT, --softcard=IDENT

These options load all keys protected by softcards matching IDENT. The IDENT variable can be the hash or the name of a softcard; the preload command tries to guess whether IDENT is a hash or a name based on the form you supply.

Note The current release of the preload command-line utility can only load softcard-protected keys, not softcards themselves. To load softcards, use the ppmk command-line utility; see ppmk on page 287.

If you definitely want to preload a named softcard, use the --softcard-name=NAME option instead.

Use the ppmk or nfkminfo command-line utilities to identify keys and softcards that are used by particular applications. For further information, see the appropriate Operator Guide for your module. Softcard patterns or names are treated as substrings.



--softcard-name=NAME

This option loads all keys protected by softcards matching NAME.

Note The current release of the preload command-line utility can only load softcard-protected keys, not softcards themselves. To load softcards, use the ppmk command-line utility; see ppmk on page 287.

Use the ppmk or nfkminfo command-line utilities to identify keys and softcards that are used by particular applications. For further information, see the appropriate Operator Guide for your module. Softcard patterns or names are treated as substrings.

-M, --module-prot

These options load module-protected keys in addition to any keys specified by other options.

--no-cardset-keys

This option specifies that keys protected by the requested Operator Card Sets are not automatically loaded.

--admin=KEYS

This option loads the administrator keys specified by KEYS; to load more than one administrator key, the value of KEYS can be a comma-separated list, or you can. specify all to load all administrator keys. Allow administrator keys are: NSO, M, RA, P, NV, RTC, FIPS, MC, RE, DSEE, and FTO.

Note When using preload to load non-persistent tokens, you must ensure that you have enough remaining Operator Cards in order to load the token onto the final module. Usually, this means you need one or more cards than you have modules, depending on the circumstances. For example, if you have 4 modules and K is 3, then N must be at least 6 so that there are at least 3 cards remaining to load the token onto the final module.



FIPS options

-F, --require-fips

These options specify that FIPS authorization is required.

-N, --no-fips

These options specify that FIPS authorization must never be loaded. The default is to load FIPS authorization if possible but not to fail if loading FIPS authorization is not possible.

Loading options

-f PRELOADFILE, --preload-file=PRELOADFILE

These options specify a preloaded objects file to be used.

-R, --reload-everything

These options specify the reloading of keys and tokens that are already loaded.

Output examples

If you want to load keys from a number of Operator Card Sets in module 2 and use them immediately in an application, for example, with nfkminfo, give the following command:

C:\nfast\bin\preload -R -m 2 nfkminfo

If there is no card in the specified module, preload displays the following message:

Loading cardset(s):

Module 2 slot 0: empty


Insert/change card(s) (or change module mode).



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

Loading cardset(s):



Module 2 slot 0: 'pt2' #1

Module 2 slot 0: Enter passphrase:

Enter the appropriate pass phrase, and preload displays:

Loading cardset(s):




Module 2 slot 0:- passphrase supplied - reading card

Module #2 Slot #0: Remove card.

If you insert a card that has no pass phrase, preload displays:

Loading cardset(s):






Module 2 slot 0: 'ct' #1

Module 2 slot 0: Read this card? (press Return)



Press to confirm reading this card, and preload displays:

Loading cardset(s):






Module 2 slot 0: 'ct' #1

Module 2 slot 0:- confirmed - reading card


Being finished, now press - , and preload displays:

Loading cardset(s):

Loaded seeconf testconf key (DES3) on modules 2

Loaded seeinteg testinteg key (RSAPrivate) on modules 2

Loaded simple cs key (DES3) on modules 2

Loaded simple test12 key (RSAPrivate) on modules 2








Executing nfkminfo

To preload a specific key with an ident of mykey for the application seeconf on all modules, give the following command:

C:\nfast\bin\preload -A seeconf -K mykey pause

Enter

Ctrl D



The preload command then displays the following message:

Loading 'pt2':




Insert/change card(s) (or change module mode).

Insert a card in module 1, and preload displays:

Loading `pt2':




Module 1 slot 0: `pt2' #1



Loading 'pt2':






Module 1: completed.


Remove the card, and preload displays:

Loading 'pt2':







Module #1 Slot #0: Insert appropriate card.



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

Loading 'pt2':








Module #1 Slot #0: Insert appropriate card.

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

Loading 'pt2':










Loading 'pt2':









Card reading complete.

Loaded seeconf testconf key (DES3) on modules 1, 2

Loading complete; now pausing



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.


15 nShield Administrator Utilities racs

racs

The racs utility creates a new Administrator Card Set to replace a set that was created with the new-world utility.See Replacing an Administrator Card Set with racs on page 225.

Usage

racs [-m|--module=MODULE]

Options

-m, --module=MODULE

These options specifies the ModuleID to use.


15 nShield Administrator Utilities rfs-setup

rfs-setup

This utility creates a default remote file system on the client. You run rfs-setup when you first configure a client. See Setting up client cooperation on page 53 for details of client configuration.

Usage

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


15 nShield Administrator Utilities rfs-setup

--write-noauth

This option allows cooperating clients to access the remote file system without HKNETI authorization. You do not need to supply module_ESN or keyhash with this option.

nCipher does not recommend using the --write-noauth option except on completely secure networks.

module_IP_address

This option specifies the IP address of the module.

module_ESN

This option specifies the ESN of the module.

keyhash

This option specifies the HKNETI (key hash) of the module.

You can obtain the ESN and HKNETI of the module from the module’s front panel. You can also obtain it with the anonkneti utility. See anonkneti on page 227 for details.


15 nShield Administrator Utilities rfs-sync

rfs-sync

This utility synchronises the kmdata between a cooperating client and the remote file system it is configured to access. It should be run when a cooperating client is initialised in order to retrieve data from the remote file system and also whenever a client needs to update its local copy of the data or, if the client has write access, to commit changes to the data. See Chapter 3: Getting the module working for more details about client cooperation.

Usage

C:\nfast\bin\rfs-sync.exe [-U|--update] [-c|--commit] [-s|--show] [--remove] [--setup

[setup_options] ip_address]

Options

-U, --update

These options update local key-management data from the remote file system.

Note If a cooperating client has keys in its kmdata/local directory that are also on the remote file system, if these keys are deleted from the remote file system and then rfs-sync --update is run on the client, these keys remain on the client they are until manually removed.

-c, --commit

These options commit local key-management data changes to the remote file system.

-s, --show

These options display the current synchronisation configuration.



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



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.


15 nShield Administrator Utilities rtc

rtc

The rtc utility reads the time from a module’s onboard real-time clock. It can also be used to set the clock.

Usage:

rtc [[-g|--get-clock]|[-t|--set-clock [-a|--no-admin-keys] [-A|--adjust]]] [-m|--

module=MODULE] TIME


-g, --get-clock

These options tell rtc to read the module’s clock time. This is the default if no action option is specified.

-t, --set-clock

These options tell rtc to read the module’s ’s clock time to TIME.

Clock setting options

-a, --no-admin-keys

These options tell rtc not to read Administrator cards.

--adjust

This option tells rtc to calibrate the clock drift.

Module selection option

-m, --module=MODULE

These options tell rtc to read or write the clock of the module MODULE. If MODULE is not specified, the default is 1.



Reading the clock

Use the command:

rtc [-g|--get-clock] [-m|--module=MODULE]

In this command:

• --get-clock if used explicitly tells rtc to set the clock.

• --module=MODULE tells rtc to set the clock and adjust the drift rate.

rtc returns a message similar to this:

time on module 1 is 2001-03-21 12:33:12

Note The rechargeable back-up battery in some nShield modules (used to maintain RTC operation when the module is unpowered) can last as long as two weeks without recharging. If the module is without power for longer than this, the battery is discharged and RTC time is lost; no other nonvolatile data is lost if this occurs. In such a case, however, attempts to read the clock (such as with ncdate or rtc) return a BadTokenData error status. You can resolve this by resetting the clock and leave the module powered up for at least 10 hours to recharge the battery to recharge.

Setting the clock

Use the command:

rtc [[-t|--set-clock]|[-A|--adjust]] [-a|--no-admin-keys] [-m|--module=MODULE] [TIME]

In this command:

• --set-clock tells rtc to set the clock.

• --adjust tells rtc to set the clock and adjust the drift rate.



• --no-admin-keys tells rtc not to read the Administrator Card Set.

• --module=MODULE specifies the ModuleID to use.

• TIME is the time to which to set the clock in the form YYYY-MM-DD/HH:MM:SS, where -, /, and : are arbitrary delimiter characters that can be any non-numeric character.

Unless you give the --no-admin-keys option, rtc prompts you for the number of cards required from the Administrator Card Set to enable it to set the real-time clock.

If you do not specify a time, rtc uses the time from the host computer's clock.

If you specify a time, rtc asks you to confirm the operation. This feature enables you to check that you have entered the time correctly.


15 nShield Administrator Utilities slotinfo

slotinfo

The slotinfo utility returns information about the tokens that are present in a module. slotinfo can also be used to format a token.

Usage

C:\nfast\bin\slotinfo -m|--module=MODULE [-s|--slot=SLOT]

Module selection

-m, --module=MODULE

These options specify the module number of the module to be used. You must specify a module number.

-s, --slot=SLOT

These options specify the number of the slot to be used. If this option is set, slotinfo returns information about the files on the token. If, however, you do not specify --slot, slotinfo returns information about all slots.

--format

This option tells slotinfo to format the token that is currently in the slot. You must specify a slot number if you want to format a token. The token is formatted without a challenge response key.

Note Use of the --format option is deprecated. If you use slotinfo with the --format option to format a token, it does not remove the card from the security world lists and cannot erase cards in FIPS 140-2 level 3 compliant security worlds.

slotinfo does not update the security world host data. If you are using an nCipher security world:


15 nShield Administrator 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


15 nShield Administrator Utilities sppupgradekeys

sppupgradekeys

The sppupgradekeys utility upgrades keys created on older payShield installations so that they can be used with newer payShield installations. You can use the optional EXPORTFILE to specify (by name) those keys that are to be allowed to be exported in attended operations.

Note This utility requires a quorum of administrator cards and must only run on a secure host.

Usage

sppupgradekeys [options] psiname [EXPORTFILE]

Options

-m, --module=MODULE

These options specify the number of the module to be used. The default is 1.

-s, --slot=SLOT

These options specify the number of the slot to be used. The default is 0.

--no-name-keys

This option prevents the names of keys being bound to their ACL. If you have already run sppupgradekeys, this will make the operation faster.


15 nShield Administrator Utilities sppupgradekeys

Key worlds

psiname

This is the name of the payShield installation that you are going to import the key into. psiname must consist of 16, or fewer, lower case alphanumeric characters.

EXPORTFILE

This is a file containing lines of the form:

NAME

Each line specifies, by name, a keys that can be exported.


15 nShield Administrator Utilities stattree

stattree

The stattree utility returns the statistics gathered by the nCipher server and modules.

Usage

C:\nfast\bin\stattree [<node> [<node> [...]]]

Output

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

Statistics are displayed in the form of a tree. At each node in the tree, either a set of statistics or a list of sub-categories is displayed. Each node has a label which consists of one of the following:

• a tag that identifies its contents as described in Node tags on page 316.

• a number the corresponds to an instance in the category, for example, a module identifier or a client connection identifier

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



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



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.



Statistics IDs

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.

Category Contains

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.



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.

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.

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.

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.

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.

ID Value


Appendix A: Upgrading module firmware

nCipher module firmware is supplied on your nCipher CD-ROM. The following sections describe how to load updated firmware onto you nCipher module.

There are separate instructions for modules that are mounted internally in your computer and those that are mounted in external boxes supplied by nCipher.

nCipher modules can be damaged by static discharge. nCipher recommends that you wear an anti-static wristband or similar device while handling modules.

Version Security Number

All nCipher firmware includes a Version Security Number (VSN). This number is increased whenever nCipher improves the security of the firmware or adds significant new functionality.

For firmware version 2.12.0 and subsequent releases, nCipher supplies several versions of the module firmware. You can always upgrade to firmware with an equal or higher VSN than that currently installed on your module.

You can never load firmware with a lower VSN than the currently installed firmware.

Ensuring you use firmware with the highest available VSN allows you to benefit from security improvements and enhanced functionality. It also prevents future downgrades of the firmware that could potentially weaken security. However, you may choose to install firmware that does not have the highest available VSN. For example, if you have a regulatory requirement to use FIPS-approved firmware, you should install the latest available FIPS validated firmware which may not have the highest VSN. Similarly, if you want to install a version with


A Upgrading module firmware Firmware on the CD-ROM

enhanced features without committing yourself to the upgrade, you can do so providing upgrade only to firmware with a VSN equal to that currently installed on your module.

In general, nCipher recommends using the latest firmware with the highest available VSN.

To support the use of Feature Enable, the VSN was increased for the firmware release 2.x.x. If you install this firmware in order to use optional features, you cannot then reload earlier firmware. For firmware versions 2.x.x and above, the firmware filenames have changed to include the model code of your module.

Firmware on the CD-ROM

Your nCipher CD-ROM contains several sets of firmware for each supplied product. These can include:

• the latest available FIPS-approved firmware with the base VSN

• the latest available FIPS-approved firmware with a higher VSN

• the latest available firmware awaiting FIPS approval with the base VSN

• the latest available firmware awaiting FIPS approval with a higher VSN.

Note For firmware release 2.12.0 only one version of the FIPS-approved firmware is supplied.

You should ensure you are using the latest firmware, unless you have a regulatory requirement to use firmware that has been FIPS validated. In the latter case, you should ensure that you are using the latest available FIPS validated firmware. See the release notes for details of current versions.


A Upgrading module firmware What must I do?

Firmware files are in the firmware directory on the CD-ROM, under a directory identified by the firmware version. To display information about a firmware file on the CD-ROM, enter the following command:

C:\nfast\bin\loadrom --view E:\firmware\ver\filename.nff

In this command, E is the drive letter of your CD-ROM, ver is a firmware version number and filename is a file name.

See loadrom on page 253 for full details of the loadrom utility.

What must I do?

In order to use the new firmware, you must:

1. Install the latest server software as described in Chapter 3: Getting the module working.

2. Install the latest firmware, as described below.

This appendix assumes that you have installed the nCipher server as a service. This is the default installation procedure described in Chapter 3: Getting the module working.

Where commands are described, it is assumed that you have installed the nCipher software in the default location, C:\nfast\. If you have chosen to install the nCipher software in another directory, replace references to this directory with the name of the directory in which you have chosen to install the software.

This chapter describes how to upgrade module firmware for nShield/payShield modules only. If you have another module refer to the corresponding chapter in the appropriate Administrator Guide.

Key data

The firmware upgrade process destroys all persistent data held in a key management module.


A Upgrading module firmware Firmware installation overview

If your security system requires that the persistent data held in a key-management module live beyond the upgrade or initialization of the key management module, a backup and recovery mechanism must be implemented.

If you are using an SEE program that stores data in nonvolatile memory, or NVRAM key storage, use the nvram-backup utility to backup your data before upgrading and to restore the data after the upgrade is complete. See nvram-backup on page 266 for further information on this utility.

Firmware installation overview

The process of installing or updating firmware on a nCipher module can be broken down into three basic steps:

1. Ensure the module is in maintenance mode (thus taking it out of any security world of which it is part).

2. Install the appropriate firmware.

3. Initialize the module.

This three-step process is diagrammed in Maintenance mode and firmware installation on page 327. The methods needed to change a given module to the maintenance mode and to initialize it after firmware installation depend on the model of module. Follow the directions in this appendix that are appropriate to the specific model of module whose firmware you are upgrading.


A Upgrading module firmware PCI modules

Figure 6 Maintenance mode and firmware installation

If you are upgrading a module which has SEE program data or NVRAM-stored keys in its nonvolatile memory, use thenvram-backup utility to backup your data before’s nonvolatile memory usingnvram-backup. See nvram-backup on page 266 for information on using this utility.

PCI modules

If you have a PCI module, you can upgrade the firmware without having to open your computer case, provided that the override switch is off. (Refer to the installation instructions in the Hardware Installation Guide for information on accessing the override switch and switching it off.)

To upgrade the firmware on a PCI module, follow these steps:

1. Log in to the host Administrator.

2. Place the mode switch in the maintenance position, as shown in Figure 7 or , depending on your module type.


A Upgrading module firmware PCI modules


3. Reset the module by pressing the Clear button or by issuing the nopclearfail command.

4. Use the enquiry command-line utility to check that the module is in the pre-maintenance state. (See enquiry on page 229 for information on using this utility.)

Note If the PCI module is still in the operational state, it means that the override switch is on. Refer to the installation instructions in the Hardware Installation Guide for information on accessing the override switch and switching it off.

5. Place the nCipher CD-ROM in the CD-ROM drive and mount it on your file system.

6. In order to load the new firmware, use the command:

C:\nfast\bin\loadrom E:\firmware\ver\filename.nff

In this command, E is the drive letter of your CD-ROM, ver is a firmware version number and filename is a file name.

The firmware files are signed and encrypted: you can load only the correct version for your module.

7. Switch the mode switch to the Initialization position.

Status LED

Clear switch

Mode switch

Smart cardconnector

DC power

MOI

J1 overrideJ2 unused

on off


A Upgrading module firmware After firmware installation

8. Reset the module by pressing the clear button until the LED flashes short pulses to indicate that the module is in pre-initialization state. Alternatively, issue the nopclearfail command.

9. Switch the mode switch to the Operational position.

10. Reset the module by pressing the clear button or by issuing the nopclearfail command.

11. Log in to the host as normal.

After firmware installation

After you have installed new firmware and initialized the module, you can create a new security world with the module or reinitialize the module into an existing security world.

If you are initializing the module into a new security world, see Creating a security world on page 129.

If you are reinitializing the module into an existing security world, see Adding or restoring a module to the security world on page 155.


Appendix B: Components on nCipher CD-ROMs

nCipher supplies the hardserver and associated software as bundles of common components that provide much of the required software for your installation. In addition to the component bundles, nCipher provides individual components for use with specific applications and features supported by certain nCipher modules. This appendix lists the contents of the component bundles and the additional software supplied on your nCipher CD-ROM. For information on installing the supplied software, see Chapter 3: Getting the module working.

You can list installed components, both those installed as part of the standard bundles and those installed individually, by using the ncversions command-line utility described in the Operator Guide appropriate to your module type.

nCipher component bundles

nCipher supplies component bundles containing many of the necessary components for your installation. Certain standard component bundles are offered for installation on all standard nCipher support software CD-ROMs, while additional component bundles are found on CipherTools and CodeSafe CD-ROMs.

Standard component bundles

You are always offered the following standard component bundles on all standard nCipher support software CD-ROMs:

Standard component bundles

hwsp Hardware Support (mandatory)

ctls Core Tools (recommended)

javasp Java Support (including KeySafe)


B Components on nCipher CD-ROMs nCipher component bundles

On nCSS User and CipherTools CD-ROMs, you are also offered the psusr payShield User standard component bundle.

The component bundles consist of various individual components.

The hwsp Hardware Support (mandatory) bundle contains the nCipher server and kernel device drivers:

The ctls Core Tools (recommended) bundle contains all the nCipher command-line utilities, including generatekey, low level utilities, and test programs:

hwsp Hardware Support (mandatory) bundle

nfdrv Windows device drivers

nfserv Hardserver process executables and scripts

sdrv nFast Win 2000 driver signatures

cfgall Hardserver config file support

nflog Logging library support

ctls Core Tools (recommended) bundle

convrt Command line key conversions

nftcl Command line key management (Tcl)

nftcl Command line key generation and import

nfuser Low level utilities and test programs

nfuser Command line remote server management

opensl nftcl certificate generation utility

sworld Command line key management (C)

tclsrc Tcl run time

tclstf Small Tcl utilities

nftcl Command line key generation and import

tct2 Trusted Code Tool 2 command-line utility

pysrc Python source for developers

nfpy nFPython header files



nCipher recommends that you always install the ctls Core Tools bundle.

Note The Core Tools bundle includes the tclsrc Tcl run time’s tools for creating the security world, KeySafe, and new-world. This does not affect any other installation of Tcl on your computer.

The javasp Java Support (including KeySafe)’s Java applications, including KeySafe:

The psusr payShield User bundle contains the components required if you want to use payShield secure payments:

Additional component bundles

nCipher supplies the following additional component bundles on CipherTools CD-ROMs:

javasp Java Support (including KeySafe) bundle

jutils Java utilities

jutils JNI shared library for jutils.jar

kmjava Java Key Management classes

ksafe KeySafe 2

nfjava nFast Java generic stub classes

nftcl Java Key Management Support

psusr payShield User bundle

emvspp payShield command-line tools

emvsms SEE machine for EMV library

emvspj payShield Java interface

emvjni Dynamic shared library for payShield JNI

Additional CipherTools component bundles

ctd CipherTools Developer

jd Java Developer



nCipher supplies the following additional component bundles on CodeSafe CD-ROMs:

The ctd CipherTools Developer bundle contains components supplied with the CipherTools Developer Kit:

The csd CodeSafe Developer bundle contains components supplied with the CodeSafe Developer Kit:

Additional CodeSafe component bundles

csd CodeSafe Developer

jd Java Developer

ctd CipherTools Developer bundle

emvspj JNI library for payShield Java

emvspp payShield developer library

hwcrhk Crypto Hardware Interface (CHIL) dev kit

nflibs nCipher libraries and headers, and example C source for utility functions

nfuser nCore & KM tools and example source

pkcs11 nFast PKCS#11 developer’s library

sworld Key Management C library developers kit

tclsrc Tcl run time - Headers and Libraries

cutils C utilities library

nflog Logging library

hilibs GS libs & headers



csd CodeSafe Developer bundle

csee Codesafe-C moduleside example code

csee Codesafe-C hostside example code

module Firmware test scripts

nflibs Generic stub libraries and headers, and example C source for utility functions



The jd Java Developer bundle contains components to support development of Java applications:

nfuser nCore & KM tools and example source

sworld Key Management C library developers kit

tclsrc Tcl run time - Headers and Libraries

cutils C utilities library

nflog Logging library

hilibs GS libs & headers

jhsee Java hostside developer's kit

jhsee Java hostside SEE examples

ssllib Codesafe-SSL hostside code

ssllib Codesafe-SSL moduleside code



nfpy Libs and headers for codesafe/python

csd CodeSafe Developer bundle

jd Java Developer bundle

jcecsp Java Key Management developer

jutils Java utilities source and javadocs

kmjava Java Key Management developer

nfjava Java Generic Stub examples & javadoc


B Components on nCipher CD-ROMs nCSS User CD-ROM

nCSS User CD-ROM

nCipher supplies the following component bundles and additional components on the nCSS User CD-ROM:

CipherTools CD-ROM

nCipher supplies the following component bundles and additional components on the CipherTools CD-ROM:

Component Bundles




psusr payShield User

Individual Components

hwcrhk Crypto Hardware Interface (CHIL) plugin

jcecsp nCipherKM JCA/JCE provider classes

mscapi CSP support files

mscapic nCipher Win 2000 domestic strength CSP

ncsnmp nCipher SNMP monitoring agent

pkcs11 nCipher pkcs11 library

Component Bundles




psusr payShield User

ctd CipherTools Developer

jd Java Developer


B Components on nCipher CD-ROMs CodeSafe CD-ROM

CodeSafe CD-ROM

nCipher supplies the following component bundles and additional components on the CodeSafe CD-ROM:








sslyp Open SSL source code patch file

Component Bundles




csd CodeSafe Developer

jd Java Developer


gccsrc Prebuilt arm-gcc for Codesafe/C

gccsrc Prebuilt powerpcm-gcc for Codesafe/C








B Components on nCipher CD-ROMs Components Required for ParticularFunctionality

Components Required for Particular Functionality

Some functionality requires particular component bundles or individual components to be installed.

nCipher recommends that you ensure that you have installed the hwsp Hardware Support (mandatory) and ctls Core Tools (recommended) bundles. If you have a CipherTools CD-ROM, nCipher recommends that you install the ctd CipherTools Developer bundle. If you have a CodeSafe CD-ROM, nCipher recommends that you install the csd CodeSafe Developer bundle.

If you have a CodeSafe CD-ROM and you are developing in C,

• if your module has a part code of the form nC4XX2 or Bn1XXX, install the gccsrc Prebuilt arm-gcc for Codesafe/C component.

• if your module has a part code of the form nC4XX3 or Bn2XXX, install the gccsrc Prebuilt powerpc-gcc for Codesafe/C component.

In these part codes, X represents any integer.

If you have a CipherTools CD-ROM or a CodeSafe CD-ROM and you are developing in Java, install the jd Java Developer and javasp Java Support (including KeySafe) bundles; after installation, ensure that you have added the .jar files to your CLASSPATH.

KeySafe

To use KeySafe, install the ctls Core Tools and the javasp Java Support (including KeySafe) bundles.

payShield secure payments

If you have an nCipher Support Software (nCSS) CD-ROM or a CipherTools CD-ROM and you want to use payShield secure payments, install the psusr payShield User bundle.


B Components on nCipher CD-ROMs PKCS #11 applications

Windows CSP

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

• mscapic nCipher Win 2000 domestic strength CSP

• mscapi CSP support files

PKCS #11 applications

If you want to use the module with PKCS #11 applications, including release 4.0 or later of Netscape Enterprise Server, iPlanet Enterprise Edition 4, or Netscape Certificate Server 4, install the pkcs11 nCipher PKCS11 library. For detailed PKCS #11 configuration options, see the Operator Guide appropriate to your module type.

Cryptographic Hardware Interface Library applications

If you want to use the module with the Cryptographic Hardware Interface Library (CHIL) applications, install the hwcrhk Crypto Hardware Interface (CHIL) plugin component and, if required, the NCsslyp OpenSSL source code patch file component.

Note nCipher supports OpenSSL 0.9.7g and later.

nCipherKM JCA/JCE cryptographic service provider

If you want to use the nCipherKM JCA/JCE cryptographic service provider, you must install the javasp Java Support (including KeySafe) bundle and also the jcecsp nCipherKM JCA/JCE provider classes component.

Note In order to use the nCipherKM JCA/JCE cryptographic service provider, you must also add the nfjava.jar, kmjava.jar, jutils.jar, and kmcsp.jar files to your CLASSPATH after installation is complete. For details, see Operator Guide .


B Components on nCipher CD-ROMs nCipher SNMP monitoring agent

An additional JCE provider nCipherRSAPrivateEncrypt is supplied that is required for RSA encryption with a private key. Install this provider above the standard nCipherKM provider and ensure that the file rsaprivenc.jar is in your CLASSPATH. nCipher has successfully tested SSLSocketClientWithClientAuth (JSSE sample code) with iPlanet 4.1 and 6.0 SP5 with this provider.

For details about configuring these providers, see the Operator Guide.

nCipher SNMP monitoring agent

If you want to use the nCipher SNMP monitoring agent to monitor your modules, install the ncsnmp nCipher SNMP monitoring agent component. During the first installation process of the nCipher SNMP agent, the agent displays the following message:

If this is a first time install, the nCipher SNMP Agent will not run by default. Please

see the manual for further instructions.

For instructions on how to activate the agent after installation, see the Operator Guide appropriate to your module type.


Appendix C: Environment variables

nCipher software uses the following environment variables:

Variable Description

NFAST_DEBUG This variable enables debug logging for the hardserver and the PKCS #11 library. You must set NFAST_DEBUG equal to a nonzero value in order for debug messages to be logged (see Logging and debugging on page 343). For more information, see also Hardserver debugging on page 350 and Logging and debugging information for PKCS #11 on page 349.

NFAST_HOME This variable controls the location of the nCipher software, which is set by the nCipher installation script. By default, the nCipher software is located in C:\nfast\. You only need to change this variable if you move the nCipher files. See NFAST_KMDATA and NFAST_KMLOCAL.

NFAST_HWCRHK_LOGFILE This variable sets the name of the file to which the CHIL (Cryptographic Hardware Interface Library) writes its log from applications. This is in addition to the logging done according to the mechanisms in the published hwcrhk API, which vary according to the application in use.

NFAST_KMDATA This variable sets the location of the kmdata directory. If this environment variable is not set, the module looks for the security world data in the local directory of the kmdata directory, in the nCipher installation directory. See NFAST_HOME and NFAST_KMDATA.

NFAST_KMLOCAL This variable sets the location of the key-management and security world data directory. If this environment variable is not set, the module looks for the security world data in the local directory of the kmdata directory in the nCipher installation directory. See NFAST_HOME and NFAST_KMDATA.


C Environment variables Environment variables

NFAST_NFKM_TOKENSFILENFAST_NFKM_TOKENSSELECT

This variable sets the default values for a file in which ClientID and KeyIDs are stored by the preload command-line utility. Refer to for information on using this utility.

NFAST_SEE_MACHINEENCKEY_DEFAULT This variable is the name of the SEEConf key needed to decrypt SEE-machine images.

NFAST_SEE_MACHINEENCKEY_module This variable is the name of the SEEConf key needed to decrypt the SEE-machine image targeted for the specified module. It overrides NFAST_SEE_MACHINEENCKEY_DEFAULT for the specified module.

NFAST_SEE_MACHINEIMAGE_DEFAULT This variable is the path of the SEE machine image to load on to any module for which a specific image is not defined.

NFAST_SEE_MACHINEIMAGE_module This variable is the path of the SEE machine image to load on to the specified module. it overrides the use of NFAST_SEE_MACHINEIMAGE_DEFAULT for the specified module.

NFAST_SEE_MACHINESIGHASH_DEFAULT This variable is the default key hash of the vendor signing key.

NFAST_SEE_MACHINESIGHASH_module This variable is the key hash of the vendor signing key for the specified module. It overrides NFAST_SEE_MACHINESIGHAST_DEFAULT for the specified module.



C Environment variables Environment variables

NFAST_SERVER_PORTNFAST_SERVER_PRIVPORT

If this variable is set in the nFast server’s environment, the values are used to specify the TCP port numbers that the nFast server uses for connections over TCP sockets. This variable is available for this purpose for backward compatibility only: you should configure ports in the configuration file, as described in server_remotecomms on page 90. If you set this variable, it overrides the values in the configuration file.If this variable is not set, the nFast server defaults to using port 9000 and port 9001.If this variable is set in a C application, the application connects to the nFast server using TCP sockets rather than named pipes. The value of the environment variable determines the port to connect to. It must be the same value as used by the nFast server.You need only change these environment variables if another application is already using the default port numbers.

NFLOG_CATEGORIES This variable is used to filter log messages by supplying a colon-separated list of allowable message categories; see Logging and debugging on page 343. If no value is supplied, all message categories are logged.

NFLOG_SEVERITY This variable is used to filter log messages by supplying a minimum severity level to be logged; see Logging and debugging on page 343. If no value is supplied, the default severity level is WARNING.

NFLOG_DETAIL This variable is used to filter log messages by supplying a bitmask of detail flags; see Logging and debugging on page 343. The default is time+severity+writeable.

NFLOG_FILE This variable is used to specify a filename (or file descriptor) in which log messages are to be written; see Logging and debugging on page 343. The default is stderr (the equivalent of file descriptor &2).

OPENSSL_HWCRHK_LOG This variable sets the directory in which the CHIL (Cryptographic Hardware Interface Library) creates its log file. This must be a directory for which the user as which the CHIL-enabled application runs has write permission.



Appendix D: Logging and debugging

Note The current release of nCipher support software uses controls for logging and log files, as well as debugging, that differ from those used in previous releases. However, settings you made in previous releases to control logging, log files, and debugging are still generally supported in the current release, although in some situations the output is now formatted differently.

Environment variables to control logging

The nCipher Support Software generates logging information that is configured through a set of four environment variables:

NFLOG_FILE

This environment variable specifies the name of a file (or a file descriptor, if prefixed with the & character) to which logging information is written. The default is stderr (the equivalent of &2).

NFLOG_SEVERITY

This environment variable specifies a minimum severity level for logging messages to be written (all log messages less severe than the specified level are ignored). The level can be one of (in order of greatest to least severity):

1. FATAL

2. SEVERE

3. ERROR

4. WARNING

5. NOTIFICATION


D Logging and debugging Environment variables to control logging

6. DEBUGn (where n can be an integer between 1 and 10 inclusive that specifies different level of debugging detail, with 10 representing the greatest level of detail).

Note nCipher recommends not setting the severity level to DEBUGn unless you are directed to do so by Support at nCipher.

The default severity level is WARNING.

NFLOG_DETAIL

This environment variable takes a hexadecimal value from a bitmask of detail flags as described in the following table (the logdetail flags are also used in the hardserver configuration file to control hardserver logging; see Hardserver configuration file on page 85):

Hexadecimal flag

Function logdetail flags

0x00000001 This flag shows the external time (that is, the time according to your machine's local clock) with the log entry. It is on by default.

external_time

0x00000002 This flag shows the external date (that is, the date according to your machine's local clock) with the log entry.

external_date

0x00000004 This flag shows the external process ID with the log entry.

external_pid

0x00000008 This flag shows the external thread ID with the log entry.

external_tid

0x00000010 This flag shows the external time_t (that is, the time in machine clock ticks rather than local time) with the log entry.

external_time_t

0x00000020 This flag shows the stack backtrace with the log entry.

stack_backtrace

0x00000040 This flag shows the stack file with the log entry.

stack_file

0x00000080 This flag shows the stack line number with the log entry.

stack_line



0x00000100 This flag shows the message severity (a severity level as used by the NFLOG_SEVERITY environment variable) with the log entry. It is on by default.

msg_severity

0x00000200 This flag shows the message category (a category as used by the NFLOG_CATEGORY environment variable) with the log entry.

msg_categories

0x00000400 This flag shows message writeables, extra information that can be written to the log entry, if any such exist. It is on by default.

msg_writeable

0x00000800 This flag shows the message file in the original library. This flag is likely to be most useful in conjunction with nCipher-supplied example code that has been written to take advantage of this flag.

msg_file

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

msg_line

0x00002000 This flag shows the date and time in UTC (Coordinated Universal Time) instead of local time.

options_utc

Hexadecimal flag

Function logdetail flags



NFLOG_CATEGORIES

This environment variable takes a colon-separated list of categories on which to filter log messages (categories may contain the wild-card characters * and ?). If you do not supply any values, then all categories of messages are logged. This table lists the available categories:

Category Description

nflog This category logs all general messages relating to nflog.

nflog-stack This category logs messages from StackPush and StackPop functions.

memory-host This category logs messages concerning host memory.

memory-module This category logs messages concerning module memory.

gs-stub This category logs general generic stub messages. (Setting this category works like using the dbg_stub flag with the logging functionality found in previous nCipher support software releases.)

gs-stubbignum This category logs bignum printing messages. (Setting this category works like using the dbg_stubbignum flag with the logging functionality found in previous nCipher support software releases.)

gs-stubinit This category logs generic stub initialization routines. (Setting this category works like using the dbg_stubinit flag with the logging functionality found in previous nCipher support software releases.)

gs-dumpenv This category logs environment variable dumps. (Setting this category works like using the dbg_dumpenv flag with the logging functionality found in previous nCipher support software releases.)

nfkm-getinfo This category logs nfkm-getinfo messages.

nfkm-newworld This category logs messages about world generation.

nfkm-admin This category logs operations using the Administrator Card Set.

nfkm-kmdata This category logs file operations in the kmdata directory.

nfkm-general This category logs general NFKM library messages.

nfkm-keys This category logs key loading operations.



nfkm-preload This category logs preload operations.

nfkm-ppmk This category logs softcard operations.

serv-general This category logs general messages about the local hardserver.

serv-client This category logs messages relating to clients or remote hardservers.

serv-internal This category logs severe or fatal internal errors.

serv-startup This category logs fatal startup errors.

servdbg-stub This category logs all generic stub debugging messages.

servdbg-env This category logs generic stub environment variable messages.

servdbg-underlay This category logs messages from the OS-specific device driver interface

servdbg-statemach This category logs information about the server’s internal state machine.

servdbg-perf This category logs messages about the server's internal queueing.

servdbg-client This category logs external messages generated by the client.

servdbg-messages This category logs server command dumps.

servdbg-sys This category logs OS-specific messages.

hwcrhk This category logs messages from the CHIL (Cryptographic Hardware Interface Library).

pkcs11-sam This category logs all security assurance messages from the PKCS #11 library.

pkcs11 This category logs all other messages from the PKCS #11 library.

rqcard-core This category logs all card-loading library operations that involve standard message passing (including slot polling).

rqcard-logic This category logs all card-loading library messages from specific logics.

rqcard-logic This category logs all card-loading library messages from the current user interface.

Category Description


D Logging and debugging Logging from the nCipher CSP

You can set a minimum level of hardserver logging by supplying one of the values for the NFLOG_SEVERITY environment variable in the hardserver configuration file, and you can likewise specify one or more values for the NFLOG_CATEGORIES environment variable. See Chapter 6: Configuring the hardserver for more detailed information about controlling hardserver logging.

Note If none of the four environment variables are set, the default behavior is to log nothing, unless this is overridden by any individual library. If any of the four variables are set, all unset variables are given default values.

Logging from the nCipher CSP

By default, the nCipher CSP for Windows sends log messages to the event log. In order to send log messages to a file, edit the registry, and then set the value of the registry key HKLM\Software\nCipher\Cryptography\LogLevel as follows:

Note Do not set this value to 3 unless either you are asked to do so by Support at nCipher or you are debugging your own code. At this level of logging, a single SSL connection generates approximately 30 kilobytes of log messages. In addition, sensitive information may appear in the log file.

The log file is created in the directory C:\nfast\log\ unless you set the registry key HKLM\Software\nCipher\Cryptography\PathName to the name of another directory.

Value Output

0 Messages are sent to the event log.

1 Error messages are sent to the log file.

2 Function calls and error messages are sent to the log file.

3 All information, including debugging information, is sent to the log file.


D Logging and debugging Logging and debugging information for PKCS#11

Logging and debugging information for PKCS #11

In order to get PKCS #11 logging and debugging output, you must set the CKNFAST_DEBUG environment variable equal to 1 and specify any appropriate pkcs11 categories using the NFLOG_CATEGORIES environment variable.

This environment variable takes a colon-separated list of categories on which to filter log messages (categories may contain the wildcards characters * and ?).

The following table maps PKCS #11 debug level numbers to the corresponding NFLOG_SEVERITY value

PKCS #11 debug level

PKCS #11 debug meaning

NFLOG_SEVERITY value

Output in log

0 DL_None NONE

1 DL_EFatal FATAL "Fatal error:"

2 DL_EError ERROR "Error:"

3 DL_Fixup WARNING "Fixup:"

4 DL_Warning WARNING "Warning:"

5 DL_EApplic ERROR "Application error:"

6 DL_Assumption NOTIFICATION "Unsafe assumption:"

7 DL_Call DEBUG2 ">> "

8 DL_Result DEBUG3 "< "

9 DL_Arg DEBUG4 "> "

10 DL_Detail DEBUG5 "D "

11 DL_DetailMutex DEBUG6 "DM "


D Logging and debugging Hardserver debugging

Hardserver debugging

Hardserver debugging is controlled by specifying one or more servdbg-* categories (from the NFLOG_CATEGORIES environment variable) in the hardserver configuration file (see Hardserver configuration file on page 85). However, unless you also set the NFAST_DEBUG environment variable to a non-zero value, no debugging is produced (regardless of whether or not you specify servdbg-* categories in the hardserver configuration file). This behavior helps guard against the additional load debugging places on the CPU usage; you can set the desired servdbg-* categories in the hardserver configuration file, and then enable or disable debugging by setting the NFAST_DEBUG environment variable.

Note If the NFAST_DEBUG environment variable is used to control debugging (instead of simply enabling or disabling it), the logdetail value in the hardserver configuration file (one of the values for the NFLOG_LEVEL environment variable) controls the level of detail printed. Standard debugging messages are printed at level DEBUG2. Environment variables are at DEBUG3, bignums and other byteblocks are printed at DEBUG4, and extra verbose debugging is available at DEBUG5.

Debugging information for payShield

PAYSHIELD_DEBUGFILE

The environment variable PAYSHIELD_DEBUGFILE is used to set the name of the file that can be used by payShield to record log messages returned from the hostside payShield library.

PAYSHIELD_DEBUG

The environment variable PAYSHIELD_DEBUG is used to set the level and destination of log messages returned from the hostside payShield library.


D Logging and debugging Debugging information for payShield

The payShield library can be configured to return log information from various categories and to either of two different locations.

The environment variable PAYSHIELD_DEBUG should be set to an integer which represents the kind of logging desired.

The integer value used to set PAYSHIELD_DEBUG must be calculated by ORing the binary values assigned to each log information category.

For example, to log payShield errors to the system log, and also log payShield warnings and errors to the payShield logfile specified by PAYSHIELD_DEBUGFILE, PAYSHIELD_DEBUGFILE must be set to 19.

19 is the integer value of the binary number 00010011, calculated by ORing 00010000, 00000001 and 00000010 together.

Value payShield log information category

00000000 Log no data at all

00000001 Log errors to the payShield logfile

00000010 Log warnings to the payShield logfile

00000100 Log informational messages to the payShield logfile

00001000 Log debug data to the payShield logfile

00010000 Log errors to the system log

00100000 Log warnings to the system log

01000000 Log informational messages to the system log

10000000 Log debug data to the system log


D Logging and debugging Debugging information for Java

Debugging information for Java

This section describes how you can specify the debugging information generated by Java.

Note Do not set NFJAVA_DEBUG or NFJAVA_DEBUGFILE in the environment because Java does not pick up variables from the environment.

Setting the Java debugging information level

In order to make the Java generic stub output debugging information, set the Java property NFJAVA_DEBUG. The debugging information for NFJAVA, NFAST, and other libraries (for example, KMJAVA) can all use the same log file and have their entries interleaved.

You set the debugging level as a decimal number. To determine this number:

1. Select the debugging information that you want from the following list:

NONE = 0x00000000 (debugging off)

MESS_NOTIFICATIONS = 0x00000001 (occasional messages including important errors)

MESS_VERBOSE = 0x00000002 (all messages)

MESS_RESOURCES = 0x00000004 (resource allocations)

FUNC_TRACE = 0x00000008 (function calls)

FUNC_VERBOSE = 0x00000010 (function calls + arguments)

REPORT_CONTEXT = 0x00000020 (calling context e.g ThreadID and time)

FUNC_TIMINGS = 0x00000040 (function timings)

NFJAVA_DEBUGGING = 0x00000080 (Output NFJAVA debugging info)

2. Add together the hexadecimal value associated with each type of debugging information.

For example, to set NFJAVA_DEBUGGING and MESS_NOTIFICATIONS, add 0x00000080 and 0x00000001 to make 0x00000081.


D Logging and debugging Debugging information for Java

3. Convert the total to a decimal and specify this as the value for the variable.

For example, to set NFJAVA_DEBUGGING and MESS_NOTIFICATIONS, include the line:

NFJAVA_DEBUG=129

For NFJAVA to produce output, NFJAVA_DEBUG must be set to at least NFJAVA_DEBUGGING + MESS_NOTIFICATIONS. Other typical values are:

- 255: All output

- 130: nfjava debugging and all messages (NFJAVA_DEBUGGING and MESS_VERBOSE)

- 20: function calls and arguments and resource allocations (FUNC_VERBOSE and MESS_RESOURCES)

Setting the Java debugging file

You can set the NFJAVA_DEBUGFILE property to direct output to a given file name, for example:

java -DNFJAVA_DEBUGFILE=myfile -classpath .... classname

If NFJAVA_DEBUGFILE is not set, the standard error stream System.err is used.

Note Set these variables only when developing code or at the request of Support at nCipher.

Debug output contains all commands and replies sent to the hardserver in their entirety, including all plain texts and the corresponding cipher texts as applicable.


Appendix E: Installed Utilities

The following utility files are supplied in the bin subdirectory of your nCipher installation:

Utility Description

cardpp This utility adds, changes, removes, or verifies a pass phrase. It is described in Changing pass phrases with cardpp on page 218 and the Operator Guide.

cfg-reread This utility loads the hardserver configuration from the configuration file. It is described in cfg-reread on page 228.

checkmod This utility checks modulo exponentiations. It is described in the Operator Guide.

ckimportbackend This utility is internal to nCipher.

ckinfo This utility is for PKCS #11 developer use. It displays C_GetInfo, C_GetSlotInfo, and C_GetTokenInfo results. See the Developer Reference for details of all API calls.

cklist This utility is for PKCS #11 developer use. It lists some details of objects on all slots. It lists public and private objects if invoked with a PIN argument and public objects only if invoked with the -n (--nopin) option. It does not output any potentially sensitive attributes, even if the object has CKA_SENSITIVE set to FALSE.


E Installed Utilities Installed Utilities

ckmechinfo This is a PKCS #11 developer utility. Refer to the relevant developer documentation.

ckrsagen This is a PKCS #11 developer utility. Refer to the relevant developer documentation.

cksigtest This utility measures module signing speed with nCipher PKCS #11 library calls. It is described in the Operator Guide.

config This utility is a Netscape configuration tool. It is described in the relevant integration guide.

createocs This utility creates or erases Operator Card Sets. It is described in Creating the Operator Card Set from the command line on page 71.

cryptest This utility tests all defined symmetric cryptographic mechanisms. It is described in the Operator Guide.

cspcheck This utility checks that CSP container files are intact and uncorrupted and that referenced key files exist. It is described in the Operator Guide.

cspimport This utility allows you to insert keys manually into existing CSP containers. It is described in the Operator Guide.

cspmigrate This utility moves CSP container information for an existing security world from the registry into the security world. It is described in the Operator Guide.

Utility Description



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

csptest This utility tests installed Cryptographic Service Providers. It is described in the Operator Guide.

csputils This utility lists and gives detailed information about CSP containers. It is described in the Operator Guide.

des_kat This utility performs DES known-answer tests. It is described in the Operator Guide.

dump_marshalled This utility can be used to examine nCipher data formats. Contact Support at nCipher for information.

enquiry This utility returns information about the nCipher server and connected modules. It is described in enquiry on page 229.

floodtest This utility performs hardware speed testing. It is described in floodtest on page 238.

fwcheck This utility verifies the firmware. It is described in the Operator Guide.

genkeyprops This utility is internal to nCipher.

generatekey This utility generates or imports keys. It is described in the Operator Guide.

hardserver This is the hardserver program. It is installed as a service and run automatically. Information on stopping and restarting it manually is given in hardserver on page 242.

Utility Description



iisinstallcert This utility is an IIS configuration tool. It is described in the relevant integration guide.

initunit This utility initializes a module. It is described in initunit on page 244.

key2pem This utility is internal to nCipher.

keytst This utility displays information about existing CSP key containers. It is described in the Operator Guide.

key-xfer-im This utility imports a module key that has been programmed into a new security world. It is described in key-xfer-im on page 250.

killrecov This utility disables the Replace Operator Card Set feature for a security world. Contact Support at nCipher for information.

kmfile-dump This utility displays key-management information from a security world’s key-management data file. It is described in the Operator Guide.

kptest This utility tests the consistency of encryption and decryption, or of signature and verification, with the RSA and DSA algorithms. It is described in the Operator Guide.

loadkeys This utility prepares Key Detail cards and loads keys for payShield installations. It is described in the Operator Guide.

loadrom This utility loads new firmware into a module. It is described in loadrom on page 253.

Utility Description



mkaclx This utility contains example code for key generation. It is described in the Operator Guide.

mk-reprogram This utility programs a module key that is in one security world to another security world. It is described in mk-reprogram on page 255.

ncdate This utility sets, updates and views the time on a module’s realtime clock. It is described in the Operator Guide.

ncthread-test This utility stress tests modules and tests nCore API concurrent connection support. It is described in the Operator Guide.

ncversions This utility displays the versions of installed nCipher support software components. It is described in ncversions on page 257.

new-world This utility creates a security world that supports SEE functions. It is described in new-world on page 259.

nffwd This utility is internal to nCipher.

nfkminfo This utility displays information about a security world, cards, and keys. It is described in the Operator Guide.

nopclearfail This utility clears a module, puts a module into the error state, or retries a failed module. It is described in the Operator Guide.

nvram-backup

This utility copies files between a module's NVRAM and a smart card allowing files to be backed up and restored. It is described in the Operator Guide.

Utility Description



nvram-sw

This utility modifies and displays information about NVRAM areas. It is described in nvram-sw on page 272.

payshield-config This utility enables the Master Card Set holders to modify a payShield installation’s settings. It is described in payshield-config on page 278.

payshield-info This utility displays information about a payShield installation. It is described in the Operator Guide.

payshield-install This utility configures a security world specifically for payShield modules. It is described in payshield-install on page 283 in the Administrator Guide.

pollbare

This example utility returns information about state changes. It is described in the Operator Guide.

postrocs This utility is required after key transfer if the previous Operator Card Set protected PKCS #11 objects. It is described in postrocs on page 286.

ppmk This utility is used to manage softcards. It is described in ppmk on page 287.

preload This utility loads keys onto a module before an application is run in another session. It is described in the Operator Guide.

pubkey-find This example utility returns information the key, certificate, or certificate request in a file. It is described in the Operator Guide.

Utility Description



racs This utility creates a new Administrator Card Set. It is described in Replacing an Administrator Card Set with racs on page 225.

randchk

This utility runs a universal statistical test on random numbers returned by the module. It is described in the Operator Guide.

rdlinene

This utility is internal to nCipher.

rfs-sync This utility copies security world and key data from a remote file system to a module. It is used with modules which are not netHSM or payShield net modules. It is described in rfs-sync on page 304.

rtc This utility reads and sets the module’s real-time clock. It is described in the Operator Guide.

sigtest

This utility measures module speed using RSA or DSA signatures or signature verifications. It is described in the Operator Guide.

slotinfo

This utility returns information about tokens in a module. It can also be used to format a token. It is described in the Operator Guide.

sppupgradekeys This utility upgrades keys created on older payShield installations. It is described in sppupgradekeys on page 312.

stattree This utility returns statistics gathered by the nCipher server and modules. It is described in stattree on page 314.

Utility Description


Appendix F: The nCipher SNMP monitoring agent

Note The nCipher SNMP monitoring agent provides you with components that can be added to your (third-party) SNMP manager application. Every SNMP manager adds monitor components differently. Please consult the documentation supplied with your SNMP Manager application for details on how to add the nCipher MIB files.

The Simple Network Management Protocol (SNMP) was developed in 1988 and revised in 1996. It is currently regarded as the standard method of network management. It is widely supported and offers greater interoperability than traditional network management tools (for example, rsh or netstat). This makes it ideal for use for the large array of platforms that nCipher supports and also avoids the overhead of remote login and execution, helping to reduce network congestion and improve performance.

The SNMP protocol defines a collection of network management functions allowing management stations to gather information from, and transmit commands to, remote machines on the network. Agents running on the remote machines can take information gathered from the system and relay this information to the manager application. Such information could have been requested from the underlying operating system or gained by interrogating the hardware.

The SNMP protocol defines the following SNMP messages:

get

This message is sent by a manager to retrieve the value of an object at the agent.

set

This message is sent by a manager to set the value of an object at the agent.


F The nCipher SNMP monitoring agent Activating the nCipher SNMP agent

trap

This message is sent by an agent to notify a management station of significant events.

In the development of the nCipher SNMP agent, nCipher has used open-source tools that are part of the NET-SNMP project (formerly UCD-SNMP). More information on SNMP in general, and the data structures used to support SNMP installations, is available from the NET-SNMP project Web site: http://net-snmp.sourceforge.net/. This site includes some support information and offers access to discussion E-mail lists. You can use the discussion lists to monitor subjects that might affect the operation or security of the nCipher SNMP agent or command-line utilities.

Discuss any enquiries arising from information on the NET-SNMP website with Support at nCipher before posting potentially sensitive information to the NET-SNMP website.

Activating the nCipher SNMP agent

The nCipher SNMP Agent enables other computers on the network to connect to it and make requests for information. The nCipher agent is based on the NET-SNMP kit, which has been tested but not fully reviewed by nCipher. nCipher strongly recommends that the nCipher agent is deployed only on a private network, or protected from the global Internet by an appropriate firewall.

The nCipher SNMP agent is installed and activated separately. After installing the nCipher SNMP components, an activation command must be issued. This two-stage process is to avoid the inadvertent activation of SNMP capabilities that could supply management information from servers and nCipher modules that are not explicitly protected, or which could potentially expose the host computer to attacks on the nCipher SNMP agent itself.

http://net-snmp.sourceforge.net/


F The nCipher SNMP monitoring agent Default settings

Default settings

By default, installing nCipher support software for Windows 2000 or Windows 2003 also installs the nCipher SNMP agent but does not activate it. The nCipher SNMP agent can be specifically excluded from an nCipher installation by deselecting the box associated with the SNMP agent in the installation component list. The default installation directory for the nCipher Management Information Base (MIB) and the SNMP configuration files (snmp.conf and snmpd.conf) is %NFAST_HOME%\etc\snmp\.

Do you already have an SNMP agent running?

If you already have an SNMP agent running, you need to configure the ports used by the agents to avoid conflicts before enabling the nCipher SNMP agent. See the NET-SNMP project Web site: http://net-snmp.sourceforge.net/. A port is assigned by editing the agentaddress entry in the snmpd.conf file or by editing the defaultPort entry in snmp.conf. If both files have been edited, the agentaddress entry in snmpd.conf takes priority, and the defaultPort entry in snmp.conf is ignored.

Activation of the SNMP agent

To activate the nCipher SNMP agent:

1. Log in as Administrator.

2. Open a command line window.

3. Enter the following command:

e:\ncipher\devel\ncsnmp\src\ntbuild\agent\snmpd.exe -register [param list]



F The nCipher SNMP monitoring agent Further Information

where param list is a list of startup parameters: see Useful nCipher SNMP agent command-line switches on page 382 for more details. This installs the agent as a Windows Service and also starts the new service.

To de-activate and uninstall the nCipher SNMP agent, enter the following command:

e:\ncipher\devel\ncsnmp\src\ntbuild\agent\snmpd.exe -unregister

Further Information

Protecting the nCipher SNMP installation

The nCipher SNMP Agent allows other computers on the network to connect to it and make requests for information. The nCipher agent is based on the NET-SNMP code base, which has been tested but not fully reviewed by nCipher. nCipher strongly recommends that the nCipher agent be deployed only on a private network or protected from the global Internet by an appropriate firewall.

The default nCipher SNMP installation allows read-only access to the Management Information Base (MIB) with any community string. There is no default write access to any part of the MIB.

Every effort has been taken to ensure the confidentiality of cryptographic keys even when the SNMP agent is enabled. In particular, the nCipher module is designed to prevent the theft of keys even if the security of the host system is compromised, provided that the Administrator Cards are used only with trusted hosts. Care must be used when changing the configuration of the nCipher SNMP agent.

nCipher strongly advises that you set up suitable access controls in snmpd.conf, or a firewall, to protect the agent and the information it can return.



Care has also been taken to ensure that malicious attackers are unable to flood your module with requests by flooding your SNMP agent. Command results from administration or statistics commands are cached, and therefore the maximum rate at which the agent sends commands to the module is throttled. See <Undefined Cross-Reference> for details on setting the cache time-outs.

Configuring the nCipher SNMP agent

The nCipher package uses various configuration files to configure its applications. This section describes the overall nature of the configuration files for the SNMP agent.

If you are installing the nCipher SNMP agent to a host that has an existing, non-nCipher, SNMP agent installation, you may need to edit the SNMP configuration files (snmpd.conf and snmp.conf) associated with the nCipher SNMP agent to change the port on which the agent listens for SNMP requests. See Do you already have an SNMP agent running? on page 363.

Note Make sure you protect the configuration files if you are storing sensitive information in them.

By default, the nCipher SNMP configuration file (snmp.conf) is located in the $NFAST_HOME\etc\snmp\ directory. In this directory, the agent looks for files with the extension of .conf.

Note The default search path can be overridden by setting the environment variable SNMPCONFPATH to a semi-colon (“;”) separated list of directories for which to search.

For further information about SNMP configuration files, see the standard SNMP documentation available from the NET-SNMP project Web site: http://net-snmp.sourceforge.net/




Re-reading snmpd.conf and snmpd.local.conf

The nCipher SNMP agent can be forced to re-read its configuration files with an snmp set of integer(1) to enterprises.nCipher.reloadConfig.0(.1.3.6.1.4.1.7682.999.0).

The SNMP configuration file - snmp.conf

The snmp.conf configuration file contains directives that apply to all SNMP applications. These directives can be configured to apply to specific applications, see the standard SNMP documentation available from the NET-SNMP project Web site: http://net-snmp.sourceforge.net/. The snmp.conf configuration file is not required for the agent to operate and report MIB entries.

The SNMP agent configuration file - snmpd.conf

The snmpd.conf configuration file defines how the nCipher SNMP agent operates. It is required only if an agent is running. This file can contain any of the directives described in this section.

The snmpd.conf file can also contain any of the directives available for use in the snmp.conf file. See the standard SNMP documentation available from the NET-SNMP project Web site: http://net-snmp.sourceforge.net/.

The snmpd.conf file can also contain the following nCipher-specific directives:

statstimeout

This directive specifies the maximum length of time for which statistics commands are cached. The default is 60 seconds.

admintimeout

This directive specifies the maximum length of time for which administrative commands are cached. The default is 5 seconds.






F The nCipher SNMP monitoring agent Using the nCipher SNMP agent with a managerapplication

keytable

This directive sets the initial state of the key table to none, all, or query. See listKeys in Administration sub-tree overview on page 369.

Using the nCipher SNMP agent with a manager application

Note The nCipher SNMP monitoring agent provides you with components that can be added to your (third-party) SNMP manager application. Every SNMP manager adds monitor components differently. Please consult the documentation supplied with your SNMP Manager application for details on how to add the nCipher MIB files.

Manager configuration

The manager application is the interface through which the user is able to perform network management functions. A manager communicates with agents using SNMP primitives (get, set, trap) and is unaware of how data is retrieved from, and sent to, managed devices. This form of encapsulation raises two main issues:

• the manager is hidden from all platform specific details

• the manager can communicate with agents running on any IP-addressable machine.

As a consequence, manager applications are generic and can be bought “off the shelf”. You may already be running SNMP managers, and if so, you can use them to query the nCipher agent.

Note The manager is initially unaware of the MIB tree structure at a particular node. Managed objects can be retrieved or modified, but only if their location in the tree is known.



It is more useful if the manager can see the MIB tree present at each managed node. The MIB module descriptions for a particular node must be parsed by a manager-specific MIB compiler and converted to configuration files. These files are read by the manager application at run time.

The nCipher SNMP agent is designed to monitor all current nCipher modules. The SNMP agent can monitor e-commerce accelerator and key management modules, working with all supported versions of nCipher firmware (contact Support at nCipher for details of supported firmware).

nCipher MIB module overview

A large proportion of the nCipher SNMP system is fully specified by the structure of the MIB; the behavior of the agent depends on relaying information according to the layout of the MIB.

The nCipher MIB module resides at a registered location in the MIB tree determined by the Internet Assigned Numbers Authority (IANA). The private enterprise number of 7682 designated by the IANA corresponds to the root of the nCipher branch, and by convention this (internal) node is the company name.

The MIB module groups logically related data together, organizing itself into a classification tree, with managed objects present at leaf nodes. The nC-series node (enterprises.nCipher.nC-series) is placed as a sub-tree of the nCipher root (enterprises.nCipher); this allows future product lines to be added as additional sub-trees. The structure of the tree underneath the registered location is vendor-defined, and this specification defines the structure chosen to represent nCipher-specific data.

MIB functionality

The nCipher MIB module separates module information into the following categories:



• retrieval of status and information about installed nC-series modules

• retrieval of live statistics of performance of installed nC-series modules

These categories form the top-level nodes of the nCipher sub-tree; the functionality of the first category is in the administration sub-tree, and the second category is in the statistics sub-tree. The top-level tree also contains 3 items that it would be useful to check at-a-glance:

Administration sub-tree overview

The administration sub-tree (enterprises.nCipher.nC-series.administration) contains information about the permanent state of the nCipher server and the connected modules. It is likely that most of the information in this branch rarely changes over time, unlike the statistics branch. The information given in the administration sub-tree is mostly acquired by the NewEnquiry command and is supplied both per-module and (where appropriate) aggregated over all modules.

Node name R/W Type Remarks

hardserverFailed R TruthValue True if the remote nCipher server is not running. If the nCipher server is not running, then most of the rest of the information is unreliable or missing.

modulesFailed R TruthValue True if any modules have failed

load R Unsigned32 Percentage of total available capacity currently utilized



The following table gives details of the individual nodes in the administration sub-tree.

listKeys can be preset using the keytable config directive in snmpd.conf (see <Undefined Cross-Reference>).


SecurityWorld R TruthValue True if a security world is installed and operational

hardserverRunning R Enum1: Running2: NotRunning

This variable reflects the current state of the hardserver (Running or NotRunning)

noOfModules R Unsigned32 Number of nC-series modules

hsVersion R DisplayString Hardserver version string

[global]speedIndex R Unsigned32 Number of 1024-bit signatures per second

[global]minQ [global]maxQ

R Unsigned32 Minimum and maximum recommended queues

swState R DisplayString Security World display flags, as reported by nfkminfo

listKeys R/W Enum1: none2: all3: query4: resetquery

Controls the behavior of the key table (switch off, display all keys, enable individual attribute queries, clear the query fields). Displaying all keys can result in a very long list.

serverFlags R DisplayString Supported hardserver facilities (the NewEnquiry level 4 flags)

remoteServerPort R Gauge TCP port the hardserver is listening on

swGenTime R DisplayString Security world’s generation time

swGeneratingESN R DisplayString ESN of the module that generated the security world



Security world hash sub-tree

The following table gives details of the nodes in the security world hash sub-tree (enterprises.nCipher.nC-series.administration.swHashes):


hashKNSO R MHash Hash of the nCipher security officer’s key

hashKM R MHash Hash of the security world key

hashKRA R MHash Hash of the recovery authorization key

hashKRE R MHash Hash of the recovery key pair

hashKFIPS R MHash Hash of the FIPS authorization key

hashKMC R MHash Hash of the module certification key

hashKP R MHash Hash of the pass phrase recovery key

hashKNV R MHash Hash of the nonvolatile memory (NVRAM) authorization key

hashKRTC R MHash Hash of the real time clock authorization key

hashKDSEE R MHash Hash of the SEE Debugging authorization key

hashKFTO R MHash Hash of the Foreign Token Open authorization key



Security world quorums sub-tree

The following table gives details of the nodes in the security world quorums sub-tree (enterprises.nCipher.nC-series.administration.swQuorums):


adminQuorumK R Unsigned The default quorum of admin cards

adminQuorumN R Unsigned The total number of cards in the admin cardset

adminQuorumM R Unsigned The quorum required for module reprogramming

adminQuorumR R Unsigned The quorum required to recover keys for operator card recovery

adminQuorumP R Unsigned The quorum required to recover the pass phrase for an operator card

adminQuorumNV R Unsigned The quorum required to access nonvolatile memory (NVRAM)

adminQuorumRTC R Unsigned The quorum required to update the real time clock

adminQuorumDSEE R Unsigned The quorum required to view full SEE debug information

adminQuorumFTO R Unsigned The quorum required to use a Foreign Token Open Delegate Key



Module administration table

The following table gives details of the nodes in the module administration table (enterprises.nCipher.nC-series.administration.moduleAdminTable):


moduleAdminIndex R Integer Module number of this row in the table

mode R Enum1: Operational2: Pre-init3: Init4: Pre-maint5: Maint6: AccelOnly7: Failed8: Unknown

Current module state

fwVersion R DisplayString Firmware version string

serialNumber R DisplayString Module Electronic Serial Number (ESN)

moduleType R DisplayString Module type code

productName R DisplayString (only returned if module supports enquiry level 5)

hwPosInfo R DisplayString Hardware bus/slot info (such as PCI slot number). Modules only return a meaningful value if they support enquiry level 5.

moduleSecurityWorld R TruthValue Indicates whether or not the module is in the current SW

smartcardState R DisplayString Description of smartcard in slot (empty, unknown card, admin/operator card from current SW, failed). N/A for acceleration only modules.



moduleSWState R Enum1: unknown2: usable3: maintmode4: uninitialized5: factory6: foreign7: accelonly8: failed9: unchecked10: initmode11: preinitmode12: outofrange

Current module and security world state

moduleSWFlags R DisplayString Security World flags for this module

hashKML R MHash Hash of the module’s secret key

moduleFeatures R DisplayString Features enabled on this module

moduleFlags R DisplayString Like serverFlags, but per-module

versionSerial R Gauge Firmware Version Security Number (VSN); see Version Security Number on page 323.

hashKNETI R MHash KNETI hash, if present

longQ R Gauge Max. rec. long queue

connectionStatus R DisplayString Connection status (for imported modules)

connectionInfo R DisplayString Connection information (for imported modules)

machineTypeSEE R DisplayString SEE machine type




Slot administration table

The following table gives details of the nodes in the slot administration table (enterprises.nCipher.nC-series.administration.slotAdminTable):


slotAdminModuleIndex R Unsigned32 Module number of the module containing the slot

slotAdminSlotIndex R Unsigned32 Slot number (1-based, unlike nCore which is 0-based)

slotType R Enum1: Datakey2: Smart card3: Emulated4: Soft token5: Unconnected6: Out of range7: Unknown

Slot type

slotFlags R DisplayString Flags referring to the contents of the slot (from slotinfo)

slotState R Enum1: Unused2: Empty3: Blank4: Administrator5: Operator6: Unidentified7: Read error8: Partial9: Out of range

Partial refers to cards in a partially-created cardset.

slotListFlags R DisplayString Flags referring to attributes of the slot (from getslotlist)

slotShareNumber R Unsigned32 Share number of card currently in slot, if present

slotSharesPresent R DisplayString Names of shares present in card currently in slot.



Cardset administration table

The following table gives details of the nodes in the cardset administration table (enterprises.nCipher.nC-series.administration.cardsetAdminTable):

Key administration table

The key administration table is visible as long as the listKeys node in the administration sub-tree is set to a value other than none.


hashKLTU R MHash Hash of the token protected by the cardset

cardsetName R DisplayString

cardsetK R Unsigned32 Required number of cards in the cardset

cardsetN R Unsigned32 Total number of cards in the cardset

cardsetFlags R DisplayString Other attributes of the cardset

cardsetNames R DisplayString Names of individual cards, if set

cardsetTimeout R Unsigned32 Token time-out period, in seconds, or 0 if none

cardsetGenTime R DisplayString Generation time of cardset



The following table gives details of the nodes in the key administration table (enterprises.nCipher.nC-series.administration.keyAdminTable):

Key query sub-tree

The key query sub-tree is used if the listKeys node in the administration sub-tree is set to query.


keyAppname R DisplayString Application name

keyIdent R DisplayString Name of key, as generated by the application

keyHash R MHash Required and total number of cards in the cardset

keyRecovery R Enum1: Enabled2: Disabled3: No key4: Unknown5: Invalid6: Unset

The value unset is never returned by the key table. It is used in the key query field to mean “do not care”.

keyProtection R Enum1: Module2: Cardset3: No key4: Unknown5: Invalid6: Unset


keyCardsetHash R MHash Hash of the cardset protecting the key, if applicable

keyFlags R DisplayString Certificate and public key flags

keyExtraEntities R Unsigned32 Number of extra key attributes.

keySEEInteg R DisplayString SEE integrity key, if present

keyGeneratingESN R DisplayString ESN of the module that generated the key, if present

keyTimeLimit R Gauge Time limit for the key, if set

keyPerAuthUseLimit R Gauge Per-authentication use limit for the key



If these values are set, they are taken as required attributes for filtering the list of available keys; if multiple attributes are set, the filters are combined (AND rather than OR).

The following table gives details of the nodes in the key query sub-tree (enterprises.nCipher.nC-series.administration.keyQuery):


keyQueryAppname R/W DisplayString Application name

keyQueryIdent R/W DisplayString Name of key, as generated by the application

keyQueryHash R/W DisplayString Required and total number of cards in the cardset

keyQueryRecovery R/W Enum1: Enabled2: Disabled3: No key4: Unknown5: Invalid6: Unset


keyQueryProtection R/W Enum1: Module2: Cardset3: No key4: Unknown5: Invalid6: Unset


keyQueryCardsetHash R/W DisplayString Hash of the cardset protecting the key, if applicable

keyQueryFlags R/W DisplayString Certificate and public key flags

keyQueryExtraEntities R/W Unsigned32 Number of extra key attributes

keyQuerySEEInteg R/W DisplayString SEE integrity key, if present

keyQueryGeneratingESN

R/W DisplayString ESN of the module that generated the key, if present

keyQueryTimeLimit R/W Gauge Time limit for the key, if set (0 for no limit)

keyQueryPerAuthUseLimit

R/W Gauge Per-authentication use limit for the key (0 for no limit)



Statistics sub-tree overview

The statistics sub-tree (enterprises.nCipher.nC-series.statistics) contains rapidly-changing information about the state of the nCipher modules, the work they are doing, the commands being submitted, and so on.

Note Do not rely on information returned from the agent to change instantaneously on re-reading the value. To avoid loading the nCipher module with multiple time-consuming statistics commands, the agent can choose to cache the values over a specified period. You can configure this period in the agent configuration file (see The SNMP agent configuration file - snmpd.conf on page 366).

Statistics sub-tree and module statistics table

The following table gives details of the nodes in the statistics sub-tree, and the module statistics table (enterprises.nCipher.nC-series.statistics.moduleStatsTable):


moduleStatsIndex R Integer Module number of this row (for moduleStatsTable)

[hs]uptime R Counter32 Uptime of the hardserver or module

cmdCount[All] R Counter32 Returned aggregated for all modules and all commands, and per-module for all commands

cmdBytes[All] R Counter32

cmdErrors[All] R Counter32 Returned as for cmdCount. When per-module total, aggregate all the different error states into one counter. When aggregated, returned value is combined module errors added to hardserver marshalling/unmarshalling errors.

replyCount[All] R Counter32

replyBytes[All] R Counter32

replyErrors[All] R Counter32 see notes above for cmdErrors



netHSM statistics table

The following table gives details of the nodes in the netHSM statistics table (enterprises.nCipher.nC-series.statistics.netHSMStatsTable):

clientCount R Counter32

maxClients R Counter32

deviceFails R Counter32

deviceRestarts R Counter32

load[All] R Counter32

outstandingCmds R Counter32 Total no. of outstanding commands over all modules

objectCount R Counter32

clock R DisplayString Depending on the module settings, this can require KNSO permissions to read (and therefore depend on the installation parameters of the agent)

currentTemp R DisplayString Character representation of the current temp value (SNMP does not provide for a floating-point type)

maxTemp R DisplayString Maximum temperature the module has ever reached

nvRAMInUse R Counter32

volatileRAMInUse R Counter32



netHSMStatsIndex R Integer Table index (not module number)

netHSMUptime R Counter32 netHSM host system uptime

netHSMCPUUsage R Gauge32 CPU usage of netHSM host processor

netHSMUserMem R Gauge32 Total user memory of netHSM

netHSMKernelMem R Gauge32 Total kernel memory of netHSM

netHSMCurrentTemp R DisplayString Internal netHSM temperature (sensor 1)

netHSMMaxTemp R DisplayString Max. recorded temp (sensor 1)



Software versions table

The following table gives details of the nodes in the software versions table (enterprises.nCipher.softwareVersions.softwareVersionsTable); see ncversions on page 257:

netHSMCurrentTemp2 R DisplayString Internal netHSM temperature (sensor 2)

netHSMMaxTemp2 R DisplayString Max. recorded temp (sensor 2)

netHSMPower5V R DisplayString netHSM 5V power reading

netHSMPower12V R DisplayString netHSM 12V power reading

netHSMFanSpeed R Gauge32 Fan 1 speed (RPM)

netHSMFan2Speed R Gauge32 Fan 2 speed (RPM)

netHSMFan3Speed R Gauge32 Fan 3 speed (RPM)

netHSMIPAddress R IpAddress IP address of netHSM

netHSMDescription R DisplayString Textual description of module (for example, Local module #3)



compIndex R Integer Table index

compName R DisplayString Component name

compOutput R Component output name

Component name

compMajorVersion R Gauge

compMinorVersion R Gauge

compPatchVersion R Gauge

compRepository R DisplayString Repository name

compBuildNumber R Gauge


F The nCipher SNMP monitoring agent Useful nCipher SNMP agent command-lineswitches

Useful nCipher SNMP agent command-line switches

SNMP agent (snmpd) switches

The SNMP agent that binds to a port and awaits requests from SNMP management software is snmpd. Upon receiving a request, snmpd processes the request, collects the requested information and/or performs the requested operation(s) and returns the information to the sender.

The nCipher SNMP agent supports a limited subset of command line switches that can be specified when starting the agent.

Usage

e:\ncipher\devel\ncsnmp\src\ntbuild\agent\snmpd.exe -register [param list] |

-unregister |

[-h] [-v] [-f] [-a] [-d] [-V] [-P PIDFILE):] [-q] [-D] [-p NUM]

[-L] [-l LOGFILE] [-r]

In this command:

-h

This option displays a usage message.

-register [param list]

This option registers the agent as a Windows service, and starts the service.

param list is a startup parameter list for service, the same as normal parameters, for example

snmpd.exe -register -p 2002

registers snmpd.exe as service, which listens on port 2002.



Some options do not make sense when the agent is running as service.

-unregister

This option unregisters the service if it is already registered.

-H

This option displays the configuration file directives that the agent understands.

-v

This option displays version information.

-f

This option specifies not forking from the calling shell.

-a

This option specifies logging addresses.

-d

This option specifies the dumping of sent and received UDP SNMP packets.

-V

This option specifies verbose display.

-P PIDFILE

This option specifies the use of a file (PIDFILE) to store the process ID.

-q

This option specifies that information be printed in a more parsable format (quick print).



-D

This option turns on debugging output.

-p NUM

This option specifies running on port NUM instead of the default: 161.

-c CONFFILE

This option specifies reading CONFFILE as a configuration file.

-C

This option specifies that the default configuration files not be read.

-L

This option prints warnings/messages to stdout/err.

-s

This option logs warnings/messages to syslog.

-r

This options specifies not exiting if root-only accessible files cannot be opened.

-I [-]INITLIST

This option specifies a list of MIB modules to initialize (or not). Runsnmpd with -Dmib_init for a list.

-l LOGFILE

This option prints warnings/messages to a file LOGFILE (by default, LOGFILE=log/snmpd.log).


F The nCipher SNMP monitoring agent Using the SNMP command line tools

Using the SNMP command line tools

As an alternative to using an SNMP manager application, nCipher supplies several command-line utilities to test your SNMP installation and that enable you to obtain information about your nCipher module from the nCipher SNMP agent:

snmptest

This utility monitors and manages SNMP information.

snmpget

This utility queries for SNMP information on a network entity.

snmpset

This utility sets SNMP information on a network entity.

snmpgetnext

This utility queries for SNMP information on a network entity.

snmptable

This utility obtains and prints an SNMP table.

snmptranslate

This utility translates SNMP objects into something more useful.

snmpwalk

This utility communicates with a network entity using GET NEXT request.


F The nCipher SNMP monitoring agent Using the SNMP command line tools

snmpbulkwalk

This utility communicates with a network entity using BULK request.

These tools are general purpose SNMP utilities and can be configured for use with other SNMP agents. For more information on configuring and using these tools, refer to the NET-SNMP project Web site: http://net-snmp.sourceforge.net/.


Internet addresses

Note nCipher also maintain international sales offices. Please contact the UK, or the US, head office for details of your nearest nCipher representative.

nCipher Corporation Ltd. nCipher Inc.

Cambridge, UK

Jupiter HouseStation RoadCambridgeCB1 2JDUK

Boston Metro Region, USA

92 Montvale Avenue, Suite 4500Stoneham, MA 02180USA

Tel:Fax:

+44 (0) 1223 723600+44 (0) 1223 723601

Tel:

Fax:

800-NCIPHER800-6247437+1 (781) 994 4000+1 (781) 994 4001

E-mail:[email protected]@ncipher.com

E-mail:[email protected]@ncipher.com

Web Site: http://www.ncipher.com/

Online Documentation: http://active.ncipher.com/documentation/

nCipher addresses


http://active.ncipher.com/documentation/

Date post:	20-Mar-2021
Category:	Documents
Upload:	others
View:	17 times
Download:	3 times

nShield/payShield Administrator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher...

Documents