Sunteți pe pagina 1din 387

nShield/payShield Administrator Guide Windows

Version: Date:

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

Commercial Computer Software - proprietary This computer software and documentation is Commercial Computer Software and Computer Software Documentation, as defined in sub-paragraphs (a)(1) and (a)(5) of DFAR 252.227-7014, "Rights in Noncommercial Computer Software and Noncommercial Computer Software Documentation". Use, duplication or disclosure by the Government is subject to nCipher's standard US Terms And Conditions for the Product. Patents UK Patent GB9714757.3. Corresponding patents/applications in USA, Canada, South Africa, Japan and International Patent Application PCT/GB98/00142.

nShield/payShield Administrator Guide Windows v5.5

Contents

Chapter 1:

Introduction General information Audience Contents of this guide Conventions Additional Documentation Further information

10 10 11 11 13 16 16 18 20 24 25 25 31 34 35 37 37 38 39 39

Chapter 2:

nCipher security worlds Security Application independence Platform independence Flexibility Robustness Scalability KeySafe and security worlds Applications and the security world The nCipher PKCS #11 library and security worlds Risks

Chapter 3:

Getting the module working Determining module requirements

nShield/payShield Administrator Guide Windows v5.5

Prerequisites to software installation Software installation procedure After software installation Configuring the module Creating and configuring a security world Creating and configuring a payShield installation Creating the Operator Card Set Chapter 4: Changing the module state Entering the pre-maintenance state Entering the pre-initialization state Entering the operational state Chapter 5: Uninstalling Uninstalling the nCipher support software Chapter 6: Configuring the hardserver Remote module connections Hardserver settings Hardserver start-up settings Remote slots SEE machines Hardserver configuration file Payments configuration file Chapter 7: Using multiple modules Identifying modules Multiple modules and Remote Operator Adding a module

40 43 46 51 56 64 71 76 76 78 79 82 82 83 83 84 84 84 85 85 96 98 98 99 100

nShield/payShield Administrator Guide Windows v5.5

Module fail over Chapter 8: Feature Enabling nCipher Modules Available Features payShield features Ordering features for your module Enabling features Chapter 9: Using CodeSafe Applications CodeSafe/C applications Chapter 10: Using KeySafe Starting KeySafe The KeySafe window Errors Chapter 11: Managing security worlds Security world files Security world options Creating a security world After you have created a security world Adding or restoring a module to the security world Erasing a module from a security world Deleting the security world Displaying information about your security world Windows Cryptographic Services Provider (CSP) Transferring keys between security worlds

100 101 101 103 104 105 108 108 109 109 111 120 123 123 125 129 154 155 162 165 166 179 185

nShield/payShield Administrator Guide Windows v5.5

Chapter 12:

About payShield installations About payShield Card Sets Supported payShield Key Types payShield security world properties

187 187 190 191 193 193 194 200 200 202 218 220 221 226 226 227 228 229 238 242 244 246 250 253 255

Chapter 13:

Remote Operator Card Sets About Remote Operator Configuring Remote Operator

Chapter 14:

Administration tasks with cards and softcards Replacing an Operator Cards pass phrase Replacing Operator Card Sets Changing pass phrases with cardpp Changing pass phrases with ppmk Replacing the Administrator Card Set

Chapter 15:

nShield Administrator Utilities Help options anonkneti cfg-reread enquiry floodtest hardserver initunit loadkeys key-xfer-im loadrom mk-reprogram

nShield/payShield Administrator Guide Windows v5.5

ncversions new-world nvram-backup nvram-sw payshield-config payshield-info payshield-install postrocs ppmk preload racs rfs-setup rfs-sync rtc slotinfo sppupgradekeys stattree Appendix A: Upgrading module firmware Version Security Number Firmware on the CD-ROM What must I do? Key data Firmware installation overview PCI modules After firmware installation

257 259 266 272 278 280 283 286 287 290 301 302 304 307 310 312 314 323 323 324 325 325 326 327 329

nShield/payShield Administrator Guide Windows v5.5

Appendix B:

Components on nCipher CD-ROMs nCipher component bundles nCSS User CD-ROM CipherTools CD-ROM CodeSafe CD-ROM Components Required for Particular Functionality PKCS #11 applications Cryptographic Hardware Interface Library applications nCipherKM JCA/JCE cryptographic service provider nCipher SNMP monitoring agent

330 330 335 335 336 337 338 338 338 339 340 343 343 348 349 350 350 352 354 361 362 363 363 363 364

Appendix C: Appendix D:

Environment variables Logging and debugging Environment variables to control logging Logging from the nCipher CSP Logging and debugging information for PKCS #11 Hardserver debugging Debugging information for payShield Debugging information for Java

Appendix E: Appendix F:

Installed Utilities The nCipher SNMP monitoring agent Activating the nCipher SNMP agent Default settings Do you already have an SNMP agent running? Activation of the SNMP agent Further Information

nShield/payShield Administrator Guide Windows v5.5

Using the nCipher SNMP agent with a manager application 367 Useful nCipher SNMP agent command-line switches Using the SNMP command line tools 382 385

nShield/payShield Administrator Guide Windows v5.5

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

nShield/payShield Administrator Guide Windows v5.5

10

1 Introduction

Audience

Audience
Read this guide if you need to configure or administer an nShield or payShield module, and you use or require an nCipher security world to protect your keys. This guide assumes that you are familiar with the basic concepts of cryptography and Public Key Infrastructure (PKI). This guide assumes that you have read the Hardware Installation Guide and that you have installed your nShield or payShield module.

Contents of this guide


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

nShield/payShield Administrator Guide Windows v5.5

11

1 Introduction

Contents of this guide

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

nShield/payShield Administrator Guide Windows v5.5

12

1 Introduction

Conventions

Conventions
nCipher modules
The following terms are used to distinguish different module versions:
Term
nCipher PCI module nCipher nToken module nCipher netHSM module

Model number
nCnnnnP-nnn nC2022p-000 or nC2023p-000 nHnnnn

Used for
Any nCipher module with a PCI interface. an nCipher nToken module (PCI interface). Any nCipher netHSM module (netHSM 300/800/1600, payShield net, or payShield Ultra net). Any nCipher module that does not support key management (nFast module). Any nCipher module that supports key management (nForce, nShield, payShield, netHSM 300/800/1600, payShield net, or payShield Ultra net). The OEM PCI 1600 modules are supplied to OEM customers only.

acceleration-only module

nC10nnX-nnn

key-management module

nC30nnX-nnn, nC40nnX-nnn, or nHnnnn

OEM PCI 1600 key-management module

nC3033P-1600

In this table, n is any integer.

nShield/payShield Administrator Guide Windows v5.5

13

1 Introduction

Conventions

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

nCipher software
The hardserver software controls communication between applications and nCipher modules, which may be installed locally or remotely. It runs as a service on the host computer. The nCipher support software is a collection of programs and utilities, including the hardserver, supplied by nCipher to install and maintain your nCipher security system.

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

nShield/payShield Administrator Guide Windows v5.5

14

1 Introduction

Conventions

Typographical conventions
Note The word Note in the margin indicates the appearance of important supplemental information. If there is a danger of static damage, this is indicated by the reaching hand symbol in the margin. If there is a danger of loss or exposure of key material (or any other security risk), this is indicated by a security triangle in the margin. If there is a danger of damage to the hardware, this is indicated by a caution triangle in the margin. If you see this symbol on the product itself, please refer to the Hardware Installation Guide. If there is a danger of electric shock to the user, this is indicated by a warning triangle in the margin. Examples of onscreen terminal display, both of data returned and of your input, are represented in a form like this:
install

Keyboard keys that you must type are represented like this: Enter , Ctrl - C .

nShield/payShield Administrator Guide Windows v5.5

15

1 Introduction

Additional Documentation

Additional Documentation
This guide forms one part of the information and support provided by nCipher. The following documents are produced to support nCipher products, and the guides for your product can be found in the document directory of the CD-ROM for that product:
Guide
Hardware Installation Guide, for information on hardware installation and troubleshooting; a printed copy is also supplied with nCipher modules (part number N-001027). nShield/payShield Operator Guide, for information on managing keys and other tasks with an nShield/payShield module that do not require an Administrator Card. CodeSafe/C Developers Guide, for reference material about developing in C for the Secure Execution Environment. Integration Guide, for information on developing applications with an nCipher module using industry standard interfaces. nCore Developers Guide, for information on developing applications with an nCipher module using the nCipher API and NFKM library. nCore Developers Reference, for reference material covering nCipher API, C generic stub, and NFKM libraries. payShield Developer Reference, for payShield developer reference material Key-loading Solution Guide, for information about nCiphers key-loading solution.

PDF file
Hardware_Installation.pdf

nShield_Operator.pdf

CodeSafe_C_Developer.pdf

Integration_Guide.pdf

nCore_Developer_Guide.pdf

nCore_Developer_Ref.pdf

payShield_Developer_Ref.pdf Key-loading_Solution.pdf

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

nShield/payShield Administrator Guide Windows v5.5

16

1 Introduction

Further information

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

nShield/payShield Administrator Guide Windows v5.5

17

Chapter 2: nCipher security worlds


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

The security world infrastructure lets you perform and control all these activities under your chosen security policy. A security world consists of: one or more nCipher payShield, nForce, nShield, or netHSM modules

nShield/payShield Administrator Guide Windows v5.5

18

2 nCipher security worlds

nCipher security worlds

a set of Administrator smart cards used to control access to security world configuration and recovery operations. (Security worlds compliant with the Federal Information Processing Standards (FIPS) 140-2 at level 3 require the use of smart cards to authorize most operations; see FIPS 140-2 compliance on page 23 for more information about nCipher and FIPS.) an optional set or sets of Operator smart cards used to control access to application keys. (Security worlds compliant with the Federal Information Processing Standards (FIPS) 140-2 at level 3 require the use of smart cards to authorize most operations; see FIPS 140-2 compliance on page 23 for more information about nCipher and FIPS.) some cryptographic key and certificate data that is encrypted using the security world key and stored on a host computer or computers.

Figure 1 shows how these components are related to one another. Cards, keys, and even modules can be added or removed at any time. These elements are linked by the security world key, which is unique to each world. Distributing the keys used for different tasks within the security world over different storage media means that a security world can recover from the loss of any one element. It also increases the difficulties faced by an attacker, who needs to obtain all the elements before gaining any information.

nShield/payShield Administrator Guide Windows v5.5

19

2 nCipher security worlds

Security

Figure 1

The security world

Security
Most importantly, a key-management system must store keys securely. Security must be designed into the system from the start; it cannot be added later. The nCipher security world has been designed to ensure that keys remain secure throughout their life cycle. The security world uses multiple interlocking keys, and because of this, each key is always protected by another key, even during recovery operations.

nShield/payShield Administrator Guide Windows v5.5

20

2 nCipher security worlds

Security

Because the security world is built around nCipher key-management modules, keys are only ever available in plain text in secure hardware. The security world uses smart cards for two different purposes: Note one set of cards forms an Administrator Card Set that is used to control access to recovery functions one or more sets of cards referred to as Operator Card Sets that are used to control access to application keys.

In strict FIPS 140-2 Level 3 security worlds, the Administrator Card Set or an Operator Card Set is needed to authorize most operations, including the creation of keys and Operator Card Sets. Each card set consists of a number of smart cards, N, of which a smaller number, K, is required to authorize an action. The required number is sometimes referred to as the threshold.

Note

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

Note

An individual smart card can be used as either a part of the Administrator Card Set or as part of an Operator Card Set, but not as part of both.

nShield/payShield Administrator Guide Windows v5.5

21

2 nCipher security worlds

Security

Security worlds and Remote Operator


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

Security worlds shared with netHSM modules


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

nShield/payShield Administrator Guide Windows v5.5

22

2 nCipher security worlds

Security

FIPS 140-2 compliance


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

FIPS 140-2 level 3 compliance


When you create a security world, you can choose whether you want the security world to comply with the roles and services section of FIPS 140-2 at level 2 or level 3. The FIPS 140-2 level 3 option is included for those customers who have a regulatory requirement for compliance with FIPS 140-2 at level 3. A security world that complies with FIPS 140-2 level 3 requires authorization from any smart card that is part of the security worlds Administrator Card Set, or an Operator Card Set, before you can create or erase an Operator Card Set. Note A security world only provides a complete level 3 compliant system when used with nShield and payShield modules, which have the additional physical security coating required by the FIPS 140-2 level 3. If you choose to create a security world that complies with FIPS 1402 level 3, the module initializes in strict FIPS mode. This option ensures that the module complies with the roles and services, key management, and self-test sections of FIPS 140-2 at level 3, as described in its validation certificate. For more details of the nShield/Payshield FIPS 140-2 validation see http://csrc.nist.gov/cryptval/140-2.htm

nShield/payShield Administrator Guide Windows v5.5

23

2 nCipher security worlds

Application independence

Application independence
A security world can protect keys for any nCipher-aware software. Each key belongs to a specific application and is only ever used by that application. However, within a single security world, every key can belong to a different application. Keys are stored along with any additional data that is required by the application. You do not need to specify which applications you will use. You can add a key for any supported application at any time. The security world requires no knowledge of how the key will be used by an application. A security world controls the protection for the key; the application determines how it is used. Although keys belong to a specific application, Operator Card Sets do not. If a user requires keys for different applications, they can all be protected under the same Operator Card Set. Figure 2 illustrates this. Figure 2 Operator Card Sets, keys, and applications

nShield/payShield Administrator Guide Windows v5.5

24

2 nCipher security worlds

Platform independence

Card Set 1 protects keys for use with Application 1 and Application 2. Card Set 2 protects a single key for use with Application 2. Card Set 3 protects keys for use with Application 2 and Application 3. The security world protects a key for use with Application 3.

Platform independence
A security world is completely platform independent. All key information is stored in nCipher's proprietary format. This format can be read by any computer supported by nCipher, regardless of the native format used by that computer. This means that you can safely move a security world between platforms, even between platforms with differing native formats. For example, you can move a security world between Windows and UNIX platforms. You can also include hosts running different operating systems in the same security world. Note When copying host data between computers using different Operating Systems or disk formats, use a mechanism that preserves the original data format and line endings (such as .tar file archives).

Flexibility
Within a security world, you can choose the relevant level of protection for each application key that you create. When you create a security world, a cryptographic key is generated that protects the application keys and Operator Card Sets in the created security world. You can choose to make this security world key can be a Triple DES (Data Encryption Standard) or an AES (Advanced Encryption Standard) key.

nShield/payShield Administrator Guide Windows v5.5

25

2 nCipher security worlds

Flexibility

Using the security world key: module-protected keys


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

Using Operator Card Sets: card-set protected keys


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

nShield/payShield Administrator Guide Windows v5.5

26

2 nCipher security worlds

Flexibility

Using card sets for extra security


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

Using card sets to share keys


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

Using card sets for high availability


You may have some keys to which you must have access at all times and with which you cannot afford to risk the failure of a smart card. In such a case, you can create a 1-of-2 card set. Use the first card as the working card and store the spare second card in a safe. If the

nShield/payShield Administrator Guide Windows v5.5

27

2 nCipher security worlds

Flexibility

working card fails, retrieve the spare card from the safe and use it until you re-create a new set of two cards, as described in Replacing an Operator Card Set or recovering keys to softcards on page 32. Note You can only recover card sets that were created with the recovery option explicitly set.

Using pass phrases


Each Operator Card can be given a pass phrase. The pass phrases are independent. You can choose to give only some cards in a card set pass phrases. You can change the pass phrase on a card at any time. For information on changing pass phrases, see Changing pass phrases with cardpp on page 218 or the appropriate Operator Guide for your module. This requires the card, the existing pass phrase, and a module that belongs to the security world. Note Some applications do not support the use of pass phrases. There is no absolute limit on the length of pass phrases. However, some applications may not accept pass phrases longer than 255 characters. Likewise, the security world does not impose restrictions on which characters you can use, although some applications may not accept certain characters.

Using persistent Operator Card Sets


If you create a standard Operator Card Set, the keys protected by a card can only be used while that card, or the last card loaded in the case of card sets, is in the nCipher modules smart card reader. The keys protected by this card are removed from the memory of the module as soon as the card is removed from the smart card reader. Although this feature provides added security, it means that only one user can load keys at any time because there is only one smart card reader on the module.

nShield/payShield Administrator Guide Windows v5.5

28

2 nCipher security worlds

Flexibility

Keys that are protected by a given Operator Card Set cannot be shared simultaneously between a large pool of modules. Therefore, the security world architecture gives you the option of making an Operator Card Set persistent. This means that the keys protected by a card persist after the card has been removed. This enables you to use the same smart card in several modules simultaneously. It also means that several users can load keys onto the same module at the same time. The nCipher support software maintains strict separation between the keys loaded by each user, and each user only has access to the keys protected by their Operator Card Set. Keys protected by a persistent card are automatically removed from the module: Note when the application that loaded the Operator Card Set closes the connection to the module. after a time limit that may be specified when the card set is created. when an application chooses to remove a key.

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

nShield/payShield Administrator Guide Windows v5.5

29

2 nCipher security worlds

Flexibility

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

Using softcard-protected keys


If you want to use pass phrases to restrict key access but avoid using physical tokens (as required by smart-card protection), you can create a softcard-protected key. A softcard is a file containing a logical token that cannot be loaded without a pass phrase; its logical token must be loaded in order to authorize the loading of any key that is protected by the softcard. Softcard files are stored in the kmdata directory and have names of the form softcard_hash (where hash is the hash of the logical token share). Softcard-protected keys offer greater security than module-protected keys and also have greater availability than keys protected by operator card sets (albeit without the greater security obtained through the requirement of physical tokens to authorize key-loading). A softcard's pass phrase is set when you generate it, and you can use a single softcard to protect multiple keys. Softcards function as persistent 1-of-1 logical tokens, and after a softcard is loaded, it remains valid for loading its keys until its KeyID is destroyed.

nShield/payShield Administrator Guide Windows v5.5

30

2 nCipher security worlds

Robustness

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

Backup and recovery


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

nShield/payShield Administrator Guide Windows v5.5

31

2 nCipher security worlds

Robustness

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

Replacing the Administrator Card Set


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

Replacing an Operator Card Set or recovering keys to softcards


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

nShield/payShield Administrator Guide Windows v5.5

32

2 nCipher security worlds

Robustness

Similarly, you can recover keys protected by one softcard to another softcard. Note The ability to recover an Operator Card Set is an option that is enabled by default during security world creation. To disable recoverability, you must explicitly choose to do so during the security world creation process. Once set during security world creation, the ability (or inability) to recover an Operator Card Set can never be altered. Keys protected by an Operator Card Set can only be recovered to another Operator Card Set, and not to a softcard. Likewise, softcardprotected keys can only be recovered to another softcard, and not to an Operator Card Set. You can use the rocs command-line utility or KeySafe to create new working copies of your keys protected by the key on a given card set. To recover keys protected by one softcard to another softcard, you must use the rocs command-line utility. Replacing Operator Card Sets and softcards requires authorization. Otherwise, an attacker could simply duplicate a set or softcard without your knowledge. Therefore, the recovery keys are protected by the Administrator Card Set. Storing any key recovery data introduces some extra risk, because an attacker with the Administrator Card Set and a copy of the recovery data could re-create your security world. You may have some keys that you consider to be especially sensitive. In this case, if you lose the Operator Card Set that protects the key, you may choose to issue a new key. Therefore, you can turn off the key recovery feature for the security world or for a specific key. Recovery data can only be generated when you create the security world or key. If you choose not to create recovery data when you generate the security world or key, it cannot be added later. If you have not selected the recovery feature for the security world, it cannot be enabled for any key in the security world.

Note

nShield/payShield Administrator Guide Windows v5.5

33

2 nCipher security worlds

Scalability

Similarly, if you choose to create recovery data when you generate the security world or key, it cannot be removed later in a secure manner. The recovery data for application keys is kept separate from the recovery data for the security world key. The security world always creates recovery data for the security world key. It is only the recovery of application keys that is optional.

Scalability
A security world is scalable. You can add multiple modules to a server and share a security world across multiple servers. You can also add Operator Card Sets and application keys at any time. You do not need to make any decisions about the size of the security world when you create it. To share a security world across multiple servers: ensure each server has at least one module fitted copy the host data to each server or make it available on a shared disk use the recovery data and the Administrator Card Set to load the required cryptographic keys securely onto every module.

If you want to have access to the same keys on every server, you must ensure that all changes to the data are propagated to the remaining servers. If your are part of a cluster, then the tools provided by the cluster should synchronize the data. If the servers are connected by a network, then they could all access the same copy of the data. There is no risk of an attacker obtaining information by snooping on the network, as the data is only ever decrypted inside a module. Alternatively, you can maintain copies of the data on different servers. It is now possible to allow non-netHSM modules to automatically access the remote file system (RFS) used by netHSM and payShield NET modules and to share security world and key data stored in the

nShield/payShield Administrator Guide Windows v5.5

34

2 nCipher security worlds

KeySafe and security worlds

kmdata directory. Client modules that access data in this way are

described as cooperating clients. See Setting up client cooperation on page 53 for more information.

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

KeySafe and security worlds


KeySafe provides an intuitive and easy-to-use graphical interface for managing security worlds. KeySafe manages the security world and the keys protected by it. See the Operator Guide for full information about KeySafe. Note Most applications store only their long-term keys in the security world. Session keys are short term keys generated by the application which are not normally loaded into the security world. Although you use KeySafe to generate keys, it is your chosen application that actually uses them. You do not need KeySafe to make use of the keys that are protected by the security world. For example, if you share a security world across several host computers, you do not need to install KeySafe on every computer. If you want to manage the security world from a single computer, you can install KeySafe on just that one computer even though you are using the security world data on other machines. KeySafe enables you to:

nShield/payShield Administrator Guide Windows v5.5

35

2 nCipher security worlds

KeySafe and security worlds

Note

create a security world and its Administrator Card Set, either FIPS 140-2 level 2 or level 3

This option provides compliance with the roles and services of the FIPS 140- 2 level 3 standard. It is included for those customers who have a regulatory requirement for compliance. add a module to a security world remove a module from a security world replace an Administrator Card Set create Operator Card Sets list the Operator Card Sets in the current security world change the pass phrase on an Operator Card remove a lost Operator Card Set from a security world replace Operator Card Sets erase an Operator Card add a new key to a security world import a key into a security world list the keys in the current security world delete a key from a security world.

KeySafe does not provide tools to back up and restore the host data or update module firmware, nor does KeySafe provide tools to synchronize host data between servers. These functions can be performed with your standard system utilities. In addition to KeySafe, nCipher also supplies command-line utilities to manage the security world. Current versions of these tools can be used interchangeably with the current version of KeySafe.

nShield/payShield Administrator Guide Windows v5.5

36

2 nCipher security worlds

Applications and the security world

Applications and the security world


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

The nCipher PKCS #11 library and security worlds


Many applications use a PKCS (Public Key Cryptography Standard) #11 library to generate and manage cryptographic keys. nCipher has produced a version of the PKCS #11 library that uses the security world to protect keys. Enabling a PKCS #11 based application to use nCipher hardware key protection involves configuring the application to use the nCipher PKCS #11 library. A PKCS #11 token created by the nCipher PKCS #11 library is a security world Operator Card Set. The current PKCS #11 standard only supports tokens that are part of a 1-of-N card set. A security world does not make any distinction between different applications that use the nCipher PKCS #11 library. Therefore, you can create a key in one PKCS #11 compliant application and make use of it in a different PKCS #11 compliant application.

nShield/payShield Administrator Guide Windows v5.5

37

2 nCipher security worlds

Risks

Risks
Even the best-designed tools cannot offer security against every risk. Although a security world can control which user has access to which keys, it cannot prevent a user from using a key fraudulently. For example, a security world can only determine whether a user is authorized to use a particular key; it cannot determine whether the message being sent with that key is accurate. A security world can only manage keys that were created inside the security world; keys created outside a security world, even if imported into the security world, may remain exposed to a security risk. Most failures of security systems are not the result of inherent flaws in the system, but result from carelessness on the part of the users. The following basic rules apply to any security system: Note Keep your smart cards safe. Always obtain smart cards from a trusted source: from nCipher or directly from Gemplus. Never insert a smart card used with nCipher key management into an untrusted smart card reader. Never insert any untrusted smart card into your module. Never tell anyone your pass phrase. Never write down your pass phrase. Never use a pass phrase that is easy to guess. Only use the Administrator Card Set in modules connected to trusted hosts.

If you have any doubts about the security of a key and/or security world, you should replace that key and/or security world with a newly generated one.

nShield/payShield Administrator Guide Windows v5.5

38

Chapter 3: Getting the module working


This chapter describes the steps involved in setting up the nCipher software to work with the module for the first time. These steps must be performed in the following order: 1. 2. Determine the requirements for the module, as described in Determining module requirements on page 39. Complete any prerequisites to installing nCipher support software, as described in Prerequisites to software installation on page 40. Install the software, as described in Software installation procedure on page 43. Perform post-installation tests and software environment configurations, as described in After software installation on page 46. 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 Create and configure the security world, as described in Creating and configuring a security world on page 56. Configure the payShield installation, as described in Creating and configuring a payShield installation on page 64. Create the Operator Card Set, as described in Creating the Operator Card Set on page 71.

3. 4.

5.

6. 7. 8.

Determining module requirements


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

nShield/payShield Administrator Guide Windows v5.5

39

3 Getting the module working

Prerequisites to software installation

which optional components of the nCipher software you need to install. To do this you need to know: the applications that are to use the module. any constraints on installing software on your computer.

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

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

Prerequisites to software installation


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

Installing and connecting the module


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

nShield/payShield Administrator Guide Windows v5.5

40

3 Getting the module working

Prerequisites to software installation

Removing existing installations


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

Installing Java patches


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

nShield/payShield Administrator Guide Windows v5.5

41

3 Getting the module working

Prerequisites to software installation

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

Identifying which components to install


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

You must install the hwsp Hardware Support bundle. If the hwsp Hardware Support bundle is not installed, your module cannot function. Note The nfdrv Windows device drivers component, required if you are using an nCipher PCI card, is installed as part of the hwsp Hardware Support bundle.

nShield/payShield Administrator Guide Windows v5.5

42

3 Getting the module working

Software installation procedure

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

Software installation procedure


You should have removed any nCipher installation on the computer before starting this installation. See Chapter 5: Uninstalling for more information on uninstalling your software. If the installer detects an existing nCipher installation, it asks you if you want to install the new components. These components replace your existing installation, but the installer does not delete other components that you have created. Note Because the nCipher server is installed as a service, it is only possible to have one nCipher installation on any given computer. nCipher supplies the nCipher client software as bundles of standard packages that provide much of the required software for your installation. In addition to the standard bundles, nCipher provides individual packages for use with specific applications and features supported by the module. Ensure you have determined which bundles or packages you require before beginning the installation. (See Identifying which components to install on page 42; further details about the contents of bundles and packages are provided in Appendix B: Components on nCipher CD-ROMs.) Note Visit the nCipher Web site support section to download Application Guides that give advice on installing nCipher modules with a range of third party applications.

nShield/payShield Administrator Guide Windows v5.5

43

3 Getting the module working

Software installation procedure

nCipher supplies Windows 2000 Plug and Play drivers for the nCipher module. These drivers have also been tested with Windows 2003 Server. Take the following steps to install the nCipher server and associated software: 1. 2. Log in as Administrator or as a user with local administrator rights. 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. 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

4.

nShield/payShield Administrator Guide Windows v5.5

44

3 Getting the module working

Software installation procedure

you require. See Appendix B: Components on nCipher CD-ROMs for more information about choosing which components to install. By default, the installer places files in the C:\nfast directory, but you are given the option of selecting a different directory. If the installer detects an existing installation in a different directory, it offers this other directory as the default. 5. Note Click the Next button, and the installer installs and performs basic configuration of the selected components.

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. b. installs the correct nCipher CSP makes the nCipher CSP the default SChannel provider, if requested.

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

nShield/payShield Administrator Guide Windows v5.5

45

3 Getting the module working

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. If you chose to install the nCipher PKCS #11 library and have an existing PKCS #11 installation, the installer advises you of this. The installer asks whether you want to configure the PKCS #11 library for use with Check Point VPN-1/Firewall-1. You can choose to do one of the following: a. Select Yes, and then follow the steps in the Check Point configuration dialog. See Check Points product documentation for further information. 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.

8.

b.

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. 2. Log in as a normal user. Open a command window.

nShield/payShield Administrator Guide Windows v5.5

46

3 Getting the module working

After software installation

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.

nShield/payShield Administrator Guide Windows v5.5

47

3 Getting the module working

After software installation

Testing the smart card reader


On external smart card readers fitted to an nCipher PCI module, the LED lights up red when the computer is switched on. If the LED does not light up, check the connection. The LED changes color to green whenever a card is inserted. If it does not change, check that you have fully inserted the card. Note The LED is triggered by a mechanical switch that indicates only that the card is inserted. It does not indicate that the card is a valid smart card or that it is the correct way up. The LED flashes briefly when you reset the module and when the module changes state. Note Always insert the smart card with the contacts facing up. You can check that the card reader of any module is working correctly by inserting an nCipher smart card and using the following test command (assuming that you installed the server in the default directory):
C:\nfast\bin slotinfo -m MODULE [-s SLOT]

In this command, MODULE is the number of the module and SLOT is the number of the slot. If you have only one module, MODULE is 1, and if you do not specify a slot number, slotinfo returns information about all slots. This command should return either:
Module n slot 0: Token not formatted

nShield/payShield Administrator Guide Windows v5.5

48

3 Getting the module working

After software installation

or
Module n slot 0: Authentication key: 00000000-00000000-00000000-00000000-00000000 No data on token 3698 bytes free

Note

The authentication key and data size may vary.

Monitoring the module using Performance Monitor


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

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

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

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

Setting the environment variables


You can set nCipher specific environment variables as follows: 1. Open the System dialog box by clicking the System icon in the Control Panel.

nShield/payShield Administrator Guide Windows v5.5

49

3 Getting the module working

After software installation

2. 3. 4. 5. 6. 7.

Select the Advanced tab and click the Environment Variables button. To add a variable, click New. Alternatively, to edit an existing variable select an entry in the System Variables list and click Edit. In the Variable Name text box, type or edit the name of the environment variable (for example, NFAST_HOME). In the Variable Value text box, type or edit the value to use. Click the OK button to set the value, and then click the OK button to close the dialog box. Restart the nFast Server service.

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

Logging and debugging


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

nShield/payShield Administrator Guide Windows v5.5

50

3 Getting the module working

Configuring the module

Note

NFLOG_SEVERITY NFLOG_DETAIL NFLOG_CATEGORIES

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

Configuring Java support for KeySafe


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

Configuring the module


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

nShield/payShield Administrator Guide Windows v5.5

51

3 Getting the module working

Configuring the module

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

The hardserver configuration file defines the configuration of the hardserver. It is stored in the directory %NFAST_HOME%\kmdata\config, which by default is C:\nfast\kmdata\config. A default version of this file is created when the nCipher support software is installed. See Chapter 6: Configuring the hardserver for full information about the hardserver configuration file. Note In some previous releases of nCipher support software, hardserver configuration was controlled by environment variables. The use of these variables has been deprecated. If any of these environment variables are still set, they override the settings in the configuration file. You must load the configuration file for the changes to the configuration to take effect. To configure the hardserver, follow these steps: 1. Save a copy of the configuration file
C:\nfast\kmdata\config\config so that the configuration can be

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

nShield/payShield Administrator Guide Windows v5.5

52

3 Getting the module working

Configuring the module

3. 4.

Run the cfg-reread command-line utility to load the new configuration. See cfg-reread on page 228 for details. Test that the hardserver is configured correctly by running the
enquiry command-line utility. (See enquiry on page 229 for full details of the enquiry command-line utility and its output.)

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

Setting up client cooperation


It is now possible to allow non-netHSM modules to automatically access the remote file system (RFS) used by netHSM and payShield NET modules and to share security world and key data stored in the kmdata directory. Client modules that access data in this way are described as cooperating clients. To configure client cooperation for modules that are not netHSM or payShield modules, complete the following steps: 1. Configure the remote file system used by your netHSM module to accept access by cooperating clients. For information about how to do this see the netHSM Administrator Guide. 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:

2.

nShield/payShield Administrator Guide Windows v5.5

53

3 Getting the module working

Configuring the module

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

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

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

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

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

nShield/payShield Administrator Guide Windows v5.5

54

3 Getting the module working

Configuring the module

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

remote_ip=ccc.ccc.ccc.cccremote_esn= keyhash=0000000000000000000000000000000000000000 native_path=c:\nfast\kmdata\local volume=kmdata-local allow_read=yes allow_write=yes allow_list=yes is_directory=yes is_text=no

and
remote_ip=ccc.ccc.ccc.cccremote_esn= keyhash=0000000000000000000000000000000000000000 native_path=c:\nfast\kmdata\localsync-store volume=kmdata-backup allow_read=yes allow_write=yes allow_list=yes is_directory=yes is_text=no

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

Useful utilities
To find out the ESN and the hash of the KNETI key for a given IP address, use the anonkneti command-line utility. A manual doublecheck is recommended for security. A client can use rfs-sync --show to display the current configuration, or rfs-sync --remove to revert to a stand-alone configuration. Reverting to a stand-alone configuration leaves the current contents of the kmdata directory in place. See rfs-sync on page 304 for more information.

nShield/payShield Administrator Guide Windows v5.5

55

3 Getting the module working

Creating and configuring a security world

Creating and configuring a security world


Before you can use the module to manage keys, you must create a security world. A security world can only be created with a single module. If you have more than one module, you must choose one with which to create the new security world. You can add additional modules to an existing security world later (as described in Adding or restoring a module to the security world on page 155). Before you start to create a security world: The modules that you wish to add to the security world must be in pre-initialization state, as described in Entering the pre-initialization state on page 78. You must be logged in to the host computer as a user who is permitted to create privileged connections. See hardserver on page 242. You must have set the NFAST_HOME environment variable. You should know what the security policy for the module is, and in particular the number and quorum of administrator and operator cards to be used. You must have enough smart cards to form the security worlds card sets.

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

nShield/payShield Administrator Guide Windows v5.5

56

3 Getting the module working

Creating and configuring a security world

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

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

Creating a security world by using new-world


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

Running the new-world command-line utility


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

In this command:

nShield/payShield Administrator Guide Windows v5.5

57

3 Getting the module working

Creating and configuring a security world

-i, --initialize

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

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

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

These options tell new-world to create a security world that conforms to the FIPS 140-2 requirements for roles and services at level 3. If you do not specify this flag, new-world creates a security world that complies with FIPS 140-2 requirements for level 2. Note This option provides compliance with the roles and services of the FIPS 140-2 level 3 standard. It is included for those customers who have a regulatory requirement for compliance.
-R, --no-recovery

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

nShield/payShield Administrator Guide Windows v5.5

58

3 Getting the module working

Creating and configuring a security world

By default, new-world creates key-recovery material that is protected by the cryptographic keys on the Administrator Card Set. This option does not give nCipher or any other third party access to your keys. Keys can only be recovered by using the Administrator Cards. nCipher recommends that you leave Operator Card Set recovery enabled. If you set the --no-recovery option, you will not be able to replace lost or damaged Operator Card Sets and therefore will not be able to access the keys that are protected by such cards. Key recovery cannot be enabled later without reinitializing your security world and discarding all your existing keys. Note All keys are recoverable unless otherwise specified at key generation, even PKCS #11 keys that have the sensitive flag set to TRUE or extractable flag set to FALSE.
-tTIMEOUT, --nso-timeout=TIMEOUT

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

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

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

nShield/payShield Administrator Guide Windows v5.5

59

3 Getting the module working

Creating and configuring a security world

to the total number of cards in the set. If a value for K is not specified, new-world creates an Administrator Card Set that requires a single card for authorization. Note Some applications do not have mechanisms for requesting that cards be inserted. Therefore any Operator Card Sets that you create for use with these applications must have K=1. 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

Note

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

new-world command-line utility features


Security world features can be specified on the command line.

nShield/payShield Administrator Guide Windows v5.5

60

3 Getting the module working

Creating and configuring a security world

You can specify multiple features as a comma-separated list of terms. Each term consists of a feature name, optionally preceded by either a dash (-) or an exclamation point (!) to turn off the feature and can optionally be followed by an equals sign (=) and the threshold for this feature. Note The ! character is interpreted by some shells as history expansion and must be escaped with a backslash, \\!. The dash may be interpreted as being the start of an command-line option unless you have used the f option or specified a module without including the -m flag. 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. If you want to use extended debugging from the module, you must set the dseeall flag. The following feature names are available:
m

Note

Note

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


r

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

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

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

nShield/payShield Administrator Guide Windows v5.5

61

3 Getting the module working

Creating and configuring a security world

rtc

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

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

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

This feature specifies that the Administrator Card Set is needed to enable foreign token operations. If the threshold of a feature is set to 0, it may still be available using the standard Administrator Card Set quorum. The pass phrase recovery (p) and dseeall features are turned off by default; the other options are turned on by default. Note The non-volatile memory and SEE world debugging options are relevant only if you are using the Secure Execution Engine. If you have bought the CodeSafe Developer Kit, refer to the CodeSafe Developer Guide for more information. 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.

Note

nShield/payShield Administrator Guide Windows v5.5

62

3 Getting the module working

Creating and configuring a security world

For example, the following features:


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

create a security world for which: a single card from the Administrator Card Set is required to add a new module the default number is required to replace an Operator Card Set pass phrase recovery is not enabled two cards are required to allocate nonvolatile memory one card is required to set the real-time clock (applies to SEE only).

new-world command-line utility output


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

ready for programming:


Initialization link not fitted Internal PCI modules

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

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

nShield/payShield Administrator Guide Windows v5.5

63

3 Getting the module working

Creating and configuring a payShield installation

Maintenance link fitted Internal PCI modules

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

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

Creating and configuring a payShield installation


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

nShield/payShield Administrator Guide Windows v5.5

64

3 Getting the module working

Creating and configuring a payShield installation

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

See About payShield Card Sets on page 187 for important advice about the choice of a value for K. the SEE debugging for all option enabled, if you wish to make use of the extended payShield module debugging option. (You must have configured the security worlds card requirements separately to enable this option.)

This option is designed for testing purposes only. Do not enable it on production security worlds as it may enable SEE applications to leak security information. You must know what the security policy and the associated card sets for the payShield installation are. If this is not already decided, see About payShield Card Sets on page 187. You must have enough smart cards to form the security worlds card sets. You must know which payShield functions are required.

Creating the payShield installation from the command line


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

nShield/payShield Administrator Guide Windows v5.5

65

3 Getting the module working

Creating and configuring a payShield installation

See payshield-install on page 283 for full details of the payshield-install utility. To run the payshield-install utility, type the following command, specifying the options required for your installation:
payshield-install [options] psiname keyhash

In this command:
psiname

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


psiname must be in all lowercase characters because it is used for a

key generation operation.


keyhash

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

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

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

nShield/payShield Administrator Guide Windows v5.5

66

3 Getting the module working

Creating and configuring a payShield installation

The payshield-install utility performs or prompts for the following operations in the order specified: If you have set the --totally-insecure option, the payshield-install utility issues the following warning:

WARNING: Creating an insecure payShield installation.

You must not set the --totally-insecure option, the -I (--allow-insecureimports) option, or the -D (--allow-insecure-debug) option when creating a live commercial payShield installation. If this warning is displayed, the payShield installation you create is suitable only for testing environments. No sensitive keys or data should ever be allowed to pass through a payShield installation created with the -I (--allow-insecure-imports) option set. The payshield-install utility prompts for a KFTO quorum of security world Administrator cards. This quorum is the K value that you specified for FTO when you created the security world. The payshield-install utility prompts for a KFTO quorum of security world Administrator Cards. This quorum is the K value that you specified for FTO when you created the security world. The payshield-install install utility loads the security worlds KFTO and displays the following message:
payShield Master Cardset creation ...

It then prompts for new operator cards.

nShield/payShield Administrator Guide Windows v5.5

67

3 Getting the module working

Creating and configuring a payShield installation

Following the onscreen prompts, each Master Card Set card holder inserts a blank card and enters a name and pass phrase for this card. The payshield-install utility displays the following message:

payShield Key Establishment Cardset creation ...

It then prompts for new operator cards. Following the onscreen prompts, each Key Establishment Card Set card holder inserts a blank card and enters a name and pass phrase for this card. The payshield-install utility displays a success message and exits. A successful operation might have output similar to the following:
payshield-install.exe: no card in module 1 slot 0 Insert an administrator card into module 1 slot 0 and press return... Passphrase for administrator card 1: payShield Master key generation ... payShield Master key generated Making FTO delegation certificate ... payShield Master Cardset creation ... Insert new operator card 1 into module 1 slot 0 and press return... Passphrase for new operator card 1: Name for card 1: master payShield Master Cardset created payShield Key Establishment key generation ... payShield Key Establishment key generated payShield Key Establishment Cardset creation ... Insert new operator card 1 into module 1 slot 0 and press return... Passphrase for new operator card 1: Name for card 1: kec payShield Key Establishment Cardset created Successfully created new payShield Installaton psi

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

nShield/payShield Administrator Guide Windows v5.5

68

3 Getting the module working

Creating and configuring a payShield installation

Configuring the payShield installation options


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

Enabling payments functions


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

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

Configuring modules to use payShield


For each module you must create an entry in the load_seemachine section of the hardserver configuration file. Make each entry of the following form:
... module module machine_file=c:\nfast\nc-seemachines\payshield\version\emvsmtype1.sar postload_prog=payshield postload args=-n psiname [-d] ...

nShield/payShield Administrator Guide Windows v5.5

69

3 Getting the module working

Creating and configuring a payShield installation

Separate the flags for each module by a dash on its own line, as in the following example:
postload args=-n psiname [-d] module MODULE

In this example:
MODULE

This represents the module number (for example, 1)


version

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

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

This flag specifies that the operating SEE World has the
dseeall feature set and that the operating payShield installation has the -D option set. Both of these conditions

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

nShield/payShield Administrator Guide Windows v5.5

70

3 Getting the module working

Creating the Operator Card Set

Creating the Operator Card Set


The Operator Card Set provides access to application keys. Operator Card Sets are optional, but if you require one, create it before you start to use the module with applications. You can create Operator Card Sets with: names for individual cards, as well as for the card set
K-of-N policies

optional pass phrases for any card within a given set formal FIPS 140-2 level 3 compliance.

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

Pass phrase
Not permitted Required

Netscape Certificate Required Server

You can create an Operator Card Set from the command line with the
createocs utility (as described here). Alternatively, you can use

KeySafe, or the nCipher CSP wizard. For more information about creating Operator Card Sets, see the Operator Guide appropriate to your module type.

Creating the Operator Card Set from the command line


To create an Operator Card Set:

nShield/payShield Administrator Guide Windows v5.5

71

3 Getting the module working

Creating the Operator Card Set

1.

Use the command:

C:\nfast\bin\createocs -m MODULE|--module=MODULE -Q|--ocs-quorum=K/N -N|--name=NAME [-M|--name-cards] [[-p|--persist]|[-P|--no-persist]] [[-R|--no-pprecovery]|--pprecovery] [-q|--remotely-readable] [-f|--force] [-T|--timeout=TIME]

In this command:
-m MODULE, --module=MODULE

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

In these options, K is the minimum required number of cards. If you do not specify the value K, the default is 1. Note Some applications do not have mechanisms for requesting that cards be inserted. Therefore any Operator Card Sets that you create for use with these applications must have K=1.
N is the total number of cards. If you do not specify the value N, the default is 1. -N, --name=NAME

These options enable you to name the card set. The card set must be named with this option before individual cards can be named using the -M, --name-cards=NAME options.
-M, --name-cards

These options enable you to name individual cards within the card set. You can only use this option after the card set has been named by using the --name=NAME

nShield/payShield Administrator Guide Windows v5.5

72

3 Getting the module working

Creating the Operator Card Set

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

These options create a persistent card set.


-P, --no-persist

These options create a non-persistent card set.


-R, --no-pprecovery

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

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

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

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

nShield/payShield Administrator Guide Windows v5.5

73

3 Getting the module working

Creating the Operator Card Set

Card never times out. Otherwise, the module automatically unloads the Operator Card Set TIME after the Operator Card was loaded. If you have created a FIPS 140-2 level 3 compliant security world, you must provide authorization to create new Operator Cards; createocs prompts you to insert a card that contains this authorization. Insert any card from the Administrator Card Set or any Operator Card from the current security world. When createocs has obtained the authorization from a valid card or if no authorization is required, it prompts you to insert a card into the module you specified. 2. Insert the smart card to use. If you insert an Administrator Card from another security world or an Operator Card that you have just created, createocs displays the following message:
Module x slot n: unknown card Module x slot n: Overwrite card ?

(press Return)

where x is the module number and n is the slot number. If you insert an Operator Card from another security world, createocs displays the following message:
Module x slot n: inappropriate Operator Card (TokenAuthFailed).

When you have inserted a valid card, createocs prompts you to type a pass phrase. Note Note The nCipher PKCS #11 library requires Operator Cards with pass phrases. Some applications do not have mechanisms for entering pass phrases. Do not give pass phrases to Operator Cards that are to be used with these applications.

nShield/payShield Administrator Guide Windows v5.5

74

3 Getting the module working

Creating the Operator Card Set

3.

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

4.

Type the pass phrase again and press Enter . If the pass phrases do not match, createocs prompts you to input and confirm the pass phrase again.

5.

When the new card has been created, if you are creating a card set with more than one card in it, createocs prompts you to insert another card. For each additional card in the Operator Card Set, follow the instructions from step 2 through step 4.

nShield/payShield Administrator Guide Windows v5.5

75

Chapter 4: Changing the module state


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

Entering the pre-maintenance state


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

Internal PCI modules


1. Switch the mode switch to the maintenance position, as shown in Figure 3. PCI module back panel

Figure 3
Status LED Clear switch Mode switch

M O I

Maintenance

Smart card connector

DC power

2.

Reset the module by pressing the clear button.

nShield/payShield Administrator Guide Windows v5.5

76

4 Changing the module state

Entering the pre-maintenance state

When the self tests are complete, the unit should enter the premaintenance state. In this state, the Status LED emits repeated single long flashes. Refer to the table below if the Status LED does not emit repeated single long flashes:
LED State Reason and remedy
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.

Operational Mainly on but regularly blinks off (The exact timing depends on the nCipher module.The longer the LED stays on the less the load. At 100% load the LED is off for as long as it is on.) 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. The module has encountered an unrecoverable error. There is a list of these errors and the actions to take in the Hardware Installation Guide.

Flashes the Morse SOS pattern followed by a code

Error

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.

nShield/payShield Administrator Guide Windows v5.5

77

4 Changing the module state

Entering the pre-initialization state

Entering the pre-initialization state


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

Internal PCI modules


1. Switch the mode switch to the initialization position, as shown in Figure 4. PCI module back panel

Figure 4
Status LED Clear switch Mode switch

M O I

Initialization

Smart card connector

DC power

2.

Reset the module by pressing the clear button.

nShield/payShield Administrator Guide Windows v5.5

78

4 Changing the module state

Entering the operational state

The module performs self tests, during which the Status LED is on. When the self tests are complete, the unit should enter the preinitialization state. In this state, the Status LED emits repeated single short flashes. Refer to the table below if the Status LED does not emit repeated single short flashes:
LED State Reason and remedy
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.

Operational Mainly on but regularly blinks off (The exact timing depends on the nCipher module.The longer the LED stays on the less the load. At 100% load the LED is off for as long as it is on.) 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. The module has encountered an unrecoverable error. There is a list of these errors and the actions to take in the Hardware Installation Guide.

Flashes the Morse SOS pattern followed by a code

Error

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.

nShield/payShield Administrator Guide Windows v5.5

79

4 Changing the module state

Entering the operational state

Internal PCI modules nC3022P-xxx


1. Switch the mode switch to the operational position, as shown in Figure 5. nCipher PCI module back panel and switches

Figure 5
Status LED Clear switch Mode switch

M O I

Operational

Smart card connector

DC power

2.

Reset the module by pressing the clear button.

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

nShield/payShield Administrator Guide Windows v5.5

80

4 Changing the module state

Entering the operational state

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

State
Pre-initialization

Reason and remedy


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. The mode switch is in the maintenance position. Repeat the process described in this section to set the mode switch in the operational position. The module has encountered an unrecoverable error. There is a list of these errors and the actions to take in the Hardware Installation Guide.

Emits repeated single long flashes

Pre-maintenance

Flashes the Morse SOS pattern followed by a code

Error

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.

nShield/payShield Administrator Guide Windows v5.5

81

Chapter 5: Uninstalling
This chapter provides information on uninstalling nCipher software.

Uninstalling the nCipher support software


Note Do not uninstall the nCipher software unless either you are certain it is no longer required or you are going to upgrade it. 1. 2. 3. Note Log on to the host computer as Administrator or as a user with local administrator rights. Select Add/Remove Programs from the Windows Control Panel. Select the nCipher support software entry, and click the Add/Remove button to uninstall the support software.

The uninstall process restores the Microsoft CSP as the default SChannel CSP. If required, you can safely remove the nCipher module after shutting down all connected hardware.

nShield/payShield Administrator Guide Windows v5.5

82

Chapter 6: Configuring the hardserver


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

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

Remote module connections


A remote module is a module that is not connected directly to the host computer but with which the hardserver can communicate. It can be one of the following: a network-connected nCipher module that is configured to use the host computer as a client computer. For information about configuring network-connected modules, see the netHSM/payShield net Administrator Guide.

nShield/payShield Administrator Guide Windows v5.5

83

6 Configuring the hardserver

Hardserver settings

a module to which an attended remote slot is imported for the hardservers unattended local module.

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

Hardserver settings
You configure the hardservers settings in the server_settings section of the configuration file. This section defines how connections and hardserver logging are handled. These settings can be changed while the hardserver is running.

Hardserver start-up settings


You configure the hardservers start-up settings in the server_startup section of the configuration file. This section defines the sockets and ports used by the hardserver. You should need to change this section only if the default ports for privileged or unprivileged connections (9000 and 9001) are not available.

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

nShield/payShield Administrator Guide Windows v5.5

84

6 Configuring the hardserver

SEE machines

These sections define the slots that are imported to or exported from the module. See Chapter 13: Remote Operator Card Sets for full information about remote slots.

SEE machines
You configure the hardserver to load SEE machines on start-up in the load_seemachine section of the configuration file. The SEE Activation feature must be enabled on the module, as described in Chapter 8: Feature Enabling nCipher Modules. This section defines the SEE machines and optional user data to be loaded, as well any other applications to be run in order to initalize the machine after it is loaded. See Chapter 9: Using CodeSafe Applications for information about SEE machines.

Hardserver configuration file


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

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

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

nShield/payShield Administrator Guide Windows v5.5

85

6 Configuring the hardserver

Hardserver configuration file

notice client remoteserver error serious internal startup fatal fatalinternal

The default is info. See Logging and debugging on page 343. If NFAST_SERVERLOGLEVEL is set, it overrides the value in the configuration file.
logdetail

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

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

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

nShield/payShield Administrator Guide Windows v5.5

86

6 Configuring the hardserver

Hardserver configuration file

external_pid

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

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

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

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

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

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

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

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

nShield/payShield Administrator Guide Windows v5.5

87

6 Configuring the hardserver

Hardserver configuration file

msg_writeable

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

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

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

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

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

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

nShield/payShield Administrator Guide Windows v5.5

88

6 Configuring the hardserver

Hardserver configuration file

connect_keepalive

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

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

The maximum PCI interface version number. If this is set to 0 (the default) there is no limit. These flags are those used by the NFLOG_DETAIL environment variable (see Environment variables to control logging on page 343).

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

The electronic serial number of the module.


priority

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

nShield/payShield Administrator Guide Windows v5.5

89

6 Configuring the hardserver

Hardserver configuration file

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

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

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

This field is not used on Windows systems.


unix_privsocket_name

This field is not used on Windows systems.


nt_pipe_name

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

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

nShield/payShield Administrator Guide Windows v5.5

90

6 Configuring the hardserver

Hardserver configuration file

nt_privpipe_name

The name of the pipe to use for privileged connections on Windows. An empty string specifies none. The default is \\.\pipe\privcrypto. If the NFAST_PRIVSERVER environment variable is set, it overrides the value in the configuration file.
nt_privpipe_users

A list of users allowed to issue privileged connections on Windows. If empty, any user can issue non-privileged connections. This is the default. If the NFAST_SERVER environment variable is set, it overrides the value in the configuration file.
nonpriv_port

The port on which the hardserver listens for local nonprivileged TCP connections. 0 specifies none. Java clients default to connecting to 9000. The default is 0. If the NFAST_SERVER_PORT environment variable is set, it overrides the value in the configuration file.
priv_port

The port on which the hardserver listens for local privileged TCP connections. 0 specifies none. Java clients default to connecting to 9001. The default is 0. If the NFAST_SERVER_PRIVPORT environment variable is set, it overrides the value in the configuration file.

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

nShield/payShield Administrator Guide Windows v5.5

91

6 Configuring the hardserver

Hardserver configuration file

module

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

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

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

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

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

nShield/payShield Administrator Guide Windows v5.5

92

6 Configuring the hardserver

Hardserver configuration file

postload_args

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

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

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


local_slotid

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

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


remote_port

The port number on which the remote hardserver is listening.


remote_esn

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

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

nShield/payShield Administrator Guide Windows v5.5

93

6 Configuring the hardserver

Hardserver configuration file

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

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

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

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

The ESN of the module allowed to import the slot.

remote_file_system
This section is updated automatically when the rfs-setup utility is run. You should not edit it manually. The remote_file_system section defines a remote file system on the client, by listing the modules allowed to access the filesystem on this client. Each module is defined by an entry as follows:

nShield/payShield Administrator Guide Windows v5.5

94

6 Configuring the hardserver

Hardserver configuration file

remote_ip

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

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

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

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

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

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

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

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

nShield/payShield Administrator Guide Windows v5.5

95

6 Configuring the hardserver

Payments configuration file

is_directory

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

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

Payments configuration file


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

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

This section determines the types of keys that can be imported or exported. Here you can specify which key block formats are acceptable for each import or export operation. Listing no formats for an operation means that the operation is disabled. For example the following entry would mean that TPKs: Can be generated in attended operations (using the VeriFone solution) Cannot be generated automatically Can (in principle) be exported as components or wrapped in attended operations

nShield/payShield Administrator Guide Windows v5.5

96

6 Configuring the hardserver

Payments configuration file

Cannot be imported from components or wrapped in attended operations Can be imported automatically from a wrapped key.

role=KeyRole_TPK gen_a=allow gen_u= ex_a=ExportFormat_XORComponents,ExportFormat_ECBWrapped ex_u= im_a=ExportFormat_XORComponents,ExportFormat_ECBWrapped im_u=ExportFormat_ECBWrapped

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

nShield/payShield Administrator Guide Windows v5.5

97

Chapter 7: Using multiple modules


The hardserver can communicate with multiple nShield payShield modules connected to the host. By default, the server accepts requests from applications and submits each request to the first available module. The server can share load across buses, which includes the ability to share load across a mixture of modules. If your application is multi-threaded, you can add additional modules and expect performance to increase proportionally until you reach the point where cryptography no longer forms a bottleneck in the system.

Identifying modules
Modules are identified in two ways: by serial number by ModuleID.

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

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

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

nShield/payShield Administrator Guide Windows v5.5

98

7 Using multiple modules

Multiple modules and Remote Operator

The order in which buses are searched and order of modules on a bus depends on the exact configuration of the host. If you add or remove a module, this can change the allocation of ModuleIDs to all the modules on your system. You can use the enquiry command-line utility to identify the PCI bus and slot number associated with a module. See enquiry on page 229 for further information. All commands sent to nShield payShield modules require a
ModuleID. Many nCipher commands, including all acceleration-only commands, can be called with a ModuleID of 0. Such a call causes the

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

Multiple modules and Remote Operator


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

nShield/payShield Administrator Guide Windows v5.5

99

7 Using multiple modules

Adding a module

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

Adding a module
If you have a module installed, you can add further modules without reinstalling the server software. However, nCipher recommends that you always upgrade to the latest server software and upgrade the firmware in existing modules to the latest firmware. Note Before you install new hardware, check the release notes on the CDROM supplied with your new module for information about specific compatibility issues, new features, and bug fixes. 1. 2. 3. Install the module hardware. Refer to the Hardware Installation Guide for information on installing nCipher hardware. Reboot your computer. Add the module to the security world. Refer to Adding or restoring a module to the security world on page 155.

Module fail over


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

nShield/payShield Administrator Guide Windows v5.5

100

Chapter 8: Feature Enabling nCipher Modules


nCipher modules support a range of optional features. Optional features must be enabled with a certificate that you order from nCipher. You can order the features when you purchase a module, or you can obtain the certificate at a later date and use the Feature Enable Tool to enable the features. See Ordering features for your module on page 104 for details of ordering optional features. See Enabling features on page 105 for details of enabling features. The module firmware checks to confirm whether any features that it attempts to use are enabled. It normally does this when it authorizes the commands, or command options, that relate to a specific feature. Most features are static; that is, they are enabled by means of a switch in the modules EEPROM. A static feature remains enabled when the module is reinitialized. Some optional features are dynamic, that is, they are enabled by means of a software switch in the modules volatile memory. A dynamic feature must be enabled again if the module is reinitialized. Once you have enabled features on a module, you must clear the module to make them available.

Available Features
This section lists the features that can be added to modules. Contact sales@ncipher.com for full details of all available features.

Elliptic Curve
Elliptic curves allow small key sizes to provide improved levels of security and are commonly used in embedded devices. See Developers Reference for full details of the elliptic curve feature.

nShield/payShield Administrator Guide Windows v5.5

101

8 Feature Enabling nCipher Modules

Available Features

Secure Execution Engine (SEE)


The SEE is a unique secure execution environment. The SEE features available to you are:
SEE Activation (EU+10) Provided with the CodeSafe developer product to enable you to develop and run SEE applications. The CodeSafe developer product is only available to customers in the Community General Export Area (CGEA, also known as EU+10). Contact nCipher to find out whether your country is currently within the CGEA. Provided with specific products that include an SEE application. This feature enables you to run your specific SEE application, and is available to customers in any part of the world.

SEE Activation (Restricted)

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

Remote Operator support


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

nShield/payShield Administrator Guide Windows v5.5

102

8 Feature Enabling nCipher Modules

payShield features

ISO smart card Support (ISS)


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

Korean Certificate-based Digital Signature Algorithm (KCDSA)


This algorithm is used extensively in Korea as part of compliance with local regulations specified by the Korean government. See Developers Reference for full details of the KCDSA algorithm.

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

payShield features
If you have purchased payShield, the module is always supplied with the following feature enabling tokens: SEE Activation (Restricted), to allow software to run inside your module payShield Activation, to allow payShield software to run inside your module. payShield Rnumber, to set the performance variant of the payShield module to the number number ISO smart card support (ISS), also called Foreign Token Open (FTO), to allow the use of non-nCipher smart cards.

nShield/payShield Administrator Guide Windows v5.5

103

8 Feature Enabling nCipher Modules

Ordering features for your module

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

Ordering features for your module


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

You must provide the ESN number to order a new feature. If you prefer, you can include this information in an E-mail to
sales@ncipher.com. You can use the Feature Enable Tool to save the

ESN details to a file. See The Feature Enable Tool on page 105. When your order has been processed, you receive a Feature Enabling Certificate in one of the following ways: nCipher E-mails you the Feature Enabling Certificate. nCipher sends you a smart card that contains the Feature Enabling Certificate.

The Feature Enabling Certificate contains the information that you need to enable the features you have ordered. For more information, including pricing of features, telephone or Email your nearest nCipher sales representative using the contact details from this guide, or the nCipher web site (http://www.ncipher.com).

nShield/payShield Administrator Guide Windows v5.5

104

8 Feature Enabling nCipher Modules

Enabling features

Enabling features
The Feature Enable Tool
The Feature Enable Tool utility, by default, scans the smart card readers of all modules attached to the host, and enables any features found on inserted FEM cards. To use the Feature Enable Tool, you must be logged in as a user who is permitted to create privileged connections. You can enable a feature without having physical access to a module by exporting the slot on your local module, importing that slot into the remote module, and then running the Feature Enable utility on the remote host. The Feature Enable Tool offers you the choice of clearing the module after it has enabled features. If you do not choose to clear the module then (for example, because you have another process running on the module), you must clear it later. You can use any appropriate method to do this (for example, the nopclearfail utility or the Clear button).

Usage
fet.exe

Help options
-h, --help

display help for fet.exe


-v, --version

display the version number of fet.exe

nShield/payShield Administrator Guide Windows v5.5

105

8 Feature Enabling nCipher Modules

Enabling features

-u, --usage

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

Viewing features already enabled on a module


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

Enabling features with a smart card


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

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

Enabling new features on your module without a smart card


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

nShield/payShield Administrator Guide Windows v5.5

106

8 Feature Enabling nCipher Modules

Enabling features

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

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

nShield/payShield Administrator Guide Windows v5.5

107

Chapter 9: Using CodeSafe Applications


If you have enabled the Secure Execution Engine (SEE), your system can run CodeSafe applications that implement special functionality. Note If you wish to use the SEE to run applications, you must order and enable it as described in Chapter 8: Feature Enabling nCipher Modules. An SEE application is typically a standalone SEE machine that is loaded automatically by the hardserver, for example, a CodeSafe C application. Please check the documentation supplied by your application vendor for information about signatures that may be required to set up and use the application, and any other installation and configuration information.

CodeSafe/C applications
CodeSafe/C applications are standalone applications. Each CodeSafe C application can consist of multiple parts, and its installation can include several configuration steps. Please see your application vendors documentation for instructions on installing and configuring each application. You may need to use the hardserver, loadmache and tct2 utilities when configuring and loading an applicationl; see hardserver on page 242, and .

nShield/payShield Administrator Guide Windows v5.5

108

Chapter 10: Using KeySafe


This chapter introduces KeySafe, nCiphers security world management tool. It describes: how to start KeySafe KeySafes graphical interface how to use buttons to select and run operations how to use the keyboard to navigate KeySafe how KeySafe reports errors.

Later chapters in this guide contain instructions for performing the following operations with KeySafe: creating a security world adding a module to a security world removing a module from a security world replacing an Administrator Card Set creating Operator Card Sets replacing Operator Card Sets

Starting KeySafe
In order to use KeySafe, Suns Java run-time environment version 1.5, or the equivalent developer kit must be installed. It is recommended that you install it before you install the nCipher components. The Java executable must be on your path. Note You can download Sun's Java Run-time Environment (and Java Developer Kit) from http://www.sun.com/. If your security policy does not allow the use of downloaded software, these components can be obtained on CD-ROM from Sun or your Operating System vendor. The keysafe.jar file must be specified in the Java class path.

nShield/payShield Administrator Guide Windows v5.5

109

10 Using KeySafe

Starting KeySafe

In order for KeySafe to work, you must set priv_port (the port on which the hardserver listens for local privileged TCP connections) to 9001 and nonpriv_port (the port on which the hardserver listens for local nonprivileged TCP connections) to 9000. Note See Setting the environment variables on page 49 and server_settings on page 85 for information on setting these parameters. Start KeySafe by selecting the KeySafe entry from the Programs folder on the Windows Start menu. The Windows KeySafe launcher checks that the components required to run KeySafe are installed. Any missing components are listed in a dialog box similar to the following:

nShield/payShield Administrator Guide Windows v5.5

110

10 Using KeySafe

The KeySafe window

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

Note

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

The KeySafe window


The KeySafe window is divided into two areas: the sidebar (on the left), subdivided into: the menu buttons (at the top of the sidebar) the Module Status tree (at the bottom of the sidebar)

the main panel area (on the right).

This layout is consistent throughout the KeySafe application.

nShield/payShield Administrator Guide Windows v5.5

111

10 Using KeySafe

The KeySafe window

Sidebar
The sidebar provides access to different parts of the KeySafe application (with the menu buttons) and also displays information about both the current security world and your module or modules (with the Module Status tree).

Menu buttons
There are six menu buttons at the top of the sidebar:
Introduction

Clicking the Introduction menu button takes you to the introductory panel that KeySafe displays at startup.
Keys

Clicking the Keys menu button takes you to the Key Operations panel, from which you can choose to create, import, view, or destroy keys.
Cards

Clicking the Cards menu button takes you to the Card Operations panel, from which you can: create, view, or erase Operator Cards change the pass phrase on an Operator or Administrator Card, or recover the pass phrase from an Operator Card replace an Operator or Administrator Card Set.

Softcards

Clicking the Softcards menu button takes you to the Softcard Operations panel, from which you can: create, view or erase softcards change or recover the pass phrase on a softcard

nShield/payShield Administrator Guide Windows v5.5

112

10 Using KeySafe

The KeySafe window

Modules

Clicking the Modules menu button takes you to the Module Operations panel, from which you can initialize a security world, add modules to a security world, or remove modules from a security world. You cannot perform these operations on a module that is not in the pre-initialization state.
Exit

Clicking the Exit button displays a dialog asking whether you are sure you want to exit KeySafe. Click Yes (or press Enter ) to exit KeySafe; click No to continue using KeySafe. Clicking the Exit dialogs close-window button will take you back to your KeySafe session. These features prevent you from closing KeySafe accidentally. While KeySafe is executing a command, the menu buttons are disabled. Their normal functionality returns when the command is completed.

Module Status tree


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

nShield/payShield Administrator Guide Windows v5.5

113

10 Using KeySafe

The KeySafe window

setting. Click the toggle to display expanded information about the security world or module. Click the toggle again to collapse this information. Note For purposes of clarity, screen shots in this guide are shown with some of the Module Status tree toggles expanded. Security world information When you toggle the Module Status tree view of security world information to its expanded setting, KeySafe reports Yes or No for each of the following conditions: the security world is initialized key recovery is enabled for this security world (for more information on key recovery, see Replacing Operator Card Sets on page 202) pass phrase recovery is enabled for a security world (for more information on pass phrase recovery, see Replacing Operator Card Sets on page 202)

It also gives the following information: which type of key protects the security world (DES or AES/Rijndael) which FIPS 140-2 level the security world is operating at (level 2 or level 3)

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

nShield/payShield Administrator Guide Windows v5.5

114

10 Using KeySafe

The KeySafe window

whether or not you have generated a Secure Execution Engine (SEE) debugging key for this security world the level of SEE debugging that is enabled for this security world. whether or not you enabled the Foreign Token Open key for this security world

Module information When you toggle the Module Status tree view of module information to its expanded setting for a given module, KeySafe displays: the modules electronic serial number (ESN), which is a unique identifier. You must quote a modules ESN if you need to contact Support at nCipher. Keep a record of the ESN(s) associated with your module(s). the modules state, which will be one of the following: PreInitMode, indicating that the module is in the preinitialization state InitMode, indicating that the module is in the initialization

state
Operational:Useable, indicating that the module is in the current security world and can be used for key operations Operational:Unknown, indicating that the modules state could not be determined Operational:Uninitialized, indicating that the module key is

set and that the module must be initialized before use


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

the factory default


Operational:Foreign, indicating that the module is from an unknown security world Operational:AccelOnly, indicating that the module is an acceleration-only module

nShield/payShield Administrator Guide Windows v5.5

115

10 Using KeySafe

The KeySafe window

Operational:Unchecked, indicating that, although the module appears to be in the current security world, KeySafe could not find a module initialization certificate (a module_ESN file) for this module Failed, indicating that the module has failed PreMaintMode, indicating that the module is in the premaintenance state MaintMode, indicating that the module is in the maintenance

state. the status of the smart card reader slot(s). You cannot initialize a security world from KeySafe unless you have at least one module in the pre-initialization state (PreInitMode). Likewise, if you want to add a module to an existing security world, that module must be in the preinitialization state. Note For information about putting a module into the pre-initialization state, see Entering the pre-initialization state on page 78. After you have initialized a security world, in order for a module to be usable, you must put it into the operational state (as described in Entering the operational state on page 79). for strict FIPS 140-2 level 3 security worlds, a FIPS Auth Loaded entry will show if an Administrator Card or Operator Card has been inserted to authorise a FIPS key required operation. The Module status tree has an Advanced folder that shows the following details when expanded: the version of the modules firmware whether the module has a Real Time Clock (RTC) whether the module has nonvolatile memory (NVRAM).

nShield/payShield Administrator Guide Windows v5.5

116

10 Using KeySafe

The KeySafe window

Main panel area


KeySafes main panel area is used to display information and options pertaining to a chosen operation. For example, clicking the Modules menu button takes you to the Module Operations panel in the main panel area:

Navigation buttons
At the bottom left of the Module Operations panel are three navigation buttons. Clicking a navigation button does not commit you to an action, but instead selects an operation and loads another panel of additional information and options related to the selected operation.

nShield/payShield Administrator Guide Windows v5.5

117

10 Using KeySafe

The KeySafe window

From the Module Operations panel, for example, clicking the Erase Module navigation button does not itself erase a module, but rather loads the Erase Module panel:

Command buttons
At the bottom right of the Erase Module panel is a command button (the Erase Module! command button, in this case). Unlike clicking a navigation button, clicking a command button does commit you to an operation. Clicking a command button tells KeySafe to write or delete data: it is not necessarily possible to reverse such changes even if you subsequently cancel the operation. For these reasons, command buttons are usually marked with an exclamation point (!) if there is a danger that a command could overwrite data that you may not want deleted. In some cases, clicking a command button causes KeySafe to display a dialog box asking you to confirm your command. Such features help prevent you from accidentally destroying your data or keys.

nShield/payShield Administrator Guide Windows v5.5

118

10 Using KeySafe

The KeySafe window

Some panels require that, before you can click a command button, you select options by means of radio buttons or that you enter data into text fields:

If you click a command button without having entered data into a mandatory text field or if KeySafe detects that the information you provided is inconsistent or invalid, KeySafe displays an error message. Click the messages OK button, and then provide or correct the necessary information. After you successfully issue a command by clicking a command button, the sidebars menu buttons are disabled until the requested command is completed.

Back buttons
Some KeySafe panels have Back buttons. Clicking a Back button takes you to the panel from which the panel you are on is normally reached. For example, clicking the Back button on the Erase Module panel takes

nShield/payShield Administrator Guide Windows v5.5

119

10 Using KeySafe

Errors

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

Navigating with the keyboard


The Tab key always takes you to the next field or button. If the cursor is not currently active in a text field, pressing the space bar or the Enter key activates the currently selected button (as if you had clicked it). Pressing the Shift - Tab button combination takes you to the previous field (if any) or deselects an automatically selected button (if any).

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

In this case, it could be that the nCipher server is unable to receive TCP connections for some reason. The server program communicates with clients by using named pipes or TCP sockets. Note See Setting the environment variables on page 49 and Hardserver start-up settings on page 84 for information on setting these parameters. The error message shown could also indicate that the nCipher server is not running (or that your module is physically disconnected). If the nCipher server is not running, take the following steps: 1. 2. 3. Exit KeySafe. Restart the server as described in the section hardserver on page 242. Restart KeySafe.

nShield/payShield Administrator Guide Windows v5.5

120

10 Using KeySafe

Errors

Another Fatal Error from which KeySafe cannot recover is:

This error may mean that your nCipher server or nCipher firmware is not current. To update your firmware, take the following steps: 1. 2. 3. Note Exit KeySafe. Update the nCipher firmware as described in Appendix A: Upgrading module firmware. Restart KeySafe.

The firmware upgrade process destroys all persistent data held in a key-management module. If your security system requires that the persistent data held in a key-management module must survive intact during the upgrade or initialization of the key-management module, a backup and recovery mechanism of your kmdata directory must be implemented. Other, more trivial errors include:

This error occurs if you are attempting to initialize, reprogram, or erase a module that is not in the pre-initialization state.

This error occurs if you attempt to create a card set with more than 64 cards.

nShield/payShield Administrator Guide Windows v5.5

121

10 Using KeySafe

Errors

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

nShield/payShield Administrator Guide Windows v5.5

122

Chapter 11: Managing security worlds


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

Security world files


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

Location of security world files


Security world files are created or updated in the directory specified by the environment variable NFAST_KMLOCAL on the host. By default, this is C:\nfast\kmdata\local. Note By default, the kmdata directory, and sub-directories, inherit permissions from the user that creates them. Installation of nCipher support software must be performed by a user with Administrator rights that allow read and write operations, and the starting and stopping of applications.

nShield/payShield Administrator Guide Windows v5.5

123

11 Managing security worlds

Security world files

Files and operations


Security world operations create or modify files in the C:\nfast\kmdata\local directory as follows:
Operation
Create a security world Load a security world Replace an Administrator Card Set Create an Operator Card Set Generate a key Create an Operator Card Set Recover a key

Creates/modifies
creates creates or modifies modifies

Creates files...
world module_ESN module_ESN

world

creates creates modifies modifies

cards_ident card_ident_cardno

(one per card)


key_appname_ident key_appname (for each key

that has been recovered)


key_appname (for each key

that has been recovered)

In this table:
ESN is the electronic security number of the module on which the

security world is created


ident is the identifier given to the card set or key when it is created cardno is the number of the card in the card set appname is the name of the application by which the key was

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

nShield/payShield Administrator Guide Windows v5.5

124

11 Managing security worlds

Security world options

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

a module_ESN file for each module that this host uses a cards_ident file for each cardset that is to be loaded from this host a card_ident_cardno file for each card in each cardset that is to be loaded from this host a key_appname_ident file for each key that is to be loaded from this host.

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

Security world options


Decide what kind of security world you need before you create it. Depending on the kind of security world you need, you can choose different options at the time of creation. For convenience, security world options can be divided into the following groups: basic options, which must be configured for all security worlds recovery options, which must be configured if the security world, keys, or pass phrases are to be recoverable SEE options, which only need be configured if you are using nCiphers Secure Execution Engine (SEE) options relating to the replacement of an existing security world with a new security world.

nShield/payShield Administrator Guide Windows v5.5

125

11 Managing security worlds

Security world options

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

Security world basic options


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

Security world key type


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

K and N
You must decide the total number of cards (N) in a security worlds ACS and must have that many blank cards available before you start to create the security world. You must also decide how many cards from the ACS must be present (K) when performing administrative functions on the security world. Note nCipher recommends that you do not create Administrator Card Sets for which K is equal to N, because you cannot replace such an Administrator Card Set if even 1 card is lost or damaged. 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.

Note

nShield/payShield Administrator Guide Windows v5.5

126

11 Managing security worlds

Security world options

FIPS 140-2 level 3 compliance


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

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

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

Security world recovery options


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

nShield/payShield Administrator Guide Windows v5.5

127

11 Managing security worlds

Security world options

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

Security world SEE options


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

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

Real-time clock (RTC) options


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

nShield/payShield Administrator Guide Windows v5.5

128

11 Managing security worlds

Creating a security world

Nonvolatile memory (NVRAM) options


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

Security world replacement options


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

Creating a security world


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

nShield/payShield Administrator Guide Windows v5.5

129

11 Managing security worlds

Creating a security world

You should know what the security policy for the module is, and in particular the number and quorum of administrator and operator cards to be used. See Determining module requirements on page 39 for details. You must have enough smart cards to form the security worlds card sets.

When you have completed the operation and run the payshield-install utility if required, you must restart the module in the operational state. The process of creating a security world: erases the module creates a new module key for this security world creates a new Administrator Card Set to protect this module key stores the security world information on the computers hard disk. The information is encrypted using the secrets stored on the Administrator Card Set.

Any Operator Cards created in a previous security world cannot be used in the new security world. If you are replacing a security world, you must erase all the Operator Cards created in the previous security world before you create the new world. See the Operator Guide. You can create a security world from the command line with the
new-world utility, as described in the section Creating a security world

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

nShield/payShield Administrator Guide Windows v5.5

130

11 Managing security worlds

Creating a security world

Creating a security world with KeySafe


1. Start KeySafe. (For an introduction to KeySafe and information on starting the software, see the appropriate Operator Guide for your module.) Check the Module Status tree to ensure that you have a module in the pre-initialization state (PreInitMode). See Entering the premaintenance state on page 76. Click the Modules menu button, which takes you to the Module Operations panel. Click the Initialize Security World navigation button. 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:

2.

3. 4. 5.

nShield/payShield Administrator Guide Windows v5.5

131

11 Managing security worlds

Creating a security world

Note

Overwriting an existing security world in this way does not delete that security worlds host and recovery data, but renames the existing kmdata directory in which these reside as kmdata_nn (where nn is a 2digit integer assigned depending on how many security worlds have been previously saved during overwrites up to a maximum of 99). If you want to overwrite an existing security world, click the Overwrite Security World button on the Existing Security World panel. KeySafe then takes you to the Initialize Security World panel. 6. If KeySafe does not find existing security world data, it takes you to the Initialize Security World panel:

7.

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

nShield/payShield Administrator Guide Windows v5.5

132

11 Managing security worlds

Creating a security world

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

Note

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. 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. Choose the parameters for SEE debugging and the number of Administrator Cards required to change SEE debugging settings. These are:

b.

c.

nShield/payShield Administrator Guide Windows v5.5

133

11 Managing security worlds

Creating a security world

Restricted Generate Authorization Key No Access Control.

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

nShield/payShield Administrator Guide Windows v5.5

134

11 Managing security worlds

Creating a security world

Use the Initialize Security World Advanced Options panel to create key and pass phrase recovery material that is protected by the cryptographic keys on the Administrator Card Set. This does not give nCipher, or any other third party, access to your keys. Keys can only be recovered by using the Administrator Cards. Note nCipher recommends that you always select the recovery option. a. Select whether or not you want to enable key recovery, and the number of Administrator Cards required to authorize key recovery. Select whether or not you want to enable pass phrase recovery, and the number of Administrator Cards required to authorize pass phrase recovery. Specify the number of Administrator Cards required to authorize loading this security world on to another module. 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.

b.

c. d.

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

Note

nShield/payShield Administrator Guide Windows v5.5

135

11 Managing security worlds

Creating a security world

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

14. KeySafe prompts you to insert the cards that are to form the Administrator Card Set. Insert a blank card and click the OK button. If you insert a nonblank card that KeySafe can erase, the Erase Card! button is enabled, giving you the option of overwriting that card. Note When creating a card set, KeySafe recognizes a card that belongs to the set before the card set is complete. If you accidentally insert a card to be written again after it has already been written, you see a warning.

nShield/payShield Administrator Guide Windows v5.5

136

11 Managing security worlds

Creating a security world

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

If you want to set a pass phrase for this Administrator Card: a. b. c. select the Yes option enter the same pass phrase in both text fields click the OK button.

A given pass phrase is associated with a specific card, so each card can have a different pass phrase. You can change these pass phrases at any time by using KeySafes Examine/Change Card option (available from the Card Operations panel) or the cardpassphrase command-line utility. If you do not want to set a pass phrase for this Administrator Card: d. e. select the No option click the OK button.

nShield/payShield Administrator Guide Windows v5.5

137

11 Managing security worlds

Creating a security world

16. KeySafe then prompts you for the next card (if any). Note When creating a card set, KeySafe recognizes a card that belongs to the set before the card set is complete. If you accidentally insert a card to be written again after it has already been written, you see the following warning:

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

nShield/payShield Administrator Guide Windows v5.5

138

11 Managing security worlds

Creating a security world

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

Creating the security world using the CSP wizard


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

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

nShield/payShield Administrator Guide Windows v5.5

139

11 Managing security worlds

Creating a security world

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:

nShield/payShield Administrator Guide Windows v5.5

140

11 Managing security worlds

Creating a security world

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

nShield/payShield Administrator Guide Windows v5.5

141

11 Managing security worlds

Creating a security world

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

nShield/payShield Administrator Guide Windows v5.5

142

11 Managing security worlds

Creating a security world

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.

nShield/payShield Administrator Guide Windows v5.5

143

11 Managing security worlds

Creating a security world

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

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

4.

Click the Next button. If you are replacing an existing security world, go to step 14. If there are no modules in the pre-initialization state, the wizard prompts you to reset the modules as described in Entering the pre-initialization state on page 78.

Note

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

nShield/payShield Administrator Guide Windows v5.5

144

11 Managing security worlds

Creating a security world

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 worlds module key type.

nShield/payShield Administrator Guide Windows v5.5

145

11 Managing security worlds

Creating a security world

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 1402 level 3 compatible security world option. If you select this option, you must insert a card from the Administrator Card Set or an existing Operator Card Set before you can create a new Operator Card Set.

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.

nShield/payShield Administrator Guide Windows v5.5

146

11 Managing security worlds

Creating a security world

10. Click the Next button. If you did not select the Configure advanced security world options option, continue from step 11. If you selected the Advanced settings option, the World Advanced Options window is displayed:

Each tab in this window lets you specify the number of cards required to authorize specific tasks: 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.

nShield/payShield Administrator Guide Windows v5.5

147

11 Managing security worlds

Creating a security world

On the PP rec. tab, disable or enable pass phrase recovery. If you enable pass phrase recovery, select the number of Administrator Cards required to recover a pass phrase. On the NVRAM tab, specify whether you require a key to authorize the creation of entries in the modules NVRAM. If you require this key, select the number of Administrator Cards required to access the NVRAM. The NVRAM authorization key is required if you want to use NVRAM to store SEE program data or you require NVRAM key storage. On the RTC tab, specify whether you require a key to authorize setting the modules real-time clock (RTC). If you require this key, select the number of Administrator Cards required to set the clock. On the DSEE tab, disable SEE debugging, enable SEE debugging for all users, or enable SEE debugging and create an associated key. If you enable debugging with this key, select the number of Administrator Cards required to authorize SEE debugging. On the FTO tab, specify whether you require a key to authorize foreign token operations (FTO). If you require this key, select the number of Administrator Cards required to perform foreign token operations.

Note

FTO must be enabled to create a payShield installation. 11. Select Enable remote cardset support if required.

nShield/payShield Administrator Guide Windows v5.5

148

11 Managing security worlds

Creating a security world

12. The wizard displays the following window:

If you want to protect this card with a pass phrase, select the Card requires a pass phrase option. The wizard prompts you to enter and confirm the pass phrase. Note The Next button is only enabled when you have entered two matching pass phrases. 13. When you have entered the pass phrase, click the Next button. 14. Place the smart card in the module. 15. Click the Next button.

nShield/payShield Administrator Guide Windows v5.5

149

11 Managing security worlds

Creating a security world

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

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

nShield/payShield Administrator Guide Windows v5.5

150

11 Managing security worlds

Creating a security world

17. If there are no more modules to add to the security world, go to step 18. If there are further modules to add to the security world, the wizard prompts you to insert a card from the Administrator Card Set in the next module. Follow this process: a. Insert one of the cards from the Administrator Card Set that you have just created, and click the Next button. If the card is not from the Administrator Card Set, the wizard prompts for another card. 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.

b.

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

nShield/payShield Administrator Guide Windows v5.5

151

11 Managing security worlds

Creating a security world

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

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

nShield/payShield Administrator Guide Windows v5.5

152

11 Managing security worlds

Creating a security world

20. The wizard displays the following window:

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

nShield/payShield Administrator Guide Windows v5.5

153

11 Managing security worlds

After you have created a security world

the security world. This option is suited to applications where 24hour operation is required, because no human intervention is required to use application keys. If you want to use Operator Card Sets to protect your keys, select the Operator Card Set protection keys option. If you are using Microsofts CA and you want the wizard to prompt you every time you create or import a key, turn on the Always use the wizard when creating or importing keys option. If you leave this option turned off, the wizard attempts to protect the new or imported key by using the card currently in the module. You can change these settings by rerunning the wizard and selecting the Use the existing security world option. If your security world is FIPS compliant, the option to use module-protected keys is not available.

Backing up the security world and CSP


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

After you have created a security world


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

nShield/payShield Administrator Guide Windows v5.5

154

11 Managing security worlds

Adding or restoring a module to the security world

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

Adding or restoring a module to the security world


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

nShield/payShield Administrator Guide Windows v5.5

155

11 Managing security worlds

Adding or restoring a module to the security world

You can also restore a module to a security world in order to continue using existing keys and Operator Cards: after you upgrade the firmware if you replace the module

The additional modules can be any nCipher modules. For information about adding a network-connected module to the security world, see the documentation for the appropriate module type. In order to add a module to a security world, you must: have a copy of the security world data on this host. This is the host data written by KeySafe, the nCipher CSP wizard, or new-world when you created the security world. This data is stored in the directory to which the environment variable NFAST_KMDATA points (by default, C:\nfast\kmdata). set the environment variable NFAST_KMDATA (if the security world data is not in the default location). be logged in to the host computer as a user who is permitted to create privileged connections. See hardserver on page 242. have started the module in pre-initialization state (as described in Entering the pre-initialization state on page 78). possess a sufficient number of cards from the Administrator Card Set and the appropriate pass phrases.

Adding or restoring a module to a security world: erases the module reads the required number of cards (K) from the Administrator Card Set so that it can re-create the secret reads the security world data from the computers hard disk uses the secret from the Administrator Card Set to decrypt the security world key stores the security world key in the modules nonvolatile memory.

nShield/payShield Administrator Guide Windows v5.5

156

11 Managing security worlds

Adding or restoring a module to the security world

When you have added a module to a security world, you cannot access any keys that were protected by a previous security world on the module. Note It is not possible to program a module into two separate security worlds simultaneously. Initialization removes any data stored in a modules nonvolatile memory (for example, data for an SEE program or NVRAM-stored keys). To preserve this data, you must back it up before initializing the module and restore it after the module has been reprogrammed. nCipher provides the nvram-backup utility to enable data stored in nonvolatile memory to be backed up and restored. See nvram-backup on page 266 for details. In order to continue using existing keys and Operator Cards, you must reprogram the module: after you upgrade the firmware if you replace the module if you need to add a module to an existing security world.

Adding a module to a security world with KeySafe


The current release of KeySafe works with multiple modules. In order to add a module to an existing security world with KeySafe, follow these steps: 1. Start KeySafe. (For an introduction to KeySafe and information on starting the software, see the appropriate Operator Guide for your module.) Click the Modules menu button. KeySafe takes you to the Module Operations panel. Click the Reprogram Module navigation button.

2. 3.

nShield/payShield Administrator Guide Windows v5.5

157

11 Managing security worlds

Adding or restoring a module to the security world

4. Note

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

The module that you want to add to your security world must be in the pre-initialization state. 5. Click the Reprogram Module! command button. KeySafe takes you to the Load Administrator Card Set panel:

6.

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

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.

nShield/payShield Administrator Guide Windows v5.5

158

11 Managing security worlds

Adding or restoring a module to the security world

After you have added a module to the security world: Put the module into the operational state, as described in Entering the operational state on page 79. Return the Administrator Card Set to safe storage.

The newly added module can now be used with keys and cards from the existing security world.

Adding a module to a security world with the nCipher CSP wizard


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

3.

Click the Next button. If the wizard finds an existing security world, it displays the following window:

nShield/payShield Administrator Guide Windows v5.5

159

11 Managing security worlds

Adding or restoring a module to the security world

If the wizard displays any of the other windows: a. b. c. cancel the operation check that you have correctly set the environment variable
NFAST_KMDATA

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. run the wizard again.

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

nShield/payShield Administrator Guide Windows v5.5

160

11 Managing security worlds

Adding or restoring a module to the security world

Adding a module to a security world with new-world


1. Open a command window and type the command:

C:\nfast\bin\new-world [-l|--program] [-S|--no-remoteshare-cert] [-m|--module=MODULE]

In this command:
-l, --program

These options tell new-world to load the existing security world from the kmdata directory into a module.
-S, --no-remoteshare-cert

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

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

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

nShield/payShield Administrator Guide Windows v5.5

161

11 Managing security worlds

Erasing a module from a security world

3. Note

Store the Administrator Card Set in a safe place.

If any error occurs (for example, if you do not enter the correct pass phrases), the module is reset to the factory state. The module does not form part of the security world unless you run new-world again.

Erasing a module from a security world


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

You do not need the Administrator Card Set in order to erase a module. However, unless you have a valid Administrator Card Set and the host data for this security world, you cannot restore the security world after you have erased it.

nShield/payShield Administrator Guide Windows v5.5

162

11 Managing security worlds

Erasing a module from a security world

After you have erased a module, it is in the same state as when it left nCipher (that is, it has a random module key and a known KNSO).

Erasing a module with KeySafe


You can erase a module on a server with KeySafe by following these steps: 1. Start KeySafe. (For an introduction to KeySafe and information on starting the software, see the appropriate Operator Guide for your module.) Click the Modules menu button. KeySafe takes you to the Module Operations panel. Click the Erase Module navigation button. KeySafe takes you to the Erase Module panel:

2. 3.

4.

Select the module that you want to erase by clicking its listing on the Module Status tree. Then click the Erase Module! command button.

nShield/payShield Administrator Guide Windows v5.5

163

11 Managing security worlds

Erasing a module from a security world

5. Note

KeySafe erases all secrets from the module, returning it to its factory state.

If you have any keys that were protected by an erased module, you cannot access them unless you restore these secrets. You cannot restore these secrets unless you have the appropriate Administrator Card Set.

Erasing a module with new-world


new-world can erase any modules that are in the pre-initialization

state. Run new-world with the command:


new-world [-e|--factory] [-m|--module=MODULE]

In this command:
-e, --factory

These options tell new-world to restore a module to its factory state.


-m, --module=MODULE

These options specify the ModuleID to use. new-world erases only one module at a time. To erase multiple modules, you must run new-world once for every module that you want to erase.

Output
If new-world successfully erased a module, it does not display any messages. Otherwise, new-world returns an error message.

nShield/payShield Administrator Guide Windows v5.5

164

11 Managing security worlds

Deleting the security world

Erasing a module with initunit


initunit erases any modules that are in the pre-initialization state.

Run initunit with the command:


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

In this command, --module=MODULE specifies the ModuleID of the module you want to erase. If --module=MODULE is not specified, all modules in the pre-initialization state are erased.

Output
If initunit is successful, for each module that is in the pre-initialization state, it returns a message similar to this:
Initialising Unit # Setting dummy HKNSO Module Key Info: HKNSO ################### HKM ###################

Otherwise, initunit returns an error message.

Deleting the security world


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

nShield/payShield Administrator Guide Windows v5.5

165

11 Managing security worlds

Displaying information about your security world

before you remove an old security world, you must reformat any smart cards that were used previously as Operator Cards within this security world.

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. b. c. Delete the files in the directory to which the NFAST_KMDATA environment variable points. Create a new security world. Add all your modules to this world.

Method 2: a. b. Remove all the modules from the security world. Delete the files in the directory to which the NFAST_KMDATA environment variable points.

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

Displaying information about your security world


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

nShield/payShield Administrator Guide Windows v5.5

166

11 Managing security worlds

Displaying information about your security world

You can use KeySafe to view details of Operator Cards in a security world as described in the Operator Guide.

Displaying information about your security world with nfkminfo


To display information about the security world from the command line, issue the following command:
nfkminfo [-w|--world-info] [-r|--repeat] [-p|--preload-client-id]

In this command:
-w, --world-info

These options specify that you want to display general information about the security world. These options are the default and need not be included explicitly.
-r, --repeat

These options display the information repeatedly. There is a pause at the end of each set of information. The information is displayed again when you press Enter .
-p, --preload-client-id

These options display the preloaded client ID value, if any. The command also has the standard help options:
-h, --help

This option displays help for nfkminfo.


-v, --version

This option displays the version number of nfkminfo.


-u, --usage

This option displays a brief usage summary for nfkminfo.

nShield/payShield Administrator Guide Windows v5.5

167

11 Managing security worlds

Displaying information about your security world

Output
nfkminfo displays information similar to that shown in the following

examples:
generation 1 state 0x70000 Initialised Usable Recovery !PINRecovery !ExistingClient !RTC !NVRAM !FTO !SEEDebug n_modules 1 hknso hash_knso hkm hash_km hkmwk hash_knwk hkre hash_kre hkra hash_kra ex.client none ...

... Module #1 generation 1 state 0x1 Useable flags 0x10000 ShareTarget n_slots 2 esn 34F3-9CB4-753B hkml hash_kml Module #1 Slot #0 IC 11 generation 1 phystype SmartCard slotlistflags 0x2 state 0x4 Operator flags 0x20000 RemoteEnabled shareno 2 error OK Cardset name "fred" k-out-of-n 1/2 flags NotPersistent timeout none card names "" "" hkltu hash_kt Module #1 Slot #1 IC 0 generation 1

nShield/payShield Administrator Guide Windows v5.5

168

11 Managing security worlds

Displaying information about your security world

phystype slotlistflags state flags shareno shares error No Cardset

SoftToken 0x0 0x1 Empty 0x0 0 OK

No Pre-Loaded Objects

Security world
nfkminfo reports the following information about the security world: generation

This indicates the nCipher internal number.


state

This indicates the status of the current world:


Initialised

indicates that the security world has been initialized


Usable

This indicates that there is at least one usable module in this security world on this host.
!Usable

This indicates that there are no usable modules in this security world on this host.
Recovery

This indicates that the security world has the key recovery feature enabled.

nShield/payShield Administrator Guide Windows v5.5

169

11 Managing security worlds

Displaying information about your security world

!Recovery

This indicates that the security world has the key recovery feature disabled.
StrictFIPS140

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

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

This indicates that no Client ID is set. The ex.client output will be empty.
!SEEDebug

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

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

This indicates no authorization is required for SEE Debugging.

nShield/payShield Administrator Guide Windows v5.5

170

11 Managing security worlds

Displaying information about your security world

PINRecovery

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

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

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

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

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

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

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

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

nShield/payShield Administrator Guide Windows v5.5

171

11 Managing security worlds

Displaying information about your security world

n_modules

This indicates the number of nCipher modules connected to this computer.


hknso

This indicates the SHA-1 hash of the nCipher Security Officers key.
hkm

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


hkmwk

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

This indicates the SHA-1 hash of the recovery key pair.


hkra

This indicates the SHA-1 hash of the recovery authorization key.


ex.client

This indicates the ClientID required to use any pre-loaded keys and tokens.
k-out-of-n

This indicates the values of K and N for this security world.

nShield/payShield Administrator Guide Windows v5.5

172

11 Managing security worlds

Displaying information about your security world

other quora

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

This indicates the version of the module data.


state

This indicates is one of the following:


PreInitMode

This indicates that the module is in the preinitialization state.


InitMode

This indicates that the module is in the initialization state.


Unknown

This indicates that the modules state could not be determined.


Usable

This indicates that the module is programmed in the current security world and can be used.

nShield/payShield Administrator Guide Windows v5.5

173

11 Managing security worlds

Displaying information about your security world

Uninitialized

This indicates that the module does not have the nCipher Security Officers key set and that the module must be initialized before use.
Factory

This indicates indicating that the module has module key zero only and that the nCipher Security Officers key is set to the factory default.
Foreign

This indicates that the module is from an unknown security world.


AccelOnly

This indicates that the module is acceleration only.


Unchecked

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

This indicates that the module has failed.


MaintMode

This indicates that the module is in the maintenance state.


flags

This displays ShareTarget if the module has been initialized to allow reading of remote card sets.

nShield/payShield Administrator Guide Windows v5.5

174

11 Managing security worlds

Displaying information about your security world

n_slots

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

This indicates the electronic serial number of the module (if the module is not in the Usable state, the electronic serial number may not be available).
hkml

This indicates the hash of the module signing key (if the module is not in the Usable state, this value may not be available). Slot For each nCipher slot on the module, nfkminfo reports:
IC

This indicates the insertion count for this slot (which is 0 if there is no card in the slot).
generation

This indicates the version of the slotinfo structure.


phystype

This indicates the type of slot, which can be one of:


slotlistflags SmartCard SoftToken.

These are flags describing the capabilities of the slot:

nShield/payShield Administrator Guide Windows v5.5

175

11 Managing security worlds

Displaying information about your security world

0x1

This indicates that the slot uses a protected PIN path.


0x2

This indicates that the slot supports challengeresponse authentication.


state

This can be one or more of the following flags:


Blank

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


Admin

This indicates that the smart card in the reader is part of the Administrator Card Set.
Empty

This indicates indicating that there is no smart card in the reader.


Error

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

This indicates that the smart card in the reader is an Operator Card.

nShield/payShield Administrator Guide Windows v5.5

176

11 Managing security worlds

Displaying information about your security world

flags

This displays Passphrase if the smart card requires a pass phrase.


shareno

This indicates the number of the card within the card set.
error

This indicates the error status encountered if the smart card could not be read:
OK

This indicates that there were no errors.


TokenAuthFailed

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

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

This indicates the name given to this card set.


k-out-of-n

This indicates the values of K and N for this card.

nShield/payShield Administrator Guide Windows v5.5

177

11 Managing security worlds

Displaying information about your security world

flags

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


NotPersistent

This indicates that the Operator Card is not persistent.


Persistent

This indicates that the Operator Card is persistent.


NotRemoteEnabled

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

This indicates that the card in the slot is from a Remote Operator Card Set.
PINRecoveryForbidden(disabled)

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

This indicates that the card in the slot does have PIN recovery enabled.
timeout

the period of time in seconds after which the module automatically removes the Operator Card Set. If timeout is set to none, the Operator Card Set does not time out.

nShield/payShield Administrator Guide Windows v5.5

178

11 Managing security worlds

Windows Cryptographic Services Provider (CSP)

card

names the names of the cards in the set, not all software can give names to individual cards in a set.
hkltu

the SHA-1 hash of the secret on the card. For more information about nfkminfo, see the appropriate Operator Guide for your module.

Windows Cryptographic Services Provider (CSP)


Container storage format
Note Versions of the CSP later than 1.11.0 have an updated container storage mechanism. CSP containers are now stored as part of the nCipher security world instead of in the Windows registry file. Versions of the CSP later than 1.11.0 use a non-backwardscompatible container and key storage format. If you are installing version 1.11.0 or later of the CSP over older versions, you must run thecspmigrateutility in order to convert containers and keys from the old system to the new system. CSP versions 1.11.0 and later have a number of advantages over older versions: The CSP state is easily mirrored between multiple machines simply by copying the contents of the kmdata directory or by sharing the kmdata directory across a network. The CSP key files can have arbitrary names (previously, the names of key files were linked to their key type and their container name). This new method facilitates the importation of existing nCipher security world keys into the CSP.

nShield/payShield Administrator Guide Windows v5.5

179

11 Managing security worlds

Windows Cryptographic Services Provider (CSP)

Every different container is now guaranteed to have a distinct storage location. There were circumstances in CSP versions older than 1.11.0 in which two containers with similar names could have shared the same keys wrongly.

However, there are some points to bear in mind concerning CSP versions 1.11.10 and later: If you want to share the same key between multiple computers, nCipher supplies the cspimport utility for transferring keys between containers. Any existing containers with older versions of the CSP must be migrated to the new format. nCipher provides a utility, cspmigrate, to migrate containers from the old to the new system.

nShield/payShield Administrator Guide Windows v5.5

180

11 Managing security worlds

Windows Cryptographic Services Provider (CSP)

Setting up the Microsoft CA with an existing key


If you want to set up the Microsoft CA with an existing key, select the check box labelled Use an existing key in the Advanced Options section of the CA setup process. You are presented with a menu of suitable containers (machine containers that contain signature keys) from which to select:

If the key you select already has a certificate associated with it, you can choose to use the same certificate for the CA. Such a choice is typically used if you are reinstalling the CA and using the same key.

Setting up IIS 5 with an existing key


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

nShield/payShield Administrator Guide Windows v5.5

181

11 Managing security worlds

Windows Cryptographic Services Provider (CSP)

For example, in order to generate a suitable server certificate using the web interface of the Microsoft CA, make the following selections in order: 1. 2. 3.
Request a certificate Advanced request 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: Note the intended purpose must be Server Authentication
Certificate

the Use local machine store option must be enabled.

If you do not enable these options, the created certificate is not suitable for use as a Web server certificate and SSL does not work. The selected CSP must also be a suitable nCipher CSP (typically,
nCipher Enhanced SChannel Cryptographic Provider for an RSA key).

In order to use an existing key set, enable the Use existing key sets name. The key size option is ignored in this case because the key size was decided at the original key creation time.

nShield/payShield Administrator Guide Windows v5.5

182

11 Managing security worlds

Windows Cryptographic Services Provider (CSP)

The portion of the advanced certificate request form used for the CSP and key setup is shown below, with all needed options selected correctly:

Migrating an existing security world to the new CSP format


There is a set of utilities supplied with CSP version 1.11.0 and later that help you migrate from the Windows registry-based CSP container storage to the new CSP format. The new CSP format stores all information about a security world in the kmdata directory. These utilities are:
cspcheck

This utility checks that CSP container files are intact and uncorrupted, and also that referenced key files exist. Use cspcheck in conjunction with nfkmcheck, but run nfkmcheck first in order to test the integrity of your security world files.

nShield/payShield Administrator Guide Windows v5.5

183

11 Managing security worlds

Windows Cryptographic Services Provider (CSP)

cspimport

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

This utility moves an existing security worlds CSP container information from the registry to the security worlds kmdata directory.
csputils

This utility lists CSP containers and provides detailed information about them. It can also be used to delete container files if the current user has administrative privileges.
keytst

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

nShield/payShield Administrator Guide Windows v5.5

184

11 Managing security worlds

Transferring keys between security worlds

Transferring keys between security worlds


The utilities mk-reprogam and key-xfer-im are used to transfer keys between security worlds. Before you can use these utilities to transfer keys, the following must be the case: the security world from which keys are being transferred must have recovery enabled (the destination security world can be nonrecoverable). the key being transferred must have recovery enabled or be module-protected you must have the Administrator Card Sets for both the exporting module and the importing module. If one of the modules is a netHSM, it should be imported

To transfer keys: 1. Program the module to which you intend to transfer the key into one of the security worlds involved. If one of the security worlds is FIPS 140-2 level 3 compliant and the other is not, then program the module into the security world that is not FIPS 140-2 level 3 compliant. 2. Run the mk-reprogram utility on the exporting security world in order to program a module key from that security world to a module in the importing security world. See mk-reprogram on page 255. To authorize this operation, you must first present a quorum of Administrator Cards for KNSO for the exporting (current) security world, then a quorum of Administrator Cards for module programming from the importing security world. Note If you change security worlds by using the command new-world -l, the programmed module key is lost.

nShield/payShield Administrator Guide Windows v5.5

185

11 Managing security worlds

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

4.

Initialize the importing security world. To verify that module-protected keys have been imported: a. Run the following command:

C:\nfast\bin\preload --module-prot exit

The output shows whether the key was imported successfully. b. Check the C:\nfast\kmdata\local\ directory to see if the key has been exported.

You can use preload to load other types of keys to verify that they have been imported.See the Operator Guide for details. 5. If you have transferred keys that protect PKCS #11 objects, run
postrocs on the target module once the key transfer is complete.

See postrocs on page 286.

nShield/payShield Administrator Guide Windows v5.5

186

Chapter 12: About payShield installations


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

About payShield Card Sets


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

nShield/payShield Administrator Guide Windows v5.5

187

12 About payShield installations

About payShield Card Sets

Administrator Card Set


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

payShield Master Card Set


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

payShield Key Establishment Card Set


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

Card Set Quorums


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

nShield/payShield Administrator Guide Windows v5.5

188

12 About payShield installations

About payShield Card Sets

Additionally, the Administrator Card Set has a separate quorum for Foreign Token Open operations (FTO). An FTO quorum of Administrator Cards is required (and sufficient) to authorize the reading of data directly from non-nCore-format smart cards. Thus, the FTO quorum of Administrator Cards must be used to enable the payShield system to use the module smart-card reader to exchange key setup information with the VeriFone handset. Similarly, any attacker who can use the FTO quorum of Administrator Cards may be able to interfere with and subvert key establishment, including reading key components from transfer smart cards. The quorum for FTO should be selected to prevent this. nCipher suggests as a minimum a quorum of 3. nCipher recommends that you give careful consideration to the choice of K and N for the Key Establishment Card Set. Any quorum of K Key Establishment Card holders can introduce new keys, as can an attacker who is able to use K Key Establishment Cards with a module in the security world. If new keys are not authorized and secure, they may compromise the security of other payShield keys and PINS that are being processed. nCipher suggests as a minimum a quorum of 2 cards out of 4 (that is, a 2-of-4 card set) for the Key Establishment Card Set.

Card Holders
The entire security of the keys you create within the payShield installation and of the data that they protect depends on the security of the security world and of the payShield installation card sets. You must ensure that all cards are stored securely and in the custody of trusted personnel. Cards should never be exposed needlessly. No individual should ever have possession of more than one card from a particular card set, although an individual may hold one card from each of a number of different card sets.

nShield/payShield Administrator Guide Windows v5.5

189

12 About payShield installations

Supported payShield Key Types

Supported payShield Key Types


lmku

This type is the Local Master Key for key and data encryption.
lmkr

This type is the Local Master Key for key encryption only.
zmk

This type is the Zone Master Key.


cvk

This type is for CVC generation and verification.


cvkv

This type is for CAVV generation and verification.


pvk

This type is the Pin Verification Key.


tpk

This type is the Terminal PIN Key.


zpk

This type is the Zone PIN Key.


mksmi

This type is for secure messaging for the integrity master key
mkidn

This type is the dynamic number master key

nShield/payShield Administrator Guide Windows v5.5

190

12 About payShield installations

payShield security world properties

mkac

This type is the AC (ARQ, AAC, TC) master key


mkdac

This type is for the static data authentication master key. A Local Master Key (lmk) can be used for the encryption both of key material and of data such as PINs. However, nCipher considers it useful to split and restrict the capabilities of certain key types. Therefore, the following two new types of lmk are provided for use with payShield:
lmku for the encryption of keys and data lmkr for the encryption of keys only

When specifying an lmk in a payShield installation, you must select one of these types of lmk depending on your requirements. These are treated as strictly separate roles and cannot be changed after creation.

payShield security world properties


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

nShield/payShield Administrator Guide Windows v5.5

191

12 About payShield installations

payShield security world properties

It is extremely important that you choose the settings carefully because you cannot change the properties of a security world after you have created it.

nShield/payShield Administrator Guide Windows v5.5

192

Chapter 13: Remote Operator Card Sets


This chapter describes: Note the concept of the Remote Operator functions how to configure Remote Operator.

If you wish to use the Remote Operator feature, you must enable it as described in Chapter 8: Feature Enabling nCipher Modules. The Remote Operator feature must be ordered for, and enabled on, the module that you intend to use as the remote, unattended module.

About Remote Operator


The Remote Operator facility enables the contents of a smart card inserted into the slot of one module (the attended module, such a client module) to be securely transmitted and loaded onto another module (the unattended module, such as a netHSM). This is useful when you need to load a key protected by an Operator Card Set onto a machine to which you do not have physical access, for example, because it is in a secure area. For Remote Operator to work, the modules must be in the same security world. The Operator Card Set is inserted into a slot in the attended module. From this module, the contents of the card set are transmitted over secure channels to another module. This module, the unattended module, loads the contents of the Operator Card Set. You do not need physical access to this module during the loading of the card set. The following limitations apply to Remote Operator: Non-persistent card sets cannot be accessed remotely. The createocs utility cannot use remote slots to write new cards or card sets.

nShield/payShield Administrator Guide Windows v5.5

193

13 Remote Operator Card Sets

Configuring Remote Operator

You can export a slot from an attended module and import a slot to any (unattended) module in the security world. The unattended module for import may be a local module connected to the host or a networkconnected module such as a netHSM or payShield net module.. (You can import or export slots between netHSM or payShield net modules and local modules only if the local module uses a hardserver whose version is 2.6.10 or higher.) Before you can import a slot to one module, you must first export it from another module.

Configuring Remote Operator


This section describes how to configure Remote Operator.

Before you configure Remote Operator


Requirements for Remote Operator
Before you start to configure Remote Operator, you must do the following: Initialize two modules in the same security world, as described below. Initialize the unattended module as described below. Ensure both the attended and unattended module are in the operational state, as described in Entering the operational state on page 79. Create an Operator Card Set with the correct permissions, as described in Creating a Remote Operator Card Set on page 196. Configure each hardserver to allow communication between the modules.

nShield/payShield Administrator Guide Windows v5.5

194

13 Remote Operator Card Sets

Configuring Remote Operator

Initializing modules for Remote Operator Firmware version 2.6.10 or greater must be installed in both the attended and unattended module. Use the enquiry utility to determine the version of the firmware on the modules. For instructions on upgrading firmware, see Appendix A: Upgrading module firmware or the documentation for the appropriate module type. After updating the firmware, the unattended module must be reinitialized into the security world by using KeySafe or new-world. Note By default, a module is initialized with remote card set reading enabled. If you do not want a module to be able to read remote card sets, you must configure it accordingly. Use the command new-world S MODULE (where MODULE is the modules ModuleID number) if you do not want this module to be able to read remote card sets. See new-world on page 259 for full information. The attended module does not need to be re-initialized. If a module has been initialized to allow loading of remote card sets, nfkminfo displays a module section of the following form:
Module #1 generation state flags n_slots esn hkml

Note

2 0x2 Usable 0x10000 ShareTarget 3 8851-43DF-3795 391eb12cf98c112094c1d3ca06c54bfe3c07a103

The ShareTarget flag indicates that the module can be used as an attended module for the loading of Remote Operator Card Sets.

nShield/payShield Administrator Guide Windows v5.5

195

13 Remote Operator Card Sets

Configuring Remote Operator

Creating a Remote Operator Card Set


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

In this output, the RemoteEnabled flag indicates the card can be loaded remotely.

Importing and exporting slots


To import a slot from an attended module on to an unattended module:

nShield/payShield Administrator Guide Windows v5.5

196

13 Remote Operator Card Sets

Configuring Remote Operator

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.

nShield/payShield Administrator Guide Windows v5.5

197

13 Remote Operator Card Sets

Configuring Remote Operator

Importing remote slots


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

nShield/payShield Administrator Guide Windows v5.5

198

13 Remote Operator Card Sets

Configuring Remote Operator

Loading Remote Operator Card Sets


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

Creating keys protected by Remote Operator Card Sets


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

nShield/payShield Administrator Guide Windows v5.5

199

Chapter 14: Administration tasks with cards and softcards


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

Before you can perform any of these operations, you must first create a security world, as described in Chapter 11: Managing security worlds.

Replacing an Operator Cards pass phrase


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

nShield/payShield Administrator Guide Windows v5.5

200

14 Administration tasks with cards and softcards

Replacing an Operator Cards pass phrase

Replacing a pass phrase with cardpp (on a client)


Take the following steps: 1. Run the cardpp utility using the command:

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

In this command: --recover

This option tells cardpp to recover the pass phrase.


-m, --module=MODULE

These options specify the number of the module to use. If you only have one module, MODULE is 1. If you do not specify a module number, cardpp uses all modules by default. 2. At the prompt, supply the number of cards from the Administrator Card Set required to authorize pass phrase recovery. At the prompt, insert the Operator Card whose pass phrase you want to replace. At the prompt, type the pass phrase or press Enter if you do not want to set a pass phrase. If you have entered a pass phrase, at the prompt, confirm it.
cardpp sets the new pass phrase and prompts you for another

3. 4. 5.

Operator Card. 6. To change the pass phrase on further cards, repeat steps 3 though 5, or press Q to quit.

Administrator cards should only be inserted in a server you know is secure.

nShield/payShield Administrator Guide Windows v5.5

201

14 Administration tasks with cards and softcards

Replacing Operator Card Sets

Replacing Operator Card Sets


In order to prevent you from losing access to your keys if the smart card you are using as the Operator Card is lost or damaged, nCipher supplies several utilities that can recover the keys protected by the lost Operator Card to another token: KeySafe includes an option to replace Operator Card Sets on the Card Operations panel (click the Replace OCS navigation button). The rocs command-line utility provides an interactive method or a command-line only method to replace Operator Card Sets.

When you replace an Operator Card Set, the key material is not changed by the process. The process deletes the original host data (that is, the encrypted version of the key or keys and the smart card data file) and replaces this data with host data protected by the new Operator Card Set. In order to replace an Operator Card Set, you must have: Note enabled key recovery when you created the security world

If you did not enable key recovery, or if you created the security world with an early version of pkcs-init that did not support key recovery, you cannot recover keys from lost or damaged smart cards. created the original Operator Card Set using createocs, createocsimple, KeySafe, or the nCipher PKCS #11 library version 1.6 or later If you initialized the token using ckinittoken from the nCipher PKCS #11 library version 1.5 or earlier, you must contact Support at nCipher to arrange for them to convert the token to the new format while you still possess a valid card.

nShield/payShield Administrator Guide Windows v5.5

202

14 Administration tasks with cards and softcards

Replacing Operator Card Sets

Note

a sufficient number of cards from the Administrator Card Set to authorize recovery

All recovery options require authorization from the Administrator Card Set. If any of the smart cards in the Administrator Card Set are lost or damaged, immediately replace the entire Administrator Card Set. initialized a second Operator Card Set using createocs, createocsimple, KeySafe, or the nCipher PKCS #11 library version 1.6 or later.

Note

The new Operator Card Set need not have the same K-of-N policy as the old set. If you are sharing the security world across several host computers, you must ensure that the changes to the host data are propagated to all your computers. One way to achieve this is to use client cooperation; see Setting up client cooperation on page 53.

Replacing Operator Card Sets with KeySafe


In order to replace an Operator Card Set, you must have another Operator Card Set onto which to copy the first sets data. If you do not already have an existing second Operator Card Set, you must create a new one. See the Operator Guide for details. When you have a second Operator Card Set ready, follow these steps in order to replace the first Operator Card Set: 1. Start KeySafe. (For an introduction to KeySafe and information on starting the software, see the appropriate Operator Guide for your module.) Click the Cards menu button. KeySafe takes you to the Card Operations panel.

2.

nShield/payShield Administrator Guide Windows v5.5

203

14 Administration tasks with cards and softcards

Replacing Operator Card Sets

3.

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

nShield/payShield Administrator Guide Windows v5.5

204

14 Administration tasks with cards and softcards

Replacing Operator Card Sets

This panel lists existing Operator Card Sets in tabular form. For each card set it displays:
Name

the name of the card set


Required (K)

the number of cards needed to re-create a key


Total (N)

the total number of cards in the set


Persistent

whether or not the card set is persistent


Recoverable Key Count

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

the number of private keys protected by this card set that cannot be recovered. You can click and drag with your mouse in order to resize this table's column widths and to rearrange the column order. Clicking a column heading sorts the rows in ascending order based on that column heading. 4. 5. Note Select an Operator Card Set that you want to replace by clicking its list entry. Click the Replace OCS! command button.

If the card set does not have any recoverable keys, it cannot be replaced.

nShield/payShield Administrator Guide Windows v5.5

205

14 Administration tasks with cards and softcards

Replacing Operator Card Sets

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 modules 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 modules smart card slot, you must click the OK button. When you have loaded enough cards from the new Operator Card Set, KeySafe creates new working versions of the recoverable keys that are protected by this card set. KeySafe deletes the original host data for all recovered keys and replaces this data with host data that is protected by the new Operator Card Set. If there are no nonrecoverable keys protected by the card set, KeySafe also removes the old card set from the security world. However, if the Operator Card Set has nonrecoverable keys, the host data for the original card set and for the nonrecoverable keys is not deleted. These keys can only be accessed with the original Operator Card Set. If you want to delete these files, use the Remove OCS option. 8. When the process is complete, KeySafe displays a dialog box indicating that the Operator Card Set has been successfully replaced. Click the OK button. KeySafe returns you the Replace Operator Card Set panel, where you may replace another Operator Card Set or choose a different operation.

nShield/payShield Administrator Guide Windows v5.5

206

14 Administration tasks with cards and softcards

Replacing Operator Card Sets

Recovering keys to Operator Card Sets or softcards with rocs


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

Using rocs interactively


Run the rocs utility using the command:
C:\nfast\bin\rocs

rocs displays the following prompt:


'rocs' key recovery tool Useful commands: 'help', 'help intro', 'quit'. rocs >

In order to use rocs to replace an Operator Card Set or recover keys to a softcard, take the following steps: 1. 2. You must select a module to use by using the module command, which is described in the section module number on page 213. 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. 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.

3.

Note

Keys protected by an Operator Card Set can only be recovered to another Operator Card Set, and not to a softcard. Likewise, softcardprotected keys can only be recovered to another softcard, and not to an Operator Card Set. 4. List the keys in the current security world using the list keys command, which is described in the section list keys on page 212.

nShield/payShield Administrator Guide Windows v5.5

207

14 Administration tasks with cards and softcards

Replacing Operator Card Sets

5.

Select the keys that are to be recovered by using the mark command, which is described in the section mark key-spec on page 213. 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. 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

6.

7.

Set. 8. Insert a card from the Administrator Card Set.


rocs prompts you for the pass phrase for this card. This action is

repeated until you have loaded the required number of cards from the Administrator Card Set. If you do not have the required number of cards from the Administrator Card Set, press Q and then Enter . The rocs utility returns you to the rocs > prompt without processing any keys. Administrator cards should only be inserted in a server you know is secure.

nShield/payShield Administrator Guide Windows v5.5

208

14 Administration tasks with cards and softcards

Replacing Operator Card Sets

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. c. Insert a card from this Operator 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 Operator Card Set. If you are recovering keys to a softcard, rocs prompts you for the pass phrase for the softcard that you have selected as the target. If you decide that you do not want to transfer the keys to the selected card set or softcard, press Q and then Enter (to quit).rocs returns you to the rocs > prompt and does not process any further Operator Card Sets or softcards. When you have loaded the target softcard or the required number of cards from the target Operator Card Set, rocs transfers the selected keys to the target Operator Card Set or softcard. If you have selected other target Operator Card Sets or softcards,
rocs prompts for a card from the next Operator Card Set.

10. Repeat step 9 for each selected target. 11. If you have transferred the correct keys, write the key blobs to disk by using the save function (described in the section save keyspec on page 214). If you have transferred a key by mistake, you can restore it to its original protection by using the revert command (described in the section revert key-spec on page 214). At the rocs prompt, you can use the following commands:
help topic help intro list cardsets list keys

nShield/payShield Administrator Guide Windows v5.5

209

14 Administration tasks with cards and softcards

Replacing Operator Card Sets

Note

mark key-spec module number quit recover rescan revert key-spec save key-spec status target cardset-spec unmark key-spec

You can specify a command by typing enough characters to identify the command uniquely. For example, for the status command, you can type st and then press Enter . help With no arguments specified, help shows a list of available commands with brief usage messages and a list of other help topics. With an argument, help shows detailed help information about a given topic.
help intro displays a brief step-by-step guide to using rocs.

list cardsets This command lists the Operator Card Sets and softcards in the current security world. For example:
No. 1 2 3 Name test test2 test3 Keys (recov) 6 (6) 3 (2) 1 (1) Sharing 3 of 5; 20 minute timeout 2 of 3 1 of 1; persistent

In this output:

nShield/payShield Administrator Guide Windows v5.5

210

14 Administration tasks with cards and softcards

Replacing Operator Card Sets

No.

This is the card set or softcard number, which can be used to identify this card set in rocs commands.
Name

This is the Operator Card Set or softcard name


Keys

This is the number of keys protected by this Operator Card Set or softcard
(recov)

This is the number of recoverable keys


Sharing

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


persistent

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

This indicates that the Operator Card Set is persistent and has a time-out set.

nShield/payShield Administrator Guide Windows v5.5

211

14 Administration tasks with cards and softcards

Replacing Operator Card Sets

list keys This command lists the keys in the current security world, as in the following example:
No. 1 2 R 3 4 5 Name rsa-test Id: uc63e0ca3cb032d71c1c Server-Cert Id: uc63e0ca3cb032d71c1c Server-Cert App hwcrhk pkcs11 pkcs11 pkcs11 pkcs11 Protected by module test2 test --> test2 test --> test3 module (test ---> fred2)

where:
No.

This is the key number, which can be used in mark and


unmark commands. Name

This is the key name.


App

This is the application with which this key is associated.


Protected by

This indicates the protection method:


method
module name name-->name2 module (name) module (name-->name2)

description
key protected by the security world key protected by the named Operator Card Set or softcard key protected by the Operator Card Set or softcard name1 marked for recovery to Operator Card Set or softcard name2 PKCS #11 public object, which are protected by the security world but associated with a specific Operator Card Set or softcard PKCS #11 public object marked for recovery

nShield/payShield Administrator Guide Windows v5.5

212

14 Administration tasks with cards and softcards

Replacing Operator Card Sets

mark key-spec This command marks the listed keys that are to be recovered to the target Operator Card Set or softcard. You can mark one or more keys by number, ident, Operator Card Set or softcard, or hash. See Specifying keys on page 217 for details. To mark more than one key at a time, ensure that each key-spec is separated from the other by spaces, as in the following example:
mark key-spec1 key-spec2 key-spec3

If you have not selected a target Operator Card Set or softcard, or if rocs cannot parse the key-spec, then rocs displays an error message. You can mark and remark the keys to be recovered to various target Operator Card Sets or softcards. Remarking a key displaces the first target in favor of the second target. Note Keys protected by an Operator Card Set can only be recovered to another Operator Card Set, and not to a softcard. Likewise, softcardprotected keys can only be recovered to another softcard, and not to an Operator Card Set. module number This command selects the module to be used. The module number must correspond to a module in the current security world. If the module does not exist, is not in the security world, or is otherwise unusable, then rocs displays an error message and does not change to the selected module. quit This command allows you to leave rocs. If you attempt to quit when you have recovered keys but have not saved them, rocs displays a warning.

nShield/payShield Administrator Guide Windows v5.5

213

14 Administration tasks with cards and softcards

Replacing Operator Card Sets

recover This command transfers the marked keys to their target Operator Card Sets or softcards. This operation is not permanent until you save these keys by using the save command. rescan This command updates the card set and key information. revert key-spec This command returns keys that have been recovered, but not saved, to being protected by the original protection method. If the selected keys have not been recovered, rocs displays an error message. save key-spec This command writes the new key blobs to disk. If you specify a key-spec, only those keys are saved. Otherwise, all recovered keys are saved. status This command lists the currently selected module and target Operator Card Set or softcard. target cardset-spec This command selects a given Operator Card Set or softcard as the target. You can specify the card set or softcard name, the number returned by list cardsets, or the hash.

nShield/payShield Administrator Guide Windows v5.5

214

14 Administration tasks with cards and softcards

Replacing Operator Card Sets

unmark key-spec This command unmarks the listed keys. Unmarked keys are not recovered.

Using rocs from the command line


You can select all the options on the command line using the command:
C:\nfast\bin\rocs -m|--module=MODULE [-t|--target=CARDSET-SPEC] [-k|--keys=KEYS-SPEC] [-c|--cardset=CARDSET-SPEC] [-i|--interactive]

In this command:
-m, --module=MODULE

specify the module number of the module to use.


-t, --target=CARDSET-SPEC

specifies the Operator Card Set or softcard to be used to protect the keys. See Specifying card sets on page 217 for details.
-k, --keys=KEYS-SPEC

selects the keys to be recovered. See Specifying keys on page 217 for details.
-c, --cardset=CARDSET-SPEC

selects all keys that are protected by the given Operator Card Set or softcard. See Specifying card sets on page 217 for details.
-i, --interactive

forces rocs to start interactively even if you have already selected keys.

nShield/payShield Administrator Guide Windows v5.5

215

14 Administration tasks with cards and softcards

Replacing Operator Card Sets

The rocs command also has the standard help options:


-h, --help

displays help for rocs


-v, --version

displays the version number of rocs


-u, --usage

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

nShield/payShield Administrator Guide Windows v5.5

216

14 Administration tasks with cards and softcards

Replacing Operator Card Sets

Specifying card sets


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

selects the Operator Card Set or softcard with the given number from the list produced by the list cardsets command
[name] cardset-name

selects card sets or softcards by their names (the card set or softcard name may be a wildcard pattern in order to select all matching Operator Card Sets or softcards)
hash cardset-hash

selects the Operator Card Set or softcard with the given hash. In order to specify multiple Operator Card Sets or softcards, include several CARDSET-SPECs on the command line. Note Keys protected by an Operator Card Set can only be recovered to another Operator Card Set, and not to a softcard. Likewise, softcardprotected keys can only be recovered to another softcard, and not to an Operator Card Set.

Specifying keys
The --keys=KEYS-SPEC option identifies one or more keys. It may have any of the following forms:
mark key-number

This selects the key with the given number from the list produced by the list keys command. Examples of usage are:
rocs -t target_OCS -k key_number

nShield/payShield Administrator Guide Windows v5.5

217

14 Administration tasks with cards and softcards

Changing pass phrases with cardpp

and
rocs -t target_OCS -k "mark 56"

appname:keyident

This selects keys by their internal application name and ident. You must supply at least one of appname or keyident, but you can use wildcard patterns for either or both in order to select all matching keys. An example of usage is:
rocs -t target_OCS --keys="simple:simplekey"

hash keyhash

This selects the key with the given key hash. An example of usage is:
rocs -t target_OCS --keys="hash e364[...]"

--cardset cardset-spec

This selects all keys protected by a given card set

Changing pass phrases with cardpp


If you have generated your security world with pass phrase recovery, the cardpp utility allows you to: change a pass phrase add a pass phrase to a card that currently does not have one remove a pass phrase from a card that currently has one

nShield/payShield Administrator Guide Windows v5.5

218

14 Administration tasks with cards and softcards

Changing pass phrases with cardpp

replace the pass phrase of an Operator Card even though you do not know the current pass phrase. This operation requires authorization from the Administrator Card Set. Changing a pass phrase with cardpp when you do know the current pass phrase does not require authorization from the Administrator Card Set; for more information see the Operator Guide appropriate for your module.

Each card in a card set can have its own individual pass phrase. You can even have a set in which some cards have pass phrases and others do not. A pass phrase can be of any length and can contain any characters that you can type.

Changing pass phrases with cardpp (pass phrase not known)


To change a pass phrase for an Operator Card using the cardpp command-line utility when you do not know the pass phrase, you must: have created a security world with pass phrase recovery have sufficient cards from the Administrator Card Set to authorize the action.

If these conditions are met, take the following steps: 1. Run the cardpp utility using the command:

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

In this command:
--recover

tells cardpp to recover the pass phrase.


-m, --module=MODULE

specify the number of the module to use. If you only have one module, MODULE is 1. If you do not specify a module number, cardpp uses all modules by default.

nShield/payShield Administrator Guide Windows v5.5

219

14 Administration tasks with cards and softcards

Changing pass phrases with ppmk

2. 3. 4. 5.

When cardpp prompts you, insert sufficient cards from the Administrator Card Set to authorize pass phrase recovery. When cardpp prompts you, insert the Operator Card whose pass phrase you want to replace. When cardpp prompts you for the new pass phrase, type the pass phrase or press Enter if you do not want to set a pass phrase. 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. If you do not want to continue press Q to quit.

6.

Changing pass phrases with ppmk


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

Changing pass phrases with ppmk (pass phrase not known)


To change a pass phrase for a softcard using the ppmk command-line utility when you do not know the pass phrase, you must: have created a security world with pass phrase recovery have sufficient cards from the Administrator Card Set to authorize the action.

If these conditions are met, take the following steps:

nShield/payShield Administrator Guide Windows v5.5

220

14 Administration tasks with cards and softcards

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. 3. When ppmk prompts you, insert sufficient cards from the Administrator Card Set to authorize pass phrase recovery. When prompted, type a pass phrase for the new softcard, and press Enter . A pass phrase can contain any characters that you can type and can be up to 1024 characters long.
ppmk prompts you to confirm the pass phrase. Type the pass phrase again and press Enter .

4.

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. 2. 3. load the secret information that is to be used to protect the archived copy of the security world key. create a new secret that is to be shared between a new set of cards create a new archive that is to be protected by this secret.

nShield/payShield Administrator Guide Windows v5.5

221

14 Administration tasks with cards and softcards

Replacing the Administrator Card Set

If you discover that one of the cards in the current Administrator Card Set has been damaged or lost, use the command-line utility racs or the KeySafe Replace Administrator Card Set option to create a new set immediately. If further cards are damaged, you may not be able to recreate your security world. nCipher recommends that you erase your old Administrator Cards as soon as you have created the new Administrator Card Set. An attacker with the old Administrator Card Set and a copy of the old host data could still re-create all your keys. With a copy of a current backup, they could even access keys that were created after you replaced the Administrator Card Set. Note Before you start to replace an Administrator Card Set, you must ensure that you have enough blank cards to create a complete new Administrator Card Set. If you start the procedure without enough cards, you will have to cancel the procedure part way through.

Replacing an Administrator Card Set with KeySafe


When you have enough cards to create a complete new Administrator Card Set ready, follow these steps in order to replace the old Administrator Card Set. 1. Start KeySafe. (For an introduction to KeySafe and information on starting the software, see the appropriate Operator Guide for your module.) Click the Cards menu button. KeySafe takes you to the Card Operations panel. Click the Replace ACS navigation button, and KeySafe takes you to the Replace Administrator Card Set panel. If you are sure that you want to replace the Administrator Card Set, click the Replace ACS! command button

2. 3. 4.

nShield/payShield Administrator Guide Windows v5.5

222

14 Administration tasks with cards and softcards

Replacing the Administrator Card Set

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

nShield/payShield Administrator Guide Windows v5.5

223

14 Administration tasks with cards and softcards

Replacing the Administrator Card Set

7.

When you insert a blank card, KeySafe takes you to the Set Card Protection Pass Phrase panel:

8.

If you want to set a pass phrase for this Administrator Card: a. b. c. Select the Yes option. Enter the same pass phrase in both text fields. Click the OK button.

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

nShield/payShield Administrator Guide Windows v5.5

224

14 Administration tasks with cards and softcards

Replacing the Administrator Card Set

10. After you have created all the Administrator Cards, KeySafe displays a message:
ACS successfully replaced. Now consider erasing your old Administrator Cards

Click the OK button, and KeySafe returns you to its introduction panel. 11. When you have finished replacing the Administrator Card Set, erase the old Administrator Cards.

Replacing an Administrator Card Set with racs


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

In this command:
--module=MODULE

specifies the ModuleID of the module to use.


--force

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

nShield/payShield Administrator Guide Windows v5.5

225

Chapter 15: nShield Administrator Utilities


This chapter contains reference information about the utilities referred to in this manual. See Appendix E: Installed Utilities for a full list of all the utilities supplied with the nCipher software.

Help options
If a utility has the standard help options, these are not included in the synopsis or in the description. The standard help options are as follows:
-h, --help displays help for the utility -v, --version displays the version number of the utility -u, --usage displays a brief usage summary for the utility

Some commands have alternative help options. These are described but are not included in the synopsis.

nShield/payShield Administrator Guide Windows v5.5

226

15 nShield Administrator Utilities

anonkneti

anonkneti
This utility displays the ESN and HKNETI key hash from a netHSM module identified by its IP address. This information is required to configure your client hardserver to import the remote module. This utility uses an anonymous host and is insecure. Use it only if you trust your network. Otherwise, obtain the ESN and HKNETI of the module from the welcome screen.

Usage
c:\nfast\bin\anonkneti [-m module] [-p port] IP_address

In this command:
-m module

This option specifies the module to query. The default is module 1.


-p port

This option specifies the port to use to communicate with the module.
IP_address

This option specifies the IP address of the module from which to obtain the ESN and HKNETI key hash.

nShield/payShield Administrator Guide Windows v5.5

227

15 nShield Administrator Utilities

cfg-reread

cfg-reread
This utility loads the hardserver configuration from the configuration file.

Usage
C:\nfast\bin\cfg-reread.exe

This command has no options or parameters. It loads the file C:\nfast\kmdata\config\config as the clients current configuration. See server_remotecomms on page 90 for details of the configuration file. The cfg-reread utility calls a number of separate utilities, each of which loads one section of the configuration file. If you update only one section of the configuration file, you can reload just that section by running the corresponding command as follows:
Utility
hsc_loadseemachine.exe hsc_serverremotecomms.exe hsc_serversettings.exe hsc_slotimports.exe hsc_slotexports.exe

Configuration file section


load_seemachine server_remotecomms

Updates ...
SEE machine settings Remote communications settings Module settings and hardserver settings Imported slot settings Exported slot settings

module_settings server_settings slot_imports slot_exports

nShield/payShield Administrator Guide Windows v5.5

228

15 nShield Administrator Utilities

enquiry

enquiry
The enquiry utility returns information about the nCipher server and the modules connected to it.

Usage
enquiry -m|--module=MODULE

In this command, --module=MODULE is the module number of the module about which you want to receive information. If you do not specify a module, enquiry returns information about all modules.

Output
enquiry returns the following data for the server and each module: enquiry reply flags Failed indicates that the module has failed. This failure may be because the module is in the Error state or because there

is a problem on the PCI bus.


enquiry reply level

This is the version of enquiry that the module (or hardserver) supports. For release 9.0 and later, this level is Six or higher.
serial number

This is the electronic serial number of the module. Please quote this number when contacting Support at nCipher. For the server, this field contains the electronic serial numbers for all attached modules.
mode

This is one of:

nShield/payShield Administrator Guide Windows v5.5

229

15 nShield Administrator Utilities

enquiry

operational initialisation maintenance pre-initialisation pre-maintenance uninitialised.

For the server, this is always operational.


version

This is the version of the nCipher server or firmware.


speed index

This is the estimated number of 1024-bit modular exponentiations that the module can perform in 1 second.
rec. queue

This is the recommended minimum and maximum number of jobs in the job queue to keep the module fully loaded.
level one flags

If the module supports enquiry level One or greater, one or more of the following flags is set:
Hardware

The Hardware flag is always set.


HasTokens

The HasTokens flag is set if the module has a smart card interface.

nShield/payShield Administrator Guide Windows v5.5

230

15 nShield Administrator Utilities

enquiry

MaintenanceMode

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


InitialisationMode

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


PreMaintInitMode

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


version string

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

For modules that support enquiry level One or greater, this indicates the date on which the firmware was last modified.
level two flags

This is for nCipher internal use only.. Note There should be no level two flags set. If any are set, contact Support at nCipher.
max write size

Currently, this is 8192 for nShield/payShield modules.


level three flags

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

nShield/payShield Administrator Guide Windows v5.5

231

15 nShield Administrator Utilities

enquiry

level four flags

For modules that support enquiry level Four or greater, one or more of the following flags can be set:
OrderlyClearUnit

The OrderlyClearUnit flag is set for firmware release 1.40 and later.
HasRTC

The HasRTC flag is set if the module has a RealTime Clock.


HasNVRAM

The HasNVRAM flag is set if the module has nonvolatile memory.


HasNSOPermsCmd

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

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

nShield/payShield Administrator Guide Windows v5.5

232

15 nShield Administrator Utilities

enquiry

FastPollSlotList

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

The HasSEE flag is set if the module firmware supports the Secure Execution Engine (SEE).
HasKLF

The HasKLF flag is set if the module has a longterm fixed signing key.
HasShareACL

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

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

The HasFileOp flag is set if the module supports operations using nonvolatile memory.
HasPCIPush

The HasPCIPush flag is set by the module if it has PCI push functionality.

nShield/payShield Administrator Guide Windows v5.5

233

15 nShield Administrator Utilities

enquiry

HasKernelInterface

The HasKernelInterface flag is set if the module has a kernel interface.


HasLongJobs

The HasLongJobs flag is set if the module supports unlimited time for job completion.
SeverHasLongJobs

The SeverHasLongJobs flag is set if the hardserver supports unlimited time for job completion.
AESModuleKeys

The AESModuleKeys flag is set if the module supports the use of the AES Algorithm (Rijndael) for module keys.
NTokenCmds

The NTokenCmds flag is set if the module supports the commands necessary for nToken. For the server, the level four flags field contains all the flags set for attached modules.
module type code

For modules that support enquiry level Five or greater, this field contains the numeric value of the module type. This can be:
0 for the server 5 for models nC3022W-nnn, nC4022W-nnn, and

nC4032W-nnn
6 for models nC3022P-nnn, nC4022P-nnn, nC4032P-

nnn, and nC4132P-nnn

nShield/payShield Administrator Guide Windows v5.5

234

15 nShield Administrator Utilities

enquiry


product name

7 for models nC3023P-nnn, nC4023P-nnn, and

nC4033P-nnn
11 for model nC4031Z-nnn.

For modules that support enquiry level Five or greater, this is the product name. For the server, this is nFast server.
device name

For modules that support enquiry level Five or greater, the ModuleID, bus, and slot for the device, as reported in log messages. For example, #1 PCI bus 0 id 2 means ModuleID 1 on PCI bus 0 with PCI ID 2. device name is blank in the information on the server and for installations where the server software is earlier than version 1.60.5.
EnquirySix version

For modules that support enquiry level Six, this is the extended enquiry reply level six version number. (The highest currently supported level is Five.)
impath kx groups

For modules that support enquiry level Six, this lists the available key exchange groups that this module can use when it makes a connection with another module.
feature ctrl flags

For modules that support enquiry level Six version 1 or greater, this is always set to LongTerm. This field does not exist for the server.

nShield/payShield Administrator Guide Windows v5.5

235

15 nShield Administrator Utilities

enquiry

features enabled

For modules that support enquiry level Six version 1 or greater, this lists the features currently enabled. Possible values are as follows:
Value
ForeignTokenOpen RemoteShare KISAAlgorithms

Feature that is enabled


Foreign Token access features (ISS). Remote Operator Card support Support for KISA algorithm suite (KCDSA, SEED, HAS160 hash function) Allows any SEE machine to be loaded. Available only within CGEA locations. Allows small key sizes to provide improved levels of security.

Feature name
ISO Smart Card Support Remote Operator Korean Algorithms.

GeneralSEE

SEE Activation (EU+10)

EllipticCurve

Elliptic Curve

If no features are enabled, this field is set to StandardKM. This field does not exist for the server.
version serial

For modules that support enquiry level Six version 2 or greater, this is the version serial number of the module.
remote server port

For modules that support enquiry level Six version 4 or greater, this is the port on which the hardserver listens for communications from remote modules. (The default is 9004.)
kneti hash

For modules that support enquiry level Six version 4 or greater, this is the HKNETI key hash (if present) of this module.

nShield/payShield Administrator Guide Windows v5.5

236

15 nShield Administrator Utilities

enquiry

rec. LongJobs queue

For modules that support enquiry level Six version 5 or greater, this is the recommended minimum and maximum number of jobs in the job queue to keep the modules that support LongJobs fully loaded.
SEE machine type

For modules that support enquiry level Six version 5 or greater, this is gen1AIF for modules with ARM processors and PowerPCSXF for modules with Power PC processors. This information is needed if you are developing CodeSafe applications (see the CodeSafe Developers Guide for more information).

nShield/payShield Administrator Guide Windows v5.5

237

15 nShield Administrator Utilities

floodtest

floodtest
The floodtest utility performs hardware speed testing using modular exponentiation with the Chinese Remainder Theorem.

Usage
C:\nfast\bin\floodtest.exe [--crt|--no-crt] [-Q|--query] [-R|--no-round-robin] [-l|-job-size=BITS] [-t|--stop-after=TIME] [-j|--outstanding-jobs=COUNT] [-n|--jobs-count=COUNT] [[[-K|--skew-check=SKEW ]| [-T|--min-check=COUNT ]] [-C|--check-start=TIME ]] [--overprint][-o|--output=FILE] [-r|--report-interval=TIME]

Program options
--crt

This option specifies use of CRT optimization. This is the default.


--no-crt

This option specifies no use of CRT optimization


-Q, --query

These options specify use Query mode (spinlock) rather than Wait mode
-R, --no-round-robin

These options specify that replies be accepted in any order. (The default is that replies are accepted on a round-robin basis.)

nShield/payShield Administrator Guide Windows v5.5

238

15 nShield Administrator Utilities

floodtest

-l, --job-size=BITS

These options set the size of exponentiation modulus to the number of bits specified in BITS. The default is 1024. The value of BITS must be between 64 and 4096. BITS must be a multiple of 64 Note Certain older modules (with serial numbers beginning 01-52, 01-54, 01-56, 01-P2, 01-P4, or 01-P6) can run out of memory if you run floodtest with sizes greater than 2048, especially if the module has any keys or tokens loaded.
-j, --outstanding-jobs=COUNT

These options try to keep COUNT number of jobs outstanding at a time. The default value of COUNT is the maximum number of jobs recommended for the hardserver, plus 1.
-t, --stop-after=TIME

These options specify the maximum time to run the test. Use the suffix s to specify seconds, m for minutes, h for hours, and d for days. The default value of TIME is infinity.
-n, --jobs-count=COUNT

These options specify the maximum number of jobs to run. The default value of COUNT is infinity.

Automatic checking options


-T, min-check=COUNT

These options perform threshold checking, starting after either 15 seconds or the time specified by --check-start. Subsequently, when floodtest writes an output line, it quits with an error message if the overall average number of modular exponentiations each second drops below COUNT.

nShield/payShield Administrator Guide Windows v5.5

239

15 nShield Administrator Utilities

floodtest

-K, --skew-check=SKEW

These options perform skew checking, after either 15 seconds or the time specified by --check-start. floodtest records the overall average number of modular exponentiations each second as rec_ave. Subsequently, when floodtest writes an output line, it quits with an error message if the average is outside the range rec_aveSKEW. Note The --min-check and --skew-check options are mutually exclusive.
-C, --check-start=TIME

This option specifies the time in seconds at which threshold or skew checking starts. The default value of TIME is 15.

Output options
--overprint

This option prints results all on one line, using \r rather than \n.
-o, --output=FILE

This option specifies that results be written to FILE in addition to stdout.


-r, --report-interval=TIME

This option displays, at the specified interval of TIME seconds, the total number of exponentiations achieved, and the rate at which they are performed. The default value of TIME is 1.

nShield/payShield Administrator Guide Windows v5.5

240

15 nShield Administrator Utilities

floodtest

Output
floodtest returns output similar to this:
hardware, speed index 296, using rec. max outstanding + 1 = 46 1, 148 59.2, 151 overall 2, 410 140.32, 206 overall 3, 677 190.992, 226 overall 4, 944 221.395, 267 overall 5, 1190 231.237, 256.5 overall ...

The first column, to the right of the line numbers, shows the number of seconds. The second shows the total number of exponentiations performed. The third column shows the number of exponentiations achieved this second. The last column shows a moving average of the number of exponentiations achieved each second.

nShield/payShield Administrator Guide Windows v5.5

241

15 nShield Administrator Utilities

hardserver

hardserver
The hardserver is the communications service between applications and nCipher modules. You must be logged in as Administrator to use the command-line options for this command.

Usage
hardserver.exe [-c|--command-line]

The hardserver is configured by means of configuration files. See Hardserver configuration file on page 85 for information. The -c or --command-line options run the hardserver program as a command line program instead of as a service

Hardserver startup
The hardserver utility is the hardserver program. It is installed as a service and started automatically.
%NFAST_HOME%\scripts\hardserver.d

On startup, the hardserver looks for scripts in the directory and executes them as follows: On hardserver startup, all batch files whose names begin with S are executed in strict lexicological order (for example, S01_myscript.bat followed by S02_myscript.bat). On module reset, if and only if the module is being reset into operation mode, all batch files whose names begin with M are executed in strict lexicological order (for example, M01_myscript.bat followed by M02_myscript.bat ).

When the hardserver starts, it clears all modules and runs all the S scripts and then all the M scripts in order for all operational modules.

nShield/payShield Administrator Guide Windows v5.5

242

15 nShield Administrator Utilities

hardserver

Stopping the hardserver


1. 2. 3. 4. Ensure that you are logged in as a user who is permitted to stop and that services (for example, a Local Administrator). Open the Computer Management dialog. This is usually found by choosing Programs > Administrative Tools from the Start menu. Highlight the Services entry under Services and Applications. nFast Server should be listed with the status Started. 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. 2. Ensure that you are logged in as as a user who is permitted to create privileged connections. Open the Computer Management dialog. This is usually found by choosing Programs > Administrative Tools > Computer Management from the Start menu. Highlight the Services entry under Services and Applications.
nFast Server should be listed with the status Stopped.

3. 4.

Scroll down the list of services until you have highlighted the
nFast Server entry, and click the Start button in order to restart the

server.

nShield/payShield Administrator Guide Windows v5.5

243

15 nShield Administrator Utilities

initunit

initunit
The initunit utility initializes a unit with a random module key and a known KNSO. This utility makes a key-management module usable but does not enable any key archival or recovery.

Usage
In order to use initunit, you must be logged in to the host computer as root or as a user in the group nfast and must start the module in the pre-initialization state. See Entering the pre-maintenance state on page 76 for information on putting the module into a pre-initialization state.
C:\nfast\bin\initunit.exe [-m|--module=MODULE] [-n|--ntoken]

In this command:
-m, --module=MODULE

These options specify the module number (MODULE) of the module you want to initialize. If you do not specify a module, initunit initializes all modules that are in a preinitialization state.
-n, --ntoken

These options specify the initialization of a module as an nToken.

nShield/payShield Administrator Guide Windows v5.5

244

15 nShield Administrator Utilities

initunit

Output
If initunit is successful, it returns a message similar to this for each module that has been initialized:
Initialising Unit # Setting dummy HKNSO Module Key Info: HKNSO ###################HKM

###################

Otherwise, it returns an error message that points to the reason for the initialization failure.

nShield/payShield Administrator Guide Windows v5.5

245

15 nShield Administrator Utilities

loadkeys

loadkeys
The loadkeys utility is used with a payShield installation. It imports, generates or exports keys. Its use is described in full in the Keyloading Solution Guide.

Usage
C:\nfast\bin\loadkeys.exe [options] psiname

In this command, psiname is the name of the payShield installation that you are going to import the key into. psiname must consist of 16, or fewer, lower case alphanumeric characters.

Options
Modes of Operation
-I, --import

These options import a key (requires --format option).


-E, --export

These options export a key (requires --format option).


-G, --generate

These options generate a new key.


--batch

This option specifies that the application does not prompt for nonessential options that have not been specified on the command line. Non-essential options include key export options, rolespecific options and group memberships.

nShield/payShield Administrator Guide Windows v5.5

246

15 nShield Administrator Utilities

loadkeys

General options
-m, --module=MODULE

These options select the hardware security module to use. The default is 1.
-f, --format=FORMAT

These options specify the import or export format for the key. This can be wrapped or components.
--kcvf=CV_FORMAT

These options specify the key Check Value format. This can be one of none (for no check value), zero (for the encryptzeros method) or self (for the encrypt-self method).
-d, --debug

These options enable library debugging.


-k, --key-name=NAME

These options specify the name for the imported key. This can be either the name of the key to be exported or the name to give the newly imported key, depending upon the operation. Import/Generate options
-l, --length=LENGTH

These options set the lengths for each component. LENGTH can be 8, 16 or 24 bytes. This is equal to the length of the resulting derived key, or half the length of the derived key if you are importing cvk or cvkv keys.

nShield/payShield Administrator Guide Windows v5.5

247

15 nShield Administrator Utilities

loadkeys

You can omit this option if the key type specified in --role=ROLE has only one permitted length.
-r, --role=ROLE

These options specify the role for the imported key


-g, --group=NAME

These options add the key to group NAME. NAME can be a maximum of 16 characters. The option may be specified multiple times.
-a, --export-attended

These options makes the key exportable in attended operations.


-A, --no-export-attended

These options specify that the key is not to be exportable in attended operations.

Component options
--ccvf=CV_FORMAT

These options specify the component Check Value format. This can be one of none (for no check value), zero (for the encrypt zeros method) or self (for the encrypt-self method).
-n, --num=COMPONENTS

These options specify the total number of components. This can be an integer from 2 through 9.

nShield/payShield Administrator Guide Windows v5.5

248

15 nShield Administrator Utilities

loadkeys

Wrapped options
-w, --wrapper=NAME

These options specify the name of the wrapping key. key. If the payShield key that you specify cannot be loaded, the application prompts you for another name.

Reduced AC import options


-i, --iipb=MASK

These options specify the IIPB mask to be used with this reduced AC key operation. The default is ffff000000000000.

IBM PIN key options


--dtable=TABLE

This option specifies the decimalization table that is to be used with a new PVKIBM key.
--pan-n=PAN

This option specifies the number of PAN digits to be required for PIN generation with a new PVKIBM key. PAN can be an integer from 0 through 12: the default is 12.

nShield/payShield Administrator Guide Windows v5.5

249

15 nShield Administrator Utilities

key-xfer-im

key-xfer-im
The key-xfer-im utility transfers a key into a second security world. The module must previously have had the second security worlds module key loaded using the mk-reprogram utility, described in mkreprogram on page 255. (See Transferring keys between security worlds on page 185.)

Usage
key-xfer-im SOURCE-KMDATA-LOCAL DESTINATION-KMDATA-LOCAL NEW-PROTECT KEY-FILE [KEYFILE ...] [NEW-PROTECT KEY-FILE [KEY-FILE ...]]

Parameters
SOURCE-KMDATA-LOCAL

The full path name of the kmdata file for the source security world.
DESTINATION-KMDATA-LOCAL

The full path name of the kmdata file for the target security world.
NEW-PROTECT

The protection for the key in the target security world. You must specify either --module or --cardset. If you specify --cardset, it must be followed by the key hash for the destination card set. In addition, you can also specify options to configure the key protection further:

nShield/payShield Administrator Guide Windows v5.5

250

15 nShield Administrator Utilities

key-xfer-im

--export-leave

This option is used to leave the keys list of operations requiring authorization from the Administrator Card Set (ACS)= the same. This is the default.
--export-add

This option is used to add export to the keys list of operations requiring authorization from the ACS. This option is available only when exporting keys from a strict FIPS 140-2 level 3 security world into a non-strict FIPS 140-2 level 3 security world.
--export-delete

This option is used to remove export from the keys list of operations requiring authorization from the ACS. This option is available only when exporting keys from a non-strict FIPS 140-2 level 3 security world into a strict FIPS 140-2 level 3 security world.
--aclbase-recovery

This option is used to base the Access Control List (ACL) of the exported key on the ACL in the recovery key blob. This is the default.
--aclbase-working

This option is used to base the ACL of the exported key on the ACL in the working key blob.
KEY-FILE

This is the full path of source kmdata file for the key. The module must have module keys from both worlds: program it into one world with new-world and use mk-reprogram to

nShield/payShield Administrator Guide Windows v5.5

251

15 nShield Administrator Utilities

key-xfer-im

add the other module key. If transferring between Strict FIPS-140 level 3 and non-strict worlds, the modules owning world must be non-strict. The following example command demonstrates the second step in moving a module from a security world that is not FIPS 140 2 level 3 compliant to one that is:
key-xfer-im C:\nfast\kmdata\local\ C:\nfast\kmdata-FIPS\local\ --module --export-delete KEY-FILE

nShield/payShield Administrator Guide Windows v5.5

252

15 nShield Administrator Utilities

loadrom

loadrom
The loadrom utility loads new firmware into a module. Firmware is supplied as an encrypted and signed file. See Upgrading module firmware on page 323 for information on upgrading firmware. You can also use loadrom to obtain information about the firmware.

Usage
C:\nfast\bin\ [-v|--view] [-n|--notypecheck] [-m|--module=MODULE] [-b|--maxblocksize=SIZE] NFF_file

In this command NFF_file is the name of the file that contains the firmware. This has the extension .nff. See Appendix A: Upgrading module firmware for information on the file name for your module.

Help options
-h, --help

These options display help for loadrom.exe.


-V, --version

These options display the version number of loadrom.exe.


-u, --usage

These options display a brief usage summary for loadrom.exe.

Programming options
-v, --view

These options only display information about the .nff file and do not load it.

nShield/payShield Administrator Guide Windows v5.5

253

15 nShield Administrator Utilities

loadrom

-i, --ioboard

This option is for nCipher internal use only.


-m, --module=MODULE

These options load the firmware on the module MODULE.


-b, --maxblocksize=SIZE

These options set the maximum block size in bytes for module programming.
--notypecheck

This option omits the module type check.

Output
If you select the --view option, loadrom displays output similar to this:
File :..\..\module\firmware\2-18-13\ncx3p-21.nff Firmware : PCI Type 3 firmware version 2.18.13cam1 (VSN 21) for : nC1003P/nC3023P Filetype : NFast3 Programming chunks: 12 Confidentiality key: nC3023P confidentiality key (dorris #2) Confidentiality mech: DES3mCBCi64pPKCS5 Signatures: #0: <unknown> integrity key #1: nC3023P integrity key (dorris-1)

During installation and when upgrading module firmware you can compare the output of loadrom --view with the information provided by the enquiry command-line utility to ensure that the correct version of the firmware is present on the module. See enquiry on page 229.

nShield/payShield Administrator Guide Windows v5.5

254

15 nShield Administrator Utilities

mk-reprogram

mk-reprogram
The mk-reprogram utility programs a security-world module key into a module to which it does not yet belong. A key that is to be transferred from one security world to another must be loaded into a module that: has been programmed into one of the security worlds has had the module key of the target security world loaded into it using mk-reprogram.

After the security-world module key has been loaded, you can use the key-xfer-im utility to transfer a key into the second security world. (See Transferring keys between security worlds on page 185.)

Usage
mk-reprogram.exe [[--module MODULE-NO----] CHANGES

In this command CHANGES specifies the parameters of the reprogrammed security world, as described in Keywords on page 256. kmdata must be from the security world that includes the module.

Options
--module=MODULE-NO

specifies the module on to which to program the security world. The default is the first available module.
--protocol

specifies the protocol to use.


--owner kmlocal-path

specifies the path to the source module's kmlocal directory.

nShield/payShield Administrator Guide Windows v5.5

255

15 nShield Administrator Utilities

mk-reprogram

Keywords
CHANGES can be one of the following: list

lists the details of the security world.


add kmdata-path

adds the path to the local kmdata directory. This directory must be from the security world that includes the specified module.
delete MODULE-KEY-HASH

deletes the specified module key hash.

Example
The following example command demonstrates the first step in moving a module-protected key from a security world that is not FIPS 140 1 level 3 or FIPS 140 2 level 3 compliant to one that is:
mk-reprogram --module 1 add C:\nfast\kmdata_FIPS\local

nShield/payShield Administrator Guide Windows v5.5

256

15 nShield Administrator Utilities

ncversions

ncversions
The ncversions utility displays installed nCipher support software components and their versions. The utility lists all components, whether installed individually or as part of a component bundle, and also the component bundles themselves. See Components on nCipher CD-ROMs on page 330.

Usage
C:\nfast\bin\ncversions.exe

Output
The following in an example of a component list produced by ncversions:
Comp Output Version Repository/Build no. ---------------------------------------------------------------convrt user 1.1.0 cam/1 csee armdev 0.10.5 cam/3 csee seedev 0.10.5 cam/3 ctd agg 0.0.12 cam/4 ctls agg 0.0.13 cam/3 cutils devel 1.4.2 cam/8 emvjni user 0.2.2 cam/36 emvspj user 0.2.6 cam/20 emvspj devel 0.2.6 cam/20 emvspp user 1.5.10 cam/14 emvspp devel 1.5.10 cam/14 gcchk user 1.1.1 cam/2 ... ... ... ... ... ... ... ...

ncversions displays a line of information for each component:

nShield/payShield Administrator Guide Windows v5.5

257

15 nShield Administrator Utilities

ncversions

Comp

This gives the component's identifying code


Output

This identifies the type of component, such as:


Version user for a user component devel for a developer component agg for a component bundle

This identifies the version of the component


Repository/Build no.

This identifies the repository and build number.

nShield/payShield Administrator Guide Windows v5.5

258

15 nShield Administrator Utilities

new-world

new-world
The new-world utility creates a security world that supports SEE functions and remote Operator Card Set use. new-world also allows you to specify different thresholds for different operations, such as: adding a module replacing an Operator Card Set authorizing real-time clock operations authorizing nonvolatile memory operations.

new-world can also be used to add a module to an existing security

world. To use the new-world utility, you must be logged in to the host computer as Administrator or a user who is permitted to create privileged connections. Note If you create a security world with new-world, this security world is created with only one module. If you use other modules, then you must add them to the security world with new-world or KeySafe.

Usage
new-world -i|initialize [-S|--no-remoteshare-cert][-o|--overwrite][-F|--strict-fips140-level-2-level-3] [-R|--no-recovery][-m|--module]MODULE] -Q|--acs-quorum=K/N FEATURES -k|--km-type=KEY-TYPE [--reduced-features]

new-world -l|program [-S|--no-remoteshare-cert][-m|--module=MODULE]

new-world -e|--factory -m|--module=MODULE

nShield/payShield Administrator Guide Windows v5.5

259

15 nShield Administrator Utilities

new-world

Module selection option


-m, --module=MODULE

These options specify the module to use. new-world initializes only one module at a time. If you have multiple modules, you must run new-world once for every module. The default is 1.

Action selection options


-i, --initialize

These options tell new-world to initialize a new security world and program it into the module specified in --module=MODULE, replacing any existing kmdata directory.
-l, --program

These options tell new-world to load the existing security world from the kmdata directory into a module specified in --module=MODULE.
-e, --factory

These options tell new-world to erase a module, restoring it to factory state. Note You must not include more than one of the --initialize, --program, and -factory options. If you do not specify any of these options and a kmdata directory already exists, new-world loads the security world found within the directory. If you do not specify any of these options and no kmdata directory exists, new-world creates a security world.

nShield/payShield Administrator Guide Windows v5.5

260

15 nShield Administrator Utilities

new-world

Module reprogramming options


-S, --no-remoteshare-cert

These options tell new-world that the selected module is not a target for remote shares.

New security world options


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

In these options K is the maximum number of smart cards required from the Administrator Card Set to authorize a feature. You can specify lower thresholds for a particular feature. Thresholds must be less than or equal to the total number of cards in the set. N is the total number of smart cards to be used in the Administrator Card Set. This value must be less than or equal to 64. Note You should not create an Administrator Card Set for which the required number of cards is equal to the total number of cards because you cannot replace the Administrator Card Set if even a single card is lost or damaged. The --acs-quorum=K/N option only takes effect if you are creating a new security world.

nShield/payShield Administrator Guide Windows v5.5

261

15 nShield Administrator Utilities

new-world

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

These options create a security world that conforms to the FIPS 140-2 requirements for roles and services at level 3. If you do not specify this flag, new-world creates a security world that complies with FIPS 140-2 requirements for level 2. Note This option provides compliance with the roles and services of the FIPS 140-2 level 3 standard. It is included for those customers who have a regulatory requirement for compliance. The current release of the nCipher PKCS #11 library works with a FIPS 140-2 level 3 compliant security world. However, if you intend to use the security world with the PKCS #11 applications iPlanet Enterprise Server or iPlanet Proxy Server, do not specify this flag. The --strict-fips-140-2-level-3 option only has any effect if you are creating a new security world.
-O, --overwrite

These options tell new-world to allow the use of smart cards that already contain data. Any existing data is erased. If a value for this flag is not specified, new-world prompts you if a card contains data.
-R, --no-recovery

These options tell new-world to disable Operator Card Set recovery. The effect of setting this flag is the same as for specifying the feature !r. By default, new-world creates key-recovery material that is protected by the cryptographic keys on the Administrator Card Set. This option does not give nCipher or any other third party access to your keys. Keys can only be recovered by using the Administrator Cards. nCipher recommends that you leave Operator Card Set recovery enabled.

nShield/payShield Administrator Guide Windows v5.5

262

15 nShield Administrator Utilities

new-world

If you do not enable this option at the time of security world creation, you can never enable recovery for keys in the security world. If you do not enable this option when you create the ACS, you can never enable recovery for any card sets protected by the ACS.
-k, --km-type=KEY-TYPE

These options specify the type of key that is to protect the new security world. KEY-TYPE can be des3 or rijndael).

Features
When initializing a security world, features may be specified as arguments after the module number. Some features are enabled by default, and you can give the command new-world --help-features to display a list of features indicating which are enabled by default when initializing a security world with new-world. Features are specified as a comma-separated list of terms. Each term consists of a feature name, optionally preceded by either a dash (-) or an exclamation point (!) to turn off the feature and can optionally be followed by an equal sign (=) and the threshold for this feature. However, the ! character, used to turn off a given feature, is interpreted by some shells (for example, the C shell and its derivatives, bash and zsh) as requesting a history expansion. In such cases, you must escape the ! character by preceding it with a \ character, as in the following example:
new-world 2 rtc,nv,\!r

Additionally, any feature entered on the command line with a leading hyphen (-) can be interpreted as an option. Attempting to pass a feature as a nonexistent option in this way returns an error (for example, unknown option). Prevent errors of this kind by using the

nShield/payShield Administrator Guide Windows v5.5

263

15 nShield Administrator Utilities

new-world

standard POSIX double hyphen (--) marker to indicate that any subsequent features on the command line are not to be interpreted as options, as in the following example:
new-world -m 2 -- -r

Currently understood feature names are:


m, for module programming (this feature cannot be disabled) r, for Operator Card Set recovery p, for pass phrase recovery dsee, to make an SEE debugging key dseeall, enable SEE debugging without authorization nv, for nonvolatile memory allocation rtc, real-time clock setting fto, Foreign Token Open authorization. Use this feature with ISO

Smartcard Support. The dsee and dseeall options are not applicable unless you have purchased and installed nCiphers CodeSafe Developer kit. For example, the following features:
m=1,r,!p,nv=2,rtc=1

create a security world for which: a single card from the Administrator Card Set is required to add a new module the default number is required to replace an Operator Card Set pass phrase recovery is not enabled 2 cards are required to allocate nonvolatile memory

nShield/payShield Administrator Guide Windows v5.5

264

15 nShield Administrator Utilities

new-world

Note

1 card is required to set the real-time clock.

Under most conditions, it is advisable to turn on such features as nv, rtc, dsee, and (if desired) p. There is usually no benefit in turning on both dsee and dseeall simultaneously.

Output
If new-world cannot interpret the command line, it displays its usage message and exits. If you attempt to set a threshold for a feature that you have disabled or if you attempt to set a threshold too high, new-world displays an error and exits. If the module is not in the pre-initialization state, new-world displays and error and exits. To put the module in the pre-initialization state, see Entering the pre-maintenance state on page 76. If the module is in the pre-initialization state, new-world prompts you for smart cards and pass phrases as required. When new-world has initialized the module, restart the module in the operational state.

nShield/payShield Administrator Guide Windows v5.5

265

15 nShield Administrator Utilities

nvram-backup

nvram-backup
The nvram-backup utility copies files between a modules nonvolatile memory and a smart card. It can be used to back up and restore files that are stored in NVRAM. Files you can back up and restore are data files stored in NVRAM by an SEE program and NVRAM-stored keys. See the Operator Guide for more details. Do not store keys in NVRAM unless you must do so to satisfy regulatory requirements. Note nCipher introduced NVRAM key storage only for users who must store keys within the physical boundary of a module to comply with regulatory requirements. NVRAM-stored keys provide no additional security benefits and their use exposes your Administrator Card Set to increased risk. Storing keys in nonvolatile memory also reduces loadbalancing and recovery capabilities. Because of these factors, nCipher recommends you always use standard security world keys unless explicitly required to use NVRAM-stored keys. To use nvram-backup you specify an action and, optionally, the location of the files to be acted on. Available actions are list, copy and delete. You can list the contents of, and delete files from, a modules NVRAM, and copy files from NVRAM to a smart card. You can list files on a smart card and copy from a card to a modules NVRAM. You cannot use nvram-backup to delete files from a smart card. Note Use the bulkerase utility to format cards for use with nvram-backup. If you are using a FIPS 140-2 level 3 compliant security world, you will be prompted for an Administrator Card or Operator Card from the security world to authorize copying of files to or from NVRAM and deletion of files from the modules NVRAM. When you copy files to a modules NVRAM or delete files from NVRAM, you are required to insert a quorum of Administrator Cards for NVRAM authentication.

nShield/payShield Administrator Guide Windows v5.5

266

15 nShield Administrator Utilities

nvram-backup

Usage
C:\nfast\bin\nvram-backup.exe -l|--list -M|--from-module|-S|--from-smartcard [-m|-module=MODULE] [-s|--slot=SLOT] [-f|--force] [-v|--verbose] [-x|--hex] [FILES]

C:\nfast\bin\nvram-backup.exe -c|--copy -M|--from-module|-S|--from-smartcard [-m|-module=MODULE] [-s|--slot=SLOT] [-f|--force] [-v|--verbose] [-x|--hex] [FILES]

C:\nfast\bin\nvram-backup.exe -d|--delete -M|--from-module [-m|--module=MODULE] [-s|-slot=SLOT] [-f|--force] [-v|--verbose] [-x|--hex] [FILES]]

Help options
-h, --help

These options display help for nvram-backup.exe.


-V, --version

These options display the version number for nvrambackup.exe. -u, --usage

These options display a brief usage summary for nvrambackup.exe.

Action selection options


-l, --list

These options list files either on a modules NVRAM or on a smart card. By default nvram-backuplists the contents of the modules NVRAM.

nShield/payShield Administrator Guide Windows v5.5

267

15 nShield Administrator Utilities

nvram-backup

-c, --copy

These options copy files between a modules NVRAM and a smart card. You cannot copy from a modules NVRAM to a smart card those files whose ACL prohibits copying. Copying is prevented by use of the --no-copy option in the nvram-sw utility described in nvram-sw on page 272.
-d, --delete

These options delete files from a modules NVRAM. You cannot use nvram-backup to delete files from a smart card. If you attempt to use nvram-backup to delete files from a smart card, a message displays and nvram-backup terminates..

Transfer direction options


-M, --from-module

These options read files from a modules NVRAM for copying to a smart card or for listing, or deletes files from the modules NVRAM.
-S, --from-smartcard

These options reads files from a smart card for copying to a modules NVRAM or for listing.

Module selection options


-m, --module=MODULE

These options specify the module for nvram-backup to use. The default is 1.

nShield/payShield Administrator Guide Windows v5.5

268

15 nShield Administrator Utilities

nvram-backup

-s, --slot=SLOT

These options identify the slot on the selected module for the specified nvram-backup action. The default is 0. You do not need to specify a slot when listing the contents of, or deleting files from, a modules NVRAM.

File selection option


FILES This specifies the files for nvram-backup to copy, list or delete. If you do not specify a file, nvram-backup performs the action on all available files. Wildcards are permitted in the file selection option, for example b* to select all NVRAM-stored keys. For information on identifying file types by their FileIDs, see nvram-sw on page 272.

General options
-f, --force

These options force nvram-backup to delete or overwrite a file without requesting confirmation.
-v, --verbose

These options provide verbose output.


-x, --hex

These options specify that hex notation is used for the file selection option.
--no-length

When used with the --list option, the --no-length option specifies that file lengths are not printed.

nShield/payShield Administrator Guide Windows v5.5

269

15 nShield Administrator Utilities

nvram-backup

Output
To list the contents of the default modules NVRAM, use the command:
C:\nfast\bin\nvram-backup.exe --list

nvram-backup displays file information in the following format:


File ID (hex) ------------725178c71ba5cf959318fc 625178c71ba5cf959318fc 72d2fb7c9d0c58f6424855 62d2fb7c9d0c58f6424855 File ID (ASCII) --------------File Length -----------

In this example, four files are stored in the modules NVRAM, two NVRAM-stored keys and their associated recovery information. For information on identifying file types by their File IDs, see nvram-sw on page 272. To obtain a listing of the contents of a modules NVRAM with further information, including file size, use the nvram-sw utility. To back up NVRAM-stored keys from the default module to a smart card, use the command:
C:\nfast\bin\nvram-backup.exe --copy --from-module b*

If you have a FIPS 140-2 level 3 compliant security world, you must provide authorization to back up files stored on NVRAM. nvrambackup prompts you to insert a smart card from this security world for authorization.

nShield/payShield Administrator Guide Windows v5.5

270

15 nShield Administrator Utilities

nvram-backup

1.

If prompted, insert a smart card from the current security world. When nvram-backup has obtained authorization, it prompts you to insert a card into the module and slot you specified for nvrambackup actions.

2.

Insert the smart card to use and press Enter .


nvram-backup copies the specified file(s) and terminates.

You can check the success of the command by listing the contents of the smart card. Use the command:
C:\nfast\bin\nvram-backup.exe --list --from-smartcard

To delete NVRAM-stored keys from the default module, use the command:
C:\nfast\bin\nvram-backup.exe --delete *b

If you have a FIPS 140-2 level 3 compliant security world, you must provide authorization to delete files from the modules NVRAM. nvram-backup prompts you to insert a smart card from this security world for authorization. 1. If prompted, insert a smart card from the current security world. Deleting files from a modules NVRAM requires authentication and you are prompted to insert Administrator Cards for NVRAM authentication. 2. Insert the required number of cards, each one in turn, into the authentication slot. When authentication is complete, for each file that matches the specified criteria, nvram-backup prompts for confirmation. 3. Input yes to delete a file or no to retain it in NVRAM.

When all files have been listed for confirmation, nvram-backup terminates.

nShield/payShield Administrator Guide Windows v5.5

271

15 nShield Administrator Utilities

nvram-sw

nvram-sw
The nvram-sw utility views and modifies NVRAM areas.

Usage
C:\nfast\bin\nvram-sw.exe -a|--alloc [-m|--module=MODULE] [-b|--bytes=BYTES] [-n|-nvram-id=ID] [-k|--key=APPNAME,IDENT][--no-copy]

C:\nfast\bin\nvram-sw.exe -d|--delete [-m|--module=MODULE] [-n|--nvram-id=ID]

C:\nfast\bin\nvram-sw.exe -w|--write [-m|--module=MODULE] [-f|--file=FILE]

C:\nfast\bin\nvram-sw.exe -r|--read [-m|--module=MODULE] [-f|--file=FILE]

C:\nfast\bin\nvram-sw.exe -c|--delete-noadmin [-m|--module=MODULE] [-n|--nvram-id=ID]

C:\nfast\bin\nvram-sw.exe -i|--acl [-m|--module=MODULE] [-n|--nvram-id=ID]

C:\nfast\bin\nvram-sw.exe -l|--list [-m|--module=MODULE]

C:\nfast\bin\nvram-sw.exe -a|--alloc [-m|--module=MODULE] [-b|--bytes=BYTES] [-n|-nvram-id=ID] [-k|--key=APPNAME,IDENT][--no-copy]

Help options
-h, --help

These options display help for nvram-sw.exe.

nShield/payShield Administrator Guide Windows v5.5

272

15 nShield Administrator Utilities

nvram-sw

-V, --version

These options display the version number for nvram-sw.exe.


-u, --usage

These options display a brief usage summary for nvramsw.exe.

Action selection options


-a, --alloc

These options allocate a new NVRAM area on the module specified in MODULE. An Administrator Card Set must be inserted to perform this action.
-d, --delete

These options delete the NVRAM area on the module specified in MODULE. An Administrator Card Set must be inserted to perform this action.
-w, --write

These options write data to the NVRAM area on the module specified in MODULE. The data is written from the file specified in FILE, if present. Otherwise, it is written from stin. If the ACL of the NVRAM area requires it, an Operator Card Set must be inserted to perform this action. This action may not be permitted by the ACL of the NVRAM area.
-r, --read

These options read data from the NVRAM area on the module specified in MODULE. The data is written to the file specified in FILE, if present. Otherwise it is written to stdout. If the ACL of the NVRAM area requires it, an Operator Card Set must be inserted to perform this action. This action may not be permitted by the ACL of the NVRAM area.

nShield/payShield Administrator Guide Windows v5.5

273

15 nShield Administrator Utilities

nvram-sw

-c, --delete-noadmin

These options delete the NVRAM area on the module specified in MODULE when no Administrator Card Set is required. If the ACL of the NVRAM area requires it, an Operator Card Set must be inserted to perform this action.
-i, --acl

These options display the ACL of the NVRAM area on the module specified in MODULE. If the ACL of the NVRAM area requires it, an Operator Card Set must be inserted to perform this action.
-l, --list

These options list the entire contents of the NVRAM.

General options
-m, --module=MODULE

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


-v, --verbose

These option provides verbose output.


-x, --hex

These option specify that hex notation is used for the ID value supplied to the --nvram-id option.

Action specific options


-b, --bytes=BYTES

These option specify the number of bytes to allocate for -alloc or to read for --read. The default is 100.

nShield/payShield Administrator Guide Windows v5.5

274

15 nShield Administrator Utilities

nvram-sw

-n, --nvram-id=ID

These option specify the identifier of the NVRAM file for all actions except --list. The default is test-file
-f, --file=FILE

These option specify the file to be read or written for the -read and --write options. If this option is not specified for these actions, stdin or stdout is used by default.
-k, --key=APPNAME, IDENT

These option specify a key during the --alloc action. This key is required for all subsequent --read or --write actions on the NVRAM area.
--no-copy

This option used with the --alloc option allocates a file with an ACL that does not allow copying.

Identifying files
Files created by nCipher security world tools often have a FileID that consists of a character identifying the type followed by a M_ShortHash. You can use this information to identify the type of files stored in NVRAM and for specifying types of files for use with an nCipher security world utility.

nShield/payShield Administrator Guide Windows v5.5

275

15 nShield Administrator Utilities

nvram-sw

nCipher uses following identifying characters:


File type
0x1

Description
Counter for a MSCAPI key-exchange key NVRAM-counted use limit. The hash is of the MSCAPI container. Counter for a MSCAPI signature key NVRAM-counted use limit. The hash is of the MSCAPI container. Old PKCS #11 token identifier. If you have such tokens present, contact Support at nCipher. Working blob for a NVRAM-stored key. Recovery blob for a NVRAM-stored key. 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. Old PKCS #11 token identifier. If you have such tokens present, contact Support at nCipher.

0x2

0x53 (S)

0x62 (b) 0x72 (r) 0x74 (t)

0x80 (z)

nCipher may define further file types in future, but the first byte is always in the range 0-127 (top bit clear). nCipher recommends that third party developers use FileIDs with a first byte in the range 128255 (top bit set). nCipher also uses the following specific FileIDs:

nShield/payShield Administrator Guide Windows v5.5

276

15 nShield Administrator Utilities

nvram-sw

FileID (hex)
5761726e 74496448 6c7475

FileID (ascii)
WarntIdHltu

Description
Smart card file created by the nCipher Warranting server. Contains the hash of LTID. Smart card file created by the nCipher Warranting server. Contains a blob of KID under LTID. NVRAM file. This is the default FileID for nvram-sw.

5761726e 74496442 6c6f62

WarntIdBlob

74657374 2d66696c 650000

test-file

nShield/payShield Administrator Guide Windows v5.5

277

15 nShield Administrator Utilities

payshield-config

payshield-config
The payshield-config utility modifies the payShield installations settings. The utility must be run immediately after running payshieldinstall or payshield-install - -retarget to complete the setup or retargeting of the payShield installation. This utility can be used to enable the AcquirePIN Clear PIN functionality. It uses its own key role which is incompatible with other payShield PIN functions (KeyRole_AWK). Use of this function is not recommended as best practice. You should only enable the AcquirePIN function if the payShield installation will be running in a physically secure location with trusted operators and network at all times. Any PIN entered via the AcquirePIN function cannot be considered to be secured by the module. Using the same PIN and PAN combination for both AcquirePIN and PVV/Offset PIN operations may therefore negate the security of PVV/Offset. This utility can also be used to enable IBM PIN functions and unattended key import and export. Enabling these functions may reduce the security of the system and is not recommended. If any of these functions are needed, the proper restrictions should be applied. If you are not sure whether you need these functions, or do not know what the proper restrictions are, please contact nCipher Support.

Usage
payshield-config.exe [-h|- -help][-v|- -version][-u|- -usage] [{-m|--module}=MODULE] [{-s|- -slot}=SLOT] [{-c|--configfile}=FILENAME] [{-d|--dump-config}=FILE] [-helpfeatures]PSINAME FEATURES

-m, --module=MODULE

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

nShield/payShield Administrator Guide Windows v5.5

278

15 nShield Administrator Utilities

payshield-config

-s, --slot=SLOT

These options identify the slot to use. The default is 0.


-c, --configfile=FILENAME

These options specify the configuration file to insert into the PUD. If the option is not used, then a default configuration is written to the PUD, unless one is already present.
-d, --dump-config=FILENAME

These options dump the configuration file that is stored in the PUD.
--help-features

This option describes the syntax for non-interactive feature selection, including a list of features that can be specified in the comma-separated list FEATURES.

Altering the Installation Settings


The following settings can be changed using the payshield-config utility: which payments functions are enabled or disabled acceptable PINBlock formats for PIN operations acceptable import and export formats for key roles.

nShield/payShield Administrator Guide Windows v5.5

279

15 nShield Administrator Utilities

payshield-info

payshield-info
The payshield-info utility displays information about a specified payShield installation.

Usage
payshield-info.exe [-i|--info][-k|--keys][-n|--name]=keynamePSINAME

General options
-V, --verbose

These options display verbose key details, where applicable.


-s, --sort=KEY

These options select the output sort mode for the --keys and
--roles modes.

Operation mode options


-i, --info

These options display basic information about the PSI.


-k, --keys

These options display keys for the named PSI.


-f, --features

These options display the features enabled in the PUD.


-c, --config

These options dumpt the configuration files stored in the PUD.

nShield/payShield Administrator Guide Windows v5.5

280

15 nShield Administrator Utilities

payshield-info

-n, --name=keyname

These options display detailed information about the named key.


-r, --role=keyrole

These options display all the keys in the payShield installation named PSINAME that have the role specified in keyrole (for example, PVKP). To view keys for which role information is unavailable, use --role=unknown.

Keywords
PSINAME The name of the payShield installation to provide information about.

Output
The following information is displayed: The name of the payShield installation The version of the SEE machine in use The K and N values of the Master Card Set The K and N values of the Key Establishment Card Set The hash of the Master key The hash of the Key Establishment Key The maximum possible number of loaded keys The flags that are set on the payShield installation

nShield/payShield Administrator Guide Windows v5.5

281

15 nShield Administrator Utilities

payshield-info

For example:
PSI Name: qapsi EMVSM version: 1.0.6+ 2003-01-13 16:55:51. jgeater Master Key Hash: d42e1791a4e5ea5021444e521bb2c650093efd4d Estab Key Hash: a06fe51b52725b344dade13a59466bdb77400c1f Max Keys: 1000 Flags (0x3e0000): TotallyInsecure InsecureImport InsecureDebug SmartcardImport UnrestrictedImport Cardsets: allocated 0053BCD8 Estab CardSet: 1/1 (aaa002b568604e5bbc3a63dcdb0209cd478f317b) Master CardSet: 1/1 (b9a595b21446ca82dee93a482d60848ec0f1b5dd)

nShield/payShield Administrator Guide Windows v5.5

282

15 nShield Administrator Utilities

payshield-install

payshield-install
The payshield-install utility is used to configure a security world specifically for the requirements of your payShield installation.

Usage
payshield-install.exe [--master-quorum=K/N --estab-quorum=K/N[{-m|--module}=MODULE] [{s|- -slot}=SLOT] [{-A|- -adminslot}=ADMIN_SLOT] [{-L|--max-loaded-keys}=NUM] [--nonfips-temporarykeys] [--totally-insecure] [--override-keyhash-check] [-D|- -allowinsecure-debug] [-S|--allow-smartcard-import] [-I|- -allow-insecure-import] [-U|- allow-unrestricted-import] [--require-estab-always] [--retarget-see-machine] [-acquirepin-wait=INT] PSINAME KEYHASH

Security options
--master-quorum=K/N

This option specifies the K-of-N sharing parameters for the Master card set. The default is 3 of 5 (3/5).
--estab-quorum=K/N

This option specifies the K-of-N sharing parameters for the Key Establishment card set. The default is 2 of 4 (2/4).
-m, --module=MODULE

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


-s, --slot=SLOT

These options specify the slot to use. The default is 0.


-A, --adminslot=SLOT

These options specify the slot to use for loading FIPS and FTO authorizations. The default is 0.

nShield/payShield Administrator Guide Windows v5.5

283

15 nShield Administrator Utilities

payshield-install

-L, --max-loaded-keys=NUM

These options specify the maximum number of keys the SEE machine is allowed to load (default=1000).
--non-fips-temporarykeys

This options prohibits the passing of temporary keys through the hardware security modules firmware.
--totally-insecure

This option allows you to set the --allow-insecure-debug and --allow-insecure-imports options, which make the installation totally insecure.
--override-keyhash-check

This option overrides the key hash check against known payShield SEE machine signing key hashes.
-D, --allow-insecure-debug

These options allow the generation of insecure debug. They require you to have also set the --totally-insecure option.
-S, --allow-smartcard-imports

These options allow the import of keys from smart cards.


-L, --allow-insecure-imports

These options allow the importing of keys non-interactively. They require you to have also set the --totally-insecure option.
-L, --allow-insecure-imports

These options allow the importing of keys non-interactively. They require you to have also set the --totally-insecure option.

nShield/payShield Administrator Guide Windows v5.5

284

15 nShield Administrator Utilities

payshield-install

When these options are set, you can use the payShield/Verifone key import method to import nonpayShield keys into your security world. These keys are described as unrestricted because they are imported as module protected and their encrypt/decrypt ACL permissions are not restricted by a certifier or SEE world.
-U, --allow-unrestricted-imports

These options allow the importing of keys with ACLs that allow unrestricted use.
--require-estab-always

This option requires establishment cards to be presented for unrestricted key imports. This is not a security feature.
--acquirepin-wait=INT

This option forces at least INT centiseconds of elapsed time between AcquirePIN operations. The default is 0 (that is, no rate limiting). The delay rate for AcquirePIN is enforced separately for each module. If you have two nShield modules, then two AcquirePIN operations are allowed in the specified time period.

Keywords
PSINAME

This is the payShield installation name, which must be of 16 or fewer lowercase alphanumeric characters.
KEYHASH

This is the hash of the nCipher SPP SEE machine signing key.

nShield/payShield Administrator Guide Windows v5.5

285

15 nShield Administrator Utilities

postrocs

postrocs
The postrocs utility performs clean-up tasks after key-xfer-im has been used to transfer keys that protect PKCS #11 objects.

Usage
C:\nfast\bin\postrocs [-m|--module=MODULE] [-s|--slot=SLOT]

Help options
-h, --help

These options display help for postrocs.exe.


-V, --version

These options display the version number for postrocs.exe.


-u, --usage

These options display a brief usage summary for postrocs.exe.

Options
-m, --module=MODULE

These options specify the target module for the key transfer. The default is 1.
-s, --slot=SLOT

These options specify the target slot for the key transfer. The default is 0.

nShield/payShield Administrator Guide Windows v5.5

286

15 nShield Administrator Utilities

ppmk

ppmk
This utility allows you to manage softcards. It can be used to perform the following tasks: listing softcards creating a new softcard checking or changing a softcards pass phrase recovering a softcards pass phrase deleting a softcard.

Usage
C:\nfast\bin\ppmk.exe --new [-r|-R] NAME C:\nfast\bin\ppmk.exe -l C:\nfast\bin\ppmk.exe -icCpr|--delete [PRELOAD-OPTIONS] NAME|IDENT

NAME

This option specifies the name of a new or existing softcard.


IDENT

This option specifies the identifier of an existing softcard


-n, --new

These options create a new softcard. When creating a new softcard with these options, the -r/--recover options make the pass phrase of the new softcard recoverable, while the -R/-non-recoverable options make it unrecoverable.
-l, --list

These options list all softcards in the current security world.

nShield/payShield Administrator Guide Windows v5.5

287

15 nShield Administrator Utilities

ppmk

-i, --info NAME|IDENT

These options show the details of the softcard specified by


NAME or IDENT. -c, --check NAME|IDENT

These options check the pass phrase of the softcard specified by NAME or IDENT.
-C, --change NAME|IDENT

These options change the pass phrase of the softcard specified by NAME or IDENT.
-p, --preload [PRELOAD-OPTIONS]

This option preloads a softcard. PRELOAD-OPTIONS are as follows:


-m, --module=MODULE preloads a softcard on the

specified module number. The default value for


MODULE is all.

-r, --recover

-f, --preload-file=FILE specifies the location of an

alternative loaded objects file.

These options allow you to recover the pass phrase of a softcard (if it was created with a recoverable pass phrase).
--recoverable

This options specifies that the pass phrase of a new softcard is to be recoverable; this is the default, so it is not normally necessary to specify this option in order to create a softcard with a recoverable pass phrase. The pass phrase recovery key Krp be loaded in order to create a softcard with a recoverable pass phrase.

nShield/payShield Administrator Guide Windows v5.5

288

15 nShield Administrator Utilities

ppmk

-R, --non-recoverable

These options specify that the pass phrase of a new softcard is to be non-recoverable.
--delete NAME|IDENT

This option deletes the softcard specified by NAME or


IDENT.

nShield/payShield Administrator Guide Windows v5.5

289

15 nShield Administrator Utilities

preload

preload
The preload command-line utility enables keys to be loaded onto a module before an application is run. The application can be run immediately in the same session or the first session can be paused and the application can be run in a separate session. Additional keys can be loaded while a session is running. For applications that do not support K-of-N Operator Card Sets, preload enables K-of-N Operator Card Sets and module-protected keys to be loaded before the application is run. You can use the
preload command to preload K-of-N Operator Card Sets before

running PKCS #11 applications. Some command-line options may cause preload to function interactively by prompting for Operator Cards. Note Currently, preload can be used only with command-line utilities.

Usage
C:\nfast\bin\preload.exe [-m MODULE|--module=MODULE] [-c IDENT|--cardset=IDENT] [-cardset-name=NAME] [-s IDENT|--softcard=IDENT] [-o|--any-one] [-i|--interactive] [-A APP|--appname=APP] [-K PATTERN|--key-ident=PATTERN] [-n PATTERN| --name-pattern=PATTERN] [--name-exact=NAME] [-M|--module-prot] [--no-cardset-keys] [--admin=NAME] [-F|--requirefips] [-N|--no-fips] [-f PRELOADFILE|--preload-file=PRELOADFILE] [-R|--reloadeverything] | pause | exit

Module selection options


-m MODULE, --module=MODULE

These options select the module (where MODULE is a module number) onto which keys are to be loaded. Repeating the option with different values for MODULE enables a number of selected modules to be used. By default, preload loads keys on all usable modules.

nShield/payShield Administrator Guide Windows v5.5

290

15 nShield Administrator Utilities

preload

Card set selection options


Note The current release of the preload command-line utility cannot load softcards; use the ppmk command-line utility to load softcards (see ppmk on page 287). However, the preload command can load softcard-protected keys; see Key selection options on page 292.
-c IDENT, --cardset=IDENT

These options specify that all Operator Card Sets that match IDENT are to be loaded. The IDENT variable can be the hash or the name of a card set; the preload command tries to guess whether IDENT is a hash or a name based on the form you supply. If you definitely want to preload a named card set, use the --cardset-name=NAME option instead. Use KeySafe or the nfkminfo command-line utility to identify keys and cards that are used by particular applications. For further information, see the appropriate Operator Guide for your module. Card set patterns or names are treated as substrings.
--cardset-name=NAME

This option specify an Operator Card Set with the given name NAME to be loaded.
-o, --any-one

This option loads a single Operator Card Set and then stops.
-i, --interactive

This option causes preload to load Operator Card Sets interactively until you tell it to stop.

nShield/payShield Administrator Guide Windows v5.5

291

15 nShield Administrator Utilities

preload

Key selection options


Note If you specify keys and do not explicitly select Operator Card Sets with
--cardset, or use --module-prot, then preload loads only the Operator

Card Sets that are required by the specified keys. By default, if no key selection options are used, preload loads all keys on the loaded Operator Card Set(s) and, if --module-prot is specified, all moduleprotected keys.
-A APP, --appname=APP

These options specify the application to be used by a subsequent --key-ident or --name-exact options. You can set multiple instances of the --appname option to specify more than one application. Examples of APPNAME include:
custom embed hwcrhk netscape simple ssleay

-K PATTERN, --key-ident=PATTERN

These options load all keys whose ident includes or matches PATTERN for the application previously specified by APP. PATTERN is treated as a substring. You can set multiple instances of these options to load keys that match more than one pattern.
-K, --key-ident=PATTERN

These options load all keys with an ident that includes or matches PATTERN for the application previously specified by APP. You can set multiple instances of the --key-ident option to load more than one key. Use KeySafe or the

nShield/payShield Administrator Guide Windows v5.5

292

15 nShield Administrator Utilities

preload

nfkminfo command-line utility in order to identify keys that

are used by particular applications. For further information, see the appropriate Operator Guide for your module.
-n PATTERN, --name-pattern=PATTERN

These options load all keys (for the APP specified by --appname) whose name includes or matches PATTERN. PATTERN is treated as a substring. You can set multiple instances of these options to load keys that match more than one pattern. If you want to load a particular named key, use the
--name-exact=NAME option instead. --name-exact=NAME

This option loads the key whose name is specified by NAME for the APP specified by --appname.
-s IDENT, --softcard=IDENT

These options load all keys protected by softcards matching


IDENT. The IDENT variable can be the hash or the name of a softcard; the preload command tries to guess whether IDENT is a hash or a name based on the form you supply.

Note

The current release of the preload command-line utility can only load softcard-protected keys, not softcards themselves. To load softcards, use the ppmk command-line utility; see ppmk on page 287. If you definitely want to preload a named softcard, use the
--softcard-name=NAME option instead.

Use the ppmk or nfkminfo command-line utilities to identify keys and softcards that are used by particular applications. For further information, see the appropriate Operator Guide for your module. Softcard patterns or names are treated as substrings.

nShield/payShield Administrator Guide Windows v5.5

293

15 nShield Administrator Utilities

preload

--softcard-name=NAME

This option loads all keys protected by softcards matching NAME. Note The current release of the preload command-line utility can only load softcard-protected keys, not softcards themselves. To load softcards, use the ppmk command-line utility; see ppmk on page 287. Use the ppmk or nfkminfo command-line utilities to identify keys and softcards that are used by particular applications. For further information, see the appropriate Operator Guide for your module. Softcard patterns or names are treated as substrings.
-M, --module-prot

These options load module-protected keys in addition to any keys specified by other options.
--no-cardset-keys

This option specifies that keys protected by the requested Operator Card Sets are not automatically loaded.
--admin=KEYS

This option loads the administrator keys specified by KEYS; to load more than one administrator key, the value of KEYS can be a comma-separated list, or you can. specify all to load all administrator keys. Allow administrator keys are: NSO, M, RA, P, NV, RTC, FIPS, MC, RE, DSEE, and FTO. Note When using preload to load non-persistent tokens, you must ensure that you have enough remaining Operator Cards in order to load the token onto the final module. Usually, this means you need one or more cards than you have modules, depending on the circumstances. For example, if you have 4 modules and K is 3, then N must be at least 6 so that there are at least 3 cards remaining to load the token onto the final module.

nShield/payShield Administrator Guide Windows v5.5

294

15 nShield Administrator Utilities

preload

FIPS options
-F, --require-fips

These options specify that FIPS authorization is required.


-N, --no-fips

These options specify that FIPS authorization must never be loaded. The default is to load FIPS authorization if possible but not to fail if loading FIPS authorization is not possible.

Loading options
-f PRELOADFILE, --preload-file=PRELOADFILE

These options specify a preloaded objects file to be used.


-R, --reload-everything

These options specify the reloading of keys and tokens that are already loaded.

Output examples
If you want to load keys from a number of Operator Card Sets in module 2 and use them immediately in an application, for example, with nfkminfo, give the following command:
C:\nfast\bin\preload -R -m 2 nfkminfo

If there is no card in the specified module, preload displays the following message:
Loading cardset(s): Module 2 slot 0: empty Module 2 slot 2: empty Insert/change card(s) (or change module mode).

nShield/payShield Administrator Guide Windows v5.5

295

15 nShield Administrator Utilities

preload

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


Loading cardset(s): Module 2 slot 0: empty Module 2 slot 2: empty Module 2 slot 0: 'pt2' #1 Module 2 slot 0: Enter passphrase:

Enter the appropriate pass phrase, and preload displays:


Loading cardset(s): Module 2 slot 0: empty Module 2 slot 2: empty Module 2 slot 0: 'pt2' #1 Module 2 slot 0:- passphrase supplied - reading card Module #2 Slot #0: Remove card.

If you insert a card that has no pass phrase, preload displays:


Loading cardset(s): Module 2 slot 0: empty Module 2 slot 2: empty Module 2 slot 0: 'pt2' #1 Module 2 slot 0:- passphrase supplied - reading card Module 2 slot 0: empty Module 2 slot 0: 'ct' #1 Module 2 slot 0: Read this card? (press Return)

nShield/payShield Administrator Guide Windows v5.5

296

15 nShield Administrator Utilities

preload

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


Loading cardset(s): Module 2 slot 0: empty Module 2 slot 2: empty Module 2 slot 0: 'pt2' #1 Module 2 slot 0:- passphrase supplied - reading card Module 2 slot 0: empty Module 2 slot 0: 'ct' #1 Module 2 slot 0:- confirmed - reading card Module #2 Slot #0: Remove card.

Being finished, now press Ctrl - D , and preload displays:


Loading cardset(s): Loaded seeconf testconf key (DES3) on modules 2 Loaded seeinteg testinteg key (RSAPrivate) on modules 2 Loaded simple cs key (DES3) on modules 2 Loaded simple test12 key (RSAPrivate) on modules 2 Loaded simple test3 key (RSAPrivate) on modules 2 Loaded simple test4 key (RSAPrivate) on modules 2 Loaded simple test5 key (RSAPrivate) on modules 2 Loaded simple test6 key (RSAPrivate) on modules 2 Loaded simple test7 key (RSAPrivate) on modules 2 Loaded simple test8 key (RSAPrivate) on modules 2 Loaded simple test9 key (RSAPrivate) on modules 2 Executing nfkminfo

To preload a specific key with an ident of mykey for the application seeconf on all modules, give the following command:
C:\nfast\bin\preload -A seeconf -K mykey pause

nShield/payShield Administrator Guide Windows v5.5

297

15 nShield Administrator Utilities

preload

The preload command then displays the following message:


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

Insert a card in module 1, and preload displays:


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

Enter the appropriate pass phrase, and preload displays:


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

Remove the card, and preload displays:


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

nShield/payShield Administrator Guide Windows v5.5

298

15 nShield Administrator Utilities

preload

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


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

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


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

Enter the appropriate pass phrase, and preload displays:


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

nShield/payShield Administrator Guide Windows v5.5

299

15 nShield Administrator Utilities

preload

You can use the preloaded keys and tokens when running commands in a separate command window. For example, to load keys for generatekey that were preloaded in the preceding example, open second command window and give the command:
C:\nfast\bin\preload generatekey hwcrhk

In such an example, the preloaded keys and cards remain loaded at least until the open preload -A seeconf -K mykey pause command is terminated in the first window.

nShield/payShield Administrator Guide Windows v5.5

300

15 nShield Administrator Utilities

racs

racs
The racs utility creates a new Administrator Card Set to replace a set that was created with the new-world utility.See Replacing an Administrator Card Set with racs on page 225.

Usage
racs [-m|--module=MODULE]

Options
-m, --module=MODULE

These options specifies the ModuleID to use.

nShield/payShield Administrator Guide Windows v5.5

301

15 nShield Administrator Utilities

rfs-setup

rfs-setup
This utility creates a default remote file system on the client. You run rfs-setup when you first configure a client. See Setting up client cooperation on page 53 for details of client configuration.

Usage
C:\nfast\bin\rfs-setup.exe C:\nfast\bin\rfs-setup.exe C:\nfast\bin\rfs-setup.exe C:\nfast\bin\rfs-setup.exe [-c|--configfile=FILENAME] [-f|--force] <ADDRESS> module_ESN keyhash --gang-client module_ip_address module_ESN keyhash --gang-client --write-noauth module_IP_address

Options
-c, --configfile=FILENAME

These options specify a configuration file named


FILENAME to use. -f, --force

These options specify that any existing remote file system is to be overwritten.
--gang-client

This option configures the remote file system to accept connections from a cooperating client. For this option, module_IP_address is the IP address of the cooperating client while module_ESN and keyhash are respectively the electronic serial number (ESN) and key hash for the local module.You must supply values for module_ESN and keyhash when using the --gang-client option unless you also pass the --write-no-auth option.

nShield/payShield Administrator Guide Windows v5.5

302

15 nShield Administrator Utilities

rfs-setup

--write-noauth

This option allows cooperating clients to access the remote file system without HKNETI authorization. You do not need to supply module_ESN or keyhash with this option. nCipher does not recommend using the --write-noauth option except on completely secure networks.

module_IP_address

This option specifies the IP address of the module.


module_ESN

This option specifies the ESN of the module.


keyhash

This option specifies the HKNETI (key hash) of the module. You can obtain the ESN and HKNETI of the module from the modules front panel. You can also obtain it with the anonkneti utility. See anonkneti on page 227 for details.

nShield/payShield Administrator Guide Windows v5.5

303

15 nShield Administrator Utilities

rfs-sync

rfs-sync
This utility synchronises the kmdata between a cooperating client and the remote file system it is configured to access. It should be run when a cooperating client is initialised in order to retrieve data from the remote file system and also whenever a client needs to update its local copy of the data or, if the client has write access, to commit changes to the data. See Chapter 3: Getting the module working for more details about client cooperation.

Usage
C:\nfast\bin\rfs-sync.exe [-U|--update] [-c|--commit] [-s|--show] [--remove] [--setup [setup_options] ip_address]

Options
-U, --update

These options update local key-management data from the remote file system. Note If a cooperating client has keys in its kmdata/local directory that are also on the remote file system, if these keys are deleted from the remote file system and then rfs-sync --update is run on the client, these keys remain on the client they are until manually removed.
-c, --commit

These options commit local key-management data changes to the remote file system.
-s, --show

These options display the current synchronisation configuration.

nShield/payShield Administrator Guide Windows v5.5

304

15 nShield Administrator Utilities

rfs-sync

--setup

This option sets up a new synchronisation configuration. Specifics of the configuration can be altered using setup_options as follows:
-a, --authenticate

These set-up options specify use of KNETI authentication. This is the default.
--no-authenticate

This set-up option specifies that KNETI authentication should not be used.
-m, --module=module

These options select which module to use for KNETI authorisation. The default is module 1. This option can only be used with with the --authenticate option.
-p, --port=port

These options specify the port on which to connect to the remote file system. The default is 9004.
ip_address

This option specifies the IP address of the remote file system.


--remove

This option removes the synchronisation configuration. The rfs-sync command also has additional administrative options for examining and removing lock files that have been left behind by failed rfs-sync --commit operations. Using the --who-has-lock option displays

nShield/payShield Administrator Guide Windows v5.5

305

15 nShield Administrator Utilities

rfs-sync

the task ID of the lock owner. As a last resort, you can use the rfs-sync command-line utility to remove lock files. In such a case, the --killlock option forcibly removes the lock file.

nShield/payShield Administrator Guide Windows v5.5

306

15 nShield Administrator Utilities

rtc

rtc
The rtc utility reads the time from a modules onboard real-time clock. It can also be used to set the clock.

Usage:
rtc [[-g|--get-clock]|[-t|--set-clock [-a|--no-admin-keys] [-A|--adjust]]] [-m|-module=MODULE] TIME

Action selection options


-g, --get-clock

These options tell rtc to read the modules clock time. This is the default if no action option is specified.
-t, --set-clock

These options tell rtc to read the modules s clock time to TIME.

Clock setting options


-a, --no-admin-keys

These options tell rtc not to read Administrator cards.


--adjust

This option tells rtc to calibrate the clock drift.

Module selection option


-m, --module=MODULE

These options tell rtc to read or write the clock of the module MODULE. If MODULE is not specified, the default is 1.

nShield/payShield Administrator Guide Windows v5.5

307

15 nShield Administrator Utilities

rtc

Reading the clock


Use the command:
rtc [-g|--get-clock] [-m|--module=MODULE]

In this command:
--get-clock if used explicitly tells rtc to set the clock. --module=MODULE tells rtc to set the clock and adjust the drift

rate.
rtc returns a message similar to this:
time on module 1 is 2001-03-21 12:33:12

Note

The rechargeable back-up battery in some nShield modules (used to maintain RTC operation when the module is unpowered) can last as long as two weeks without recharging. If the module is without power for longer than this, the battery is discharged and RTC time is lost; no other nonvolatile data is lost if this occurs. In such a case, however, attempts to read the clock (such as with ncdate or rtc) return a BadTokenData error status. You can resolve this by resetting the clock and leave the module powered up for at least 10 hours to recharge the battery to recharge.

Setting the clock


Use the command:
rtc [[-t|--set-clock]|[-A|--adjust]] [-a|--no-admin-keys] [-m|--module=MODULE] [TIME]

In this command:
--set-clock tells rtc to set the clock. --adjust tells rtc to set the clock and adjust the drift rate.

nShield/payShield Administrator Guide Windows v5.5

308

15 nShield Administrator Utilities

rtc

--no-admin-keys tells rtc not to read the Administrator Card Set. --module=MODULE specifies the ModuleID to use.

TIME is the time to which to set the clock in the form YYYY-MMDD/HH:MM:SS, where -, /, and : are arbitrary delimiter characters that can be any non-numeric character.

Unless you give the --no-admin-keys option, rtc prompts you for the number of cards required from the Administrator Card Set to enable it to set the real-time clock. If you do not specify a time, rtc uses the time from the host computer's clock. If you specify a time, rtc asks you to confirm the operation. This feature enables you to check that you have entered the time correctly.

nShield/payShield Administrator Guide Windows v5.5

309

15 nShield Administrator Utilities

slotinfo

slotinfo
The slotinfo utility returns information about the tokens that are present in a module. slotinfo can also be used to format a token.

Usage
C:\nfast\bin\slotinfo -m|--module=MODULE [-s|--slot=SLOT]

Module selection
-m, --module=MODULE

These options specify the module number of the module to be used. You must specify a module number.
-s, --slot=SLOT

These options specify the number of the slot to be used. If this option is set, slotinfo returns information about the files on the token. If, however, you do not specify --slot, slotinfo returns information about all slots.
--format

This option tells slotinfo to format the token that is currently in the slot. You must specify a slot number if you want to format a token. The token is formatted without a challenge response key. Note Use of the --format option is deprecated. If you use slotinfo with the --format option to format a token, it does not remove the card from the security world lists and cannot erase cards in FIPS 140-2 level 3 compliant security worlds.
slotinfo does not update the security world host data. If you are using

an nCipher security world:

nShield/payShield Administrator Guide Windows v5.5

310

15 nShield Administrator Utilities

slotinfo

Use createocs to format Operator Cards Use KeySafe or createocs to erase cards.

Output
slotinfo --module=1 returns information in the format:
Slot Type Token IC Flags Details #0 Smartcard present 1 A #1 Software Tkn - 0

In this output:
Type Unconnected means that the slot is a remote slot for this module, but the hardserver has failed to import it. The reason for the failure is given in the Details field.

An A in the Flags field means that the token supports token authentication in a call to format token. An R in the Flags. field means that the slot is a remote slot.

slotinfo --module=1 --slot=0 returns information in the format:


Module # slot #: Authentication key: 00000000-00000000-00000000-00000000-00000000 No data on token 3698 bytes free

slotinfo --module=1 --slot=0 --format returns:


Formatting token in module 1 slot 0: Formatted token OK

nShield/payShield Administrator Guide Windows v5.5

311

15 nShield Administrator Utilities

sppupgradekeys

sppupgradekeys
The sppupgradekeys utility upgrades keys created on older payShield installations so that they can be used with newer payShield installations. You can use the optional EXPORTFILE to specify (by name) those keys that are to be allowed to be exported in attended operations. Note This utility requires a quorum of administrator cards and must only run on a secure host.

Usage
sppupgradekeys [options] psiname [EXPORTFILE]

Options
-m, --module=MODULE

These options specify the number of the module to be used. The default is 1.
-s, --slot=SLOT

These options specify the number of the slot to be used. The default is 0.
--no-name-keys

This option prevents the names of keys being bound to their ACL. If you have already run sppupgradekeys, this will make the operation faster.

nShield/payShield Administrator Guide Windows v5.5

312

15 nShield Administrator Utilities

sppupgradekeys

Key worlds
psiname This is the name of the payShield installation that you are going to import the key into. psiname must consist of 16, or fewer, lower case alphanumeric characters. EXPORTFILE This is a file containing lines of the form:
NAME

Each line specifies, by name, a keys that can be exported.

nShield/payShield Administrator Guide Windows v5.5

313

15 nShield Administrator Utilities

stattree

stattree
The stattree utility returns the statistics gathered by the nCipher server and modules.

Usage
C:\nfast\bin\stattree [<node> [<node> [...]]]

Output
Running the stattree utility displays a snapshot of statistics currently available on the host machine. Statistics are gathered both by the hardserver (relating to the server itself, and its current clients) and by each attached module. Statistics are displayed in the form of a tree. At each node in the tree, either a set of statistics or a list of sub-categories is displayed. Each node has a label which consists of one of the following: a tag that identifies its contents as described in Node tags on page 316. a number the corresponds to an instance in the category, for example, a module identifier or a client connection identifier

Times are listed in seconds. Other numbers are integers, which are either real numbers, IP addresses, or counters. For example, a result -CmdCount 74897 means that there have been 74,897 commands submitted.

nShield/payShield Administrator Guide Windows v5.5

314

15 nShield Administrator Utilities

stattree

A typical fragment of output from stattree looks like this:


+PerModule: +#1: +ModuleObjStats: -ObjectCount 4 -ObjectsCreated 4 -ObjectsDestroyed 0 +ModuleEnvStats: -MemTotal 14389248 -MemAllocKernel 86016 -MemAllocUser 0 -CurrentTempC 39.50 -MaxTempC 39.50 -MinTempC 39.50

PerModule, ModuleObjStats, and ModuleEnvStats are node tags that identify classes of statistics. #1 identifies an instance node. ObjectCount, MemTotal, and the remaining items at the same level are statistics IDs. Each has a corresponding value.

If node is provided, stattree uses the value given as the starting point of the tree and displays only information at or below that node in the tree. Values for node can be numeric or textual. For example, to view the object counts for local module number 3:
$ stattree PerModule 3 ModuleObjStats +#PerModule: +#3: +#ModuleObjStats: -ObjectCount 6 -ObjectsCreated 334 -ObjectsDestroyed 328

nShield/payShield Administrator Guide Windows v5.5

315

15 nShield Administrator Utilities

stattree

The value of node must be a node tag; it must identify a node in the tree and not an individual statistic. Thus, the following command does not work:
$ stattree PerModule 3 ModuleObjStats ObjectCount +#PerModule: +#3: +#ModuleObjStats: Unable to convert 'ObjectCount' to number or tag name.

Node tags
These hold statistics for each module:
Category
ModuleJobStats ModulePCIStats

Contains
This tag holds statistics related to the nCipher commands handled by this module. 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. 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. Statistics for connections between clients and the hardserver. There is one node for each currently active connection. Each node has an instance number that matches the log message generated by the server when that client connected. For example, when the hardserver message is Information: New client #24 connected, the clients statistics appear under node #24 in the stattree output. 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.

ServerGlobals

Connections

PerModule

nShield/payShield Administrator Guide Windows v5.5

316

15 nShield Administrator Utilities

stattree

Category
ModuleJobStats ModulePCIStats ModuleObjStats

Contains
Statistics for the commands (jobs) processed by a module. Appears under the PerModule category. Statistics from the modules PCI host interface. Appears only on PCI-interfaced modules. Statistics for the modules Object Store, which contains keys and other resources. These statistics may be useful in debugging applications that leak key handles, for example. General statistics for the modules operating environment.

ModuleEnvStats

Statistics IDs
ID
Uptime

Value
The length of time (in seconds) since a module was last reset, the hardserver was started, or a client connection was made. The total number of commands sent for processing from a client to the server, or from the server to a module. Contains the number of commands currently being processed. The total number of replies returned from server to client, or from module to server. The total length of all the command blocks sent for processing. The total length of all the reply block received after completion. The number of times a command block was not understood when it was received. A nonzero value indicates either that the parties at each end of a connection have mismatched version numbers (for example, a more recent hardserver has sent a command to a less recent module that the module does not understand), or that the data transfer mechanism is faulty.

CmdCount

ReplyCount CmdBytes ReplyBytes CmdMarshalErrors

nShield/payShield Administrator Guide Windows v5.5

317

15 nShield Administrator Utilities

stattree

ID
ReplyMarshalErrors

Value
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. The number of client connections currently made to the server. This appears in the hardserver statistics. The maximum number of client connections ever in use simultaneously to the hardserver. This gives an indication of the peak load experienced so far by the server. The number of times the hardserver has declared a device to have failed. The hardserver provides a diagnostic message when this occurs. The number of times the hardserver has attempted to restart 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. 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. 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. 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.

ClientCount MaxClients

DeviceFails

DeviceRestarts

QOutstanding

DevOutstanding

LongOutstanding

nShield/payShield Administrator Guide Windows v5.5

318

15 nShield Administrator Utilities

stattree

ID
RemoteIPAddress HostWriteCount

Value
The remote IP address of a client who has this connection. A local client has the address 0.0.0.0. The number of write operations (used to submit new commands) that have been received by the 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. The number of times write data from the host was rejected by the module. A nonzero value may indicate that data is being corrupted in transfer, or that the hardserver/device driver has got out of sync with the modules interface. Not currently reported by the module. Attempts to write bad data to the module are reflected in HostWriteErrors. Not currently reported by the module. Write overruns are reflected in HostWriteErrors. Not currently reported by the module. Write failures due to lack of memory are reflected in HostWriteErrors. 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. 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. 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. Not currently reported by the module.

HostWriteErrors

HostWriteBadData HostWriteOverruns HostWriteNoMemory HostReadCount

HostReadErrors

HostReadEmpty

HostReadUnderruns

nShield/payShield Administrator Guide Windows v5.5

319

15 nShield Administrator Utilities

stattree

ID
HostReadDeferred

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

HostReadTerminated

PFNIssued

PFNRejected

PFNCompleted

ANIssued

ChanJobsIssued

ChanJobsCompleted

nShield/payShield Administrator Guide Windows v5.5

320

15 nShield Administrator Utilities

stattree

ID
CPULoadPercent

Value
The current processing load on the module, represented as a number between 0 and 100. Because a module typically contains a number of different types of processing resources (for example, main CPU, and RSA acceleration), this figure is hard to interpret precisely. In general, modules report 100% CPU load when all RSA processing capacity is occupied; when performing nonRSA tasks the main CPU or another resource (such as the random number generator) can be saturated without this statistic reaching 100%. On PCI modules, the total number of interrupts received from the host. On current modules, approximately equal to the total of HostReadCount and HostWriteCount. The number of low-level (principally data transport) errors encountered while processing fast channel jobs. Should always be zero on current modules. On PCI modules, the number of debug interrupts received. This is used only for driver testing, and should be zero in any production environment. On PCI modules, the number of unidentified interrupts from the host. If this is nonzero, a driver or PCI bus problem is likely. 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. The number of times a new object has been put into the object store. This appears under the modules ModuleObjStats node. The number of items in the modules object store that have been deleted and their corresponding memory released. The current number of objects (keys, logical tokens, buffers, SEE Worlds) in the object store. This is equal to ObjectsCreated minus ObjectsDestroyed. An empty module contains a small number of objects that are always present.

HostIRQs

ChanJobErrors

HostDebugIRQs

HostUnhandledIRQs

HostReadReconnect

ObjectsCreated

ObjectsDestroyed

ObjectCount

nShield/payShield Administrator Guide Windows v5.5

321

15 nShield Administrator Utilities

stattree

ID
CurrentTempC

Value
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. The maximum temperature recorded by the modules temperature sensor. This is stored in non-volatile memory, which is cleared only when the unit is initialized. First-generation modules do not have a temperature sensor and do not return temperature statistics. The minimum temperature recorded by the modules temperature sensor. This is stored in non-volatile memory, which is cleared only when the unit is initialized. First-generation modules do not have a temperature sensor and do not return temperature statistics. The total amount of RAM (both allocated and free) available to the module. This is the installed RAM size, minus various fixed overheads. 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. The total amount of RAM allocated for user-mode processes in the module; will be zero for non-SEE use. This includes the size of the SEE Machine image, and the total heap space available to it. The modules kernel does not know (and does not report in the statistics) how much of the user-modes heap is currently free, and how much is in use.

MaxTempC

MinTempC

MemTotal

MemAllocKernel

MemAllocUser

nShield/payShield Administrator Guide Windows v5.5

322

Appendix A: Upgrading module firmware


nCipher module firmware is supplied on your nCipher CD-ROM. The following sections describe how to load updated firmware onto you nCipher module. There are separate instructions for modules that are mounted internally in your computer and those that are mounted in external boxes supplied by nCipher. nCipher modules can be damaged by static discharge. nCipher recommends that you wear an anti-static wristband or similar device while handling modules.

Version Security Number


All nCipher firmware includes a Version Security Number (VSN). This number is increased whenever nCipher improves the security of the firmware or adds significant new functionality. For firmware version 2.12.0 and subsequent releases, nCipher supplies several versions of the module firmware. You can always upgrade to firmware with an equal or higher VSN than that currently installed on your module. You can never load firmware with a lower VSN than the currently installed firmware. Ensuring you use firmware with the highest available VSN allows you to benefit from security improvements and enhanced functionality. It also prevents future downgrades of the firmware that could potentially weaken security. However, you may choose to install firmware that does not have the highest available VSN. For example, if you have a regulatory requirement to use FIPS-approved firmware, you should install the latest available FIPS validated firmware which may not have the highest VSN. Similarly, if you want to install a version with

nShield/payShield Administrator Guide Windows v5.5

323

A Upgrading module firmware

Firmware on the CD-ROM

enhanced features without committing yourself to the upgrade, you can do so providing upgrade only to firmware with a VSN equal to that currently installed on your module. In general, nCipher recommends using the latest firmware with the highest available VSN. To support the use of Feature Enable, the VSN was increased for the firmware release 2.x.x. If you install this firmware in order to use optional features, you cannot then reload earlier firmware. For firmware versions 2.x.x and above, the firmware filenames have changed to include the model code of your module.

Firmware on the CD-ROM


Your nCipher CD-ROM contains several sets of firmware for each supplied product. These can include: Note the latest available FIPS-approved firmware with the base VSN the latest available FIPS-approved firmware with a higher VSN the latest available firmware awaiting FIPS approval with the base VSN the latest available firmware awaiting FIPS approval with a higher VSN.

For firmware release 2.12.0 only one version of the FIPS-approved firmware is supplied. You should ensure you are using the latest firmware, unless you have a regulatory requirement to use firmware that has been FIPS validated. In the latter case, you should ensure that you are using the latest available FIPS validated firmware. See the release notes for details of current versions.

nShield/payShield Administrator Guide Windows v5.5

324

A Upgrading module firmware

What must I do?

Firmware files are in the firmware directory on the CD-ROM, under a directory identified by the firmware version. To display information about a firmware file on the CD-ROM, enter the following command:
C:\nfast\bin\loadrom --view E:\firmware\ver\filename.nff

In this command, E is the drive letter of your CD-ROM, ver is a firmware version number and filename is a file name. See loadrom on page 253 for full details of the loadrom utility.

What must I do?


In order to use the new firmware, you must: 1. 2. Install the latest server software as described in Chapter 3: Getting the module working. Install the latest firmware, as described below.

This appendix assumes that you have installed the nCipher server as a service. This is the default installation procedure described in Chapter 3: Getting the module working. Where commands are described, it is assumed that you have installed the nCipher software in the default location, C:\nfast\. If you have chosen to install the nCipher software in another directory, replace references to this directory with the name of the directory in which you have chosen to install the software. This chapter describes how to upgrade module firmware for nShield/payShield modules only. If you have another module refer to the corresponding chapter in the appropriate Administrator Guide.

Key data
The firmware upgrade process destroys all persistent data held in a key management module.

nShield/payShield Administrator Guide Windows v5.5

325

A Upgrading module firmware

Firmware installation overview

If your security system requires that the persistent data held in a key-management module live beyond the upgrade or initialization of the key management module, a backup and recovery mechanism must be implemented. If you are using an SEE program that stores data in nonvolatile memory, or NVRAM key storage, use the nvram-backup utility to backup your data before upgrading and to restore the data after the upgrade is complete. See nvram-backup on page 266 for further information on this utility.

Firmware installation overview


The process of installing or updating firmware on a nCipher module can be broken down into three basic steps: 1. 2. 3. Ensure the module is in maintenance mode (thus taking it out of any security world of which it is part). Install the appropriate firmware. Initialize the module.

This three-step process is diagrammed in Maintenance mode and firmware installation on page 327. The methods needed to change a given module to the maintenance mode and to initialize it after firmware installation depend on the model of module. Follow the directions in this appendix that are appropriate to the specific model of module whose firmware you are upgrading.

nShield/payShield Administrator Guide Windows v5.5

326

A Upgrading module firmware

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 befores nonvolatile memory usingnvram-backup. See nvram-backup on page 266 for information on using this utility.

PCI modules
If you have a PCI module, you can upgrade the firmware without having to open your computer case, provided that the override switch is off. (Refer to the installation instructions in the Hardware Installation Guide for information on accessing the override switch and switching it off.) To upgrade the firmware on a PCI module, follow these steps: 1. 2. Log in to the host Administrator. Place the mode switch in the maintenance position, as shown in Figure 7 or , depending on your module type.

nShield/payShield Administrator Guide Windows v5.5

327

A Upgrading module firmware

PCI modules

Figure 7
Status LED Clear switch Mode switch
M O I

PCI module back panel


on off J1 override J2 unused

Smart card connector

DC power

3. 4.

Reset the module by pressing the Clear button or by issuing the


nopclearfail command.

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. 6. Place the nCipher CD-ROM in the CD-ROM drive and mount it on your file system. In order to load the new firmware, use the command:

C:\nfast\bin\loadrom E:\firmware\ver\filename.nff

In this command, E is the drive letter of your CD-ROM, ver is a firmware version number and filename is a file name. The firmware files are signed and encrypted: you can load only the correct version for your module. 7. Switch the mode switch to the Initialization position.

nShield/payShield Administrator Guide Windows v5.5

328

A Upgrading module firmware

After firmware installation

8.

Reset the module by pressing the clear button until the LED flashes short pulses to indicate that the module is in preinitialization state. Alternatively, issue the nopclearfail command. Switch the mode switch to the Operational position.

9.

10. Reset the module by pressing the clear button or by issuing the nopclearfail command. 11. Log in to the host as normal.

After firmware installation


After you have installed new firmware and initialized the module, you can create a new security world with the module or reinitialize the module into an existing security world. If you are initializing the module into a new security world, see Creating a security world on page 129. If you are reinitializing the module into an existing security world, see Adding or restoring a module to the security world on page 155.

nShield/payShield Administrator Guide Windows v5.5

329

Appendix B: Components on nCipher CD-ROMs


nCipher supplies the hardserver and associated software as bundles of common components that provide much of the required software for your installation. In addition to the component bundles, nCipher provides individual components for use with specific applications and features supported by certain nCipher modules. This appendix lists the contents of the component bundles and the additional software supplied on your nCipher CD-ROM. For information on installing the supplied software, see Chapter 3: Getting the module working. You can list installed components, both those installed as part of the standard bundles and those installed individually, by using the ncversions command-line utility described in the Operator Guide appropriate to your module type.

nCipher component bundles


nCipher supplies component bundles containing many of the necessary components for your installation. Certain standard component bundles are offered for installation on all standard nCipher support software CD-ROMs, while additional component bundles are found on CipherTools and CodeSafe CD-ROMs.

Standard component bundles


You are always offered the following standard component bundles on all standard nCipher support software CD-ROMs:
Standard component bundles
hwsp Hardware Support (mandatory) ctls Core Tools (recommended) javasp Java Support (including KeySafe)

nShield/payShield Administrator Guide Windows v5.5

330

B Components on nCipher CD-ROMs

nCipher component bundles

On nCSS User and CipherTools CD-ROMs, you are also offered the psusr payShield User standard component bundle. The component bundles consist of various individual components. The hwsp Hardware Support (mandatory) bundle contains the nCipher server and kernel device drivers:
hwsp Hardware Support (mandatory) bundle
nfdrv Windows device drivers nfserv Hardserver process executables and scripts sdrv nFast Win 2000 driver signatures cfgall Hardserver config file support nflog Logging library support

The ctls Core Tools (recommended) bundle contains all the nCipher command-line utilities, including generatekey, low level utilities, and test programs:
ctls Core Tools (recommended) bundle
convrt Command line key conversions nftcl Command line key management (Tcl) nftcl Command line key generation and import nfuser Low level utilities and test programs nfuser Command line remote server management opensl nftcl certificate generation utility sworld Command line key management (C) tclsrc Tcl run time tclstf Small Tcl utilities nftcl Command line key generation and import tct2 Trusted Code Tool 2 command-line utility pysrc Python source for developers nfpy nFPython header files

nShield/payShield Administrator Guide Windows v5.5

331

B Components on nCipher CD-ROMs

nCipher component bundles

nCipher recommends that you always install the ctls Core Tools bundle. Note The Core Tools bundle includes the tclsrc Tcl run times tools for creating the security world, KeySafe, and new-world. This does not affect any other installation of Tcl on your computer. The javasp Java Support (including KeySafe)s Java applications, including KeySafe:
javasp Java Support (including KeySafe) bundle
jutils Java utilities jutils JNI shared library for jutils.jar kmjava Java Key Management classes ksafe KeySafe 2 nfjava nFast Java generic stub classes nftcl Java Key Management Support

The psusr payShield User bundle contains the components required if you want to use payShield secure payments:
psusr payShield User bundle
emvspp payShield command-line tools emvsms SEE machine for EMV library emvspj payShield Java interface emvjni Dynamic shared library for payShield JNI

Additional component bundles


nCipher supplies the following additional component bundles on CipherTools CD-ROMs:
Additional CipherTools component bundles
ctd CipherTools Developer jd Java Developer

nShield/payShield Administrator Guide Windows v5.5

332

B Components on nCipher CD-ROMs

nCipher component bundles

nCipher supplies the following additional component bundles on CodeSafe CD-ROMs:


Additional CodeSafe component bundles
csd CodeSafe Developer jd Java Developer

The ctd CipherTools Developer bundle contains components supplied with the CipherTools Developer Kit:
ctd CipherTools Developer bundle
emvspj JNI library for payShield Java emvspp payShield developer library hwcrhk Crypto Hardware Interface (CHIL) dev kit nflibs nCipher libraries and headers, and example C source for utility functions nfuser nCore & KM tools and example source pkcs11 nFast PKCS#11 developers library sworld Key Management C library developers kit tclsrc Tcl run time - Headers and Libraries cutils C utilities library nflog Logging library hilibs GS libs & headers pysrc Python source for developers nfpy nFPython header files

The csd CodeSafe Developer bundle contains components supplied with the CodeSafe Developer Kit:
csd CodeSafe Developer bundle
csee Codesafe-C moduleside example code csee Codesafe-C hostside example code module Firmware test scripts nflibs Generic stub libraries and headers, and example C source for utility functions

nShield/payShield Administrator Guide Windows v5.5

333

B Components on nCipher CD-ROMs

nCipher component bundles

csd CodeSafe Developer bundle


nfuser nCore & KM tools and example source sworld Key Management C library developers kit tclsrc Tcl run time - Headers and Libraries cutils C utilities library nflog Logging library hilibs GS libs & headers jhsee Java hostside developer's kit jhsee Java hostside SEE examples ssllib Codesafe-SSL hostside code ssllib Codesafe-SSL moduleside code pysrc Python source for developers nfpy nFPython header files nfpy Libs and headers for codesafe/python

The jd Java Developer bundle contains components to support development of Java applications:
jd Java Developer bundle
jcecsp Java Key Management developer jutils Java utilities source and javadocs kmjava Java Key Management developer nfjava Java Generic Stub examples & javadoc

nShield/payShield Administrator Guide Windows v5.5

334

B Components on nCipher CD-ROMs

nCSS User CD-ROM

nCSS User CD-ROM


nCipher supplies the following component bundles and additional components on the nCSS User CD-ROM:
Component Bundles
hwsp Hardware Support (mandatory) ctls Core Tools (recommended) javasp Java Support (including KeySafe) psusr payShield User

Individual Components
hwcrhk Crypto Hardware Interface (CHIL) plugin jcecsp nCipherKM JCA/JCE provider classes mscapi CSP support files mscapic nCipher Win 2000 domestic strength CSP ncsnmp nCipher SNMP monitoring agent pkcs11 nCipher pkcs11 library

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

nShield/payShield Administrator Guide Windows v5.5

335

B Components on nCipher CD-ROMs

CodeSafe CD-ROM

Individual Components
hwcrhk Crypto Hardware Interface (CHIL) plugin jcecsp nCipherKM JCA/JCE provider classes mscapi CSP support files mscapic nCipher Win 2000 domestic strength CSP ncsnmp nCipher SNMP monitoring agent pkcs11 nCipher pkcs11 library sslyp Open SSL source code patch file

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

Individual Components
gccsrc Prebuilt arm-gcc for Codesafe/C gccsrc Prebuilt powerpcm-gcc for Codesafe/C hwcrhk Crypto Hardware Interface (CHIL) plugin jcecsp nCipherKM JCA/JCE provider classes mscapi CSP support files mscapic nCipher Win 2000 domestic strength CSP ncsnmp nCipher SNMP monitoring agent pkcs11 nCipher pkcs11 library

nShield/payShield Administrator Guide Windows v5.5

336

B Components on nCipher CD-ROMs

Components Required for Particular Functionality

Components Required for Particular Functionality


Some functionality requires particular component bundles or individual components to be installed. nCipher recommends that you ensure that you have installed the hwsp Hardware Support (mandatory) and ctls Core Tools (recommended) bundles. If you have a CipherTools CD-ROM, nCipher recommends that you install the ctd CipherTools Developer bundle. If you have a CodeSafe CD-ROM, nCipher recommends that you install the csd CodeSafe Developer bundle. If you have a CodeSafe CD-ROM and you are developing in C, if your module has a part code of the form nC4XX2 or Bn1XXX, install the gccsrc Prebuilt arm-gcc for Codesafe/C component. if your module has a part code of the form nC4XX3 or Bn2XXX, install the gccsrc Prebuilt powerpc-gcc for Codesafe/C component.

In these part codes, X represents any integer. If you have a CipherTools CD-ROM or a CodeSafe CD-ROM and you are developing in Java, install the jd Java Developer and javasp Java Support (including KeySafe) bundles; after installation, ensure that you have added the .jar files to your CLASSPATH.

KeySafe
To use KeySafe, install the ctls Core Tools and the javasp Java Support (including KeySafe) bundles.

payShield secure payments


If you have an nCipher Support Software (nCSS) CD-ROM or a CipherTools CD-ROM and you want to use payShield secure payments, install the psusr payShield User bundle.

nShield/payShield Administrator Guide Windows v5.5

337

B Components on nCipher CD-ROMs

PKCS #11 applications

Windows CSP
If you require the Windows CSP, you must install the CSP components:
mscapic nCipher Win 2000 domestic strength CSP mscapi CSP support files

PKCS #11 applications


If you want to use the module with PKCS #11 applications, including release 4.0 or later of Netscape Enterprise Server, iPlanet Enterprise Edition 4, or Netscape Certificate Server 4, install the pkcs11 nCipher PKCS11 library. For detailed PKCS #11 configuration options, see the Operator Guide appropriate to your module type.

Cryptographic Hardware Interface Library applications


If you want to use the module with the Cryptographic Hardware Interface Library (CHIL) applications, install the hwcrhk Crypto Hardware Interface (CHIL) plugin component and, if required, the NCsslyp OpenSSL source code patch file component. Note nCipher supports OpenSSL 0.9.7g and later.

nCipherKM JCA/JCE cryptographic service provider


If you want to use the nCipherKM JCA/JCE cryptographic service provider, you must install the javasp Java Support (including KeySafe) bundle and also the jcecsp nCipherKM JCA/JCE provider classes component. Note In order to use the nCipherKM JCA/JCE cryptographic service provider, you must also add the nfjava.jar, kmjava.jar, jutils.jar, and kmcsp.jar files to your CLASSPATH after installation is complete. For details, see Operator Guide .

nShield/payShield Administrator Guide Windows v5.5

338

B Components on nCipher CD-ROMs

nCipher SNMP monitoring agent

An additional JCE provider nCipherRSAPrivateEncrypt is supplied that is required for RSA encryption with a private key. Install this provider above the standard nCipherKM provider and ensure that the file rsaprivenc.jar is in your CLASSPATH. nCipher has successfully tested SSLSocketClientWithClientAuth (JSSE sample code) with iPlanet 4.1 and 6.0 SP5 with this provider. For details about configuring these providers, see the Operator Guide.

nCipher SNMP monitoring agent


If you want to use the nCipher SNMP monitoring agent to monitor your modules, install the ncsnmp nCipher SNMP monitoring agent component. During the first installation process of the nCipher SNMP agent, the agent displays the following message:
If this is a first time install, the nCipher SNMP Agent will not run by default. Please see the manual for further instructions.

For instructions on how to activate the agent after installation, see the Operator Guide appropriate to your module type.

nShield/payShield Administrator Guide Windows v5.5

339

Appendix C: Environment variables


nCipher software uses the following environment variables:
Variable
NFAST_DEBUG

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

NFAST_HOME

NFAST_HWCRHK_LOGFILE

NFAST_KMDATA

NFAST_KMLOCAL

nShield/payShield Administrator Guide Windows v5.5

340

C Environment variables

Environment variables

Variable
NFAST_NFKM_TOKENSFILE NFAST_NFKM_TOKENSSELECT

Description
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. This variable is the name of the SEEConf key needed to decrypt SEE-machine images. 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. This variable is the path of the SEE machine image to load on to any module for which a specific image is not defined. 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. This variable is the default key hash of the vendor signing key. 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.

NFAST_SEE_MACHINEENCKEY_DEFAULT

NFAST_SEE_MACHINEENCKEY_module

NFAST_SEE_MACHINEIMAGE_DEFAULT

NFAST_SEE_MACHINEIMAGE_module

NFAST_SEE_MACHINESIGHASH_DEFAULT

NFAST_SEE_MACHINESIGHASH_module

nShield/payShield Administrator Guide Windows v5.5

341

C Environment variables

Environment variables

Variable
NFAST_SERVER_PORT NFAST_SERVER_PRIVPORT

Description
If this variable is set in the nFast servers environment, the values are used to specify the TCP port numbers that the nFast server uses for connections over TCP sockets. This variable is available for this purpose for backward compatibility only: you should configure ports in the configuration file, as described in server_remotecomms on page 90. If you set this variable, it overrides the values in the configuration file. If this variable is not set, the nFast server defaults to using port 9000 and port 9001. If this variable is set in a C application, the application connects to the nFast server using TCP sockets rather than named pipes. The value of the environment variable determines the port to connect to. It must be the same value as used by the nFast server. You need only change these environment variables if another application is already using the default port numbers. 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. 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. 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. 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). 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.

NFLOG_CATEGORIES

NFLOG_SEVERITY

NFLOG_DETAIL

NFLOG_FILE

OPENSSL_HWCRHK_LOG

nShield/payShield Administrator Guide Windows v5.5

342

Appendix D: Logging and debugging


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

Environment variables to control logging


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

This environment variable specifies the name of a file (or a file descriptor, if prefixed with the & character) to which logging information is written. The default is stderr (the equivalent of &2).
NFLOG_SEVERITY

This environment variable specifies a minimum severity level for logging messages to be written (all log messages less severe than the specified level are ignored). The level can be one of (in order of greatest to least severity): 1. 2. 3. 4. 5.
FATAL SEVERE ERROR WARNING NOTIFICATION

nShield/payShield Administrator Guide Windows v5.5

343

D Logging and debugging

Environment variables to control logging

6.

DEBUGn (where n can be an integer between 1 and 10

inclusive that specifies different level of debugging detail, with 10 representing the greatest level of detail). Note nCipher recommends not setting the severity level to DEBUGn unless
you are directed to do so by Support at nCipher.

The default severity level is WARNING.


NFLOG_DETAIL

This environment variable takes a hexadecimal value from a bitmask of detail flags as described in the following table (the logdetail flags are also used in the hardserver configuration file to control hardserver logging; see Hardserver configuration file on page 85):
Hexadecimal flag
0x00000001

Function

logdetail flags

This flag shows the external time (that is, external_time the time according to your machine's local clock) with the log entry. It is on by default. This flag shows the external date (that is, external_date the date according to your machine's local clock) with the log entry. This flag shows the external process ID with the log entry. This flag shows the external thread ID with the log entry. This flag shows the external time_t (that is, the time in machine clock ticks rather than local time) with the log entry. This flag shows the stack backtrace with the log entry. external_pid external_tid external_time_t

0x00000002

0x00000004 0x00000008 0x00000010

0x00000020 0x00000040 0x00000080

stack_backtrace

This flag shows the stack file with the log stack_file entry. This flag shows the stack line number with the log entry. stack_line

nShield/payShield Administrator Guide Windows v5.5

344

D Logging and debugging

Environment variables to control logging

Hexadecimal flag
0x00000100

Function
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. This flag shows the message category (a category as used by the NFLOG_CATEGORY environment variable) with the log entry.

logdetail flags
msg_severity

0x00000200

msg_categories

0x00000400

This flag shows message writeables, extra msg_writeable information that can be written to the log entry, if any such exist. It is on by default. This flag shows the message file in the original library. This flag is likely to be most useful in conjunction with nCiphersupplied example code that has been written to take advantage of this flag. msg_file

0x00000800

0x00001000

This flag shows the message line number msg_line in the original library. This flag is likely to be most useful in conjunction with nCipher-supplied example code that has been written to take advantage of this flag. This flag shows the date and time in UTC options_utc (Coordinated Universal Time) instead of local time.

0x00002000

nShield/payShield Administrator Guide Windows v5.5

345

D Logging and debugging

Environment variables to control logging

NFLOG_CATEGORIES

This environment variable takes a colon-separated list of categories on which to filter log messages (categories may contain the wild-card characters * and ?). If you do not supply any values, then all categories of messages are logged. This table lists the available categories:
Category
nflog nflog-stack memory-host memory-module gs-stub

Description
This category logs all general messages relating to nflog. This category logs messages from StackPush and StackPop functions. This category logs messages concerning host memory. This category logs messages concerning module memory. 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.) 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.) 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.) 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.) This category logs nfkm-getinfo messages. This category logs messages about world generation. This category logs operations using the Administrator Card Set. This category logs file operations in the kmdata directory. This category logs general NFKM library messages. This category logs key loading operations.

gs-stubbignum

gs-stubinit

gs-dumpenv

nfkm-getinfo nfkm-newworld nfkm-admin nfkm-kmdata nfkm-general nfkm-keys

nShield/payShield Administrator Guide Windows v5.5

346

D Logging and debugging

Environment variables to control logging

Category
nfkm-preload nfkm-ppmk serv-general serv-client serv-internal serv-startup servdbg-stub servdbg-env servdbg-underlay servdbg-statemach servdbg-perf servdbg-client servdbg-messages servdbg-sys hwcrhk pkcs11-sam pkcs11 rqcard-core rqcard-logic rqcard-logic

Description
This category logs preload operations. This category logs softcard operations. This category logs general messages about the local hardserver. This category logs messages relating to clients or remote hardservers. This category logs severe or fatal internal errors. This category logs fatal startup errors. This category logs all generic stub debugging messages. This category logs generic stub environment variable messages. This category logs messages from the OS-specific device driver interface This category logs information about the servers internal state machine. This category logs messages about the server's internal queueing. This category logs external messages generated by the client. This category logs server command dumps. This category logs OS-specific messages. This category logs messages from the CHIL (Cryptographic Hardware Interface Library). This category logs all security assurance messages from the PKCS #11 library. This category logs all other messages from the PKCS #11 library. This category logs all card-loading library operations that involve standard message passing (including slot polling). This category logs all card-loading library messages from specific logics. This category logs all card-loading library messages from the current user interface.

nShield/payShield Administrator Guide Windows v5.5

347

D Logging and debugging

Logging from the nCipher CSP

You can set a minimum level of hardserver logging by supplying one of the values for the NFLOG_SEVERITY environment variable in the hardserver configuration file, and you can likewise specify one or more values for the NFLOG_CATEGORIES environment variable. See Chapter 6: Configuring the hardserver for more detailed information about controlling hardserver logging. Note If none of the four environment variables are set, the default behavior is to log nothing, unless this is overridden by any individual library. If any of the four variables are set, all unset variables are given default values.

Logging from the nCipher CSP


By default, the nCipher CSP for Windows sends log messages to the event log. In order to send log messages to a file, edit the registry, and then set the value of the registry key HKLM\Software\nCipher\Cryptography\LogLevel as follows:
Value
0 1 2 3

Output
Messages are sent to the event log. Error messages are sent to the log file. Function calls and error messages are sent to the log file. All information, including debugging information, is sent to the log file.

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.

nShield/payShield Administrator Guide Windows v5.5

348

D Logging and debugging

Logging and debugging information for PKCS #11

Logging and debugging information for PKCS #11


In order to get PKCS #11 logging and debugging output, you must set the CKNFAST_DEBUG environment variable equal to 1 and specify any appropriate pkcs11 categories using the NFLOG_CATEGORIES environment variable. This environment variable takes a colon-separated list of categories on which to filter log messages (categories may contain the wildcards characters * and ?). The following table maps PKCS #11 debug level numbers to the corresponding NFLOG_SEVERITY value
PKCS #11 debug level
0 1 2 3 4 5 6 7 8 9 10 11

PKCS #11 debug NFLOG_SEVERITY meaning value

Output in log

DL_None DL_EFatal DL_EError DL_Fixup DL_Warning DL_EApplic DL_Assumption DL_Call DL_Result DL_Arg DL_Detail DL_DetailMutex

NONE FATAL ERROR WARNING WARNING ERROR NOTIFICATION DEBUG2 DEBUG3 DEBUG4 DEBUG5 DEBUG6
"Fatal error:" "Error:" "Fixup:" "Warning:" "Application error:" "Unsafe assumption:" ">> " "< " "> " "D " "DM "

nShield/payShield Administrator Guide Windows v5.5

349

D Logging and debugging

Hardserver debugging

Hardserver debugging
Hardserver debugging is controlled by specifying one or more servdbg-* categories (from the NFLOG_CATEGORIES environment variable) in the hardserver configuration file (see Hardserver configuration file on page 85). However, unless you also set the NFAST_DEBUG environment variable to a non-zero value, no debugging is produced (regardless of whether or not you specify servdbg-* categories in the hardserver configuration file). This behavior helps guard against the additional load debugging places on the CPU usage; you can set the desired servdbg-* categories in the hardserver configuration file, and then enable or disable debugging by setting the NFAST_DEBUG environment variable. Note If the NFAST_DEBUG environment variable is used to control debugging (instead of simply enabling or disabling it), the logdetail value in the hardserver configuration file (one of the values for the NFLOG_LEVEL environment variable) controls the level of detail printed. Standard debugging messages are printed at level DEBUG2. Environment variables are at DEBUG3, bignums and other byteblocks are printed at DEBUG4, and extra verbose debugging is available at DEBUG5.

Debugging information for payShield


PAYSHIELD_DEBUGFILE

The environment variable PAYSHIELD_DEBUGFILE is used to set the name of the file that can be used by payShield to record log messages returned from the hostside payShield library.
PAYSHIELD_DEBUG

The environment variable PAYSHIELD_DEBUG is used to set the level and destination of log messages returned from the hostside payShield library.

nShield/payShield Administrator Guide Windows v5.5

350

D Logging and debugging

Debugging information for payShield

The payShield library can be configured to return log information from various categories and to either of two different locations. The environment variable PAYSHIELD_DEBUG should be set to an integer which represents the kind of logging desired. The integer value used to set PAYSHIELD_DEBUG must be calculated by ORing the binary values assigned to each log information category.
Value
00000000 00000001 00000010 00000100 00001000 00010000 00100000 01000000 10000000

payShield log information category


Log no data at all Log errors to the payShield logfile Log warnings to the payShield logfile Log informational messages to the payShield logfile Log debug data to the payShield logfile Log errors to the system log Log warnings to the system log Log informational messages to the system log Log debug data to the system log

For example, to log payShield errors to the system log, and also log payShield warnings and errors to the payShield logfile specified by PAYSHIELD_DEBUGFILE, PAYSHIELD_DEBUGFILE must be set to 19. 19 is the integer value of the binary number 00010011, calculated by ORing 00010000, 00000001 and 00000010 together.

nShield/payShield Administrator Guide Windows v5.5

351

D Logging and debugging

Debugging information for Java

Debugging information for Java


This section describes how you can specify the debugging information generated by Java. Note Do not set NFJAVA_DEBUG or NFJAVA_DEBUGFILE in the environment because Java does not pick up variables from the environment.

Setting the Java debugging information level


In order to make the Java generic stub output debugging information, set the Java property NFJAVA_DEBUG. The debugging information for NFJAVA, NFAST, and other libraries (for example, KMJAVA) can all use the same log file and have their entries interleaved. You set the debugging level as a decimal number. To determine this number: 1. Select the debugging information that you want from the following list:

NONE = 0x00000000 (debugging off) MESS_NOTIFICATIONS = 0x00000001 (occasional messages including important errors) MESS_VERBOSE = 0x00000002 (all messages) MESS_RESOURCES = 0x00000004 (resource allocations) FUNC_TRACE = 0x00000008 (function calls) FUNC_VERBOSE = 0x00000010 (function calls + arguments) REPORT_CONTEXT = 0x00000020 (calling context e.g ThreadID and time) FUNC_TIMINGS = 0x00000040 (function timings) NFJAVA_DEBUGGING = 0x00000080 (Output NFJAVA debugging info)

2.

Add together the hexadecimal value associated with each type of debugging information. For example, to set NFJAVA_DEBUGGING and MESS_NOTIFICATIONS, add 0x00000080 and 0x00000001 to make 0x00000081.

nShield/payShield Administrator Guide Windows v5.5

352

D Logging and debugging

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.

nShield/payShield Administrator Guide Windows v5.5

353

Appendix E: Installed Utilities


The following utility files are supplied in the bin subdirectory of your nCipher installation:
Utility
cardpp

Description
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. This utility loads the hardserver configuration from the configuration file. It is described in cfg-reread on page 228. This utility checks modulo exponentiations. It is described in the Operator Guide. This utility is internal to nCipher. 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. 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.

cfg-reread

checkmod

ckimportbackend ckinfo

cklist

nShield/payShield Administrator Guide Windows v5.5

354

E Installed Utilities

Installed Utilities

Utility
ckmechinfo

Description
This is a PKCS #11 developer utility. Refer to the relevant developer documentation. This is a PKCS #11 developer utility. Refer to the relevant developer documentation. This utility measures module signing speed with nCipher PKCS #11 library calls. It is described in the Operator Guide. This utility is a Netscape configuration tool. It is described in the relevant integration guide. This utility creates or erases Operator Card Sets. It is described in Creating the Operator Card Set from the command line on page 71. This utility tests all defined symmetric cryptographic mechanisms. It is described in the Operator Guide. This utility checks that CSP container files are intact and uncorrupted and that referenced key files exist. It is described in the Operator Guide. This utility allows you to insert keys manually into existing CSP containers. It is described in the Operator Guide. 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.

ckrsagen

cksigtest

config

createocs

cryptest

cspcheck

cspimport

cspmigrate

nShield/payShield Administrator Guide Windows v5.5

355

E Installed Utilities

Installed Utilities

Utility
cspnvfix

Description
This utility regenerates the NVRAM key counter area for a specified nCipher CSP key. It is described in the Operator Guide. This utility tests installed Cryptographic Service Providers. It is described in the Operator Guide. This utility lists and gives detailed information about CSP containers. It is described in the Operator Guide. This utility performs DES knownanswer tests. It is described in the Operator Guide. This utility can be used to examine nCipher data formats. Contact Support at nCipher for information. This utility returns information about the nCipher server and connected modules. It is described in enquiry on page 229. This utility performs hardware speed testing. It is described in floodtest on page 238. This utility verifies the firmware. It is described in the Operator Guide. This utility is internal to nCipher. This utility generates or imports keys. It is described in the Operator Guide. 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.

csptest

csputils

des_kat

dump_marshalled

enquiry

floodtest

fwcheck

genkeyprops generatekey

hardserver

nShield/payShield Administrator Guide Windows v5.5

356

E Installed Utilities

Installed Utilities

Utility
iisinstallcert

Description
This utility is an IIS configuration tool. It is described in the relevant integration guide. This utility initializes a module. It is described in initunit on page 244. This utility is internal to nCipher. This utility displays information about existing CSP key containers. It is described in the Operator Guide. 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. This utility disables the Replace Operator Card Set feature for a security world. Contact Support at nCipher for information. This utility displays keymanagement information from a security worlds key-management data file. It is described in the Operator Guide. 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. This utility prepares Key Detail cards and loads keys for payShield installations. It is described in the Operator Guide. This utility loads new firmware into a module. It is described in loadrom on page 253.

initunit

key2pem keytst

key-xfer-im

killrecov

kmfile-dump

kptest

loadkeys

loadrom

nShield/payShield Administrator Guide Windows v5.5

357

E Installed Utilities

Installed Utilities

Utility
mkaclx

Description
This utility contains example code for key generation. It is described in the Operator Guide. 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. This utility sets, updates and views the time on a modules realtime clock. It is described in the Operator Guide. This utility stress tests modules and tests nCore API concurrent connection support. It is described in the Operator Guide. This utility displays the versions of installed nCipher support software components. It is described in ncversions on page 257. This utility creates a security world that supports SEE functions. It is described in new-world on page 259. This utility is internal to nCipher. This utility displays information about a security world, cards, and keys. It is described in the Operator Guide. This utility clears a module, puts a module into the error state, or retries a failed module. It is described in the Operator Guide. 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.

mk-reprogram

ncdate

ncthread-test

ncversions

new-world

nffwd nfkminfo

nopclearfail

nvram-backup

nShield/payShield Administrator Guide Windows v5.5

358

E Installed Utilities

Installed Utilities

Utility
nvram-sw

Description
This utility modifies and displays information about NVRAM areas. It is described in nvram-sw on page 272. This utility enables the Master Card Set holders to modify a payShield installations settings. It is described in payshield-config on page 278. This utility displays information about a payShield installation. It is described in the Operator Guide. This utility configures a security world specifically for payShield modules. It is described in payshield-install on page 283 in the Administrator Guide. This example utility returns information about state changes. It is described in the Operator Guide. 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. This utility is used to manage softcards. It is described in ppmk on page 287. This utility loads keys onto a module before an application is run in another session. It is described in the Operator Guide. This example utility returns information the key, certificate, or certificate request in a file. It is described in the Operator Guide.

payshield-config

payshield-info

payshield-install

pollbare

postrocs

ppmk

preload

pubkey-find

nShield/payShield Administrator Guide Windows v5.5

359

E Installed Utilities

Installed Utilities

Utility
racs

Description
This utility creates a new Administrator Card Set. It is described in Replacing an Administrator Card Set with racs on page 225. This utility runs a universal statistical test on random numbers returned by the module. It is described in the Operator Guide. This utility is internal to nCipher. 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. This utility reads and sets the modules real-time clock. It is described in the Operator Guide. This utility measures module speed using RSA or DSA signatures or signature verifications. It is described in the Operator Guide. 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. This utility upgrades keys created on older payShield installations. It is described in sppupgradekeys on page 312. This utility returns statistics gathered by the nCipher server and modules. It is described in stattree on page 314.

randchk

rdlinene

rfs-sync

rtc

sigtest

slotinfo

sppupgradekeys

stattree

nShield/payShield Administrator Guide Windows v5.5

360

Appendix F: The nCipher SNMP monitoring agent


Note The nCipher SNMP monitoring agent provides you with components that can be added to your (third-party) SNMP manager application. Every SNMP manager adds monitor components differently. Please consult the documentation supplied with your SNMP Manager application for details on how to add the nCipher MIB files. The Simple Network Management Protocol (SNMP) was developed in 1988 and revised in 1996. It is currently regarded as the standard method of network management. It is widely supported and offers greater interoperability than traditional network management tools (for example, rsh or netstat). This makes it ideal for use for the large array of platforms that nCipher supports and also avoids the overhead of remote login and execution, helping to reduce network congestion and improve performance. The SNMP protocol defines a collection of network management functions allowing management stations to gather information from, and transmit commands to, remote machines on the network. Agents running on the remote machines can take information gathered from the system and relay this information to the manager application. Such information could have been requested from the underlying operating system or gained by interrogating the hardware. The SNMP protocol defines the following SNMP messages:
get

This message is sent by a manager to retrieve the value of an object at the agent.
set

This message is sent by a manager to set the value of an object at the agent.

nShield/payShield Administrator Guide Windows v5.5

361

F The nCipher SNMP monitoring agent

Activating the nCipher SNMP agent

trap

This message is sent by an agent to notify a management station of significant events. In the development of the nCipher SNMP agent, nCipher has used open-source tools that are part of the NET-SNMP project (formerly UCD-SNMP). More information on SNMP in general, and the data structures used to support SNMP installations, is available from the NET-SNMP project Web site: http://net-snmp.sourceforge.net/. This site includes some support information and offers access to discussion E-mail lists. You can use the discussion lists to monitor subjects that might affect the operation or security of the nCipher SNMP agent or command-line utilities. Discuss any enquiries arising from information on the NET-SNMP website with Support at nCipher before posting potentially sensitive information to the NET-SNMP website.

Activating the nCipher SNMP agent


The nCipher SNMP Agent enables other computers on the network to connect to it and make requests for information. The nCipher agent is based on the NET-SNMP kit, which has been tested but not fully reviewed by nCipher. nCipher strongly recommends that the nCipher agent is deployed only on a private network, or protected from the global Internet by an appropriate firewall. The nCipher SNMP agent is installed and activated separately. After installing the nCipher SNMP components, an activation command must be issued. This two-stage process is to avoid the inadvertent activation of SNMP capabilities that could supply management information from servers and nCipher modules that are not explicitly protected, or which could potentially expose the host computer to attacks on the nCipher SNMP agent itself.

nShield/payShield Administrator Guide Windows v5.5

362

F The nCipher SNMP monitoring agent

Default settings

Default settings
By default, installing nCipher support software for Windows 2000 or Windows 2003 also installs the nCipher SNMP agent but does not activate it. The nCipher SNMP agent can be specifically excluded from an nCipher installation by deselecting the box associated with the SNMP agent in the installation component list. The default installation directory for the nCipher Management Information Base (MIB) and the SNMP configuration files (snmp.conf and snmpd.conf) is %NFAST_HOME%\etc\snmp\.

Do you already have an SNMP agent running?


If you already have an SNMP agent running, you need to configure the ports used by the agents to avoid conflicts before enabling the nCipher SNMP agent. See the NET-SNMP project Web site: http://net-snmp.sourceforge.net/. A port is assigned by editing the agentaddress entry in the snmpd.conf file or by editing the defaultPort entry in snmp.conf. If both files have been edited, the agentaddress entry in snmpd.conf takes priority, and the defaultPort entry in snmp.conf is ignored.

Activation of the SNMP agent


To activate the nCipher SNMP agent: 1. 2. 3. Log in as Administrator. Open a command line window. Enter the following command:

e:\ncipher\devel\ncsnmp\src\ntbuild\agent\snmpd.exe -register [param list]

nShield/payShield Administrator Guide Windows v5.5

363

F The nCipher SNMP monitoring agent

Further Information

where param list is a list of startup parameters: see Useful nCipher SNMP agent command-line switches on page 382 for more details. This installs the agent as a Windows Service and also starts the new service. To de-activate and uninstall the nCipher SNMP agent, enter the following command:
e:\ncipher\devel\ncsnmp\src\ntbuild\agent\snmpd.exe -unregister

Further Information
Protecting the nCipher SNMP installation
The nCipher SNMP Agent allows other computers on the network to connect to it and make requests for information. The nCipher agent is based on the NET-SNMP code base, which has been tested but not fully reviewed by nCipher. nCipher strongly recommends that the nCipher agent be deployed only on a private network or protected from the global Internet by an appropriate firewall. The default nCipher SNMP installation allows read-only access to the Management Information Base (MIB) with any community string. There is no default write access to any part of the MIB. Every effort has been taken to ensure the confidentiality of cryptographic keys even when the SNMP agent is enabled. In particular, the nCipher module is designed to prevent the theft of keys even if the security of the host system is compromised, provided that the Administrator Cards are used only with trusted hosts. Care must be used when changing the configuration of the nCipher SNMP agent. nCipher strongly advises that you set up suitable access controls in snmpd.conf, or a firewall, to protect the agent and the information it can return.

nShield/payShield Administrator Guide Windows v5.5

364

F The nCipher SNMP monitoring agent

Further Information

Care has also been taken to ensure that malicious attackers are unable to flood your module with requests by flooding your SNMP agent. Command results from administration or statistics commands are cached, and therefore the maximum rate at which the agent sends commands to the module is throttled. See <Undefined CrossReference> for details on setting the cache time-outs.

Configuring the nCipher SNMP agent


The nCipher package uses various configuration files to configure its applications. This section describes the overall nature of the configuration files for the SNMP agent. If you are installing the nCipher SNMP agent to a host that has an existing, non-nCipher, SNMP agent installation, you may need to edit the SNMP configuration files (snmpd.conf and snmp.conf) associated with the nCipher SNMP agent to change the port on which the agent listens for SNMP requests. See Do you already have an SNMP agent running? on page 363. Note Make sure you protect the configuration files if you are storing sensitive information in them. By default, the nCipher SNMP configuration file (snmp.conf) is located in the $NFAST_HOME\etc\snmp\ directory. In this directory, the agent looks for files with the extension of .conf. Note The default search path can be overridden by setting the environment variable SNMPCONFPATH to a semi-colon (;) separated list of directories for which to search. For further information about SNMP configuration files, see the standard SNMP documentation available from the NET-SNMP project Web site: http://net-snmp.sourceforge.net/

nShield/payShield Administrator Guide Windows v5.5

365

F The nCipher SNMP monitoring agent

Further Information

Re-reading snmpd.conf and snmpd.local.conf


The nCipher SNMP agent can be forced to re-read its configuration files with an snmp set of integer(1) to enterprises.nCipher.reloadConfig.0(.1.3.6.1.4.1.7682.999.0).

The SNMP configuration file - snmp.conf


The snmp.conf configuration file contains directives that apply to all SNMP applications. These directives can be configured to apply to specific applications, see the standard SNMP documentation available from the NET-SNMP project Web site: http://netsnmp.sourceforge.net/. The snmp.conf configuration file is not required for the agent to operate and report MIB entries.

The SNMP agent configuration file - snmpd.conf


The snmpd.conf configuration file defines how the nCipher SNMP agent operates. It is required only if an agent is running. This file can contain any of the directives described in this section. The snmpd.conf file can also contain any of the directives available for use in the snmp.conf file. See the standard SNMP documentation available from the NET-SNMP project Web site: http://netsnmp.sourceforge.net/. The snmpd.conf file can also contain the following nCipher-specific directives:
statstimeout

This directive specifies the maximum length of time for which statistics commands are cached. The default is 60 seconds.
admintimeout

This directive specifies the maximum length of time for which administrative commands are cached. The default is 5 seconds.

nShield/payShield Administrator Guide Windows v5.5

366

F The nCipher SNMP monitoring agent

Using the nCipher SNMP agent with a manager application

keytable

This directive sets the initial state of the key table to none, all, or query. See listKeys in Administration sub-tree overview on page 369.

Using the nCipher SNMP agent with a manager application


Note The nCipher SNMP monitoring agent provides you with components that can be added to your (third-party) SNMP manager application. Every SNMP manager adds monitor components differently. Please consult the documentation supplied with your SNMP Manager application for details on how to add the nCipher MIB files.

Manager configuration
The manager application is the interface through which the user is able to perform network management functions. A manager communicates with agents using SNMP primitives (get, set, trap) and is unaware of how data is retrieved from, and sent to, managed devices. This form of encapsulation raises two main issues: the manager is hidden from all platform specific details the manager can communicate with agents running on any IPaddressable machine.

As a consequence, manager applications are generic and can be bought off the shelf. You may already be running SNMP managers, and if so, you can use them to query the nCipher agent. Note The manager is initially unaware of the MIB tree structure at a particular node. Managed objects can be retrieved or modified, but only if their location in the tree is known.

nShield/payShield Administrator Guide Windows v5.5

367

F The nCipher SNMP monitoring agent

Using the nCipher SNMP agent with a manager application

It is more useful if the manager can see the MIB tree present at each managed node. The MIB module descriptions for a particular node must be parsed by a manager-specific MIB compiler and converted to configuration files. These files are read by the manager application at run time. The nCipher SNMP agent is designed to monitor all current nCipher modules. The SNMP agent can monitor e-commerce accelerator and key management modules, working with all supported versions of nCipher firmware (contact Support at nCipher for details of supported firmware).

nCipher MIB module overview


A large proportion of the nCipher SNMP system is fully specified by the structure of the MIB; the behavior of the agent depends on relaying information according to the layout of the MIB. The nCipher MIB module resides at a registered location in the MIB tree determined by the Internet Assigned Numbers Authority (IANA). The private enterprise number of 7682 designated by the IANA corresponds to the root of the nCipher branch, and by convention this (internal) node is the company name. The MIB module groups logically related data together, organizing itself into a classification tree, with managed objects present at leaf nodes. The nC-series node (enterprises.nCipher.nC-series) is placed as a sub-tree of the nCipher root (enterprises.nCipher); this allows future product lines to be added as additional sub-trees. The structure of the tree underneath the registered location is vendor-defined, and this specification defines the structure chosen to represent nCipherspecific data.

MIB functionality
The nCipher MIB module separates module information into the following categories:

nShield/payShield Administrator Guide Windows v5.5

368

F The nCipher SNMP monitoring agent

Using the nCipher SNMP agent with a manager application

retrieval of status and information about installed nC-series modules retrieval of live statistics of performance of installed nC-series modules

These categories form the top-level nodes of the nCipher sub-tree; the functionality of the first category is in the administration sub-tree, and the second category is in the statistics sub-tree. The top-level tree also contains 3 items that it would be useful to check at-a-glance:
Node name
hardserverFailed

R/W
R

Type
TruthValue

Remarks
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. True if any modules have failed Percentage of total available capacity currently utilized

modulesFailed load

R R

TruthValue Unsigned32

Administration sub-tree overview


The administration sub-tree (enterprises.nCipher.nCseries.administration) contains information about the permanent state of the nCipher server and the connected modules. It is likely that most of the information in this branch rarely changes over time, unlike the statistics branch. The information given in the administration sub-tree is mostly acquired by the NewEnquiry command and is supplied both per-module and (where appropriate) aggregated over all modules.

nShield/payShield Administrator Guide Windows v5.5

369

F The nCipher SNMP monitoring agent

Using the nCipher SNMP agent with a manager application

The following table gives details of the individual nodes in the administration sub-tree.
Node name
SecurityWorld hardserverRunning

R/W
R R

Type
TruthValue Enum 1: Running 2: NotRunning Unsigned32 DisplayString Unsigned32 Unsigned32 DisplayString Enum 1: none 2: all 3: query 4: resetquery DisplayString Gauge DisplayString DisplayString

Remarks
True if a security world is installed and operational This variable reflects the current state of the hardserver (Running or NotRunning) Number of nC-series modules Hardserver version string Number of 1024-bit signatures per second Minimum and maximum recommended queues Security World display flags, as reported by
nfkminfo

noOfModules hsVersion [global]speedIndex [global]minQ [global]maxQ swState listKeys

R R R R R R/W

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. Supported hardserver facilities (the NewEnquiry level 4 flags) TCP port the hardserver is listening on Security worlds generation time ESN of the module that generated the security world

serverFlags remoteServerPort swGenTime swGeneratingESN

R R R R

listKeys can be preset using the keytable config directive in snmpd.conf (see <Undefined Cross-Reference>).

nShield/payShield Administrator Guide Windows v5.5

370

F The nCipher SNMP monitoring agent

Using the nCipher SNMP agent with a manager application

Security world hash sub-tree


The following table gives details of the nodes in the security world hash sub-tree (enterprises.nCipher.nCseries.administration.swHashes):
Node name
hashKNSO hashKM hashKRA hashKRE hashKFIPS hashKMC hashKP hashKNV hashKRTC hashKDSEE hashKFTO

R/W
R R R R R R R R R R R

Type
MHash MHash MHash MHash MHash MHash MHash MHash MHash MHash MHash

Remarks
Hash of the nCipher security officers key Hash of the security world key Hash of the recovery authorization key Hash of the recovery key pair Hash of the FIPS authorization key Hash of the module certification key Hash of the pass phrase recovery key Hash of the nonvolatile memory (NVRAM) authorization key Hash of the real time clock authorization key Hash of the SEE Debugging authorization key Hash of the Foreign Token Open authorization key

nShield/payShield Administrator Guide Windows v5.5

371

F The nCipher SNMP monitoring agent

Using the nCipher SNMP agent with a manager application

Security world quorums sub-tree


The following table gives details of the nodes in the security world quorums sub-tree (enterprises.nCipher.nCseries.administration.swQuorums):
Node name
adminQuorumK adminQuorumN adminQuorumM adminQuorumR adminQuorumP adminQuorumNV adminQuorumRTC adminQuorumDSEE adminQuorumFTO

R/W
R R R R R R R R R

Type
Unsigned Unsigned Unsigned Unsigned Unsigned Unsigned Unsigned Unsigned Unsigned

Remarks
The default quorum of admin cards The total number of cards in the admin cardset The quorum required for module reprogramming The quorum required to recover keys for operator card recovery The quorum required to recover the pass phrase for an operator card The quorum required to access nonvolatile memory (NVRAM) The quorum required to update the real time clock The quorum required to view full SEE debug information The quorum required to use a Foreign Token Open Delegate Key

nShield/payShield Administrator Guide Windows v5.5

372

F The nCipher SNMP monitoring agent

Using the nCipher SNMP agent with a manager application

Module administration table


The following table gives details of the nodes in the module administration table (enterprises.nCipher.nCseries.administration.moduleAdminTable):
Node name
moduleAdminIndex mode

R/W
R R

Type
Integer Enum 1: Operational 2: Pre-init 3: Init 4: Pre-maint 5: Maint 6: AccelOnly 7: Failed 8: Unknown DisplayString DisplayString DisplayString DisplayString DisplayString

Remarks
Module number of this row in the table Current module state

fwVersion serialNumber moduleType productName hwPosInfo

R R R R R

Firmware version string Module Electronic Serial Number (ESN) Module type code (only returned if module supports enquiry level 5) Hardware bus/slot info (such as PCI slot number). Modules only return a meaningful value if they support enquiry level 5. Indicates whether or not the module is in the current SW Description of smartcard in slot (empty, unknown card, admin/operator card from current SW, failed). N/A for acceleration only modules.

moduleSecurityWorld smartcardState

R R

TruthValue DisplayString

nShield/payShield Administrator Guide Windows v5.5

373

F The nCipher SNMP monitoring agent

Using the nCipher SNMP agent with a manager application

Node name
moduleSWState

R/W
R

Type

Remarks

Enum Current module and security world state 1: unknown 2: usable 3: maintmode 4: uninitialized 5: factory 6: foreign 7: accelonly 8: failed 9: unchecked 10: initmode 11: preinitmode 12: outofrange DisplayString MHash DisplayString DisplayString Gauge MHash Gauge DisplayString DisplayString DisplayString Security World flags for this module Hash of the modules secret key Features enabled on this module Like serverFlags, but per-module Firmware Version Security Number (VSN); see Version Security Number on page 323. KNETI hash, if present Max. rec. long queue Connection status (for imported modules) Connection information (for imported modules) SEE machine type

moduleSWFlags hashKML moduleFeatures moduleFlags versionSerial hashKNETI longQ connectionStatus connectionInfo machineTypeSEE

R R R R R R R R R R

nShield/payShield Administrator Guide Windows v5.5

374

F The nCipher SNMP monitoring agent

Using the nCipher SNMP agent with a manager application

Slot administration table


The following table gives details of the nodes in the slot administration table (enterprises.nCipher.nCseries.administration.slotAdminTable):
Node name R/W Type
Unsigned32 Unsigned32

Remarks
Module number of the module containing the slot Slot number (1-based, unlike nCore which is 0-based)

slotAdminModuleIndex R slotAdminSlotIndex slotType R R

Slot type Enum 1: Datakey 2: Smart card 3: Emulated 4: Soft token 5: Unconnected 6: Out of range 7: Unknown DisplayString Enum 1: Unused 2: Empty 3: Blank 4: Administrator 5: Operator 6: Unidentified 7: Read error 8: Partial 9: Out of range DisplayString Unsigned32 DisplayString Flags referring to the contents of the slot (from slotinfo)
Partial refers to cards in a partially-created

slotFlags slotState

R R

cardset.

slotListFlags slotShareNumber slotSharesPresent

R R R

Flags referring to attributes of the slot (from getslotlist) Share number of card currently in slot, if present Names of shares present in card currently in slot.

nShield/payShield Administrator Guide Windows v5.5

375

F The nCipher SNMP monitoring agent

Using the nCipher SNMP agent with a manager application

Cardset administration table


The following table gives details of the nodes in the cardset administration table (enterprises.nCipher.nCseries.administration.cardsetAdminTable):
Node name
hashKLTU cardsetName cardsetK cardsetN cardsetFlags cardsetNames cardsetTimeout cardsetGenTime

R/W
R R R R R R R R

Type
MHash DisplayString Unsigned32 Unsigned32 DisplayString DisplayString Unsigned32 DisplayString

Remarks
Hash of the token protected by the cardset

Required number of cards in the cardset Total number of cards in the cardset Other attributes of the cardset Names of individual cards, if set Token time-out period, in seconds, or 0 if none Generation time of cardset

Key administration table


The key administration table is visible as long as the listKeys node in the administration sub-tree is set to a value other than none.

nShield/payShield Administrator Guide Windows v5.5

376

F The nCipher SNMP monitoring agent

Using the nCipher SNMP agent with a manager application

The following table gives details of the nodes in the key administration table (enterprises.nCipher.nCseries.administration.keyAdminTable):
Node name
keyAppname keyIdent keyHash keyRecovery

R/W
R R R R

Type
DisplayString DisplayString MHash Enum 1: Enabled 2: Disabled 3: No key 4: Unknown 5: Invalid 6: Unset Enum 1: Module 2: Cardset 3: No key 4: Unknown 5: Invalid 6: Unset MHash DisplayString Unsigned32 DisplayString DisplayString Gauge Gauge

Remarks
Application name Name of key, as generated by the application Required and total number of cards in the cardset The value unset is never returned by the key table. It is used in the key query field to mean do not care.

keyProtection

The value unset is never returned by the key table. It is used in the key query field to mean do not care.

keyCardsetHash keyFlags keyExtraEntities keySEEInteg keyGeneratingESN keyTimeLimit keyPerAuthUseLimit

R R R R R R R

Hash of the cardset protecting the key, if applicable Certificate and public key flags Number of extra key attributes. SEE integrity key, if present ESN of the module that generated the key, if present Time limit for the key, if set Per-authentication use limit for the key

Key query sub-tree


The key query sub-tree is used if the listKeys node in the administration sub-tree is set to query.

nShield/payShield Administrator Guide Windows v5.5

377

F The nCipher SNMP monitoring agent

Using the nCipher SNMP agent with a manager application

If these values are set, they are taken as required attributes for filtering the list of available keys; if multiple attributes are set, the filters are combined (AND rather than OR). The following table gives details of the nodes in the key query subtree (enterprises.nCipher.nC-series.administration.keyQuery):
Node name
keyQueryAppname keyQueryIdent keyQueryHash keyQueryRecovery

R/W
R/W R/W R/W R/W

Type
DisplayString DisplayString DisplayString Enum 1: Enabled 2: Disabled 3: No key 4: Unknown 5: Invalid 6: Unset Enum 1: Module 2: Cardset 3: No key 4: Unknown 5: Invalid 6: Unset DisplayString DisplayString Unsigned32 DisplayString DisplayString Gauge Gauge

Remarks
Application name Name of key, as generated by the application Required and total number of cards in the cardset The value unset is never returned by the key table. It is used in the key query field to mean do not care.

keyQueryProtection

R/W

The value unset is never returned by the key table. It is used in the key query field to mean do not care.

keyQueryCardsetHash keyQueryFlags keyQueryExtraEntities keyQuerySEEInteg

R/W R/W R/W R/W

Hash of the cardset protecting the key, if applicable Certificate and public key flags Number of extra key attributes SEE integrity key, if present ESN of the module that generated the key, if present Time limit for the key, if set (0 for no limit) Per-authentication use limit for the key (0 for no limit)

keyQueryGeneratingES R/W N keyQueryTimeLimit R/W

keyQueryPerAuthUseL R/W imit

nShield/payShield Administrator Guide Windows v5.5

378

F The nCipher SNMP monitoring agent

Using the nCipher SNMP agent with a manager application

Statistics sub-tree overview


The statistics sub-tree (enterprises.nCipher.nC-series.statistics) contains rapidly-changing information about the state of the nCipher modules, the work they are doing, the commands being submitted, and so on. Note Do not rely on information returned from the agent to change instantaneously on re-reading the value. To avoid loading the nCipher module with multiple time-consuming statistics commands, the agent can choose to cache the values over a specified period. You can configure this period in the agent configuration file (see The SNMP agent configuration file - snmpd.conf on page 366).

Statistics sub-tree and module statistics table


The following table gives details of the nodes in the statistics sub-tree, and the module statistics table (enterprises.nCipher.nCseries.statistics.moduleStatsTable):
Node name
moduleStatsIndex [hs]uptime cmdCount[All]

R/W
R R R

Type
Integer Counter32 Counter32

Remarks
Module number of this row (for
moduleStatsTable)

Uptime of the hardserver or module Returned aggregated for all modules and all commands, and per-module for all commands

cmdBytes[All] cmdErrors[All]

R R

Counter32 Counter32 Returned as for cmdCount. When permodule total, aggregate all the different error states into one counter. When aggregated, returned value is combined module errors added to hardserver marshalling/unmarshalling errors.

replyCount[All] replyBytes[All] replyErrors[All]

R R R

Counter32 Counter32 Counter32 see notes above for cmdErrors

nShield/payShield Administrator Guide Windows v5.5

379

F The nCipher SNMP monitoring agent

Using the nCipher SNMP agent with a manager application

Node name
clientCount maxClients deviceFails deviceRestarts load[All] outstandingCmds objectCount clock

R/W
R R R R R R R R

Type
Counter32 Counter32 Counter32 Counter32 Counter32 Counter32 Counter32 DisplayString

Remarks

Total no. of outstanding commands over all modules

Depending on the module settings, this can require KNSO permissions to read (and therefore depend on the installation parameters of the agent) Character representation of the current temp value (SNMP does not provide for a floating-point type) Maximum temperature the module has ever reached

currentTemp

DisplayString

maxTemp nvRAMInUse volatileRAMInUse

R R R

DisplayString Counter32 Counter32

netHSM statistics table


The following table gives details of the nodes in the netHSM statistics table (enterprises.nCipher.nC-series.statistics.netHSMStatsTable):
Node name
netHSMStatsIndex netHSMUptime netHSMCPUUsage netHSMUserMem netHSMKernelMem netHSMCurrentTemp netHSMMaxTemp

R/W
R R R R R R R

Type
Integer Counter32 Gauge32 Gauge32 Gauge32 DisplayString DisplayString

Remarks
Table index (not module number) netHSM host system uptime CPU usage of netHSM host processor Total user memory of netHSM Total kernel memory of netHSM Internal netHSM temperature (sensor 1) Max. recorded temp (sensor 1)

nShield/payShield Administrator Guide Windows v5.5

380

F The nCipher SNMP monitoring agent

Using the nCipher SNMP agent with a manager application

Node name
netHSMCurrentTemp2 netHSMMaxTemp2 netHSMPower5V netHSMPower12V netHSMFanSpeed netHSMFan2Speed netHSMFan3Speed netHSMIPAddress netHSMDescription

R/W
R R R R R R R R R

Type
DisplayString DisplayString DisplayString DisplayString Gauge32 Gauge32 Gauge32 IpAddress DisplayString

Remarks
Internal netHSM temperature (sensor 2) Max. recorded temp (sensor 2) netHSM 5V power reading netHSM 12V power reading Fan 1 speed (RPM) Fan 2 speed (RPM) Fan 3 speed (RPM) IP address of netHSM Textual description of module (for example, Local module #3)

Software versions table


The following table gives details of the nodes in the software versions table (enterprises.nCipher.softwareVersions.softwareVersionsTable); see ncversions on page 257:
Node name
compIndex compName compOutput compMajorVersion compMinorVersion compPatchVersion compRepository compBuildNumber

R/W
R R R R R R R R

Type
Integer DisplayString Component output name Gauge Gauge Gauge DisplayString Gauge

Remarks
Table index Component name Component name

Repository name

nShield/payShield Administrator Guide Windows v5.5

381

F The nCipher SNMP monitoring agent

Useful nCipher SNMP agent command-line switches

Useful nCipher SNMP agent command-line switches


SNMP agent (snmpd) switches
The SNMP agent that binds to a port and awaits requests from SNMP management software is snmpd. Upon receiving a request, snmpd processes the request, collects the requested information and/or performs the requested operation(s) and returns the information to the sender. The nCipher SNMP agent supports a limited subset of command line switches that can be specified when starting the agent.

Usage
e:\ncipher\devel\ncsnmp\src\ntbuild\agent\snmpd.exe -register [param list] | -unregister | [-h] [-v] [-f] [-a] [-d] [-V] [-P PIDFILE):] [-q] [-D] [-p NUM] [-L] [-l LOGFILE] [-r]

In this command:
-h

This option displays a usage message.


-register [param list]

This option registers the agent as a Windows service, and starts the service.
param list is a startup parameter list for service, the same as

normal parameters, for example


snmpd.exe -register -p 2002

registers snmpd.exe as service, which listens on port 2002.

nShield/payShield Administrator Guide Windows v5.5

382

F The nCipher SNMP monitoring agent

Useful nCipher SNMP agent command-line switches

Some options do not make sense when the agent is running as service.
-unregister

This option unregisters the service if it is already registered.


-H

This option displays the configuration file directives that the agent understands.
-v

This option displays version information.


-f

This option specifies not forking from the calling shell.


-a

This option specifies logging addresses.


-d

This option specifies the dumping of sent and received UDP SNMP packets.
-V

This option specifies verbose display.


-P PIDFILE

This option specifies the use of a file (PIDFILE) to store the process ID.
-q

This option specifies that information be printed in a more parsable format (quick print).

nShield/payShield Administrator Guide Windows v5.5

383

F The nCipher SNMP monitoring agent

Useful nCipher SNMP agent command-line switches

-D

This option turns on debugging output.


-p NUM

This option specifies running on port NUM instead of the default: 161.
-c CONFFILE

This option specifies reading CONFFILE as a configuration file.


-C

This option specifies that the default configuration files not be read.
-L

This option prints warnings/messages to stdout/err.


-s

This option logs warnings/messages to syslog.


-r

This options specifies not exiting if root-only accessible files cannot be opened.
-I [-]INITLIST

This option specifies a list of MIB modules to initialize (or not). Runsnmpd with -Dmib_init for a list.
-l LOGFILE

This option prints warnings/messages to a file LOGFILE (by default, LOGFILE=log/snmpd.log).

nShield/payShield Administrator Guide Windows v5.5

384

F The nCipher SNMP monitoring agent

Using the SNMP command line tools

Using the SNMP command line tools


As an alternative to using an SNMP manager application, nCipher supplies several command-line utilities to test your SNMP installation and that enable you to obtain information about your nCipher module from the nCipher SNMP agent:
snmptest

This utility monitors and manages SNMP information.


snmpget

This utility queries for SNMP information on a network entity.


snmpset

This utility sets SNMP information on a network entity.


snmpgetnext

This utility queries for SNMP information on a network entity.


snmptable

This utility obtains and prints an SNMP table.


snmptranslate

This utility translates SNMP objects into something more useful.


snmpwalk

This utility communicates with a network entity using GET NEXT request.

nShield/payShield Administrator Guide Windows v5.5

385

F The nCipher SNMP monitoring agent

Using the SNMP command line tools

snmpbulkwalk

This utility communicates with a network entity using BULK request. These tools are general purpose SNMP utilities and can be configured for use with other SNMP agents. For more information on configuring and using these tools, refer to the NET-SNMP project Web site: http://net-snmp.sourceforge.net/.

nShield/payShield Administrator Guide Windows v5.5

386

nCipher addresses
nCipher Corporation Ltd.
Cambridge, UK
Jupiter House Station Road Cambridge CB1 2JD UK Tel: Fax: +44 (0) 1223 723600 +44 (0) 1223 723601

nCipher Inc.
Boston Metro Region, USA
92 Montvale Avenue, Suite 4500 Stoneham, MA 02180 USA

Tel:

Fax: E-mail: sales@ncipher.com support@ncipher.com E-mail:

800-NCIPHER 800-6247437 +1 (781) 994 4000 +1 (781) 994 4001 sales@us.ncipher.com support@ncipher.com

Internet addresses
Web Site: Online Documentation: http://www.ncipher.com/ http://active.ncipher.com/documentation/

Note

nCipher also maintain international sales offices. Please contact the UK, or the US, head office for details of your nearest nCipher representative.

S-ar putea să vă placă și