Documente Academic
Documente Profesional
Documente Cultură
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.
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:
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
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
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
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
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
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
Chapter 1: Introduction
General information
This guide describes how to use an nShield, payShield or payShield Ultra hardware security module (or HSM) to protect and accelerate the performance of the longterm cryptographic keys that are used by your applications, including payment and related applications on payShield modules. In this guide, the term nShield refers to any of the nShield, payShield or payShield Ultra modules. Information specific to the payShield and payShield Ultra modules is clearly marked. nCipher modules use the security world paradigm to provide a secure environment with both application independence and platform independence for all your module and key management operations. Security worlds have the flexibility and scalability to suit your needs, while also providing the robustness that is needed for every day operation as a key component in your IT infrastructure. Standard nCipher security worlds need to be prepared for use with payShield applications. Although it is possible to convert an existing security world for use with payShield, nCipher recommends that you create a new security world and then follow the instructions in payShield security world properties on page 191. Be sure to create back up copies of any existing data in your kmdata directory before creating a new security world, or attempting to convert an existing security world. All nCipher modules support standard cryptography frameworks and can be quickly integrated with many standards based products.
10
1 Introduction
Audience
Audience
Read this guide if you need to configure or administer an nShield or payShield module, and you use or require an nCipher security world to protect your keys. This guide assumes that you are familiar with the basic concepts of cryptography and Public Key Infrastructure (PKI). This guide assumes that you have read the Hardware Installation Guide and that you have installed your nShield or payShield module.
11
1 Introduction
Chapter 9: Using CodeSafe Applications describes CodeSafe applications. Chapter 10: Using KeySafe introduces KeySafe, nCiphers security world management tool. Chapter 11: Managing security worlds contains detailed information about working with security worlds, including adding a module to an existing security world. Chapter 12: About payShield installations describes how to configure a payShield installation. Chapter 13: Remote Operator Card Sets describes the use of Remote Operator card sets. Chapter 14: Administration tasks with cards and softcards describes how to perform card-management tasks that require an Administrator Card Set. Chapter 15: nShield Administrator Utilities describes the utilities that are used in this manual. Appendix B: Components on nCipher CD-ROMs lists the contents of the standard bundles and the additional software supplied on your nCipher CD-ROM. Appendix A: Upgrading module firmware describes how to upgrade your nCipher module if nCipher has supplied updated firmware. Appendix E: Installed Utilities lists all the utilities installed with the nCipher software. Appendix F: The nCipher SNMP monitoring agent describes how to use the supplied Simple Network Management Protocol (SNMP) agent with your nCipher module.
12
1 Introduction
Conventions
Conventions
nCipher modules
The following terms are used to distinguish different module versions:
Term
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
nC3033P-1600
13
1 Introduction
Conventions
Version numbers
The version number shown on the copyright page and at the bottom of each page in this guide is the version number of this document. Please quote this version number if you contact Support at nCipher with queries about nCipher documentation.
nCipher software
The hardserver software controls communication between applications and nCipher modules, which may be installed locally or remotely. It runs as a service on the host computer. The nCipher support software is a collection of programs and utilities, including the hardserver, supplied by nCipher to install and maintain your nCipher security system.
Default directory
By default, nCipher software is installed in the /opt/nfast/ (Unix) or C:\nfast (Windows) directory, referred to as the nCipher directory. Instructions in this guide are given on the assumption that nCipher software was installed in this location. If you install the software in another directory, you must set the environment variable NFAST_HOME to point to the directory where the software is installed. You can choose to install nCipher software in another location, in which case you must substitute your location accordingly. An environment variable, NFAST_HOME, is used to specify the default location for nCipher software. For further information on setting environment variables, refer to Setting the environment variables on page 49.
14
1 Introduction
Conventions
Typographical conventions
Note The word Note in the margin indicates the appearance of important supplemental information. If there is a danger of static damage, this is indicated by the reaching hand symbol in the margin. If there is a danger of loss or exposure of key material (or any other security risk), this is indicated by a security triangle in the margin. If there is a danger of damage to the hardware, this is indicated by a caution triangle in the margin. If you see this symbol on the product itself, please refer to the Hardware Installation Guide. If there is a danger of electric shock to the user, this is indicated by a warning triangle in the margin. Examples of onscreen terminal display, both of data returned and of your input, are represented in a form like this:
install
Keyboard keys that you must type are represented like this: Enter , Ctrl - C .
15
1 Introduction
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.
16
1 Introduction
Further information
The Java Generic Stub classes, nCipher KM JCA/JCE provider classes, and Java Key Management classes are supplied with HTML documentation in standard Javadoc format, which is installed in the appropriate nfast/java directory when you install these classes. nCipher also supplies a performance tool that you can use to test Web server performance both with and without an nCipher module in order to confirm performance. This tool is supplied separately. If you require a copy, contact your nCipher sales representative. All nCipher product documentation, including a range of guides that describe how to configure popular third-party applications, is available from the nCipher web site: http://active.ncipher.com/documentation/. If you would like to receive security advisories from nCipher, please subscribe to the low volume nCipher security-announce mailing list. To do this, send a mail with the single word subscribe in the message body to security-announce-request@ncipher.com. If you cannot find the information you need or you are unable to solve a problem with your nCipher module, contact Support at nCipher by sending E-mail to support@ncipher.com.
17
The security world infrastructure lets you perform and control all these activities under your chosen security policy. A security world consists of: one or more nCipher payShield, nForce, nShield, or netHSM modules
18
a set of Administrator smart cards used to control access to security world configuration and recovery operations. (Security worlds compliant with the Federal Information Processing Standards (FIPS) 140-2 at level 3 require the use of smart cards to authorize most operations; see FIPS 140-2 compliance on page 23 for more information about nCipher and FIPS.) an optional set or sets of Operator smart cards used to control access to application keys. (Security worlds compliant with the Federal Information Processing Standards (FIPS) 140-2 at level 3 require the use of smart cards to authorize most operations; see FIPS 140-2 compliance on page 23 for more information about nCipher and FIPS.) some cryptographic key and certificate data that is encrypted using the security world key and stored on a host computer or computers.
Figure 1 shows how these components are related to one another. Cards, keys, and even modules can be added or removed at any time. These elements are linked by the security world key, which is unique to each world. Distributing the keys used for different tasks within the security world over different storage media means that a security world can recover from the loss of any one element. It also increases the difficulties faced by an attacker, who needs to obtain all the elements before gaining any information.
19
Security
Figure 1
Security
Most importantly, a key-management system must store keys securely. Security must be designed into the system from the start; it cannot be added later. The nCipher security world has been designed to ensure that keys remain secure throughout their life cycle. The security world uses multiple interlocking keys, and because of this, each key is always protected by another key, even during recovery operations.
20
Security
Because the security world is built around nCipher key-management modules, keys are only ever available in plain text in secure hardware. The security world uses smart cards for two different purposes: Note one set of cards forms an Administrator Card Set that is used to control access to recovery functions one or more sets of cards referred to as Operator Card Sets that are used to control access to application keys.
In strict FIPS 140-2 Level 3 security worlds, the Administrator Card Set or an Operator Card Set is needed to authorize most operations, including the creation of keys and Operator Card Sets. Each card set consists of a number of smart cards, N, of which a smaller number, K, is required to authorize an action. The required number is sometimes referred to as the threshold.
Note
The value for K is intended to be less than N. Although it is possible for K to equal N, this is not recommended because an error on one card renders the whole card set unusable. If this happens with your Administrator Card Set, you are forced to replace your security world and generate new keys. An Administrator Card Set is used to authorize several different actions, and each of these can have a different value for K. All the card sets are distinct; an individual smart card can only belong to the Administrator Card Set or to one Operator Card Set. Each user can access the keys protected by the security world and the keys protected by their Operator Card Set. They cannot access keys that are protected by other Operator Card Sets. The smart cards that are used as Operator Cards employ the security world key to perform a challenge-response protocol with the module. This means that Operator Cards can only be used by a module belonging to the same security world that they do.
Note
An individual smart card can be used as either a part of the Administrator Card Set or as part of an Operator Card Set, but not as part of both.
21
Security
22
Security
23
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
24
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.
25
Flexibility
26
Flexibility
27
Flexibility
working card fails, retrieve the spare card from the safe and use it until you re-create a new set of two cards, as described in Replacing an Operator Card Set or recovering keys to softcards on page 32. Note You can only recover card sets that were created with the recovery option explicitly set.
28
Flexibility
Keys that are protected by a given Operator Card Set cannot be shared simultaneously between a large pool of modules. Therefore, the security world architecture gives you the option of making an Operator Card Set persistent. This means that the keys protected by a card persist after the card has been removed. This enables you to use the same smart card in several modules simultaneously. It also means that several users can load keys onto the same module at the same time. The nCipher support software maintains strict separation between the keys loaded by each user, and each user only has access to the keys protected by their Operator Card Set. Keys protected by a persistent card are automatically removed from the module: Note when the application that loaded the Operator Card Set closes the connection to the module. after a time limit that may be specified when the card set is created. when an application chooses to remove a key.
Some applications automatically remove a key after each use, reloading it only when required. Such applications do not benefit from persistent Operator Cards. The only way of sharing keys between modules for these applications is by having multiple smart cards in an Operator Card Set. Although the module stores the key, the key is only available to the application that loaded it. If you want to use keys protected by this card in another application, you must re-insert the card, and enter its pass phrase if it has one. Certain applications are designed to allow only one user to be logged in at a time, in which case they remove any previously loaded persistent Operator Card Set used in that application before allowing the user to log into with a new Operator Card Set.
29
Flexibility
You can manually remove all keys protected by persistent cards by pressing the modules Clear button or by turning off power to the module. Either process removes all keys protected by Operator Card Sets from the module, including the card in the reader. In such cases, all users of any applications using the module must log in again. You are offered a choice as to whether or not to make an Operator Card Set persistent when you create the card set. Once you have made the decision, you cannot change it. Persistence is a property of the card set. A security world can contain a mix of persistent and non-persistent card sets.
30
Robustness
Robustness
If you are using cryptography in a production environment, you need to know that it will work 24 hours a day, 7 days a week. If something goes wrong, you must be able to recover without compromising your security. An nCipher security world offers all of these features.
31
Robustness
Replacing a module
If you have a problem with a module, you can replace it with a new module by using the Administrator Card Set and the recovery data to load the security world key securely. Use the same mechanism to reload the security world key if you need to upgrade the firmware in the module or if you need to add extra modules to the security world.
32
Robustness
Similarly, you can recover keys protected by one softcard to another softcard. Note The ability to recover an Operator Card Set is an option that is enabled by default during security world creation. To disable recoverability, you must explicitly choose to do so during the security world creation process. Once set during security world creation, the ability (or inability) to recover an Operator Card Set can never be altered. 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
33
Scalability
Similarly, if you choose to create recovery data when you generate the security world or key, it cannot be removed later in a secure manner. The recovery data for application keys is kept separate from the recovery data for the security world key. The security world always creates recovery data for the security world key. It is only the recovery of application keys that is optional.
Scalability
A security world is scalable. You can add multiple modules to a server and share a security world across multiple servers. You can also add Operator Card Sets and application keys at any time. You do not need to make any decisions about the size of the security world when you create it. To share a security world across multiple servers: ensure each server has at least one module fitted copy the host data to each server or make it available on a shared disk use the recovery data and the Administrator Card Set to load the required cryptographic keys securely onto every module.
If you want to have access to the same keys on every server, you must ensure that all changes to the data are propagated to the remaining servers. If your are part of a cluster, then the tools provided by the cluster should synchronize the data. If the servers are connected by a network, then they could all access the same copy of the data. There is no risk of an attacker obtaining information by snooping on the network, as the data is only ever decrypted inside a module. Alternatively, you can maintain copies of the data on different servers. It is now possible to allow non-netHSM modules to automatically access the remote file system (RFS) used by netHSM and payShield NET modules and to share security world and key data stored in the
34
kmdata directory. Client modules that access data in this way are
described as cooperating clients. See Setting up client cooperation on page 53 for more information.
Load sharing
If you have more than one module on your system and you load the same key onto each module, your nCipher-aware applications can make use of the load sharing features in the nCipher server to share the cryptography between them. Note It is up to the application to implement load sharing. Some applications may not be able to make use of this feature.
35
Note
create a security world and its Administrator Card Set, either FIPS 140-2 level 2 or level 3
This option provides compliance with the roles and services of the FIPS 140- 2 level 3 standard. It is included for those customers who have a regulatory requirement for compliance. add a module to a security world remove a module from a security world replace an Administrator Card Set create Operator Card Sets list the Operator Card Sets in the current security world change the pass phrase on an Operator Card remove a lost Operator Card Set from a security world replace Operator Card Sets erase an Operator Card add a new key to a security world import a key into a security world list the keys in the current security world delete a key from a security world.
KeySafe does not provide tools to back up and restore the host data or update module firmware, nor does KeySafe provide tools to synchronize host data between servers. These functions can be performed with your standard system utilities. In addition to KeySafe, nCipher also supplies command-line utilities to manage the security world. Current versions of these tools can be used interchangeably with the current version of KeySafe.
36
37
Risks
Risks
Even the best-designed tools cannot offer security against every risk. Although a security world can control which user has access to which keys, it cannot prevent a user from using a key fraudulently. For example, a security world can only determine whether a user is authorized to use a particular key; it cannot determine whether the message being sent with that key is accurate. A security world can only manage keys that were created inside the security world; keys created outside a security world, even if imported into the security world, may remain exposed to a security risk. Most failures of security systems are not the result of inherent flaws in the system, but result from carelessness on the part of the users. The following basic rules apply to any security system: Note Keep your smart cards safe. Always obtain smart cards from a trusted source: from nCipher or directly from Gemplus. Never insert a smart card used with nCipher key management into an untrusted smart card reader. Never insert any untrusted smart card into your module. Never tell anyone your pass phrase. Never write down your pass phrase. Never use a pass phrase that is easy to guess. Only use the Administrator Card Set in modules connected to trusted hosts.
If you have any doubts about the security of a key and/or security world, you should replace that key and/or security world with a newly generated one.
38
3. 4.
5.
6. 7. 8.
39
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.
40
41
The nCipher Windows install wizard determines whether you have a Java Runtime Environment (JRE) installed by examining the registry. Any warnings displayed by the installer apply to this JRE. If you intend to use a JRE not defined in the registry (for example, if you have multiple JREs installed), check that this JRE version is compatible with nCipher support software.
You must install the hwsp Hardware Support bundle. If the hwsp Hardware Support bundle is not installed, your module cannot function. Note The nfdrv Windows device drivers component, required if you are using an nCipher PCI card, is installed as part of the hwsp Hardware Support bundle.
42
Additionally, nCipher recommends that you always install the ctls Core Tools bundle, which contains all the nCipher command-line utilities, including generatekey, low level utilities, and test programs. Note The Core Tools bundle includes the tclsrc Tcl run time component that installs a run-time Tcl installation within the nCipher directories. This is used by nCiphers tools for creating the security world, by KeySafe, and by the new-world utility. This does not affect any other installation of Tcl on your computer. See Appendix B: Components on nCipher CD-ROMs for details of the optional components. Ensure that you have identified those that you require before you start the installation.
43
nCipher supplies Windows 2000 Plug and Play drivers for the nCipher module. These drivers have also been tested with Windows 2003 Server. Take the following steps to install the nCipher server and associated software: 1. 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.
44
you require. See Appendix B: Components on nCipher CD-ROMs for more information about choosing which components to install. By default, the installer places files in the C:\nfast directory, but you are given the option of selecting a different directory. If the installer detects an existing installation in a different directory, it offers this other directory as the default. 5. Note 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.
45
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.
46
3.
Verify that the server is running by using the following test command (assuming that you installed the nCipher server in the default directory):
C:\nfast\bin\enquiry
A successfully completed enquiry command returns output of a form similar to the following:
server: enquiry reply flags none enquiry reply level Four serial number ####-####-#### mode operational version #.#.# speed index ### rec. queue ##..## ... module #1: ... mode operational version #.#.# ... connection status OK
The enquiry utility returns information on the nCipher server and on each module. The serial number returned is the electronic serial number. This number is unique to each module. Keep a record of the electronic serial number: you must quote it if you ever need to contact Support at nCipher. The version number for the server is the nCipher internal release number of the server software. The version number for the module is the nCipher internal release number of the firmware.
If the enquiry utility returns an error message, refer to the troubleshooting chapter in the Hardware Installation Guide.
47
In this command, MODULE is the number of the module and SLOT is the number of the slot. If you have only one module, MODULE is 1, and if you do not specify a slot number, slotinfo returns information about all slots. This command should return either:
Module n slot 0: Token not formatted
48
or
Module n slot 0: Authentication key: 00000000-00000000-00000000-00000000-00000000 No data on token 3698 bytes free
Note
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 .
49
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.
50
Note
If none of these logging environment variables are set, the default behaviour is to log nothing, unless this is overridden by any individual library. If any of the four logging variables are set, all unset variables are given default values. Some components of the nCipher Support Software generate separate debugging information which you can manage differently. If you are setting up the module in order to develop software that uses it, you should configure debugging at this point. Otherwise, you should proceed to Creating and configuring a security world on page 56. Detailed information about controlling logging information by means of these environment variables is supplied in Appendix D: Logging and debugging.
51
The hardserver can handle transactions for multiple modules. This does not require configuration of the hardserver; see Chapter 7: Using multiple modules for information. The hardserver must be configured to control: the way the hardserver communicates with remote modules the way the hardserver communicates with local modules the import and export of remote slots the loading of SEE machines on to the module when the hardserver starts up.
The hardserver configuration file defines the configuration of the hardserver. It is stored in the directory %NFAST_HOME%\kmdata\config, which by default is C:\nfast\kmdata\config. A default version of this file is created when the nCipher support software is installed. See Chapter 6: Configuring the hardserver for full information about the hardserver configuration file. Note In some previous releases of nCipher support software, hardserver configuration was controlled by environment variables. The use of these variables has been deprecated. If any of these environment variables are still set, they override the settings in the configuration file. You must load the configuration file for the changes to the configuration to take effect. To configure the hardserver, follow these steps: 1. Save a copy of the configuration file
C:\nfast\kmdata\config\config so that the configuration can be
restored if necessary. 2. Edit the configuration file C:\nfast\kmdata\config\config to contain the required configuration. (See Hardserver configuration file on page 85 for descriptions of the options in the configuration file.)
52
3. 4.
Run the cfg-reread command-line utility to load the new configuration. See cfg-reread on page 228 for details. Test that the hardserver is configured correctly by running the
enquiry command-line utility. (See enquiry on page 229 for full details of the enquiry command-line utility and its output.)
Check that a module with the correct characteristics appears in the output. 5. Test that the client has access to the security world data. To do this, run the nfkminfo command-line utility. Check that a module with the correct ESN appears in the output and has the state 0x2 Usable.
2.
53
For clients that use a local KNETI (the nCipher integrity key, which is installed when the module is shipped) for authorization and which are to be given write access to the remote file system, run the command:
For clients that do not have a local KNETI and require write access, run the command:
In these commands, rfs.rfs.rfs.rfs is the IP address of the machine where the remote file system is located. Note The rfs-sync utility uses lock files to ensure that updates are made in a consistent fashion. If a rfs-sync --commit operation (the operation that writes data to the remote file system) fails due to a crash or other problem, it is possible for a lock file to be left behind. This would cause all subsequent operations to fail with a lock timeout error.rfssync has options for querying the current state of the lock file, and for deleting the lock file; however, these should only be used if necessary to resolve this problem. Clients without write access cannot delete the lock file. To remove a cooperating client so the remote file system no longer recognizes it, you must: know the IP address of cooperating client you want to remove
54
manually update the remote_file_system section of the hardserver configuration file by removing the following entries for that particular client:
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
Useful utilities
To find out the ESN and the hash of the KNETI key for a given IP address, use the anonkneti command-line utility. A manual doublecheck is recommended for security. A client can use rfs-sync --show to display the current configuration, or rfs-sync --remove to revert to a stand-alone configuration. Reverting to a stand-alone configuration leaves the current contents of the kmdata directory in place. See rfs-sync on page 304 for more information.
55
On some internal modules, you must access the initialization link or switch on the module. With such modules, always shut down your computer and turn off the power before opening the case. Replace the case before reconnecting the power. You normally create a security world when you first install the module. If you wish use the module to protect a different set of keys, you can replace the security world with another one. The process of creating a security world: erases the module creates a new module key for this security world creates a new Administrator Card Set to protect this module key
56
stores the security world information on the computers hard disk, or in the case of netHSM, the operating systems filesystem and the remote filesystem. The information is encrypted using the secrets stored on the Administrator Card Set.
Any Operator Cards created in a previous security world cannot be used in the new security world. If you are replacing a security world, you must erase all the Operator Cards created in the previous security world before you create the new world. You can create a security world from the command line with the newworld utility, as described here. Alternatively, you can use KeySafe (as described in Creating a security world with KeySafe on page 131), or the nCipher CSP wizard, as described in Creating the security world using the CSP wizard on page 139.
In this command:
57
-i, --initialize
These options tell new-world to initialize a new security world, replacing any existing kmdata directory. Note Replacing an existing security world in this way does not delete the security worlds host and recovery data, but renames the existing kmdata directory in which these reside as kmdata_nn (where nn is an integer, 0 or greater, depending on how many security worlds have been previously saved during overwrites).
-S, --no-remoteshare-cert
These options tell new-world to not to make the module a target for remote shares.
-o, --overwrite
These options tell new-world to overwrite smart cards without prompting. Any existing data will be erased. If a value for this flag is not specified, new-world will prompt you if a card contains data. This option does not enable you to reuse Operator Cards from other security worlds.
-F, --strict-fips-140-2-level-3
These options tell new-world to create a security world that conforms to the FIPS 140-2 requirements for roles and services at level 3. If you do not specify this flag, new-world creates a security world that complies with FIPS 140-2 requirements for level 2. Note 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.
58
By default, new-world creates key-recovery material that is protected by the cryptographic keys on the Administrator Card Set. This option does not give nCipher or any other third party access to your keys. Keys can only be recovered by using the Administrator Cards. nCipher recommends that you leave Operator Card Set recovery enabled. If you set the --no-recovery option, you will not be able to replace lost or damaged Operator Card Sets and therefore will not be able to access the keys that are protected by such cards. Key recovery cannot be enabled later without reinitializing your security world and discarding all your existing keys. Note All keys are recoverable unless otherwise specified at key generation, even PKCS #11 keys that have the sensitive flag set to TRUE or extractable flag set to FALSE.
-tTIMEOUT, --nso-timeout=TIMEOUT
These options allows you to specify the time-out (TIMEOUT) for new security worlds. By default, an integer given for TIMEOUT is interpreted in seconds, but you can supply values for TIMEOUT in the form Ns, Nh, or Nd where N is an integer and s specifies second, h specifies hours, and d specifies days.
-m, --module=MODULE
These options specify the ModuleID to use. new-world initializes only one module at a time. If you have multiple modules, you must run new-world with --initialize for the first module, and then run new-world with --program for the other modules; see new-world on page 259.
-Q, --acs-quorum=K/N
In these options, K specifies the minimum number of smart cards needed from the Administrator Card Set in order to authorize a feature. You can specify lower K values for a particular feature. All the K values must be less than or equal
59
to the total number of cards in the set. If a value for K is not specified, new-world creates an Administrator Card Set that requires a single card for authorization. Note Some applications do not have mechanisms for requesting that cards be inserted. Therefore any Operator Card Sets that you create for use with these applications must have K=1. 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.
60
You can specify multiple features as a comma-separated list of terms. Each term consists of a feature name, optionally preceded by either a dash (-) or an exclamation point (!) to turn off the feature and can optionally be followed by an equals sign (=) and the threshold for this feature. Note The ! character is interpreted by some shells as history expansion and must be escaped with a backslash, \\!. The dash may be interpreted as being the start of an command-line option unless you have used the f option or specified a module without including the -m flag. 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 Operator Card Set recovery (see Replacing an Operator Card Set or recovering keys to softcards on page 32).
p
This feature specifies PIN recovery. For information on changing pass phrases, see Changing pass phrases with cardpp on page 218 or the appropriate Operator Guide for your module.
nv
This feature specifies that the Administrator Card Set is needed to enable non-volatile memory allocation.
61
rtc
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
62
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).
In this case, move the mode switch to the initialization position, and run the command again.
External modules
In this case, hold down the initialization switch, and run the command again.
63
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.
64
the number of cards required for the Administrator Card Set set to a value greater than 1.
See About payShield Card Sets on page 187 for important advice about the choice of a value for K. the SEE debugging for all option enabled, if you wish to make use of the extended payShield module debugging option. (You must have configured the security worlds card requirements separately to enable this option.)
This option is designed for testing purposes only. Do not enable it on production security worlds as it may enable SEE applications to leak security information. You must know what the security policy and the associated card sets for the payShield installation are. If this is not already decided, see About payShield Card Sets on page 187. You must have enough smart cards to form the security worlds card sets. You must know which payShield functions are required.
65
See payshield-install on page 283 for full details of the payshield-install utility. To run the payshield-install utility, type the following command, specifying the options required for your installation:
payshield-install [options] psiname keyhash
In this command:
psiname
This is the hash of the nCipher payShield signing key. The hash is:
25d0dfc32e980c7ab8f0fd7647db7fc2252f9851
Do not type a hash that differs from this value unless you are certain that the new hash is from a valid payShield signing key. If you are in any doubt as to the origin of the hash value you have been given, do not create a payShield installation: contact Support at nCipher for confirmation of the correct signing key hash. As a minimum, specify the following:
payshield-install -S psiname keyhash
If you do not set the -S (--allow-smartcard-imports) option at this point, your payShield installation can never import keys from smart cards, but can only generate new keys.
66
The payshield-install utility performs or prompts for the following operations in the order specified: If you have set the --totally-insecure option, the payshield-install utility issues the following warning:
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 ...
67
Following the onscreen prompts, each Master Card Set card holder inserts a blank card and enters a name and pass phrase for this card. The payshield-install utility displays the following message:
It then prompts for new operator cards. Following the onscreen prompts, each Key Establishment Card Set card holder inserts a blank card and enters a name and pass phrase for this card. The payshield-install utility displays a success message and exits. A successful operation might have output similar to the following:
payshield-install.exe: no card in module 1 slot 0 Insert an administrator card into module 1 slot 0 and press return... Passphrase for administrator card 1: payShield Master key generation ... payShield Master key generated Making FTO delegation certificate ... payShield Master Cardset creation ... Insert new operator card 1 into module 1 slot 0 and press return... Passphrase for new operator card 1: Name for card 1: master payShield Master Cardset created payShield Key Establishment key generation ... payShield Key Establishment key generated payShield Key Establishment Cardset creation ... Insert new operator card 1 into module 1 slot 0 and press return... Passphrase for new operator card 1: Name for card 1: kec payShield Key Establishment Cardset created Successfully created new payShield Installaton psi
In the interests of brevity, the above output transcript shows the creation of 1-of-1 card sets. Such a card set selection is not suitable for a live, commercial payShield installation.
68
In this command, psiname is the name that you supplied when you created the payShield installation.
69
Separate the flags for each module by a dash on its own line, as in the following example:
postload args=-n psiname [-d] module MODULE
In this example:
MODULE
This represents the payShield SEE machine version and has the format X.Y.Z.camA
psiname
This represents the name of the payShield installation that the hardware security module is to host. This is the same as the psiname passed to SPP_init() in any application that wishes to use the payShield hardware security module.
-d
This flag specifies that the operating SEE World has the
dseeall feature set and that the operating payShield installation has the -D option set. Both of these conditions
must have been specified at the time of SEE World creation time, and their status can be checked using, respectively, the nfkminfo and payshield-info command-line utilities. If either of these conditions is not satisfied, then specifying -d in postload_args inhibits SEE machine loading. For further information on the hardserver configuration file, see Chapter 6: Configuring the hardserver.
70
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
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.
71
1.
C:\nfast\bin\createocs -m MODULE|--module=MODULE -Q|--ocs-quorum=K/N -N|--name=NAME [-M|--name-cards] [[-p|--persist]|[-P|--no-persist]] [[-R|--no-pprecovery]|--pprecovery] [-q|--remotely-readable] [-f|--force] [-T|--timeout=TIME]
In this command:
-m MODULE, --module=MODULE
These options specify the module number of the module to be used to create the token. If you only have one module, MODULE is 1.
-Q, --ocs-quorum=K/N
In these options, K is the minimum required number of cards. If you do not specify the value K, the default is 1. Note Some applications do not have mechanisms for requesting that cards be inserted. Therefore any Operator Card Sets that you create for use with these applications must have K=1.
N is the total number of cards. If you do not specify the value N, the default is 1. -N, --name=NAME
These options enable you to name the card set. The card set must be named with this option before individual cards can be named using the -M, --name-cards=NAME options.
-M, --name-cards
These options enable you to name individual cards within the card set. You can only use this option after the card set has been named by using the --name=NAME
72
option. createocs prompts for the names of the cards as they are created. Not all applications can display individual card names.
-p, --persist
These options mean that the pass phrase for this card set cannot be recovered. The pass phrase for the card set is recoverable by default. You can specify this explicitly with --pprecovery.
-q, --remotely-readable
These options allow this card set to be read remotely. For information on configuring Remote Operator Card Sets, see Chapter 13: Remote Operator Card Sets.
-f, --force
These options allow createocs to overwrite smart cards without prompting. If you do not specify the --force option, createocs prompts you if any smart card to be used is not blank. You can only employ --force to reuse Operator Cards from the current security world, or cards containing unknown data. You cannot use the --force option either to force the reuse of Administrator Cards from the current security world without first erasing them or to force the reuse of Operator Cards from other security worlds.
-T, --timeout=TIME
These options set the time-out for the card set. Use the suffix s to specify seconds, m for minutes, h for hours, and d for days. If the timeout is set to 0, the Operator
73
Card never times out. Otherwise, the module automatically unloads the Operator Card Set TIME after the Operator Card was loaded. If you have created a FIPS 140-2 level 3 compliant security world, you must provide authorization to create new Operator Cards; createocs prompts you to insert a card that contains this authorization. Insert any card from the Administrator Card Set or any Operator Card from the current security world. When createocs has obtained the authorization from a valid card or if no authorization is required, it prompts you to insert a card into the module you specified. 2. Insert the smart card to use. If you insert an Administrator Card from another security world or an Operator Card that you have just created, createocs displays the following message:
Module x slot n: unknown card Module x slot n: Overwrite card ?
(press Return)
where x is the module number and n is the slot number. If you insert an Operator Card from another security world, createocs displays the following message:
Module x slot n: inappropriate Operator Card (TokenAuthFailed).
When you have inserted a valid card, createocs prompts you to type a pass phrase. Note 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.
74
3.
Type a pass phrase and press Enter . Alternatively, press Enter if you do not want this card to have a pass phrase. A pass phrase can be up to 1024 characters long. If you entered a pass phrase, createocs prompts you to confirm it.
4.
Type the pass phrase again and press Enter . If the pass phrases do not match, createocs prompts you to input and confirm the pass phrase again.
5.
When the new card has been created, if you are creating a card set with more than one card in it, createocs prompts you to insert another card. For each additional card in the Operator Card Set, follow the instructions from step 2 through step 4.
75
Figure 3
Status LED Clear switch Mode switch
M O I
Maintenance
DC power
2.
76
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.
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.
77
Figure 4
Status LED Clear switch Mode switch
M O I
Initialization
DC power
2.
78
The module performs self tests, during which the Status LED is on. When the self tests are complete, the unit should enter the preinitialization state. In this state, the Status LED emits repeated single short flashes. Refer to the table below if the Status LED does not emit repeated single short flashes:
LED 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.
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.
79
Figure 5
Status LED Clear switch Mode switch
M O I
Operational
DC power
2.
The module performs self tests, during which the Status LED is on. When the self tests are complete, the unit should enter the operational state. In this state the Status LED is mainly on, but blinks off regularly. As the load on the unit increases, the length of time that the Status
80
LED is off increases. If the module is fully loaded, the Status LED is off for as long as it is on. Refer to the table below if the Status LED is not mainly on and blinking off regularly:
LED
Emits repeated single short flashes
State
Pre-initialization
Pre-maintenance
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.
81
Chapter 5: Uninstalling
This chapter provides information on uninstalling nCipher software.
The uninstall process restores the Microsoft CSP as the default SChannel CSP. If required, you can safely remove the nCipher module after shutting down all connected hardware.
82
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.
83
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.
Remote slots
You configure remote slots in the slot_imports and slot_exports sections of the configuration file. The Remote Operator feature must be enabled on the module, as described in Chapter 8: Feature Enabling nCipher Modules.
84
SEE machines
These sections define the slots that are imported to or exported from the module. See Chapter 13: Remote Operator Card Sets for full information about remote slots.
SEE machines
You configure the hardserver to load SEE machines on start-up in the load_seemachine section of the configuration file. The SEE Activation feature must be enabled on the module, as described in Chapter 8: Feature Enabling nCipher Modules. This section defines the SEE machines and optional user data to be loaded, as well any other applications to be run in order to initalize the machine after it is loaded. See Chapter 9: Using CodeSafe Applications for information about SEE machines.
server_settings
The server_settings section defines the settings for the client hardserver that can be modified while the hardserver is running. The section contains the following fields:
loglevel
This field specifies the level of logging performed by the hardserver. It takes a value that is one of:
info
85
The default is info. See Logging and debugging on page 343. If NFAST_SERVERLOGLEVEL is set, it overrides the value in the configuration file.
logdetail
This field specifies the level of detail logged by the hardserver. You can supply one or more of the following flags in a space-separated list:
external_time
This flag specifies showing the external time (that is, the time according to your machine's local clock) with the log entry.
external_date
This flag specifies showing the external date (that is, the date according to your machine's local clock) with the log entry.
86
external_pid
This flag specifies showing the external process ID with the log entry.
external_tid
This flag specifies showing the external thread ID with the log entry.
external_time_t
This flag specifies showing the external time_ti (that is, the time in machine clock ticks rather than local time) with the log entry.
stack_backtrace
This flag specifies showing the stack backtrace with the log entry.
stack_file
This flag specifies showing the stack file with the log entry.
stack_line
This flag specifies showing the stack line number with the log entry.
msg_severity
This flag specifies showing the message severity (a severity level as used by the NFLOG_SEVERITY environment variable) with the log entry.
msg_categories
This flag specifies showing the message category (a category as used by the NFLOG_CATEGORY environment variable) with the log entry.
87
msg_writeable
This flag specifies showing message writeables, extra information that can be written to the log entry, if any such exist.
msg_file
This flag specifies showing the message file in the original library. This flag is likely to be most useful in conjunction with nCipher-supplied example code that has been written to take advantage of this flag.
msg_line
This flag specifies showing the message line number in the original library. This flag is likely to be most useful in conjunction with nCiphersupplied example code that has been written to take advantage of this flag.
options_utc
This flag specifies showing the date and time in UTC (Coordinated Universal Time) instead of local time.
connect_retry
The number of seconds to wait before retrying a remote connection to a client hardserver. The default is 10.
connect_broken
The number of seconds of inactivity allowed before a connection to a client hardserver is declared broken. The default is 90.
88
connect_keepalive
The number of seconds between keepalive packets for remote connections to a client hardserver. The default is 10.
connect_command_block
When a netHSM has failed, this specifies the number of seconds the hardserver should wait before failing commands directed to that netHSM with a NetworkError message. For commands to have a chance of succeeding after a netHSM has failed this value should be greater than that of connect_retry. If it is set to 0, commands to a netHSM are failed with NetworkError immediately it has failed. The default is 35.
max_pci_if_vers
The maximum PCI interface version number. If this is set to 0 (the default) there is no limit. These flags are those used by the NFLOG_DETAIL environment variable (see Environment variables to control logging on page 343).
module_settings
The module_settings section defines the settings for the module that can be changed while the hardserver is running. The section contains the following fields:
esn
The priority of the module. This is an integer from 1 (highest) to 100 (lowest). The default is 100.
89
server_remotecomms
The server_remotecomms section defines the remote communication settings for the client hardserver. These are read only at hardserver start-up. This section contains the following fields:
impath_port
The port on which the hardserver listens for incoming impath connections. The default is 9004. Setting this field to 0 specifies that the hardserver does not listen for incoming connections.
server_startup
The server_startup section defines the settings for the hardserver that are loaded at startup. The section contains the following fields:
unix_socket_name
The name of the pipe to use for non-privileged connections on Windows. An empty string specifies none. The default is \\.\pipe\crypto. If the NFAST_SERVER environment variable is set, it overrides the value in the configuration file.
nt_pipe_users
A list of users allowed to issue non-privileged connections on Windows. If empty, any user can issue non-privileged connections. This is the default.
90
nt_privpipe_name
The name of the pipe to use for privileged connections on Windows. An empty string specifies none. The default is \\.\pipe\privcrypto. If the NFAST_PRIVSERVER environment variable is set, it 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:
91
module
The module on to which to load the SEE machine. The value must be an integer. A module with this ID must be configured on the client computer.
machine_file
The file name of the SEE machine. (For payShield, the correct version and path are found in the release notes on the current nCipher CD-ROM.)
userdata
The file name of the userdata to pass to the SEE machine on startup. If this field is blank (" "), the SEE machine is loaded but not started. If this module is a payShield net module, this field must be blank. The default is blank.
worldid_pubname
The PublishedObject name to use for publishing the KeyID of the started SEE machine. If this field is blank (" "), the KeyID is not published. This field is ignored if the value of userdata is blank. If this module is a payShield net module, this field must be blank.
postload_prog
The program to run after loading the SEE machine to perform any initialization required by the SEE machine or its clients. This program must accept an argument of the form 'm module#'. If this module is a payShield net module, this field must be set to payshield.
92
postload_args
Arguments to pass to the program specified in postload_prog. The argument '-m module#' is automatically passed as the first argument. This field is ignored if postload_prog is not specified or is blank. If this module is a payShield net module, this field must be set to -n psiname [-d].
slot_imports
The slot_imports section defines the remote slots that the client hardserver on an unattended module should import from remote modules for use by modules connected directly to that local computer. Each slot is defined by an entry as follows:
local_esn
The SlotID to use to refer to the slot when it is imported on the local module. The default is 2.
remote_ip
The ESN of the remote module from which to import the slot,
remote_slotid
The SlotID of the slot to import on the remote module. The value must be an integer. The default is 0.
93
slot_exports
The slot_exports section defines the slots on local modules that the local hardserver should allow network modules to import. Each local slot has an entry for each remote module that can import it, as follows:
local_esn
The ESN of the local module whose slot can be imported by a network module.
local_slotid
The SlotID of the slot that is to be imported. The value must be an integer. The default is 0.
remote_ip
The IP address of the network module that is allowed to import the slot. The default is to allow all modules in the security world to import the slot. The IP address of the machine that is allowed to import the slot.
remote_esn
remote_file_system
This section is updated automatically when the rfs-setup utility is run. You should not edit it manually. The remote_file_system section defines a remote file system on the client, by listing the modules allowed to access the filesystem on this client. Each module is defined by an entry as follows:
94
remote_ip
The IP address of the network module that is allowed to access the filesystem on this client.
remote_esn
The ESN of the remote module allowed to access the filesystem on this client.
keyhash
The hash of the key with which the client must authenticate itself to the module. The default is 40 zeros, which means that no key authentication is required.
native_path
The local file name for the volume to which this entry corresponds.
volume
The volume which the remote host would access to use this entry.
allow_read
If this is set to yes, a remote server is allowed to read the contents of the file. The default is no.
allow_write
If this is set to yes, a remote server is allowed to write to the file. The default is no.
allow_list
If this is set to yes, a remote server is allowed to list the contents of the file. The default is no.
95
is_directory
If this is set to yes, this entry represents a directory. The default is no.
is_text
If this is set to yes, line endings should be converted to and from the Unix convention for transfers
This section determines which PINBlock formats can be used in specific situations. If a format is not listed, then it is disabled and any attempt to use the format results in the message AccessDenied.
Role i/o permissions
This section determines the types of keys that can be imported or exported. Here you can specify which key block formats are acceptable for each import or export operation. Listing no formats for an operation means that the operation is disabled. For example the following entry would mean that TPKs: Can be generated in attended operations (using the VeriFone solution) Cannot be generated automatically Can (in principle) be exported as components or wrapped in attended operations
96
Cannot be imported from components or wrapped in attended operations Can be imported automatically from a wrapped key.
nCipher does not recommend unattended key operations, since no currently supported key block formats carry sufficient role or integrity information.
97
Identifying modules
Modules are identified in two ways: by serial number by ModuleID.
You can obtain the ModuleIDs and serial numbers of all your modules by running enquiry. See enquiry on page 229.
Serial Number
The serial number is a unique 12-digit number that is permanently encoded into each module. You should quote this number in any correspondence with Support at nCipher.
ModuleID
The ModuleID is an integer assigned to the module by the server when it starts. The first module it finds is given ModuleID 1, the next is given ModuleID 2, and so on.
98
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.
99
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.
100
Available Features
This section lists the features that can be added to modules. Contact sales@ncipher.com for full details of all available features.
Elliptic Curve
Elliptic curves allow small key sizes to provide improved levels of security and are commonly used in embedded devices. See Developers Reference for full details of the elliptic curve feature.
101
Available Features
See the CodeSafe/C Developer Guide for full details of the SEE.
102
payShield features
Client licenses
You can purchase additional client licenses that allow you to run multiple clients for the module. Three clients are always enabled on each module.
payShield features
If you have purchased payShield, the module is always supplied with the following feature enabling tokens: SEE Activation (Restricted), to allow software to run inside your module payShield Activation, to allow payShield software to run inside your module. payShield Rnumber, to set the performance variant of the payShield module to the number number ISO smart card support (ISS), also called Foreign Token Open (FTO), to allow the use of non-nCipher smart cards.
103
For payShield applications you must enable these features using the Feature Enable Tool, described in The Feature Enable Tool on page 105, before you can use the secure payment application.
You must provide the ESN number to order a new feature. If you prefer, you can include this information in an E-mail to
sales@ncipher.com. You can use the Feature Enable Tool to save the
ESN details to a file. See The Feature Enable Tool on page 105. When your order has been processed, you receive a Feature Enabling Certificate in one of the following ways: nCipher E-mails you the Feature Enabling Certificate. nCipher sends you a smart card that contains the Feature Enabling Certificate.
The Feature Enabling Certificate contains the information that you need to enable the features you have ordered. For more information, including pricing of features, telephone or Email your nearest nCipher sales representative using the contact details from this guide, or the nCipher web site (http://www.ncipher.com).
104
Enabling features
Enabling features
The Feature Enable Tool
The Feature Enable Tool utility, by default, scans the smart card readers of all modules attached to the host, and enables any features found on inserted FEM cards. To use the Feature Enable Tool, you must be logged in as a user who is permitted to create privileged connections. You can enable a feature without having physical access to a module by exporting the slot on your local module, importing that slot into the remote module, and then running the Feature Enable utility on the remote host. The Feature Enable Tool offers you the choice of clearing the module after it has enabled features. If you do not choose to clear the module then (for example, because you have another process running on the module), you must clear it later. You can use any appropriate method to do this (for example, the nopclearfail utility or the Clear button).
Usage
fet.exe
Help options
-h, --help
105
Enabling features
-u, --usage
display a brief usage summary for fet.exe. Note If you are enabling the Remote Operator feature, you must enable it on the module that is to be used as the remote module. See Chapter 13: Remote Operator Card Sets for details.
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.
106
Enabling features
When you run the Feature Enable Tool without a Feature Enabling smart card in any module slot, a message similar to the following is displayed. There is a line for the features on each module, and a list of options. In this example, only one module (ESN 511D-DB15-D438) is attached to the host.
Feature Enable Tool =================== ISO Smart Card Support | Remote Operator | | Korean Algorithms | | | SEE Activation (EU+10) Mod Electronic | | | | SEE Activation (Restricted) No. Serial Number | | | | | 1 511D-DB15-D438 -- NO NO NO NO NO 1. Read FEM certificate(s) from a smart card or cards. 2. Read FEM certificate from a file. 3. Read FEM certificate from keyboard. 4. Write table to file. Enter option :
If you select option 1, you are prompted to insert a Feature Enabling smart card into a module slot and then press Enter . The Feature Enable Tool then behaves in exactly the same way as if it were run with the Feature Enabling cards already in the slots. If you select option 2, you are prompted for the location and file name of the Feature Enabling certificate. When you supply these, you are prompted for the module number and the feature. If you select option 3, you are prompted for the module number and the feature, and are then asked to enter the certificate one line at a time, followed by a period (.) on a line by itself. You can also cut and paste a Feature Enabling certificate from an E-mail. If you select option 4, the table of enabled features is written to a file. You can include this file when you request new features from nCipher. See Ordering features for your module on page 104.
107
CodeSafe/C applications
CodeSafe/C applications are standalone applications. Each CodeSafe C application can consist of multiple parts, and its installation can include several configuration steps. Please see your application vendors documentation for instructions on installing and configuring each application. You may need to use the hardserver, loadmache and tct2 utilities when configuring and loading an applicationl; see hardserver on page 242, and .
108
Later chapters in this guide contain instructions for performing the following operations with KeySafe: creating a security world adding a module to a security world removing a module from a security world replacing an Administrator Card Set creating Operator Card Sets replacing Operator Card Sets
Starting KeySafe
In order to use KeySafe, Suns Java run-time environment version 1.5, or the equivalent developer kit must be installed. It is recommended that you install it before you install the nCipher components. The Java executable must be on your path. Note You can download Sun's Java Run-time Environment (and Java Developer Kit) from http://www.sun.com/. If your security policy does not allow the use of downloaded software, these components can be obtained on CD-ROM from Sun or your Operating System vendor. The keysafe.jar file must be specified in the Java class path.
109
10 Using KeySafe
Starting KeySafe
In order for KeySafe to work, you must set priv_port (the port on which the hardserver listens for local privileged TCP connections) to 9001 and nonpriv_port (the port on which the hardserver listens for local nonprivileged TCP connections) to 9000. Note See Setting the environment variables on page 49 and server_settings on page 85 for information on setting these parameters. Start KeySafe by selecting the KeySafe entry from the Programs folder on the Windows Start menu. The Windows KeySafe launcher checks that the components required to run KeySafe are installed. Any missing components are listed in a dialog box similar to the following:
110
10 Using KeySafe
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.
111
10 Using KeySafe
Sidebar
The sidebar provides access to different parts of the KeySafe application (with the menu buttons) and also displays information about both the current security world and your module or modules (with the Module Status tree).
Menu buttons
There are six menu buttons at the top of the sidebar:
Introduction
Clicking the Introduction menu button takes you to the introductory panel that KeySafe displays at startup.
Keys
Clicking the Keys menu button takes you to the Key Operations panel, from which you can choose to create, import, view, or destroy keys.
Cards
Clicking the Cards menu button takes you to the Card Operations panel, from which you can: create, view, or erase Operator Cards change the pass phrase on an Operator or Administrator Card, or recover the pass phrase from an Operator Card replace an Operator or Administrator Card Set.
Softcards
Clicking the Softcards menu button takes you to the Softcard Operations panel, from which you can: create, view or erase softcards change or recover the pass phrase on a softcard
112
10 Using KeySafe
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.
113
10 Using KeySafe
setting. Click the toggle to display expanded information about the security world or module. Click the toggle again to collapse this information. Note For purposes of clarity, screen shots in this guide are shown with some of the Module Status tree toggles expanded. Security world information When you toggle the Module Status tree view of security world information to its expanded setting, KeySafe reports Yes or No for each of the following conditions: the security world is initialized key recovery is enabled for this security world (for more information on key recovery, see Replacing Operator Card Sets on page 202) pass phrase recovery is enabled for a security world (for more information on pass phrase recovery, see Replacing Operator Card Sets on page 202)
It also gives the following information: which type of key protects the security world (DES or AES/Rijndael) which FIPS 140-2 level the security world is operating at (level 2 or level 3)
The expanded security world information includes a folder labeled Advanced, which itself can be toggled into an expanded view. This folder displays advanced security world attributes related to nCiphers Secure Execution Engine (SEE). When expanded, the Advanced folder displays Yes or No for each of the following: whether or not you have generated a real-time clock (RTC) authorization key for this security world whether or not you have generated a nonvolatile memory (NVRAM) authorization key for this security world
114
10 Using KeySafe
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
115
10 Using KeySafe
Operational:Unchecked, indicating that, although the module appears to be in the current security world, KeySafe could not find a module initialization certificate (a module_ESN file) for this module Failed, indicating that the module has failed PreMaintMode, indicating that the module is in the premaintenance state MaintMode, indicating that the module is in the maintenance
state. the status of the smart card reader slot(s). You cannot initialize a security world from KeySafe unless you have at least one module in the pre-initialization state (PreInitMode). Likewise, if you want to add a module to an existing security world, that module must be in the preinitialization state. Note For information about putting a module into the pre-initialization state, see Entering the pre-initialization state on page 78. After you have initialized a security world, in order for a module to be usable, you must put it into the operational state (as described in Entering the operational state on page 79). for strict FIPS 140-2 level 3 security worlds, a FIPS Auth Loaded entry will show if an Administrator Card or Operator Card has been inserted to authorise a FIPS key required operation. The Module status tree has an Advanced folder that shows the following details when expanded: the version of the modules firmware whether the module has a Real Time Clock (RTC) whether the module has nonvolatile memory (NVRAM).
116
10 Using KeySafe
Navigation buttons
At the bottom left of the Module Operations panel are three navigation buttons. Clicking a navigation button does not commit you to an action, but instead selects an operation and loads another panel of additional information and options related to the selected operation.
117
10 Using KeySafe
From the Module Operations panel, for example, clicking the Erase Module navigation button does not itself erase a module, but rather loads the Erase Module panel:
Command buttons
At the bottom right of the Erase Module panel is a command button (the Erase Module! command button, in this case). Unlike clicking a navigation button, clicking a command button does commit you to an operation. Clicking a command button tells KeySafe to write or delete data: it is not necessarily possible to reverse such changes even if you subsequently cancel the operation. For these reasons, command buttons are usually marked with an exclamation point (!) if there is a danger that a command could overwrite data that you may not want deleted. In some cases, clicking a command button causes KeySafe to display a dialog box asking you to confirm your command. Such features help prevent you from accidentally destroying your data or keys.
118
10 Using KeySafe
Some panels require that, before you can click a command button, you select options by means of radio buttons or that you enter data into text fields:
If you click a command button without having entered data into a mandatory text field or if KeySafe detects that the information you provided is inconsistent or invalid, KeySafe displays an error message. Click the messages OK button, and then provide or correct the necessary information. After you successfully issue a command by clicking a command button, the sidebars menu buttons are disabled until the requested command is completed.
Back buttons
Some KeySafe panels have Back buttons. Clicking a Back button takes you to the panel from which the panel you are on is normally reached. For example, clicking the Back button on the Erase Module panel takes
119
10 Using KeySafe
Errors
you to the Module Operations panel, and clicking the Back button on the Examine/Change Card panel takes you to the Card Operations panel.
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.
120
10 Using KeySafe
Errors
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.
121
10 Using KeySafe
Errors
Contact Support at nCipher if you receive any other error message that looks similar to the one shown below:
122
123
Creates/modifies
creates creates or modifies modifies
Creates files...
world module_ESN module_ESN
world
cards_ident card_ident_cardno
In this table:
ESN is the electronic security number of the module on which the
created. The ident of a card set is a 40-character string that represents the hash of the card sets logical token. The ident of a key is either user supplied or a hash of the keys logical token, depending on the application that created the key.
124
Required files
The following files must be present and up to date in the C:\nfast\kmdata\local directory, or the directory specified by the NFAST_KMLOCAL environment variable, for a host to use a security world:
world
a module_ESN file for each module that this host uses a cards_ident file for each cardset that is to be loaded from this host a card_ident_cardno file for each card in each cardset that is to be loaded from this host a key_appname_ident file for each key that is to be loaded from this host.
These files are not updated automatically. You must ensure that they are synchronized whenever the security world is updated on the module.
125
Security world options are highly configurable at the time of creation but, so that they remain secure, not afterwards. For this reason, nCipher recommends that you familiarize yourself with security world options, especially those required by your particular situation, before you begin to create a security world.
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
126
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.
127
can choose to disable these recovery options when creating a security world. However, if you do so, all key recovery is impossible, even for keys generated as recoverable (which is the default for key generation). If you do not enable recovery for a security world, you can never replace lost or damaged Operator Card Sets and, therefore, in such a case could never access the keys that are protected by such cards. Recovery cannot be enabled later without reinitializing your security world and discarding all your existing keys.
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.
128
129
You should know what the security policy for the module is, and in particular the number and quorum of administrator and operator cards to be used. See Determining module requirements on page 39 for details. 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.
130
2.
3. 4. 5.
131
Note
Overwriting an existing security world in this way does not delete that security worlds host and recovery data, but renames the existing kmdata directory in which these reside as kmdata_nn (where nn is a 2digit integer assigned depending on how many security worlds have been previously saved during overwrites up to a maximum of 99). If you want to overwrite an existing security world, click the Overwrite Security World button on the Existing Security World panel. KeySafe then takes you to the Initialize Security World panel. 6. If KeySafe does not find existing security world data, it takes you to the Initialize Security World panel:
7.
Enter the total number of cards (N) that you wish to have in the Administrator Card Set. This number must be less than or equal to 64.
132
8.
Enter the number of Administrator Cards that are needed to authorize any action. This number (K) must be less than or equal to the total number of cards (N).
Note
nCipher recommends that you do not create an Administrator Card Set for which K is equal to N, because you cannot replace such an Administrator Card Set even if only 1 card is lost or damaged. 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.
133
Click the Use these settings button to return to the Initialize Security World panel. Note If you wish to use SEE, you must have ordered and enabled it as described in Chapter 8: Feature Enabling nCipher Modules. 12. KeySafe always generates recovery data for the security world key. However, if you want to be able to recover Operator Cards and application keys, you must proceed to the Initialize Security World Advanced Options panel:
134
Use the Initialize Security World Advanced Options panel to create key and pass phrase recovery material that is protected by the cryptographic keys on the Administrator Card Set. This does not give nCipher, or any other third party, access to your keys. Keys can only be recovered by using the Administrator Cards. Note nCipher recommends that you always select the recovery option. a. Select whether or not you want to enable key recovery, and the number of Administrator Cards required to authorize key recovery. 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
135
13. Click the Initialize Security World! button. This takes you to the Create Administrator Card Set panel:
14. KeySafe prompts you to insert the cards that are to form the 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.
136
15. KeySafe takes you to the Set Card Protection Pass Phrase panel:
If you want to set a pass phrase for this Administrator Card: a. 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.
137
16. KeySafe then prompts you for the next card (if any). Note When creating a card set, KeySafe recognizes a card that belongs to the set before the card set is complete. If you accidentally insert a card to be written again after it has already been written, you see the following warning:
17. After you have created all the Administrator Cards, KeySafe creates a new module key. When initialization is complete, KeySafe displays a message: Security world successfully initialized. Click the OK button, and KeySafe returns you to its introduction panel. 18. After you have added a module to the security world, restart the module in the operational state. (See Entering the premaintenance state on page 76). If you have more than one module on this server, you can use KeySafes Reprogram Module option to incorporate a new module into your security world (or to restore an existing module after a firmware upgrade), as described in Adding or restoring a
138
module to the security world on page 155. Alternatively, you can also incorporate a new module into your security world by using the new-world command-line utility (see new-world on page 259).
To create a security world by using the nCipher CSP wizard, follow these steps:
139
1.
Run the wizard by double-clicking the icon on your desktop. The wizard displays this window:
If any module is in the pre-maintenance or maintenance state, the wizard displays a warning. In such a case, reset the module into the pre-initialization state, and rerun the wizard. 2. Click the Next button. The wizard determines what actions to take based on the state of the security world and the state of the modules that are attached to your computer:
140
If the wizard cannot find a module that is capable of key management, it loads the acceleration-only hook (which does not provide key management capabilities). In such a case, the wizard displays the following window:
141
If there is at least one module capable of key management and there is no existing security world, the wizard displays the following window:
142
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
143
to proceed without creating a security world, select Install cryptographic acceleration only and click the Next button. The wizard installs the acceleration-only hook. This option only provides acceleration and does not use the module to manage keys.
If you choose either to Create a new security world or to use an existing world, the following screen is displayed:
4.
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.
144
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.
145
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.
146
10. Click the Next button. If you did not select the Configure advanced security world options option, continue from step 11. If you selected the Advanced settings option, the World Advanced Options window is displayed:
Each tab in this window lets you specify the number of cards required to authorize specific tasks: 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.
147
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.
148
If you want to protect this card with a pass phrase, select the Card requires a pass phrase option. The wizard prompts you to enter and confirm the pass phrase. Note The Next button is only enabled when you have entered two matching pass phrases. 13. When you have entered the pass phrase, click the Next button. 14. Place the smart card in the module. 15. Click the Next button.
149
16. When the wizard successfully writes to this card, it prompts you to insert the next card and to enter a pass phrase for this card. Continue the process, following the onscreen instructions. When the wizard has written the number of cards you requested, it displays the following screen:
These smart cards form the Administrator Card Set for this security world. The security of your key data depends on the security of these smart cards.
150
17. If there are no more modules to add to the security world, go to step 18. If there are further modules to add to the security world, the wizard prompts you to insert a card from the Administrator Card Set in the next module. Follow this process: a. Insert one of the cards from the Administrator Card Set that you have just created, and click the Next button. If the card is not from the Administrator Card Set, the wizard prompts for another card. 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.
151
18. When all the modules have been added to the security world, the wizard displays this window:
19. Restart the module in the operational state (as described in Entering the operational state on page 79).
152
This window enables you to create Operator Cards for the new security world. If you do not want to use Operator Card Sets to protect your keys, select the Module protection option. If this option is selected, the CSP only creates keys that are protected by
153
the security world. This option is suited to applications where 24hour operation is required, because no human intervention is required to use application keys. If you want to use Operator Card Sets to protect your keys, select the Operator Card Set protection keys option. If you are using Microsofts CA and you want the wizard to prompt you every time you create or import a key, turn on the Always use the wizard when creating or importing keys option. If you leave this option turned off, the wizard attempts to protect the new or imported key by using the card currently in the module. You can change these settings by rerunning the wizard and selecting the Use the existing security world option. If your security world is FIPS compliant, the option to use module-protected keys is not available.
154
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.
155
You can also restore a module to a security world in order to continue using existing keys and Operator Cards: after you upgrade the firmware if you replace the module
The additional modules can be any nCipher modules. For information about adding a network-connected module to the security world, see the documentation for the appropriate module type. In order to add a module to a security world, you must: have a copy of the security world data on this host. This is the host data written by KeySafe, the nCipher CSP wizard, or new-world when you created the security world. This data is stored in the directory to which the environment variable NFAST_KMDATA points (by default, C:\nfast\kmdata). set the environment variable NFAST_KMDATA (if the security world data is not in the default location). be logged in to the host computer as a user who is permitted to create privileged connections. See hardserver on page 242. have started the module in pre-initialization state (as described in Entering the pre-initialization state on page 78). possess a sufficient number of cards from the Administrator Card Set and the appropriate pass phrases.
Adding or restoring a module to a security world: erases the module reads the required number of cards (K) from the Administrator Card Set so that it can re-create the secret reads the security world data from the computers hard disk uses the secret from the Administrator Card Set to decrypt the security world key stores the security world key in the modules nonvolatile memory.
156
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.
2. 3.
157
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.
158
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.
3.
Click the Next button. If the wizard finds an existing security world, it displays the following window:
159
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.
160
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.
161
3. Note
If any error occurs (for example, if you do not enter the correct pass phrases), the module is reset to the factory state. The module does not form part of the security world unless you run new-world again.
You do not need the Administrator Card Set in order to erase a module. However, unless you have a valid Administrator Card Set and the host data for this security world, you cannot restore the security world after you have erased it.
162
After you have erased a module, it is in the same state as when it left nCipher (that is, it has a random module key and a known KNSO).
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.
163
5. Note
KeySafe erases all secrets from the module, returning it to its factory state.
If you have any keys that were protected by an erased module, you cannot access them unless you restore these secrets. You cannot restore these secrets unless you have the appropriate Administrator Card Set.
In this command:
-e, --factory
These options specify the ModuleID to use. new-world erases only one module at a time. To erase multiple modules, you must run new-world once for every module that you want to erase.
Output
If new-world successfully erased a module, it does not display any messages. Otherwise, new-world returns an error message.
164
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 ###################
165
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.
166
You can use KeySafe to view details of Operator Cards in a security world as described in the Operator Guide.
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
167
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
168
No Pre-Loaded Objects
Security world
nfkminfo reports the following information about the security world: generation
This indicates that there is at least one usable module in this security world on this host.
!Usable
This indicates that there are no usable modules in this security world on this host.
Recovery
This indicates that the security world has the key recovery feature enabled.
169
!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
170
PINRecovery
This indicates that the security world has the PIN recovery feature enabled.
!PINRecovery
This indicates that the security world has the PIN recovery feature disabled.
FTO
This indicates that the security world has an FTO delegation key.
!FTO
This indicates that the security world has no FTO delegation key.
NVRAM
This indicates that the security world has an NVRAM delegation key.
!NVRAM
This indicates that the security world has no NVRAM delegation key.
RTC
This indicates that the security world has an RTC delegation key.
!RTC
This indicates that the security world has no RTC delegation key.
171
n_modules
This indicates the SHA-1 hash of the nCipher Security Officers key.
hkm
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 ClientID required to use any pre-loaded keys and tokens.
k-out-of-n
172
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 that the module is programmed in the current security world and can be used.
173
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, 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 displays ShareTarget if the module has been initialized to allow reading of remote card sets.
174
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
175
0x1
This indicates that the smart card in the reader is part of the Administrator Card Set.
Empty
This indicates that the smart card in the reader could not be read (the card may be from a different security world).
Operator
This indicates that the smart card in the reader is an Operator Card.
176
flags
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 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
177
flags
This indicates that the card in the slot is not from a Remote Operator Card Set.
RemoteEnabled
This indicates that the card in the slot is from a Remote Operator Card Set.
PINRecoveryForbidden(disabled)
This indicates that the card in the slot does not have PIN recovery enabled. This is always true if PIN recovery is disabled for the security world.
PINRecoveryRequired(enabled)
This indicates that the card in the slot does have PIN recovery enabled.
timeout
the period of time in seconds after which the module automatically removes the Operator Card Set. If timeout is set to none, the Operator Card Set does not time out.
178
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.
179
Every different container is now guaranteed to have a distinct storage location. There were circumstances in CSP versions older than 1.11.0 in which two containers with similar names could have shared the same keys wrongly.
However, there are some points to bear in mind concerning CSP versions 1.11.10 and later: If you want to share the same key between multiple computers, nCipher supplies the cspimport utility for transferring keys between containers. Any existing containers with older versions of the CSP must be migrated to the new format. nCipher provides a utility, cspmigrate, to migrate containers from the old to the new system.
180
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.
181
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
If you do not enable these options, the created certificate is not suitable for use as a Web server certificate and SSL does not work. The selected CSP must also be a suitable nCipher CSP (typically,
nCipher Enhanced SChannel Cryptographic Provider for an RSA key).
In order to use an existing key set, enable the Use existing key sets name. The key size option is ignored in this case because the key size was decided at the original key creation time.
182
The portion of the advanced certificate request form used for the CSP and key setup is shown below, with all needed options selected correctly:
This utility checks that CSP container files are intact and uncorrupted, and also that referenced key files exist. Use cspcheck in conjunction with nfkmcheck, but run nfkmcheck first in order to test the integrity of your security world files.
183
cspimport
This utility allows you to insert keys manually into existing CSP containers. This utility has two modes that either allow you to change a containers key association to that of an arbitrary nCipher security world key or to copy CSP keys between containers.
cspmigrate
This utility moves an existing security worlds CSP container information from the registry to the security worlds kmdata directory.
csputils
This utility lists CSP containers and provides detailed information about them. It can also be used to delete container files if the current user has administrative privileges.
keytst
This utility displays information about existing CSP key containers by using the Microsoft CryptoAPI. If you have the appropriate permissions, keytst also allows you to create containers and their keys, as well as delete containers. A further CSP utility, cspimport, lets you insert keys manually into existing CSP containers. This utility has two modes that allow you either to change a containers key association to that of an arbitrary nCipher security world key or to copy CSP keys between containers. Each of these commands has an -h option that display the usage message for the command.
184
To transfer keys: 1. Program the module to which you intend to transfer the key into one of the security worlds involved. If one of the security worlds is FIPS 140-2 level 3 compliant and the other is not, then program the module into the security world that is not FIPS 140-2 level 3 compliant. 2. Run the mk-reprogram utility on the exporting security world in order to program a module key from that security world to a module in the importing security world. See mk-reprogram on page 255. To authorize this operation, you must first present a quorum of Administrator Cards for KNSO for the exporting (current) security world, then a quorum of Administrator Cards for module programming from the importing security world. Note If you change security worlds by using the command new-world -l, the programmed module key is lost.
185
3.
Run the key-xfer-im utility on the exporting security world in order to transfer the key to the importing security world. See keyxfer-im on page 250 for full details of the utility. If you are transferring the key from a security world that is FIPS 140-2 level 3 compliant to one that is not, you must use the -export-add option. If you are transferring the key from a security world that is not FIPS 140-2 level 3 compliant to one that is, you must use the --export-delete option. These options must precede the key file name in the key-xfer-im command. Also, remember that the default or current security world is set by the NFAST_KMDATA environment variable, which defaults to %NFAST_HOME%\kmdata. For more information about this environment variable, see Appendix C: Environment variables.
4.
Initialize the importing security world. To verify that module-protected keys have been imported: a. Run the following command:
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.
186
187
188
Additionally, the Administrator Card Set has a separate quorum for Foreign Token Open operations (FTO). An FTO quorum of Administrator Cards is required (and sufficient) to authorize the reading of data directly from non-nCore-format smart cards. Thus, the FTO quorum of Administrator Cards must be used to enable the payShield system to use the module smart-card reader to exchange key setup information with the VeriFone handset. Similarly, any attacker who can use the FTO quorum of Administrator Cards may be able to interfere with and subvert key establishment, including reading key components from transfer smart cards. The quorum for FTO should be selected to prevent this. nCipher suggests as a minimum a quorum of 3. nCipher recommends that you give careful consideration to the choice of K and N for the Key Establishment Card Set. Any quorum of K Key Establishment Card holders can introduce new keys, as can an attacker who is able to use K Key Establishment Cards with a module in the security world. If new keys are not authorized and secure, they may compromise the security of other payShield keys and PINS that are being processed. nCipher suggests as a minimum a quorum of 2 cards out of 4 (that is, a 2-of-4 card set) for the Key Establishment Card Set.
Card Holders
The entire security of the keys you create within the payShield installation and of the data that they protect depends on the security of the security world and of the payShield installation card sets. You must ensure that all cards are stored securely and in the custody of trusted personnel. Cards should never be exposed needlessly. No individual should ever have possession of more than one card from a particular card set, although an individual may hold one card from each of a number of different card sets.
189
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 for secure messaging for the integrity master key
mkidn
190
mkac
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.
191
It is extremely important that you choose the settings carefully because you cannot change the properties of a security world after you have created it.
192
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.
193
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.
194
Initializing modules for Remote Operator Firmware version 2.6.10 or greater must be installed in both the attended and unattended module. Use the enquiry utility to determine the version of the firmware on the modules. For instructions on upgrading firmware, see Appendix A: Upgrading module firmware or the documentation for the appropriate module type. After updating the firmware, the unattended module must be reinitialized into the security world by using KeySafe or new-world. Note By default, a module is initialized with remote card set reading enabled. If you do not want a module to be able to read remote card sets, you must configure it accordingly. Use the command new-world S MODULE (where MODULE is the modules ModuleID number) if you do not want this module to be able to read remote card sets. See new-world on page 259 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
The ShareTarget flag indicates that the module can be used as an attended module for the loading of Remote Operator Card Sets.
195
In this output, the RemoteEnabled flag indicates the card can be loaded remotely.
196
1.
Configure the host of the attended module to export the slot. To do this, add an entry for the slot to be imported to the slot_exports section of the configuration file as described in slot_exports on page 94 .
2.
Configure the host of the unattended module to import the slot. To do this, add an entry for the slot exported in step 1 to the slot_imports section of the configuration file on the host.
197
198
199
Before you can perform any of these operations, you must first create a security world, as described in Chapter 11: Managing security worlds.
200
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.
201
When you replace an Operator Card Set, the key material is not changed by the process. The process deletes the original host data (that is, the encrypted version of the key or keys and the smart card data file) and replaces this data with host data protected by the new Operator Card Set. In order to replace an Operator Card Set, you must have: Note enabled key recovery when you created the security world
If you did not enable key recovery, or if you created the security world with an early version of pkcs-init that did not support key recovery, you cannot recover keys from lost or damaged smart cards. created the original Operator Card Set using createocs, createocsimple, KeySafe, or the nCipher PKCS #11 library version 1.6 or later If you initialized the token using ckinittoken from the nCipher PKCS #11 library version 1.5 or earlier, you must contact Support at nCipher to arrange for them to convert the token to the new format while you still possess a valid card.
202
Note
a sufficient number of cards from the Administrator Card Set to authorize recovery
All recovery options require authorization from the Administrator Card Set. If any of the smart cards in the Administrator Card Set are lost or damaged, immediately replace the entire Administrator Card Set. initialized a second Operator Card Set using createocs, createocsimple, KeySafe, or the nCipher PKCS #11 library version 1.6 or later.
Note
The new Operator Card Set need not have the same K-of-N policy as the old set. If you are sharing the security world across several host computers, you must ensure that the changes to the host data are propagated to all your computers. One way to achieve this is to use client cooperation; see Setting up client cooperation on page 53.
2.
203
3.
Click the Replace OCS navigation button, and KeySafe takes you to the Replace Operator Card Set panel:
204
This panel lists existing Operator Card Sets in tabular form. For each card set it displays:
Name
the 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.
205
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.
206
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.
207
5.
Select the keys that are to be recovered by using the mark command, which is described in the section mark key-spec on page 213. 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.
repeated until you have loaded the required number of cards from the Administrator Card Set. If you do not have the required number of cards from the Administrator Card Set, press Q and then Enter . The rocs utility returns you to the rocs > prompt without processing any keys. Administrator cards should only be inserted in a server you know is secure.
208
9.
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
209
Note
mark key-spec module number quit recover rescan revert key-spec save key-spec status target cardset-spec unmark key-spec
You can specify a command by typing enough characters to identify the command uniquely. For example, for the status command, you can type st and then press Enter . help With no arguments specified, help shows a list of available commands with brief usage messages and a list of other help topics. With an argument, help shows detailed help information about a given topic.
help intro displays a brief step-by-step guide to using rocs.
list cardsets This command lists the Operator Card Sets and softcards in the current security world. For example:
No. 1 2 3 Name test test2 test3 Keys (recov) 6 (6) 3 (2) 1 (1) Sharing 3 of 5; 20 minute timeout 2 of 3 1 of 1; persistent
In this output:
210
No.
This is the card set or softcard number, which can be used to identify this card set in rocs commands.
Name
This is the number of keys protected by this Operator Card Set or softcard
(recov)
This indicates that the Operator Card Set is persistent and does not have a time-out set
### minute timeout
This indicates that the Operator Card Set is persistent and has a time-out set.
211
list keys This command lists the keys in the current security world, as in the following example:
No. 1 2 R 3 4 5 Name rsa-test Id: uc63e0ca3cb032d71c1c Server-Cert Id: uc63e0ca3cb032d71c1c Server-Cert App hwcrhk pkcs11 pkcs11 pkcs11 pkcs11 Protected by module test2 test --> test2 test --> test3 module (test ---> fred2)
where:
No.
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
212
mark key-spec This command marks the listed keys that are to be recovered to the target Operator Card Set or softcard. You can mark one or more keys by number, ident, Operator Card Set or softcard, or hash. See Specifying keys on page 217 for details. To mark more than one key at a time, ensure that each key-spec is separated from the other by spaces, as in the following example:
mark key-spec1 key-spec2 key-spec3
If you have not selected a target Operator Card Set or softcard, or if rocs cannot parse the key-spec, then rocs displays an error message. You can mark and remark the keys to be recovered to various target Operator Card Sets or softcards. Remarking a key displaces the first target in favor of the second target. Note 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.
213
recover This command transfers the marked keys to their target Operator Card Sets or softcards. This operation is not permanent until you save these keys by using the save command. rescan This command updates the card set and key information. revert key-spec This command returns keys that have been recovered, but not saved, to being protected by the original protection method. If the selected keys have not been recovered, rocs displays an error message. save key-spec This command writes the new key blobs to disk. If you specify a key-spec, only those keys are saved. Otherwise, all recovered keys are saved. status This command lists the currently selected module and target Operator Card Set or softcard. target cardset-spec This command selects a given Operator Card Set or softcard as the target. You can specify the card set or softcard name, the number returned by list cardsets, or the hash.
214
unmark key-spec This command unmarks the listed keys. Unmarked keys are not recovered.
In this command:
-m, --module=MODULE
specifies the Operator Card Set or softcard to be used to protect the keys. See Specifying card sets on page 217 for details.
-k, --keys=KEYS-SPEC
selects the keys to be recovered. See Specifying keys on page 217 for details.
-c, --cardset=CARDSET-SPEC
selects all keys that are protected by the given Operator Card Set or softcard. See Specifying card sets on page 217 for details.
-i, --interactive
forces rocs to start interactively even if you have already selected keys.
215
displays a brief usage summary for rocs. You must specify the target before you specify keys. You can use multiple --keys=KEYS-SPEC and --cardset=CARDSETSPEC options, if necessary. You can specify multiple targets on one command line by including separate --keys=KEYS-SPEC or --cardset=CARDSET-SPEC options for each target. If a key is defined by --keys=KEYS-SPEC or --cardset=CARDSET-SPEC options for more than one target, it is transferred to the last target for which it is defined. If you have selected a module, a target Operator Card Set or softcard, and keys to recover but have not specified the --interactive option, rocs automatically recovers the keys. rocs prompts you for the Administrator Card Set and Operator Card Set or softcard, as described in Using rocs interactively on page 207. Note If you use rocs from the command line, all keys are recovered and saved automatically. You cannot revert the keys unless you still have cards from the original Operator Card Set. If you do not specify the target and keys to recover, or if you specify the --interactive option, rocs starts in interactive mode with the selections you have made. You can then use further rocs commands to modify your selection before using the recover and save commands to transfer the keys.
216
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
217
and
rocs -t target_OCS -k "mark 56"
appname:keyident
This selects keys by their internal application name and ident. You must supply at least one of appname or keyident, but you can use wildcard patterns for either or both in order to select all matching keys. An example of usage is:
rocs -t target_OCS --keys="simple:simplekey"
hash keyhash
This selects the key with the given key hash. An example of usage is:
rocs -t target_OCS --keys="hash e364[...]"
--cardset cardset-spec
218
replace the pass phrase of an Operator Card even though you do not know the current pass phrase. This operation requires authorization from the Administrator Card Set. Changing a pass phrase with cardpp when you do know the current pass phrase does not require authorization from the Administrator Card Set; for more information see the Operator Guide appropriate for your module.
Each card in a card set can have its own individual pass phrase. You can even have a set in which some cards have pass phrases and others do not. A pass phrase can be of any length and can contain any characters that you can type.
If these conditions are met, take the following steps: 1. Run the cardpp utility using the command:
In this command:
--recover
specify the number of the module to use. If you only have one module, MODULE is 1. If you do not specify a module number, cardpp uses all modules by default.
219
2. 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.
220
1.
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.
221
If you discover that one of the cards in the current Administrator Card Set has been damaged or lost, use the command-line utility racs or the KeySafe Replace Administrator Card Set option to create a new set immediately. If further cards are damaged, you may not be able to recreate your security world. nCipher recommends that you erase your old Administrator Cards as soon as you have created the new Administrator Card Set. An attacker with the old Administrator Card Set and a copy of the old host data could still re-create all your keys. With a copy of a current backup, they could even access keys that were created after you replaced the 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.
2. 3. 4.
222
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.
223
7.
When you insert a blank card, KeySafe takes you to the Set Card Protection Pass Phrase panel:
8.
If you want to set a pass phrase for this Administrator Card: a. 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.
224
10. After you have created all the Administrator Cards, KeySafe displays a message:
ACS successfully replaced. Now consider erasing your old Administrator Cards
Click the OK button, and KeySafe returns you to its introduction panel. 11. When you have finished replacing the Administrator Card Set, erase the old Administrator Cards.
In this command:
--module=MODULE
tells racs to allow the use of smart cards that already contain data. Any existing data is erased. If a value for this flag is not specified, racs prompts you if a card contains data. When you have finished replacing the Administrator Card Set, erase the old Administrator Cards.
225
Help options
If a utility has the standard help options, these are not included in the synopsis or in the description. The standard help options are as follows:
-h, --help displays help for the utility -v, --version displays the version number of the utility -u, --usage displays a brief usage summary for the utility
Some commands have alternative help options. These are described but are not included in the synopsis.
226
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 port to use to communicate with the module.
IP_address
This option specifies the IP address of the module from which to obtain the ESN and HKNETI key hash.
227
cfg-reread
cfg-reread
This utility loads the hardserver configuration from the configuration file.
Usage
C:\nfast\bin\cfg-reread.exe
This command has no options or parameters. It loads the file C:\nfast\kmdata\config\config as the clients current configuration. See server_remotecomms on page 90 for details of the configuration file. The cfg-reread utility calls a number of separate utilities, each of which loads one section of the configuration file. If you update only one section of the configuration file, you can reload just that section by running the corresponding command as follows:
Utility
hsc_loadseemachine.exe hsc_serverremotecomms.exe hsc_serversettings.exe hsc_slotimports.exe hsc_slotexports.exe
Updates ...
SEE machine settings Remote communications settings Module settings and hardserver settings Imported slot settings Exported slot settings
228
enquiry
enquiry
The enquiry utility returns information about the nCipher server and the modules connected to it.
Usage
enquiry -m|--module=MODULE
In this command, --module=MODULE is the module number of the module about which you want to receive information. If you do not specify a module, enquiry returns information about all modules.
Output
enquiry returns the following data for the server and each module: enquiry reply flags Failed indicates that the module has failed. This failure may be because the module is in the Error state or because there
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
229
enquiry
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 HasTokens flag is set if the module has a smart card interface.
230
enquiry
MaintenanceMode
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
For modules that support enquiry level Three or greater, the KeyStorage flag is set if you have a key-management module. If this flag is set for any of the attached modules, it is also set for the server.
231
enquiry
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 HasNSOPermsCmd flag is set if the module supports the SetNSOPerms nCore API command. If you purchased a developer kit, you can refer to the relevant developer documentation for information on nCore API commands.
ServerHasPollCmds
The ServerHasPollCmds flag is set if the server or any module supports the PollModuleState and PollSlotList API commands. If you purchased a developer kit, you can refer to the relevant developer documentation for information on nCore API commands.
232
enquiry
FastPollSlotList
The FastPollSlotList flag is set for a particular module if PollSlotList on that module does not require module interaction. This is the case if both the hardserver and the module support the relevant extensions.
HasSEE
The HasSEE flag is set if the module firmware supports the Secure Execution Engine (SEE).
HasKLF
The HasKLF flag is set if the module has a longterm fixed signing key.
HasShareACL
The HasShareACL flag is set for a module if the firmware supports creation of ACLs on smart card shares. If this flag is set, then the module is capable of creating Operator Card Sets that can be loaded remotely.
HasFeatureEnable
The HasFeatureEnable flag is set if the module supports feature enabled functions. See Chapter 8: Feature Enabling nCipher Modules for information on the features available and how to enable them.
HasFileOp
The HasFileOp flag is set if the module supports operations using nonvolatile memory.
HasPCIPush
The HasPCIPush flag is set by the module if it has PCI push functionality.
233
enquiry
HasKernelInterface
The 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-
234
enquiry
product name
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.
235
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 name
ISO Smart Card Support Remote Operator Korean Algorithms.
GeneralSEE
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.
236
enquiry
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).
237
floodtest
floodtest
The floodtest utility performs hardware speed testing using modular exponentiation with the Chinese Remainder Theorem.
Usage
C:\nfast\bin\floodtest.exe [--crt|--no-crt] [-Q|--query] [-R|--no-round-robin] [-l|-job-size=BITS] [-t|--stop-after=TIME] [-j|--outstanding-jobs=COUNT] [-n|--jobs-count=COUNT] [[[-K|--skew-check=SKEW ]| [-T|--min-check=COUNT ]] [-C|--check-start=TIME ]] [--overprint][-o|--output=FILE] [-r|--report-interval=TIME]
Program options
--crt
These options specify use Query mode (spinlock) rather than Wait mode
-R, --no-round-robin
These options specify that replies be accepted in any order. (The default is that replies are accepted on a round-robin basis.)
238
floodtest
-l, --job-size=BITS
These options set the size of exponentiation modulus to the number of bits specified in BITS. The default is 1024. The value of BITS must be between 64 and 4096. BITS must be a multiple of 64 Note Certain older modules (with serial numbers beginning 01-52, 01-54, 01-56, 01-P2, 01-P4, or 01-P6) can run out of memory if you run floodtest with sizes greater than 2048, especially if the module has any keys or tokens loaded.
-j, --outstanding-jobs=COUNT
These options try to keep COUNT number of jobs outstanding at a time. The default value of COUNT is the maximum number of jobs recommended for the hardserver, plus 1.
-t, --stop-after=TIME
These options specify the maximum time to run the test. Use the suffix s to specify seconds, m for minutes, h for hours, and d for days. The default value of TIME is infinity.
-n, --jobs-count=COUNT
These options specify the maximum number of jobs to run. The default value of COUNT is infinity.
These options perform threshold checking, starting after either 15 seconds or the time specified by --check-start. Subsequently, when floodtest writes an output line, it quits with an error message if the overall average number of modular exponentiations each second drops below COUNT.
239
floodtest
-K, --skew-check=SKEW
These options perform skew checking, after either 15 seconds or the time specified by --check-start. floodtest records the overall average number of modular exponentiations each second as rec_ave. Subsequently, when floodtest writes an output line, it quits with an error message if the average is outside the range rec_aveSKEW. Note The --min-check and --skew-check options are mutually exclusive.
-C, --check-start=TIME
This option specifies the time in seconds at which threshold or skew checking starts. The default value of TIME is 15.
Output options
--overprint
This option prints results all on one line, using \r rather than \n.
-o, --output=FILE
This option displays, at the specified interval of TIME seconds, the total number of exponentiations achieved, and the rate at which they are performed. The default value of TIME is 1.
240
floodtest
Output
floodtest returns output similar to this:
hardware, speed index 296, using rec. max outstanding + 1 = 46 1, 148 59.2, 151 overall 2, 410 140.32, 206 overall 3, 677 190.992, 226 overall 4, 944 221.395, 267 overall 5, 1190 231.237, 256.5 overall ...
The first column, to the right of the line numbers, shows the number of seconds. The second shows the total number of exponentiations performed. The third column shows the number of exponentiations achieved this second. The last column shows a moving average of the number of exponentiations achieved each second.
241
hardserver
hardserver
The hardserver is the communications service between applications and nCipher modules. You must be logged in as Administrator to use the command-line options for this command.
Usage
hardserver.exe [-c|--command-line]
The hardserver is configured by means of configuration files. See Hardserver configuration file on page 85 for information. The -c or --command-line options run the hardserver program as a command line program instead of as a service
Hardserver startup
The hardserver utility is the hardserver program. It is installed as a service and started automatically.
%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.
242
hardserver
server.
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.
243
initunit
initunit
The initunit utility initializes a unit with a random module key and a known KNSO. This utility makes a key-management module usable but does not enable any key archival or recovery.
Usage
In order to use initunit, you must be logged in to the host computer as root or as a user in the group nfast and must start the module in the pre-initialization state. See Entering the pre-maintenance state on page 76 for information on putting the module into a pre-initialization state.
C:\nfast\bin\initunit.exe [-m|--module=MODULE] [-n|--ntoken]
In this command:
-m, --module=MODULE
These options specify the module number (MODULE) of the module you want to initialize. If you do not specify a module, initunit initializes all modules that are in a preinitialization state.
-n, --ntoken
244
initunit
Output
If initunit is successful, it returns a message similar to this for each module that has been initialized:
Initialising Unit # Setting dummy HKNSO Module Key Info: HKNSO ###################HKM
###################
Otherwise, it returns an error message that points to the reason for the initialization failure.
245
loadkeys
loadkeys
The loadkeys utility is used with a payShield installation. It imports, generates or exports keys. Its use is described in full in the Keyloading Solution Guide.
Usage
C:\nfast\bin\loadkeys.exe [options] psiname
In this command, psiname is the name of the payShield installation that you are going to import the key into. psiname must consist of 16, or fewer, lower case alphanumeric characters.
Options
Modes of Operation
-I, --import
This option specifies that the application does not prompt for nonessential options that have not been specified on the command line. Non-essential options include key export options, rolespecific options and group memberships.
246
loadkeys
General options
-m, --module=MODULE
These options select the hardware security module to use. The default is 1.
-f, --format=FORMAT
These options specify the import or export format for the key. This can be wrapped or components.
--kcvf=CV_FORMAT
These options specify the key Check Value format. This can be one of none (for no check value), zero (for the encryptzeros method) or self (for the encrypt-self method).
-d, --debug
These options specify the name for the imported key. This can be either the name of the key to be exported or the name to give the newly imported key, depending upon the operation. Import/Generate options
-l, --length=LENGTH
These options set the lengths for each component. LENGTH can be 8, 16 or 24 bytes. This is equal to the length of the resulting derived key, or half the length of the derived key if you are importing cvk or cvkv keys.
247
loadkeys
You can omit this option if the key type specified in --role=ROLE has only one permitted length.
-r, --role=ROLE
These options 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 specify that the key is not to be exportable in attended operations.
Component options
--ccvf=CV_FORMAT
These options specify the component Check Value format. This can be one of none (for no check value), zero (for the encrypt zeros method) or self (for the encrypt-self method).
-n, --num=COMPONENTS
These options specify the total number of components. This can be an integer from 2 through 9.
248
loadkeys
Wrapped options
-w, --wrapper=NAME
These options specify the name of the wrapping key. key. If the payShield key that you specify cannot be loaded, the application prompts you for another name.
These options specify the IIPB mask to be used with this reduced AC key operation. The default is ffff000000000000.
This option specifies the decimalization table that is to be used with a new PVKIBM key.
--pan-n=PAN
This option specifies the number of PAN digits to be required for PIN generation with a new PVKIBM key. PAN can be an integer from 0 through 12: the default is 12.
249
key-xfer-im
key-xfer-im
The key-xfer-im utility transfers a key into a second security world. The module must previously have had the second security worlds module key loaded using the mk-reprogram utility, described in mkreprogram on page 255. (See Transferring keys between security worlds on page 185.)
Usage
key-xfer-im SOURCE-KMDATA-LOCAL DESTINATION-KMDATA-LOCAL NEW-PROTECT KEY-FILE [KEYFILE ...] [NEW-PROTECT KEY-FILE [KEY-FILE ...]]
Parameters
SOURCE-KMDATA-LOCAL
The full path name of the kmdata file for the source security world.
DESTINATION-KMDATA-LOCAL
The full path name of the kmdata file for the target security world.
NEW-PROTECT
The protection for the key in the target security world. You must specify either --module or --cardset. If you specify --cardset, it must be followed by the key hash for the destination card set. In addition, you can also specify options to configure the key protection further:
250
key-xfer-im
--export-leave
This option is used to leave the keys list of operations requiring authorization from the Administrator Card Set (ACS)= the same. This is the default.
--export-add
This option is used to add export to the keys list of operations requiring authorization from the ACS. This option is available only when exporting keys from a strict FIPS 140-2 level 3 security world into a non-strict FIPS 140-2 level 3 security world.
--export-delete
This option is used to remove export from the keys list of operations requiring authorization from the ACS. This option is available only when exporting keys from a non-strict FIPS 140-2 level 3 security world into a strict FIPS 140-2 level 3 security world.
--aclbase-recovery
This option is used to base the Access Control List (ACL) of the exported key on the ACL in the recovery key blob. This is the default.
--aclbase-working
This option is used to base the ACL of the exported key on the ACL in the working key blob.
KEY-FILE
This is the full path of source kmdata file for the key. The module must have module keys from both worlds: program it into one world with new-world and use mk-reprogram to
251
key-xfer-im
add the other module key. If transferring between Strict FIPS-140 level 3 and non-strict worlds, the modules owning world must be non-strict. The following example command demonstrates the second step in moving a module from a security world that is not FIPS 140 2 level 3 compliant to one that is:
key-xfer-im C:\nfast\kmdata\local\ C:\nfast\kmdata-FIPS\local\ --module --export-delete KEY-FILE
252
loadrom
loadrom
The loadrom utility loads new firmware into a module. Firmware is supplied as an encrypted and signed file. See Upgrading module firmware on page 323 for information on upgrading firmware. You can also use loadrom to obtain information about the firmware.
Usage
C:\nfast\bin\ [-v|--view] [-n|--notypecheck] [-m|--module=MODULE] [-b|--maxblocksize=SIZE] NFF_file
In this command NFF_file is the name of the file that contains the firmware. This has the extension .nff. See Appendix A: Upgrading module firmware for information on the file name for your module.
Help options
-h, --help
Programming options
-v, --view
These options only display information about the .nff file and do not load it.
253
loadrom
-i, --ioboard
These options set the maximum block size in bytes for module programming.
--notypecheck
Output
If you select the --view option, loadrom displays output similar to this:
File :..\..\module\firmware\2-18-13\ncx3p-21.nff Firmware : PCI Type 3 firmware version 2.18.13cam1 (VSN 21) for : nC1003P/nC3023P Filetype : NFast3 Programming chunks: 12 Confidentiality key: nC3023P confidentiality key (dorris #2) Confidentiality mech: DES3mCBCi64pPKCS5 Signatures: #0: <unknown> integrity key #1: nC3023P integrity key (dorris-1)
During installation and when upgrading module firmware you can compare the output of loadrom --view with the information provided by the enquiry command-line utility to ensure that the correct version of the firmware is present on the module. See enquiry on page 229.
254
mk-reprogram
mk-reprogram
The mk-reprogram utility programs a security-world module key into a module to which it does not yet belong. A key that is to be transferred from one security world to another must be loaded into a module that: has been programmed into one of the security worlds has had the module key of the target security world loaded into it using mk-reprogram.
After the security-world module key has been loaded, you can use the key-xfer-im utility to transfer a key into the second security world. (See Transferring keys between security worlds on page 185.)
Usage
mk-reprogram.exe [[--module MODULE-NO----] CHANGES
In this command CHANGES specifies the parameters of the reprogrammed security world, as described in Keywords on page 256. kmdata must be from the security world that includes the module.
Options
--module=MODULE-NO
specifies the module on to which to program the security world. The default is the first available module.
--protocol
255
mk-reprogram
Keywords
CHANGES can be one of the following: list
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
Example
The following example command demonstrates the first step in moving a module-protected key from a security world that is not FIPS 140 1 level 3 or FIPS 140 2 level 3 compliant to one that is:
mk-reprogram --module 1 add C:\nfast\kmdata_FIPS\local
256
ncversions
ncversions
The ncversions utility displays installed nCipher support software components and their versions. The utility lists all components, whether installed individually or as part of a component bundle, and also the component bundles themselves. See Components on nCipher CD-ROMs on page 330.
Usage
C:\nfast\bin\ncversions.exe
Output
The following in an example of a component list produced by ncversions:
Comp Output Version Repository/Build no. ---------------------------------------------------------------convrt user 1.1.0 cam/1 csee armdev 0.10.5 cam/3 csee seedev 0.10.5 cam/3 ctd agg 0.0.12 cam/4 ctls agg 0.0.13 cam/3 cutils devel 1.4.2 cam/8 emvjni user 0.2.2 cam/36 emvspj user 0.2.6 cam/20 emvspj devel 0.2.6 cam/20 emvspp user 1.5.10 cam/14 emvspp devel 1.5.10 cam/14 gcchk user 1.1.1 cam/2 ... ... ... ... ... ... ... ...
257
ncversions
Comp
258
new-world
new-world
The new-world utility creates a security world that supports SEE functions and remote Operator Card Set use. new-world also allows you to specify different thresholds for different operations, such as: adding a module replacing an Operator Card Set authorizing real-time clock operations authorizing nonvolatile memory operations.
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]
259
new-world
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.
These options tell new-world to initialize a new security world and program it into the module specified in --module=MODULE, replacing any existing kmdata directory.
-l, --program
These options tell new-world to load the existing security world from the kmdata directory into a module specified in --module=MODULE.
-e, --factory
These options tell new-world to erase a module, restoring it to factory state. Note You must not include more than one of the --initialize, --program, and -factory options. If you do not specify any of these options and a kmdata directory already exists, new-world loads the security world found within the directory. If you do not specify any of these options and no kmdata directory exists, new-world creates a security world.
260
new-world
These options tell new-world that the selected module is not a target for remote shares.
In these options K is the maximum number of smart cards required from the Administrator Card Set to authorize a feature. You can specify lower thresholds for a particular feature. Thresholds must be less than or equal to the total number of cards in the set. N is the total number of smart cards to be used in the Administrator Card Set. This value must be less than or equal to 64. Note You should not create an Administrator Card Set for which the required number of cards is equal to the total number of cards because you cannot replace the Administrator Card Set if even a single card is lost or damaged. The --acs-quorum=K/N option only takes effect if you are creating a new security world.
261
new-world
-F, --strict-fips-140-2-level-3
These options create a security world that conforms to the FIPS 140-2 requirements for roles and services at level 3. If you do not specify this flag, new-world creates a security world that complies with FIPS 140-2 requirements for level 2. Note 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.
262
new-world
If you do not enable this option at the time of security world creation, you can never enable recovery for keys in the security world. If you do not enable this option when you create the ACS, you can never enable recovery for any card sets protected by the ACS.
-k, --km-type=KEY-TYPE
These options specify the type of key that is to protect the new security world. KEY-TYPE can be des3 or rijndael).
Features
When initializing a security world, features may be specified as arguments after the module number. Some features are enabled by default, and you can give the command new-world --help-features to display a list of features indicating which are enabled by default when initializing a security world with new-world. Features are specified as a comma-separated list of terms. Each term consists of a feature name, optionally preceded by either a dash (-) or an exclamation point (!) to turn off the feature and can optionally be followed by an equal sign (=) and the threshold for this feature. However, the ! character, used to turn off a given feature, is interpreted by some shells (for example, the C shell and its derivatives, bash and zsh) as requesting a history expansion. In such cases, you must escape the ! character by preceding it with a \ character, as in the following example:
new-world 2 rtc,nv,\!r
Additionally, any feature entered on the command line with a leading hyphen (-) can be interpreted as an option. Attempting to pass a feature as a nonexistent option in this way returns an error (for example, unknown option). Prevent errors of this kind by using the
263
new-world
standard POSIX double hyphen (--) marker to indicate that any subsequent features on the command line are not to be interpreted as options, as in the following example:
new-world -m 2 -- -r
Smartcard Support. The dsee and dseeall options are not applicable unless you have purchased and installed nCiphers CodeSafe Developer kit. For example, the following features:
m=1,r,!p,nv=2,rtc=1
create a security world for which: a single card from the Administrator Card Set is required to add a new module the default number is required to replace an Operator Card Set pass phrase recovery is not enabled 2 cards are required to allocate nonvolatile memory
264
new-world
Note
Under most conditions, it is advisable to turn on such features as nv, rtc, dsee, and (if desired) p. There is usually no benefit in turning on both dsee and dseeall simultaneously.
Output
If new-world cannot interpret the command line, it displays its usage message and exits. If you attempt to set a threshold for a feature that you have disabled or if you attempt to set a threshold too high, new-world displays an error and exits. If the module is not in the pre-initialization state, new-world displays and error and exits. To put the module in the pre-initialization state, see Entering the pre-maintenance state on page 76. If the module is in the pre-initialization state, new-world prompts you for smart cards and pass phrases as required. When new-world has initialized the module, restart the module in the operational state.
265
nvram-backup
nvram-backup
The nvram-backup utility copies files between a modules nonvolatile memory and a smart card. It can be used to back up and restore files that are stored in NVRAM. Files you can back up and restore are data files stored in NVRAM by an SEE program and NVRAM-stored keys. See the Operator Guide for more details. Do not store keys in NVRAM unless you must do so to satisfy regulatory requirements. Note nCipher introduced NVRAM key storage only for users who must store keys within the physical boundary of a module to comply with regulatory requirements. NVRAM-stored keys provide no additional security benefits and their use exposes your Administrator Card Set to increased risk. Storing keys in nonvolatile memory also reduces loadbalancing and recovery capabilities. Because of these factors, nCipher recommends you always use standard security world keys unless explicitly required to use NVRAM-stored keys. To use nvram-backup you specify an action and, optionally, the location of the files to be acted on. Available actions are list, copy and delete. You can list the contents of, and delete files from, a modules NVRAM, and copy files from NVRAM to a smart card. You can list files on a smart card and copy from a card to a modules NVRAM. You cannot use nvram-backup to delete files from a smart card. Note Use the bulkerase utility to format cards for use with nvram-backup. If you are using a FIPS 140-2 level 3 compliant security world, you will be prompted for an Administrator Card or Operator Card from the security world to authorize copying of files to or from NVRAM and deletion of files from the modules NVRAM. When you copy files to a modules NVRAM or delete files from NVRAM, you are required to insert a quorum of Administrator Cards for NVRAM authentication.
266
nvram-backup
Usage
C:\nfast\bin\nvram-backup.exe -l|--list -M|--from-module|-S|--from-smartcard [-m|-module=MODULE] [-s|--slot=SLOT] [-f|--force] [-v|--verbose] [-x|--hex] [FILES]
Help options
-h, --help
These options display the version number for nvrambackup.exe. -u, --usage
These options list files either on a modules NVRAM or on a smart card. By default nvram-backuplists the contents of the modules NVRAM.
267
nvram-backup
-c, --copy
These options copy files between a modules NVRAM and a smart card. You cannot copy from a modules NVRAM to a smart card those files whose ACL prohibits copying. Copying is prevented by use of the --no-copy option in the nvram-sw utility described in nvram-sw on page 272.
-d, --delete
These options delete files from a modules NVRAM. You cannot use nvram-backup to delete files from a smart card. If you attempt to use nvram-backup to delete files from a smart card, a message displays and nvram-backup terminates..
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.
These options specify the module for nvram-backup to use. The default is 1.
268
nvram-backup
-s, --slot=SLOT
These options identify the slot on the selected module for the specified nvram-backup action. The default is 0. You do not need to specify a slot when listing the contents of, or deleting files from, a modules NVRAM.
General options
-f, --force
These options force nvram-backup to delete or overwrite a file without requesting confirmation.
-v, --verbose
These options specify that hex notation is used for the file selection option.
--no-length
When used with the --list option, the --no-length option specifies that file lengths are not printed.
269
nvram-backup
Output
To list the contents of the default modules NVRAM, use the command:
C:\nfast\bin\nvram-backup.exe --list
In this example, four files are stored in the modules NVRAM, two NVRAM-stored keys and their associated recovery information. For information on identifying file types by their File IDs, see nvram-sw on page 272. To obtain a listing of the contents of a modules NVRAM with further information, including file size, use the nvram-sw utility. To back up NVRAM-stored keys from the default module to a smart card, use the command:
C:\nfast\bin\nvram-backup.exe --copy --from-module b*
If you have a FIPS 140-2 level 3 compliant security world, you must provide authorization to back up files stored on NVRAM. nvrambackup prompts you to insert a smart card from this security world for authorization.
270
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.
You can check the success of the command by listing the contents of the smart card. Use the command:
C:\nfast\bin\nvram-backup.exe --list --from-smartcard
To delete NVRAM-stored keys from the default module, use the command:
C:\nfast\bin\nvram-backup.exe --delete *b
If you have a FIPS 140-2 level 3 compliant security world, you must provide authorization to delete files from the modules NVRAM. nvram-backup prompts you to insert a smart card from this security world for authorization. 1. If prompted, insert a smart card from the current security world. Deleting files from a modules NVRAM requires authentication and you are prompted to insert Administrator Cards for NVRAM authentication. 2. Insert the required number of cards, each one in turn, into the authentication slot. When authentication is complete, for each file that matches the specified criteria, nvram-backup prompts for confirmation. 3. Input yes to delete a file or no to retain it in NVRAM.
When all files have been listed for confirmation, nvram-backup terminates.
271
nvram-sw
nvram-sw
The nvram-sw utility views and modifies NVRAM areas.
Usage
C:\nfast\bin\nvram-sw.exe -a|--alloc [-m|--module=MODULE] [-b|--bytes=BYTES] [-n|-nvram-id=ID] [-k|--key=APPNAME,IDENT][--no-copy]
Help options
-h, --help
272
nvram-sw
-V, --version
These options allocate a new NVRAM area on the module specified in MODULE. An Administrator Card Set must be inserted to perform this action.
-d, --delete
These options delete the NVRAM area on the module specified in MODULE. An Administrator Card Set must be inserted to perform this action.
-w, --write
These options write data to the NVRAM area on the module specified in MODULE. The data is written from the file specified in FILE, if present. Otherwise, it is written from stin. If the ACL of the NVRAM area requires it, an Operator Card Set must be inserted to perform this action. This action may not be permitted by the ACL of the NVRAM area.
-r, --read
These options read data from the NVRAM area on the module specified in MODULE. The data is written to the file specified in FILE, if present. Otherwise it is written to stdout. If the ACL of the NVRAM area requires it, an Operator Card Set must be inserted to perform this action. This action may not be permitted by the ACL of the NVRAM area.
273
nvram-sw
-c, --delete-noadmin
These options delete the NVRAM area on the module specified in MODULE when no Administrator Card Set is required. If the ACL of the NVRAM area requires it, an Operator Card Set must be inserted to perform this action.
-i, --acl
These options display the ACL of the NVRAM area on the module specified in MODULE. If the ACL of the NVRAM area requires it, an Operator Card Set must be inserted to perform this action.
-l, --list
General options
-m, --module=MODULE
These option specify that hex notation is used for the ID value supplied to the --nvram-id option.
These option specify the number of bytes to allocate for -alloc or to read for --read. The default is 100.
274
nvram-sw
-n, --nvram-id=ID
These option specify the identifier of the NVRAM file for all actions except --list. The default is test-file
-f, --file=FILE
These option specify the file to be read or written for the -read and --write options. If this option is not specified for these actions, stdin or stdout is used by default.
-k, --key=APPNAME, IDENT
These option specify a key during the --alloc action. This key is required for all subsequent --read or --write actions on the NVRAM area.
--no-copy
This option used with the --alloc option allocates a file with an ACL that does not allow copying.
Identifying files
Files created by nCipher security world tools often have a FileID that consists of a character identifying the type followed by a M_ShortHash. You can use this information to identify the type of files stored in NVRAM and for specifying types of files for use with an nCipher security world utility.
275
nvram-sw
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)
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:
276
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.
WarntIdBlob
test-file
277
payshield-config
payshield-config
The payshield-config utility modifies the payShield installations settings. The utility must be run immediately after running payshieldinstall or payshield-install - -retarget to complete the setup or retargeting of the payShield installation. This utility can be used to enable the AcquirePIN Clear PIN functionality. It uses its own key role which is incompatible with other payShield PIN functions (KeyRole_AWK). Use of this function is not recommended as best practice. You should only enable the AcquirePIN function if the payShield installation will be running in a physically secure location with trusted operators and network at all times. Any PIN entered via the AcquirePIN function cannot be considered to be secured by the module. Using the same PIN and PAN combination for both AcquirePIN and PVV/Offset PIN operations may therefore negate the security of PVV/Offset. This utility can also be used to enable IBM PIN functions and unattended key import and export. Enabling these functions may reduce the security of the system and is not recommended. If any of these functions are needed, the proper restrictions should be applied. If you are not sure whether you need these functions, or do not know what the proper restrictions are, please contact nCipher Support.
Usage
payshield-config.exe [-h|- -help][-v|- -version][-u|- -usage] [{-m|--module}=MODULE] [{-s|- -slot}=SLOT] [{-c|--configfile}=FILENAME] [{-d|--dump-config}=FILE] [-helpfeatures]PSINAME FEATURES
-m, --module=MODULE
278
payshield-config
-s, --slot=SLOT
These options 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.
279
payshield-info
payshield-info
The payshield-info utility displays information about a specified payShield installation.
Usage
payshield-info.exe [-i|--info][-k|--keys][-n|--name]=keynamePSINAME
General options
-V, --verbose
These options select the output sort mode for the --keys and
--roles modes.
280
payshield-info
-n, --name=keyname
These options display all the keys in the payShield installation named PSINAME that have the role specified in keyrole (for example, PVKP). To view keys for which role information is unavailable, use --role=unknown.
Keywords
PSINAME The name of the payShield installation to provide information about.
Output
The following information is displayed: The name of the payShield installation The version of the SEE machine in use The K and N values of the Master Card Set The K and N values of the Key Establishment Card Set The hash of the Master key The hash of the Key Establishment Key The maximum possible number of loaded keys The flags that are set on the payShield installation
281
payshield-info
For example:
PSI Name: qapsi EMVSM version: 1.0.6+ 2003-01-13 16:55:51. jgeater Master Key Hash: d42e1791a4e5ea5021444e521bb2c650093efd4d Estab Key Hash: a06fe51b52725b344dade13a59466bdb77400c1f Max Keys: 1000 Flags (0x3e0000): TotallyInsecure InsecureImport InsecureDebug SmartcardImport UnrestrictedImport Cardsets: allocated 0053BCD8 Estab CardSet: 1/1 (aaa002b568604e5bbc3a63dcdb0209cd478f317b) Master CardSet: 1/1 (b9a595b21446ca82dee93a482d60848ec0f1b5dd)
282
payshield-install
payshield-install
The payshield-install utility is used to configure a security world specifically for the requirements of your payShield installation.
Usage
payshield-install.exe [--master-quorum=K/N --estab-quorum=K/N[{-m|--module}=MODULE] [{s|- -slot}=SLOT] [{-A|- -adminslot}=ADMIN_SLOT] [{-L|--max-loaded-keys}=NUM] [--nonfips-temporarykeys] [--totally-insecure] [--override-keyhash-check] [-D|- -allowinsecure-debug] [-S|--allow-smartcard-import] [-I|- -allow-insecure-import] [-U|- allow-unrestricted-import] [--require-estab-always] [--retarget-see-machine] [-acquirepin-wait=INT] PSINAME KEYHASH
Security options
--master-quorum=K/N
This option specifies the K-of-N sharing parameters for the Master card set. The default is 3 of 5 (3/5).
--estab-quorum=K/N
This option specifies the K-of-N sharing parameters for the Key Establishment card set. The default is 2 of 4 (2/4).
-m, --module=MODULE
These options specify the slot to use for loading FIPS and FTO authorizations. The default is 0.
283
payshield-install
-L, --max-loaded-keys=NUM
These options specify the maximum number of keys the SEE machine is allowed to load (default=1000).
--non-fips-temporarykeys
This options prohibits the passing of temporary keys through the hardware security modules firmware.
--totally-insecure
This option allows you to set the --allow-insecure-debug and --allow-insecure-imports options, which make the installation totally insecure.
--override-keyhash-check
This option overrides the key hash check against known payShield SEE machine signing key hashes.
-D, --allow-insecure-debug
These options allow the generation of insecure debug. They require you to have also set the --totally-insecure option.
-S, --allow-smartcard-imports
These options allow the importing of keys non-interactively. They require you to have also set the --totally-insecure option.
-L, --allow-insecure-imports
These options allow the importing of keys non-interactively. They require you to have also set the --totally-insecure option.
284
payshield-install
When these options are set, you can use the payShield/Verifone key import method to import nonpayShield keys into your security world. These keys are described as unrestricted because they are imported as module protected and their encrypt/decrypt ACL permissions are not restricted by a certifier or SEE world.
-U, --allow-unrestricted-imports
These options allow the importing of keys with ACLs that allow unrestricted use.
--require-estab-always
This option requires establishment cards to be presented for unrestricted key imports. This is not a security feature.
--acquirepin-wait=INT
This option forces at least INT centiseconds of elapsed time between AcquirePIN operations. The default is 0 (that is, no rate limiting). The delay rate for AcquirePIN is enforced separately for each module. If you have two nShield modules, then two AcquirePIN operations are allowed in the specified time period.
Keywords
PSINAME
This is the payShield installation name, which must be of 16 or fewer lowercase alphanumeric characters.
KEYHASH
This is the hash of the nCipher SPP SEE machine signing key.
285
postrocs
postrocs
The postrocs utility performs clean-up tasks after key-xfer-im has been used to transfer keys that protect PKCS #11 objects.
Usage
C:\nfast\bin\postrocs [-m|--module=MODULE] [-s|--slot=SLOT]
Help options
-h, --help
Options
-m, --module=MODULE
These options specify the target module for the key transfer. The default is 1.
-s, --slot=SLOT
These options specify the target slot for the key transfer. The default is 0.
286
ppmk
ppmk
This utility allows you to manage softcards. It can be used to perform the following tasks: listing softcards creating a new softcard checking or changing a softcards pass phrase recovering a softcards pass phrase deleting a softcard.
Usage
C:\nfast\bin\ppmk.exe --new [-r|-R] NAME C:\nfast\bin\ppmk.exe -l C:\nfast\bin\ppmk.exe -icCpr|--delete [PRELOAD-OPTIONS] NAME|IDENT
NAME
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
287
ppmk
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]
-r, --recover
These options allow you to recover the pass phrase of a softcard (if it was created with a recoverable pass phrase).
--recoverable
This options specifies that the pass phrase of a new softcard is to be recoverable; this is the default, so it is not normally necessary to specify this option in order to create a softcard with a recoverable pass phrase. The pass phrase recovery key Krp be loaded in order to create a softcard with a recoverable pass phrase.
288
ppmk
-R, --non-recoverable
These options specify that the pass phrase of a new softcard is to be non-recoverable.
--delete NAME|IDENT
289
preload
preload
The preload command-line utility enables keys to be loaded onto a module before an application is run. The application can be run immediately in the same session or the first session can be paused and the application can be run in a separate session. Additional keys can be loaded while a session is running. For applications that do not support K-of-N Operator Card Sets, preload enables K-of-N Operator Card Sets and module-protected keys to be loaded before the application is run. You can use the
preload command to preload K-of-N Operator Card Sets before
running PKCS #11 applications. Some command-line options may cause preload to function interactively by prompting for Operator Cards. Note Currently, preload can be used only with command-line utilities.
Usage
C:\nfast\bin\preload.exe [-m MODULE|--module=MODULE] [-c IDENT|--cardset=IDENT] [-cardset-name=NAME] [-s IDENT|--softcard=IDENT] [-o|--any-one] [-i|--interactive] [-A APP|--appname=APP] [-K PATTERN|--key-ident=PATTERN] [-n PATTERN| --name-pattern=PATTERN] [--name-exact=NAME] [-M|--module-prot] [--no-cardset-keys] [--admin=NAME] [-F|--requirefips] [-N|--no-fips] [-f PRELOADFILE|--preload-file=PRELOADFILE] [-R|--reloadeverything] | pause | exit
These options select the module (where MODULE is a module number) onto which keys are to be loaded. Repeating the option with different values for MODULE enables a number of selected modules to be used. By default, preload loads keys on all usable modules.
290
preload
These options specify that all Operator Card Sets that match IDENT are to be loaded. The IDENT variable can be the hash or the name of a card set; the preload command tries to guess whether IDENT is a hash or a name based on the form you supply. If you definitely want to preload a named card set, use the --cardset-name=NAME option instead. Use KeySafe or the nfkminfo command-line utility to identify keys and cards that are used by particular applications. For further information, see the appropriate Operator Guide for your module. Card set patterns or names are treated as substrings.
--cardset-name=NAME
This option specify an Operator Card Set with the given name NAME to be loaded.
-o, --any-one
This option loads a single Operator Card Set and then stops.
-i, --interactive
This option causes preload to load Operator Card Sets interactively until you tell it to stop.
291
preload
Card Sets that are required by the specified keys. By default, if no key selection options are used, preload loads all keys on the loaded Operator Card Set(s) and, if --module-prot is specified, all moduleprotected keys.
-A APP, --appname=APP
These options specify the application to be used by a subsequent --key-ident or --name-exact options. You can set multiple instances of the --appname option to specify more than one application. Examples of APPNAME include:
custom embed hwcrhk netscape simple ssleay
-K PATTERN, --key-ident=PATTERN
These options load all keys whose ident includes or matches PATTERN for the application previously specified by APP. PATTERN is treated as a substring. You can set multiple instances of these options to load keys that match more than one pattern.
-K, --key-ident=PATTERN
These options load all keys with an ident that includes or matches PATTERN for the application previously specified by APP. You can set multiple instances of the --key-ident option to load more than one key. Use KeySafe or the
292
preload
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
Note
The current release of the preload command-line utility can only load softcard-protected keys, not softcards themselves. To load softcards, use the ppmk command-line utility; see ppmk on page 287. If you definitely want to preload a named softcard, use the
--softcard-name=NAME option instead.
Use the ppmk or nfkminfo command-line utilities to identify keys and softcards that are used by particular applications. For further information, see the appropriate Operator Guide for your module. Softcard patterns or names are treated as substrings.
293
preload
--softcard-name=NAME
This option loads all keys protected by softcards matching NAME. Note The current release of the preload command-line utility can only load softcard-protected keys, not softcards themselves. To load softcards, use the ppmk command-line utility; see ppmk on page 287. Use the ppmk or nfkminfo command-line utilities to identify keys and softcards that are used by particular applications. For further information, see the appropriate Operator Guide for your module. Softcard patterns or names are treated as substrings.
-M, --module-prot
These options load module-protected keys in addition to any keys specified by other options.
--no-cardset-keys
This option specifies that keys protected by the requested Operator Card Sets are not automatically loaded.
--admin=KEYS
This option loads the administrator keys specified by KEYS; to load more than one administrator key, the value of KEYS can be a comma-separated list, or you can. specify all to load all administrator keys. Allow administrator keys are: NSO, M, RA, P, NV, RTC, FIPS, MC, RE, DSEE, and FTO. Note When using preload to load non-persistent tokens, you must ensure that you have enough remaining Operator Cards in order to load the token onto the final module. Usually, this means you need one or more cards than you have modules, depending on the circumstances. For example, if you have 4 modules and K is 3, then N must be at least 6 so that there are at least 3 cards remaining to load the token onto the final module.
294
preload
FIPS options
-F, --require-fips
These options specify that FIPS authorization 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 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).
295
preload
296
preload
To preload a specific key with an ident of mykey for the application seeconf on all modules, give the following command:
C:\nfast\bin\preload -A seeconf -K mykey pause
297
preload
298
preload
299
preload
You can use the preloaded keys and tokens when running commands in a separate command window. For example, to load keys for generatekey that were preloaded in the preceding example, open second command window and give the command:
C:\nfast\bin\preload generatekey hwcrhk
In such an example, the preloaded keys and cards remain loaded at least until the open preload -A seeconf -K mykey pause command is terminated in the first window.
300
racs
racs
The racs utility creates a new Administrator Card Set to replace a set that was created with the new-world utility.See Replacing an Administrator Card Set with racs on page 225.
Usage
racs [-m|--module=MODULE]
Options
-m, --module=MODULE
301
rfs-setup
rfs-setup
This utility creates a default remote file system on the client. You run rfs-setup when you first configure a client. See Setting up client cooperation on page 53 for details of client configuration.
Usage
C:\nfast\bin\rfs-setup.exe C:\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 that any existing remote file system is to be overwritten.
--gang-client
This option configures the remote file system to accept connections from a cooperating client. For this option, module_IP_address is the IP address of the cooperating client while module_ESN and keyhash are respectively the electronic serial number (ESN) and key hash for the local module.You must supply values for module_ESN and keyhash when using the --gang-client option unless you also pass the --write-no-auth option.
302
rfs-setup
--write-noauth
This option allows cooperating clients to access the remote file system without HKNETI authorization. You do not need to supply module_ESN or keyhash with this option. nCipher does not recommend using the --write-noauth option except on completely secure networks.
module_IP_address
This option specifies the HKNETI (key hash) of the module. You can obtain the ESN and HKNETI of the module from the modules front panel. You can also obtain it with the anonkneti utility. See anonkneti on page 227 for details.
303
rfs-sync
rfs-sync
This utility synchronises the kmdata between a cooperating client and the remote file system it is configured to access. It should be run when a cooperating client is initialised in order to retrieve data from the remote file system and also whenever a client needs to update its local copy of the data or, if the client has write access, to commit changes to the data. See Chapter 3: Getting the module working for more details about client cooperation.
Usage
C:\nfast\bin\rfs-sync.exe [-U|--update] [-c|--commit] [-s|--show] [--remove] [--setup [setup_options] ip_address]
Options
-U, --update
These options update local key-management data from the remote file system. Note If a cooperating client has keys in its kmdata/local directory that are also on the remote file system, if these keys are deleted from the remote file system and then rfs-sync --update is run on the client, these keys remain on the client they are until manually removed.
-c, --commit
These options commit local key-management data changes to the remote file system.
-s, --show
304
rfs-sync
--setup
This option sets up a new synchronisation configuration. Specifics of the configuration can be altered using setup_options as follows:
-a, --authenticate
These set-up options specify use of KNETI authentication. This is the default.
--no-authenticate
This set-up option specifies that KNETI authentication should not be used.
-m, --module=module
These options select which module to use for KNETI authorisation. The default is module 1. This option can only be used with with the --authenticate option.
-p, --port=port
These options specify the port on which to connect to the remote file system. The default is 9004.
ip_address
This option removes the synchronisation configuration. The rfs-sync command also has additional administrative options for examining and removing lock files that have been left behind by failed rfs-sync --commit operations. Using the --who-has-lock option displays
305
rfs-sync
the task ID of the lock owner. As a last resort, you can use the rfs-sync command-line utility to remove lock files. In such a case, the --killlock option forcibly removes the lock file.
306
rtc
rtc
The rtc utility reads the time from a modules onboard real-time clock. It can also be used to set the clock.
Usage:
rtc [[-g|--get-clock]|[-t|--set-clock [-a|--no-admin-keys] [-A|--adjust]]] [-m|-module=MODULE] TIME
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.
These options tell rtc to read or write the clock of the module MODULE. If MODULE is not specified, the default is 1.
307
rtc
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.
In this command:
--set-clock tells rtc to set the clock. --adjust tells rtc to set the clock and adjust the drift rate.
308
rtc
--no-admin-keys tells rtc not to read the Administrator Card Set. --module=MODULE specifies the ModuleID to use.
TIME is the time to which to set the clock in the form YYYY-MMDD/HH:MM:SS, where -, /, and : are arbitrary delimiter characters that can be any non-numeric character.
Unless you give the --no-admin-keys option, rtc prompts you for the number of cards required from the Administrator Card Set to enable it to set the real-time clock. If you do not specify a time, rtc uses the time from the host computer's clock. If you specify a time, rtc asks you to confirm the operation. This feature enables you to check that you have entered the time correctly.
309
slotinfo
slotinfo
The slotinfo utility returns information about the tokens that are present in a module. slotinfo can also be used to format a token.
Usage
C:\nfast\bin\slotinfo -m|--module=MODULE [-s|--slot=SLOT]
Module selection
-m, --module=MODULE
These options specify the module number of the module to be used. You must specify a module number.
-s, --slot=SLOT
These options specify the number of the slot to be used. If this option is set, slotinfo returns information about the files on the token. If, however, you do not specify --slot, slotinfo returns information about all slots.
--format
This option tells slotinfo to format the token that is currently in the slot. You must specify a slot number if you want to format a token. The token is formatted without a challenge response key. Note Use of the --format option is deprecated. If you use slotinfo with the --format option to format a token, it does not remove the card from the security world lists and cannot erase cards in FIPS 140-2 level 3 compliant security worlds.
slotinfo does not update the security world host data. If you are using
310
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.
311
sppupgradekeys
sppupgradekeys
The sppupgradekeys utility upgrades keys created on older payShield installations so that they can be used with newer payShield installations. You can use the optional EXPORTFILE to specify (by name) those keys that are to be allowed to be exported in attended operations. Note This utility requires a quorum of administrator cards and must only run on a secure host.
Usage
sppupgradekeys [options] psiname [EXPORTFILE]
Options
-m, --module=MODULE
These options specify the number of the module to be used. The default is 1.
-s, --slot=SLOT
These options specify the number of the slot to be used. The default is 0.
--no-name-keys
This option prevents the names of keys being bound to their ACL. If you have already run sppupgradekeys, this will make the operation faster.
312
sppupgradekeys
Key worlds
psiname This is the name of the payShield installation that you are going to import the key into. psiname must consist of 16, or fewer, lower case alphanumeric characters. EXPORTFILE This is a file containing lines of the form:
NAME
313
stattree
stattree
The stattree utility returns the statistics gathered by the nCipher server and modules.
Usage
C:\nfast\bin\stattree [<node> [<node> [...]]]
Output
Running the stattree utility displays a snapshot of statistics currently available on the host machine. Statistics are gathered both by the hardserver (relating to the server itself, and its current clients) and by each attached module. Statistics are displayed in the form of a tree. At each node in the tree, either a set of statistics or a list of sub-categories is displayed. Each node has a label which consists of one of the following: a tag that identifies its contents as described in Node tags on page 316. a number the corresponds to an instance in the category, for example, a module identifier or a client connection identifier
Times are listed in seconds. Other numbers are integers, which are either real numbers, IP addresses, or counters. For example, a result -CmdCount 74897 means that there have been 74,897 commands submitted.
314
stattree
PerModule, ModuleObjStats, and ModuleEnvStats are node tags that identify classes of statistics. #1 identifies an instance node. ObjectCount, MemTotal, and the remaining items at the same level are statistics IDs. Each has a corresponding value.
If node is provided, stattree uses the value given as the starting point of the tree and displays only information at or below that node in the tree. Values for node can be numeric or textual. For example, to view the object counts for local module number 3:
$ stattree PerModule 3 ModuleObjStats +#PerModule: +#3: +#ModuleObjStats: -ObjectCount 6 -ObjectsCreated 334 -ObjectsDestroyed 328
315
stattree
The value of node must be a node tag; it must identify a node in the tree and not an individual statistic. Thus, the following command does not work:
$ stattree PerModule 3 ModuleObjStats ObjectCount +#PerModule: +#3: +#ModuleObjStats: Unable to convert 'ObjectCount' to number or tag name.
Node tags
These hold statistics for each module:
Category
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
316
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
317
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
318
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
HostReadErrors
HostReadEmpty
HostReadUnderruns
319
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
320
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
321
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
322
323
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.
For firmware release 2.12.0 only one version of the FIPS-approved firmware is supplied. You should ensure you are using the latest firmware, unless you have a regulatory requirement to use firmware that has been FIPS validated. In the latter case, you should ensure that you are using the latest available FIPS validated firmware. See the release notes for details of current versions.
324
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.
This appendix assumes that you have installed the nCipher server as a service. This is the default installation procedure described in Chapter 3: Getting the module working. Where commands are described, it is assumed that you have installed the nCipher software in the default location, C:\nfast\. If you have chosen to install the nCipher software in another directory, replace references to this directory with the name of the directory in which you have chosen to install the software. This chapter describes how to upgrade module firmware for nShield/payShield modules only. If you have another module refer to the corresponding chapter in the appropriate Administrator Guide.
Key data
The firmware upgrade process destroys all persistent data held in a key management module.
325
If your security system requires that the persistent data held in a key-management module live beyond the upgrade or initialization of the key management module, a backup and recovery mechanism must be implemented. If you are using an SEE program that stores data in nonvolatile memory, or NVRAM key storage, use the nvram-backup utility to backup your data before upgrading and to restore the data after the upgrade is complete. See nvram-backup on page 266 for further information on this utility.
This three-step process is diagrammed in Maintenance mode and firmware installation on page 327. The methods needed to change a given module to the maintenance mode and to initialize it after firmware installation depend on the model of module. Follow the directions in this appendix that are appropriate to the specific model of module whose firmware you are upgrading.
326
PCI modules
Figure 6
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.
327
PCI modules
Figure 7
Status LED Clear switch Mode switch
M O I
DC power
3. 4.
Use the enquiry command-line utility to check that the module is in the pre-maintenance state. (See enquiry on page 229 for information on using this utility.)
Note
If the PCI module is still in the operational state, it means that the override switch is on. Refer to the installation instructions in the Hardware Installation Guide for information on accessing the override switch and switching it off. 5. 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.
328
8.
Reset the module by pressing the clear button until the LED flashes short pulses to indicate that the module is in preinitialization state. Alternatively, issue the nopclearfail command. 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.
329
330
On nCSS User and CipherTools CD-ROMs, you are also offered the psusr payShield User standard component bundle. The component bundles consist of various individual components. The hwsp Hardware Support (mandatory) bundle contains the nCipher server and kernel device drivers:
hwsp Hardware Support (mandatory) bundle
nfdrv Windows device drivers nfserv Hardserver process executables and scripts sdrv nFast Win 2000 driver signatures cfgall Hardserver config file support nflog Logging library support
The ctls Core Tools (recommended) bundle contains all the nCipher command-line utilities, including generatekey, low level utilities, and test programs:
ctls Core Tools (recommended) bundle
convrt Command line key conversions nftcl Command line key management (Tcl) nftcl Command line key generation and import nfuser Low level utilities and test programs nfuser Command line remote server management opensl nftcl certificate generation utility sworld Command line key management (C) tclsrc Tcl run time tclstf Small Tcl utilities nftcl Command line key generation and import tct2 Trusted Code Tool 2 command-line utility pysrc Python source for developers nfpy nFPython header files
331
nCipher recommends that you always install the ctls Core Tools bundle. Note The Core Tools bundle includes the tclsrc Tcl run times tools for creating the security world, KeySafe, and new-world. This does not affect any other installation of Tcl on your computer. The javasp Java Support (including KeySafe)s Java applications, including KeySafe:
javasp Java Support (including KeySafe) bundle
jutils Java utilities jutils JNI shared library for jutils.jar kmjava Java Key Management classes ksafe KeySafe 2 nfjava nFast Java generic stub classes nftcl Java Key Management Support
The psusr payShield User bundle contains the components required if you want to use payShield secure payments:
psusr payShield User bundle
emvspp payShield command-line tools emvsms SEE machine for EMV library emvspj payShield Java interface emvjni Dynamic shared library for payShield JNI
332
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
333
The jd Java Developer bundle contains components to support development of Java applications:
jd Java Developer bundle
jcecsp Java Key Management developer jutils Java utilities source and javadocs kmjava Java Key Management developer nfjava Java Generic Stub examples & javadoc
334
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
335
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
336
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.
337
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
338
An additional JCE provider nCipherRSAPrivateEncrypt is supplied that is required for RSA encryption with a private key. Install this provider above the standard nCipherKM provider and ensure that the file rsaprivenc.jar is in your CLASSPATH. nCipher has successfully tested SSLSocketClientWithClientAuth (JSSE sample code) with iPlanet 4.1 and 6.0 SP5 with this provider. For details about configuring these providers, see the Operator Guide.
For instructions on how to activate the agent after installation, see the Operator Guide appropriate to your module type.
339
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
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
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
342
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
343
6.
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.
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
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
344
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
345
NFLOG_CATEGORIES
This environment variable takes a colon-separated list of categories on which to filter log messages (categories may contain the wild-card characters * and ?). If you do not supply any values, then all categories of messages are logged. This table lists the available categories:
Category
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
346
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.
347
You can set a minimum level of hardserver logging by supplying one of the values for the NFLOG_SEVERITY environment variable in the hardserver configuration file, and you can likewise specify one or more values for the NFLOG_CATEGORIES environment variable. See Chapter 6: Configuring the hardserver for more detailed information about controlling hardserver logging. Note If none of the four environment variables are set, the default behavior is to log nothing, unless this is overridden by any individual library. If any of the four variables are set, all unset variables are given default values.
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.
348
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 "
349
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.
The environment variable PAYSHIELD_DEBUGFILE is used to set the name of the file that can be used by payShield to record log messages returned from the hostside payShield library.
PAYSHIELD_DEBUG
The environment variable PAYSHIELD_DEBUG is used to set the level and destination of log messages returned from the hostside payShield library.
350
The payShield library can be configured to return log information from various categories and to either of two different locations. The environment variable PAYSHIELD_DEBUG should be set to an integer which represents the kind of logging desired. The integer value used to set PAYSHIELD_DEBUG must be calculated by ORing the binary values assigned to each log information category.
Value
00000000 00000001 00000010 00000100 00001000 00010000 00100000 01000000 10000000
For example, to log payShield errors to the system log, and also log payShield warnings and errors to the payShield logfile specified by PAYSHIELD_DEBUGFILE, PAYSHIELD_DEBUGFILE must be set to 19. 19 is the integer value of the binary number 00010011, calculated by ORing 00010000, 00000001 and 00000010 together.
351
NONE = 0x00000000 (debugging off) MESS_NOTIFICATIONS = 0x00000001 (occasional messages including important errors) MESS_VERBOSE = 0x00000002 (all messages) MESS_RESOURCES = 0x00000004 (resource allocations) FUNC_TRACE = 0x00000008 (function calls) FUNC_VERBOSE = 0x00000010 (function calls + arguments) REPORT_CONTEXT = 0x00000020 (calling context e.g ThreadID and time) FUNC_TIMINGS = 0x00000040 (function timings) NFJAVA_DEBUGGING = 0x00000080 (Output NFJAVA debugging info)
2.
Add together the hexadecimal value associated with each type of debugging information. For example, to set NFJAVA_DEBUGGING and MESS_NOTIFICATIONS, add 0x00000080 and 0x00000001 to make 0x00000081.
352
3.
Convert the total to a decimal and specify this as the value for the variable. For example, to set NFJAVA_DEBUGGING and MESS_NOTIFICATIONS, include the line:
NFJAVA_DEBUG=129
For NFJAVA to produce output, NFJAVA_DEBUG must be set to at least NFJAVA_DEBUGGING + MESS_NOTIFICATIONS. Other typical values are: 255: All output 130: nfjava debugging and all messages (NFJAVA_DEBUGGING and MESS_VERBOSE) 20: function calls and arguments and resource allocations (FUNC_VERBOSE and MESS_RESOURCES)
If NFJAVA_DEBUGFILE is not set, the standard error stream System.err is used. Note Set these variables only when developing code or at the request of Support at nCipher. Debug output contains all commands and replies sent to the hardserver in their entirety, including all plain texts and the corresponding cipher texts as applicable.
353
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
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
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
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
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
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
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
360
This message is sent by a manager to retrieve the value of an object at the agent.
set
This message is sent by a manager to set the value of an object at the agent.
361
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.
362
Default settings
Default settings
By default, installing nCipher support software for Windows 2000 or Windows 2003 also installs the nCipher SNMP agent but does not activate it. The nCipher SNMP agent can be specifically excluded from an nCipher installation by deselecting the box associated with the SNMP agent in the installation component list. The default installation directory for the nCipher Management Information Base (MIB) and the SNMP configuration files (snmp.conf and snmpd.conf) is %NFAST_HOME%\etc\snmp\.
363
Further Information
where param list is a list of startup parameters: see Useful nCipher SNMP agent command-line switches on page 382 for more details. This installs the agent as a Windows Service and also starts the new service. To de-activate and uninstall the nCipher SNMP agent, enter the following command:
e:\ncipher\devel\ncsnmp\src\ntbuild\agent\snmpd.exe -unregister
Further Information
Protecting the nCipher SNMP installation
The nCipher SNMP Agent allows other computers on the network to connect to it and make requests for information. The nCipher agent is based on the NET-SNMP code base, which has been tested but not fully reviewed by nCipher. nCipher strongly recommends that the nCipher agent be deployed only on a private network or protected from the global Internet by an appropriate firewall. The default nCipher SNMP installation allows read-only access to the Management Information Base (MIB) with any community string. There is no default write access to any part of the MIB. Every effort has been taken to ensure the confidentiality of cryptographic keys even when the SNMP agent is enabled. In particular, the nCipher module is designed to prevent the theft of keys even if the security of the host system is compromised, provided that the Administrator Cards are used only with trusted hosts. Care must be used when changing the configuration of the nCipher SNMP agent. nCipher strongly advises that you set up suitable access controls in snmpd.conf, or a firewall, to protect the agent and the information it can return.
364
Further Information
Care has also been taken to ensure that malicious attackers are unable to flood your module with requests by flooding your SNMP agent. Command results from administration or statistics commands are cached, and therefore the maximum rate at which the agent sends commands to the module is throttled. See <Undefined CrossReference> for details on setting the cache time-outs.
365
Further Information
This directive specifies the maximum length of time for which statistics commands are cached. The default is 60 seconds.
admintimeout
This directive specifies the maximum length of time for which administrative commands are cached. The default is 5 seconds.
366
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.
Manager configuration
The manager application is the interface through which the user is able to perform network management functions. A manager communicates with agents using SNMP primitives (get, set, trap) and is unaware of how data is retrieved from, and sent to, managed devices. This form of encapsulation raises two main issues: the manager is hidden from all platform specific details the manager can communicate with agents running on any IPaddressable machine.
As a consequence, manager applications are generic and can be bought off the shelf. You may already be running SNMP managers, and if so, you can use them to query the nCipher agent. Note The manager is initially unaware of the MIB tree structure at a particular node. Managed objects can be retrieved or modified, but only if their location in the tree is known.
367
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).
MIB functionality
The nCipher MIB module separates module information into the following categories:
368
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
369
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
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
R R R R
listKeys can be preset using the keytable config directive in snmpd.conf (see <Undefined Cross-Reference>).
370
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
371
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
372
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
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
373
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
374
Remarks
Module number of the module containing the slot Slot number (1-based, unlike nCore which is 0-based)
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.
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.
375
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
376
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.
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
377
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.
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)
378
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.
R R R
379
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
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
R R R
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)
380
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)
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
381
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 registers the agent as a Windows service, and starts the service.
param list is a startup parameter list for service, the same as
382
Some options do not make sense when the agent is running as service.
-unregister
This option displays the configuration file directives that the agent understands.
-v
This option specifies the dumping of sent and received UDP SNMP packets.
-V
This option specifies the use of a file (PIDFILE) to store the process ID.
-q
This option specifies that information be printed in a more parsable format (quick print).
383
-D
This option specifies running on port NUM instead of the default: 161.
-c CONFFILE
This option specifies that the default configuration files not be read.
-L
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
384
This utility communicates with a network entity using GET NEXT request.
385
snmpbulkwalk
This utility communicates with a network entity using BULK request. These tools are general purpose SNMP utilities and can be configured for use with other SNMP agents. For more information on configuring and using these tools, refer to the NET-SNMP project Web site: http://net-snmp.sourceforge.net/.
386
nCipher addresses
nCipher Corporation Ltd.
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:
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.