+ All Categories
Home > Documents > nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... ·...

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

Date post: 27-Mar-2021
Category:
Upload: others
View: 7 times
Download: 1 times
Share this document with a friend
320
nShield/payShield Operator Guide Windows
Transcript
Page 1: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide

Windows

Page 2: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 2

Version: 5.5

Date: 03 November 2005

© Copyright 2005 nCipher Corporation Limited, Cambridge, United Kingdom.

Neither the whole nor any part of the information contained in this document may be adapted orreproduced in any material or electronic form without the prior written consent of the copyright holder.

nCipher™, nForce™, nShield™, payShield™, nCore™, nToken™, nFast Ultra™, nForce Ultra™,netHSM™, KeySafe™, CipherTools™, CodeSafe™, keyAuthority™, SEE™, and the SEE logo aretrademarks of nCipher Corporation Limited.

nFast® and the nCipher logo are registered trademarks of nCipher Corporation Limited.

All other trademarks are the property of the respective trademark holders.

Information in this document is subject to change without notice.

nCipher Corporation Limited makes no warranty of any kind with regard to this information, including,but not limited to, the implied warranties of merchantability and fitness for a particular purpose. nCipherCorporation Limited shall not be liable for errors contained herein or for incidental or consequentialdamages concerned with the furnishing, performance or use of this material.

Commercial Computer Software - proprietary

This computer software and documentation is Commercial Computer Software and Computer SoftwareDocumentation, as defined in sub-paragraphs (a)(1) and (a)(5) of DFAR § 252.227-7014, "Rights inNoncommercial Computer Software and Noncommercial Computer Software Documentation". Use,duplication or disclosure by the Government is subject to nCipher's standard US Terms And Conditionsfor the Product.

Patents

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

Page 3: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 3

Contents

Chapter 1: Introduction 7

General information 7

Audience 8

Contents of this guide 8

Conventions 9

Additional Documentation 12

Further information 12

Chapter 2: nCipher security worlds 14

Security 16

Application independence 20

Platform independence 21

Flexibility 21

Robustness 26

Scalability 30

KeySafe and security worlds 31

Applications and the security world 32

The nCipher PKCS #11 library and security worlds 33

Risks 33

Chapter 3: Using KeySafe 35

Starting KeySafe 36

Page 4: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 4

The KeySafe window 37

Errors 46

Chapter 4: Managing cards and softcards 49

Creating Operator Card Sets 50

Creating softcards 66

Erasing Operator Cards and softcards 71

Viewing cards and softcards 75

Changing card and softcard pass phrases 81

Lost cards 85

Chapter 5: Working with keys 86

Generating keys 86

Importing keys 93

Listing supported applications with generatekey 98

Retargeting keys with generatekey 98

Viewing keys 99

Discarding keys 103

Restoring keys 103

Chapter 6: nCipher application interfaces 104

Cryptographic Hardware Interface Library (CHIL) 104

nCipherKM JCA/JCE CSP 105

PKCS #11 115

Check Point VPN-1/Firewall-1 140

nCipher native and Custom applications 140

Microsoft Cryptographic API 141

Page 5: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 5

Chapter 7: nShield Operator Utilities 142

Help options 142

bulkerase 143

cardpp 144

ckcerttool 146

checkmod 148

cksigtest 149

createocs 153

cryptest 156

cspcheck 158

cspimport 159

cspmigrate 168

cspnvfix 174

csptest 175

csputils 179

des_kat 184

enquiry 185

floodtest 194

fwcheck 198

generatekey 200

hardserver 221

initunit 223

keytst 225

kmfile-dump 231

kptest 233

Page 6: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 6

mkaclx 238

modstate 242

ncdate 243

ncthread-test 245

ncversions 247

nfkminfo 249

nfkmverify 251

nopclearfail 257

nvram-backup 260

nvram-sw 266

pollbare 272

postrocs 273

ppmk 274

preload 277

pubkey-find 288

randchk 293

rfs-setup 294

rfs-sync 296

sigtest 299

slotinfo 304

stattree 306

Appendix A: Cryptographic algorithms 315

FIPS Information 317

Page 7: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 7

Chapter 1: Introduction

General information

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

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

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

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

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

This guide describes key-management tasks, which do not require an Administrator Card Set. It contains instructions for performing these tasks using KeySafe or the command line.

Page 8: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 8

1 Introduction Audience

The Administrator Guide describes how to install the required software and how to manage security worlds.

Audience

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

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

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

Contents of this guide

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

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

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

Chapter 4: Managing cards and softcards describes how to create Operator Card Sets.

Chapter 5: Working with keys describes how to generate and import keys, view existing keys, and dispose of keys that are no longer required.

Chapter 6: nCipher application interfaces describes how to configure your application to use a module.

Chapter 7: nShield Operator Utilities describes the command-line utility functions that are supplied by nCipher.

Page 9: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 9

1 Introduction Conventions

Appendix A: Cryptographic algorithms lists the cryptographic algorithms that are supported by nCipher modules.

Conventions

nCipher modules

The following terms are used to distinguish different module versions:

In this table, n is any integer.

Term Model number Used for

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

nCipher nToken module nC2022p-000 or nC2023p-000

an nCipher nToken module (PCI interface).

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

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

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

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

OEM PCI 1600 key-management module

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

Page 10: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 10

1 Introduction Conventions

Version numbers

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

nCipher software

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

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

Default directory

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

Page 11: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 11

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

EnterCtrl C

Page 12: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 12

1 Introduction Additional Documentation

Additional Documentation

This guide forms one part of the information and support provided by nCipher. The following documents are produced to support nCipher products, and the guides for your product can be found in the document directory of the CD-ROM for that product:

Further information

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

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.

Guide PDF file

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

Hardware_Installation.pdf

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

CodeSafe_C_Developer.pdf

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

Integration_Guide.pdf

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

nCore_Developer_Guide.pdf

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

nCore_Developer_Ref.pdf

payShield Developer Reference, for payShield developer reference material

payShield_Developer_Ref.pdf

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

Key-loading_Solution.pdf

Page 13: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 13

1 Introduction Further information

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

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

If you would like to receive security advisories from nCipher, please subscribe to the low volume nCipher security-announce mailing list. To do this, send a mail with the single word subscribe in the message body to [email protected].

If you cannot find the information you need or you are unable to solve a problem with your nCipher module, contact Support at nCipher by sending E-mail to [email protected].

Page 14: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 14

Chapter 2: nCipher security worlds

Key management is the hardest part of cryptography. Although designing secure cryptographic algorithms and protocols is not easy, there is a large body of academic research upon which to rely. Keeping the keys secret is much harder. nCipher has developed its security world technology to provide an infrastructure for secure life-cycle management of keys.

Key management involves the procedures and protocols, both manual and automated, that are used throughout the entire life cycle of cryptographic keys. These procedures and protocols include the generation, distribution, use, storage, destruction, and optional archiving and disaster recovery of cryptographic keys.

The security world concept and its infrastructure enable nCipher to offer several important features in a simple and intuitive, yet secure, way, where all keys can be made available to all modules in the security world.

These features include:

• security

• application independence

• platform independence

• flexibility

• robustness

• scalability.

The security world infrastructure lets you perform and control all these activities under your chosen security policy.

A security world consists of:

• one or more nCipher payShield, nForce, nShield, or netHSM modules

Page 15: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 15

2 nCipher security worlds nCipher security worlds

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

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

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

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

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

Page 16: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 16

2 nCipher security worlds Security

Figure 1 The security world

Security

Most importantly, a key-management system must store keys securely. Security must be designed into the system from the start; it cannot be added later.

The nCipher security world has been designed to ensure that keys remain secure throughout their life cycle. The security world uses multiple interlocking keys, and because of this, each key is always protected by another key, even during recovery operations.

Page 17: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 17

2 nCipher security worlds Security

Because the security world is built around nCipher key-management modules, keys are only ever available in plain text in secure hardware.

The security world uses smart cards for two different purposes:

• one set of cards forms an Administrator Card Set that is used to control access to recovery functions

• one or more sets of cards referred to as Operator Card Sets that are used to control access to application keys.

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

Each card set consists of a number of smart cards, N, of which a smaller number, K, is required to authorize an action. The required number is sometimes referred to as the threshold.

Note The value for K is intended to be less than N. Although it is possible for K to equal N, this is not recommended because an error on one card renders the whole card set unusable. If this happens with your Administrator Card Set, you are forced to replace your security world and generate new keys.

An Administrator Card Set is used to authorize several different actions, and each of these can have a different value for K. All the card sets are distinct; an individual smart card can only belong to the Administrator Card Set or to one Operator Card Set.

Each user can access the keys protected by the security world and the keys protected by their Operator Card Set. They cannot access keys that are protected by other Operator Card Sets.

The smart cards that are used as Operator Cards employ the security world key to perform a challenge-response protocol with the module. This means that Operator Cards can only be used by a module belonging to the same security world that they do.

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

Page 18: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 18

2 nCipher security worlds Security

Security worlds and Remote Operator

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

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

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

Security worlds shared with netHSM modules

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

Page 19: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 19

2 nCipher security worlds Security

FIPS 140-2 compliance

All nCipher security worlds are compliant with the Federal Information Processing Standards 140-2. The default setting for nCipher security worlds is FIPS 140-2 at level 2.

A security world that complies with the roles and services section of FIPS 140-2 level 2 does not require any authorization to create an Operator Card Set or an application key. All security worlds rely on the security features of your operating system to control which users can write data to the host.

FIPS 140-2 level 3 compliance

When you create a security world, you can choose whether you want the security world to comply with the roles and services section of FIPS 140-2 at level 2 or level 3. The FIPS 140-2 level 3 option is included for those customers who have a regulatory requirement for compliance with FIPS 140-2 at level 3.

A security world that complies with FIPS 140-2 level 3 requires authorization from any smart card that is part of the security world’s Administrator Card Set, or an Operator Card Set, before you can create or erase an Operator Card Set.

Note A security world only provides a complete level 3 compliant system when used with nShield and payShield modules, which have the additional physical security coating required by the FIPS 140-2 level 3.

If you choose to create a security world that complies with FIPS 140-2 level 3, the module initializes in strict FIPS mode. This option ensures that the module complies with the roles and services, key management, and self-test sections of FIPS 140-2 at level 3, as described in its validation certificate.

For more details of the nShield/Payshield FIPS 140-2 validation see http://csrc.nist.gov/cryptval/140-2.htm

Page 20: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 20

2 nCipher security worlds Application independence

Application independence

A security world can protect keys for any nCipher-aware software. Each key belongs to a specific application and is only ever used by that application. However, within a single security world, every key can belong to a different application. Keys are stored along with any additional data that is required by the application.

You do not need to specify which applications you will use. You can add a key for any supported application at any time.

The security world requires no knowledge of how the key will be used by an application. A security world controls the protection for the key; the application determines how it is used.

Although keys belong to a specific application, Operator Card Sets do not. If a user requires keys for different applications, they can all be protected under the same Operator Card Set.

Figure 2 illustrates this.

Figure 2 Operator Card Sets, keys, and applications

Page 21: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 21

2 nCipher security worlds Platform independence

• Card Set 1 protects keys for use with Application 1 and Application 2.

• Card Set 2 protects a single key for use with Application 2.

• Card Set 3 protects keys for use with Application 2 and Application 3.

• The security world protects a key for use with Application 3.

Platform independence

A security world is completely platform independent. All key information is stored in nCipher's proprietary format. This format can be read by any computer supported by nCipher, regardless of the native format used by that computer. This means that you can safely move a security world between platforms, even between platforms with differing native formats. For example, you can move a security world between Windows and UNIX platforms. You can also include hosts running different operating systems in the same security world.

Note When copying host data between computers using different Operating Systems or disk formats, use a mechanism that preserves the original data format and line endings (such as .tar file archives).

Flexibility

Within a security world, you can choose the relevant level of protection for each application key that you create.

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

Page 22: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 22

2 nCipher security worlds Flexibility

Using the security world key: module-protected keys

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

This level of protection is suitable for high-availability Web servers that you want to recover immediately if the computer resets.

Using Operator Card Sets: card-set protected keys

If you want to restrict key access to a particular user, you can create a set of smart cards known as an Operator Card Set. There is no limit to the number of Operator Card Sets that you can create within a security world.

An Operator Card Set belongs to a specific security world. It cannot be read, erased, or even formatted except in a module from its security world.

An Operator Card Set stores a number of symmetric keys that are used to protect the working keys. These keys are Triple DES keys.

Each card in an Operator Card Set stores only a fragment of the Operator Card Set keys. These keys can only be re-created if you have access to enough of their fragments. Because cards sometimes fail or are lost, the number of fragments required to re-create the key (K) should usually be less than the total number of fragments (N).

Page 23: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 23

2 nCipher security worlds Flexibility

Using card sets for extra security

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

Note Some applications restrict K to 1.

Using card sets to share keys

You can use card sets that enable the same keys to be used in a number of different modules at any one time, but you must leave one of the cards in each module.

If you want to use keys protected by the card set across multiple modules, you may want to make K equal to 1 and N equal to the number of modules. You can then insert a card into each module.

If you want to issue the same key to a set of users, again you would want to make K equal to 1 and N equal to the number of users, giving one card to each user.

If a card becomes damaged, the cardset can be recovered using the Administrator Card Set.

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

Using card sets for high availability

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

Page 24: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 24

2 nCipher security worlds Flexibility

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

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

Using pass phrases

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

You can change the pass phrase on a card at any time. For information on changing pass phrases, see Changing card and softcard pass phrases on page 81. This requires the card, the existing pass phrase, and a module that belongs to the security world.

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

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

Using persistent Operator Card Sets

If you create a standard Operator Card Set, the keys protected by a card can only be used while that card, or the last card loaded in the case of card sets, is in the nCipher module’s smart card reader. The keys protected by this card are removed from the memory of the module as soon as the card is removed from the smart card reader.

Although this feature provides added security, it means that only one user can load keys at any time because there is only one smart card reader on the module.

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

Page 25: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 25

2 nCipher security worlds Flexibility

Therefore, the security world architecture gives you the option of making an Operator Card Set persistent. This means that the keys protected by a card persist after the card has been removed. This enables you to use the same smart card in several modules simultaneously. It also means that several users can load keys onto the same module at the same time. The nCipher support software maintains strict separation between the keys loaded by each user, and each user only has access to the keys protected by their Operator Card Set.

Keys protected by a persistent card are automatically removed from the module:

• when the application that loaded the Operator Card Set closes the connection to the module.

• after a time limit that may be specified when the card set is created.

• when an application chooses to remove a key.

Note Some applications automatically remove a key after each use, reloading it only when required. Such applications do not benefit from persistent Operator Cards. The only way of sharing keys between modules for these applications is by having multiple smart cards in an Operator Card Set.

Although the module stores the key, the key is only available to the application that loaded it. If you want to use keys protected by this card in another application, you must re-insert the card, and enter its pass phrase if it has one. Certain applications are designed to allow only one user to be logged in at a time, in which case they remove any previously loaded persistent Operator Card Set used in that application before allowing the user to log into with a new Operator Card Set.

You can manually remove all keys protected by persistent cards by pressing the module’s Clear button or by turning off power to the module. Either process removes all keys protected by Operator Card Sets from the module, including the card in the reader. In such cases, all users of any applications using the module must log in again.

Page 26: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 26

2 nCipher security worlds Robustness

You are offered a choice as to whether or not to make an Operator Card Set persistent when you create the card set. Once you have made the decision, you cannot change it. Persistence is a property of the card set.

A security world can contain a mix of persistent and non-persistent card sets.

Using softcard-protected keys

If you want to use pass phrases to restrict key access but avoid using physical tokens (as required by smart-card protection), you can create a softcard-protected key. A softcard is a file containing a logical token that cannot be loaded without a pass phrase; its logical token must be loaded in order to authorize the loading of any key that is protected by the softcard. Softcard files are stored in the kmdata directory and have names of the form softcard_hash (where hash is the hash of the logical token share).

Softcard-protected keys offer greater security than module-protected keys and also have greater availability than keys protected by operator card sets (albeit without the greater security obtained through the requirement of physical tokens to authorize key-loading).

A softcard's pass phrase is set when you generate it, and you can use a single softcard to protect multiple keys. Softcards function as persistent 1-of-1 logical tokens, and after a softcard is loaded, it remains valid for loading its keys until its KeyID is destroyed.

Robustness

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

Page 27: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 27

2 nCipher security worlds Robustness

Backup and recovery

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

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

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

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

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

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

Replacing a module

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

Page 28: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 28

2 nCipher security worlds Robustness

Replacing the Administrator Card Set

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

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

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

Replacing an Operator Card Set or recovering keys to softcards

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

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

Note The ability to recover an Operator Card Set is an option that is enabled by default during security world creation. To disable recoverability, you must explicitly choose to do so during the security

Page 29: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 29

2 nCipher security worlds Robustness

world creation process. Once set during security world creation, the ability (or inability) to recover an Operator Card Set can never be altered.

Note Keys protected by an Operator Card Set can only be recovered to another Operator Card Set, and not to a softcard. Likewise, softcard-protected keys can only be recovered to another softcard, and not to an Operator Card Set.

You can use the rocs command-line utility or KeySafe to create new working copies of your keys protected by the key on a given card set. To recover keys protected by one softcard to another softcard, you must use the rocs command-line utility.

Replacing Operator Card Sets and softcards requires authorization. Otherwise, an attacker could simply duplicate a set or softcard without your knowledge. Therefore, the recovery keys are protected by the Administrator Card Set.

Storing any key recovery data introduces some extra risk, because an attacker with the Administrator Card Set and a copy of the recovery data could re-create your security world. You may have some keys that you consider to be especially sensitive. In this case, if you lose the Operator Card Set that protects the key, you may choose to issue a new key. Therefore, you can turn off the key recovery feature for the security world or for a specific key.

Recovery data can only be generated when you create the security world or key. If you choose not to create recovery data when you generate the security world or key, it cannot be added later. If you have not selected the recovery feature for the security world, it cannot be enabled for any key in the security world.

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

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

Page 30: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 30

2 nCipher security worlds Scalability

Scalability

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

To share a security world across multiple servers:

• ensure each server has at least one module fitted

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

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

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

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

Page 31: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 31

2 nCipher security worlds KeySafe and security worlds

Load sharing

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

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

KeySafe and security worlds

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

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

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

KeySafe enables you to:

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

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

• add a module to a security world

Page 32: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 32

2 nCipher security worlds Applications and the security world

• remove a module from a security world

• replace an Administrator Card Set

• create Operator Card Sets

• list the Operator Card Sets in the current security world

• change the pass phrase on an Operator Card

• remove a lost Operator Card Set from a security world

• replace Operator Card Sets

• erase an Operator Card

• add a new key to a security world

• import a key into a security world

• list the keys in the current security world

• delete a key from a security world.

KeySafe does not provide tools to back up and restore the host data or update module firmware, nor does KeySafe provide tools to synchronize host data between servers. These functions can be performed with your standard system utilities.

In addition to KeySafe, nCipher also supplies command-line utilities to manage the security world. Current versions of these tools can be used interchangeably with the current version of KeySafe.

Applications and the security world

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

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

Page 33: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 33

2 nCipher security worlds The nCipher PKCS #11 library and securityworlds

For information on the range of Application Guides available, either visit the nCipher web site (http://www.ncipher.com) or contact Support at nCipher ([email protected]).

The nCipher PKCS #11 library and security worlds

Many applications use a PKCS (Public Key Cryptography Standard) #11 library to generate and manage cryptographic keys. nCipher has produced a version of the PKCS #11 library that uses the security world to protect keys.

Enabling a PKCS #11 based application to use nCipher hardware key protection involves configuring the application to use the nCipher PKCS #11 library.

A PKCS #11 token created by the nCipher PKCS #11 library is a security world Operator Card Set.

The current PKCS #11 standard only supports tokens that are part of a 1-of-N card set.

A security world does not make any distinction between different applications that use the nCipher PKCS #11 library. Therefore, you can create a key in one PKCS #11 compliant application and make use of it in a different PKCS #11 compliant application.

Risks

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

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

Page 34: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 34

2 nCipher security worlds Risks

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

• Keep your smart cards safe.

• Always obtain smart cards from a trusted source: from nCipher or directly from Gemplus.

• Never insert a smart card used with nCipher key management into an untrusted smart card reader.

• Never insert any untrusted smart card into your module.

• Never tell anyone your pass phrase.

• Never write down your pass phrase.

• Never use a pass phrase that is easy to guess.

• Only use the Administrator Card Set in modules connected to trusted hosts.

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

Page 35: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 35

Chapter 3: Using KeySafe

This chapter introduces KeySafe, nCipher’s security world management tool. It describes:

• how to start KeySafe

• KeySafe’s graphical interface

• how to use buttons to select and run operations

• how to use the keyboard to navigate KeySafe

• how KeySafe reports errors.

Later chapters in this guide contain instructions for performing the following operations with KeySafe:

• replacing an Administrator Card Set

• listing the Operator Card Sets in the current security world

• changing the pass phrase on an Operator Card

• removing a lost Operator Card Set from a security world

• erasing an Operator Card

• adding a new key to a security world

• importing an existing key into a security world

• listing the keys in the current security world

• deleting a key from a security world.

Note By default, KeySafe uses the same mechanisms and supports the same features and applications as the generatekey command-line utility (see generatekey on page 200).

Page 36: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 36

3 Using KeySafe Starting KeySafe

Starting KeySafe

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

Note You can download Sun's Java Run-time Environment (and Java Developer Kit) from http://www.sun.com/. If your security policy does not allow the use of downloaded software, these components can be obtained on CD-ROM from Sun or your Operating System vendor.

The keysafe.jar file must be specified in the Java class path.

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

Note See the Administrator Guide for information on setting these parameters. (For information about setting environment variables, see the appropriate Administrator Guide for your module.)

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

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

Page 37: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 37

3 Using KeySafe The KeySafe window

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

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

The KeySafe window

The KeySafe window is divided into two areas:

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

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

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

• the main panel area (on the right).

This layout is consistent throughout the KeySafe application.

Page 38: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 38

3 Using KeySafe The KeySafe window

Sidebar

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

Menu buttons

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

• Introduction

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

• Keys

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

• Cards

Clicking the Cards menu button takes you to the Card Operations panel, from which you can:

- create, view, or erase Operator Cards

- change the pass phrase on an Operator or Administrator Card, or recover the pass phrase from an Operator Card

- replace an Operator or Administrator Card Set.

• Softcards

Clicking the Softcards menu button takes you to the Softcard Operations panel, from which you can:

- create, view or erase softcards

- change or recover the pass phrase on a softcard

Page 39: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 39

3 Using KeySafe The KeySafe window

• Modules

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

• Exit

Clicking the Exit button displays a dialog asking whether you are sure you want to exit KeySafe. Click Yes (or press ) to exit KeySafe; click No to continue using KeySafe. Clicking the Exit dialog’s close-window button will take you back to your KeySafe session. These features prevent you from closing KeySafe accidentally.

While KeySafe is executing a command, the menu buttons are disabled. Their normal functionality returns when the command is completed.

Module Status tree

The Module Status tree, in the lower part of KeySafe’s sidebar, displays information about the current security world and your modules in the form of a tree diagram.

At the top of the Module Status tree is an icon representing the computer on which the running copy of KeySafe is installed. The name of this computer is spelled out to the right of the icon.

Below the computer icon in the Module Status tree are icons and text identifiers representing the current security world and your module(s). To the left of each icon is an expand/collapse toggle. By default, when KeySafe starts, these toggles are on their collapsed

Enter

Page 40: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 40

3 Using KeySafe The KeySafe window

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

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

Security world information

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

• the security world is initialized

• key recovery is enabled for this security world (for more information on key recovery, see the Administrator Guide)

• pass phrase recovery is enabled for a security world (for more information on pass phrase recovery, see the Administrator Guide)

It also gives the following information:

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

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

The expanded security world information includes a folder labeled Advanced, which itself can be toggled into an expanded view. This folder displays advanced security world attributes related to nCipher’s Secure Execution Engine (SEE). When expanded, the Advanced folder displays Yes or No for each of the following:

• whether or not you have generated a real-time clock (RTC) authorization key for this security world

• whether or not you have generated a nonvolatile memory (NVRAM) authorization key for this security world

Page 41: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 41

3 Using KeySafe The KeySafe window

• whether or not you have generated a Secure Execution Engine (SEE) debugging key for this security world

• the level of SEE debugging that is enabled for this security world.

• whether or not you enabled the Foreign Token Open key for this security world

Module information

When you toggle the Module Status tree view of module information to its expanded setting for a given module, KeySafe displays:

• the module’s electronic serial number (ESN), which is a unique identifier. You must quote a module’s ESN if you need to contact Support at nCipher. Keep a record of the ESN(s) associated with your module(s).

• the module’s state, which will be one of the following:

- PreInitMode, indicating that the module is in the pre-initialization state

- InitMode, indicating that the module is in the initialization state

- Operational:Useable, indicating that the module is in the current security world and can be used for key operations

- Operational:Unknown, indicating that the module’s state could not be determined

- Operational:Uninitialized, indicating that the module key is set and that the module must be initialized before use

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

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

- Operational:AccelOnly, indicating that the module is an acceleration-only module

Page 42: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 42

3 Using KeySafe The KeySafe window

- Operational:Unchecked, indicating that, although the module appears to be in the current security world, KeySafe could not find a module initialization certificate (a module_ESN file) for this module

- Failed, indicating that the module has failed

- PreMaintMode, indicating that the module is in the pre-maintenance state

- MaintMode, indicating that the module is in the maintenance state.

• the status of the smart card reader slot(s).

You cannot initialize a security world from KeySafe unless you have at least one module in the pre-initialization state (PreInitMode). Likewise, if you want to add a module to an existing security world, that module must be in the pre-initialization state.

Note For information about putting a module into the pre-initialization state, see the Administrator Guide. After you have initialized a security world, in order for a module to be usable, you must put it into the operational state (see the appropriate Administrator Guide for your module).

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

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

• the version of the module’s firmware

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

• whether the module has nonvolatile memory (NVRAM).

Page 43: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 43

3 Using KeySafe The KeySafe window

Main panel area

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

Navigation buttons

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

Page 44: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 44

3 Using KeySafe The KeySafe window

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

Command buttons

At the bottom right of the Erase Module panel is a command button (the Erase Module! command button, in this case). Unlike clicking a navigation button, clicking a command button does commit you to an operation. Clicking a command button tells KeySafe to write or delete data: it is not necessarily possible to reverse such changes even if you subsequently cancel the operation.

For these reasons, command buttons are usually marked with an exclamation point (!) if there is a danger that a command could overwrite data that you may not want deleted. In some cases, clicking a command button causes KeySafe to display a dialog box asking you to confirm your command. Such features help prevent you from accidentally destroying your data or keys.

Page 45: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 45

3 Using KeySafe The KeySafe window

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

If you click a command button without having entered data into a mandatory text field or if KeySafe detects that the information you provided is inconsistent or invalid, KeySafe displays an error message. Click the message’s OK button, and then provide or correct the necessary information.

After you successfully issue a command by clicking a command button, the sidebar’s menu buttons are disabled until the requested command is completed.

Back buttons

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

Page 46: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 46

3 Using KeySafe Errors

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

Navigating with the keyboard

The key always takes you to the next field or button. If the cursor is not currently active in a text field, pressing the space bar or the

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

Errors

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

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

Note See the Administrator Guide for information on setting these parameters.

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

1. Exit KeySafe.

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

3. Restart KeySafe.

Tab

EnterShift Tab

Page 47: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 47

3 Using KeySafe Errors

Another Fatal Error from which KeySafe cannot recover is:

This error may mean that your nCipher server or nCipher firmware is not current. To update your firmware, take the following steps:

1. Exit KeySafe.

2. Update the nCipher firmware as described in the Administrator Guide.

3. Restart KeySafe.

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

Other, more trivial errors include:

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

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

Page 48: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 48

3 Using KeySafe Errors

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

Page 49: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 49

Chapter 4: Managing cards and softcards

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

The security world has three levels of protection for keys:

• keys protected directly by the security world, which can be used at any time without further authorization

• keys protected by a softcard, which can only be used by the operator who possesses the relevant pass phrases

• keys protected by an Operator Card Set, which can only be used by the operator who possesses the Operator Card Set and, if these have been set, any relevant pass phrases.

This chapter describes tasks with Operator Card Sets and softcards. These tasks do not normally require an Administrator Card Set to authorize them.

Note Some tasks described in this chapter, when performed within a security world that complies with the FIPS 140-2 level 3 standard, do require either an Administrator Card or an Operator Card from an existing set for authorization.

This chapter describes the following tasks:

• creating Operator Card Sets

• creating softcards

• erasing Operator Cards

• erasing softcards

• viewing Card Sets

• viewing softcards

• changing a pass phrase

For other card tasks, see the Administrator Guide.

Page 50: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 50

4 Managing cards and softcards Creating Operator Card Sets

Creating Operator Card Sets

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

Operator Card Sets belong to the security world in which they are created. When you create an Operator Card Set, the smart cards in that set can only be read by modules belonging to the same security world. The cards cannot be read, erased, or reformatted by a module from a different security world.

Note IIS can only use Operator Card Sets that require a single card for authorization and which do not have a pass phrase set.

Note iPlanet can only use Operator Card Sets that require a single card for authorization. This card must have a pass phrase set.

Note Netscape Certificate Server can only use Operator Card Sets that require a single card for authorization. This card must have a pass phrase set.

Persistent Operator Card Sets

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

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

Time-outs

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

Page 51: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 51

4 Managing cards and softcards Creating Operator Card Sets

Set has timed out, it is not loadable by another application unless it is removed and reinserted. Time-outs operate independently of Operator Card Set persistence.

FIPS 140-2 level 3-compliant security worlds

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

Creating an Operator Card Set with KeySafe

KeySafe enables you to create Operator Card Sets with:

• their own names

• K-of-N policies

• optional pass phrases for any card within a given set.

• formal FIPS 140-2 level 3 compliance.

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

1. Start KeySafe. (For an introduction to KeySafe and information on starting the software, see Chapter 3: Using KeySafe.)

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

Page 52: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 52

4 Managing cards and softcards Creating Operator Card Sets

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

4. Enter a name for the card set.

5. If you are creating the card set in a FIPS 140-2 level 3 security world, insert an Administrator Card or an existing Operator Card when prompted.

6. Choose whether you want pass phrase recovery to be enabled for the card set.

7. Choose whether you want the card set to be used remotely. For more information, see see the appropriate Administrator Guide for your module type.

8. Choose whether you want this Operator Card Set to be persistent.

9. Enter the total number of Operator Cards (N) that you want this Operator Card Set to have. This number must be less than or equal to 64.

Page 53: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 53

4 Managing cards and softcards Creating Operator Card Sets

10. Choose whether you want this Operator Card Set to have a time-out, after which the card set must be inserted again, and enter value for the time-out length in seconds.

11. Enter the number of Operator Cards needed to re-create a key (K). K must be less than or equal to N.

12. When you have entered all the details, click the Create OCS! command button. KeySafe takes you to a new Create Operator Card Set panel, which prompts you to insert a card to use as the first card in the set:

13. Insert a blank card into the appropriate smart card slot. If you insert a card from another Operator Card Set or another security world, KeySafe asks whether you want to erase it. If you insert an Administrator Card from the current security world, KeySafe prevents you from accidentally erasing it.

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

Page 54: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 54

4 Managing cards and softcards Creating Operator Card Sets

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

Page 55: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 55

4 Managing cards and softcards Creating Operator Card Sets

Select whether or not you want to set a pass phrase for the currently inserted card. Each card in a set can have an individual pass phrase, and you can also create a set in which some cards have pass phrases and others do not.

Note Because neither IIS nor OpenSSL/SSLeay have mechanisms for entering pass phrases, you must not give pass phrases to Operator Cards that are to be used with these applications.

If you want to set a pass phrase for the currently inserted card, enter the same pass phrase in both text fields. A pass phrase can contain any characters you can type except for tabs or carriage returns (because these keys are used to move between data fields).

You can change a pass phrase at any time. If you do not set a pass phrase now, you can use KeySafe’s Change Pass Phrase option (on the Examine/Change Card panel) to add one later. Likewise, if you later decide that you do not need a pass phrase on a card, you can use this option to remove it.

After entering your desired pass phrase (if any) in both text fields, click the OK button. Unless you have entered details for the last card in the set, KeySafe returns you to the Create Operator Card Set panel and prompts you to enter the next card in the set to be written.

15. After KeySafe has written the details of the last smart card in the set, it displays a dialog box indicating that the Operator Card Set has been successfully created. Click the OK button, and KeySafe returns you to the Create Operator Card Set panel, where you can create another Operator Card Set or choose a different operation by clicking one of the menu buttons.

Page 56: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 56

4 Managing cards and softcards Creating Operator Card Sets

Creating an Operator Card Set with the CSP wizard

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

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

1. Ensure that you have created the security world and that all the modules are in the operational state.

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

3. The wizard displays the window:

4. Click the Next button.

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

Page 57: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 57

4 Managing cards and softcards Creating Operator Card Sets

- If the wizard cannot find the security world, it displays the following window:

In such a case, you should:

• cancel the operation

• check that you have correctly set the environment variable NFAST_KMDATA

• copy the local sub-directory from the NFAST_KMDATA world or from a backup tape of this computer to the NFAST_KMDATA directory of this computer

• run the wizard again.

Page 58: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 58

4 Managing cards and softcards Creating Operator Card Sets

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

• In order to use the existing security world, ensure that the Use the existing security world option is selected, and click the Next button.

• If there are any modules in the pre-initialization state, the wizard adds them to the security world as described in the Administrator Guide.

Page 59: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 59

4 Managing cards and softcards Creating Operator Card Sets

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

6. Ensure that the Operator Card Set option is enabled, and then select the Create a new Operator Card Set option.

If you want the Operator Card Set to be persistent, select the Persistent option. Persistence is described in Persistent Operator Card Sets on page 50.

Page 60: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 60

4 Managing cards and softcards Creating Operator Card Sets

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

Note This shows that your security world is compliant with the roles and services of the FIPS 140-2 level 3 standard. It is included for those customers who have a regulatory requirement for compliance.

Under the constraints of level 3 of the FIPS 140-2 standard, Operator Cards cannot be created without authorization. To obtain authorization, insert any card from the Administrator Card Set or any Operator Card belonging to the current security world.

The wizard does not enable the Next world, the wizard warns you and prompts you for another card.

8. Click the Next button.

The wizard prompts you for a smart card to use as the first card in the Operator Card Set.

Page 61: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 61

4 Managing cards and softcards Creating Operator Card Sets

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

Do not use a card from the Administrator Card Set or an existing Operator Card.

If you insert a card that is not blank, the installer asks you if you want to erase it

10. When you have inserted an appropriate card, the wizard displays the following window:

If you want to protect this card with a pass phrase, turn on the Card will require a pass phrase option, and enter the pass phrase. You must enter the pass phrase in both fields to ensure that you have typed it correctly.

Note Operator Cards with pass phrases are required by the nCipher PKCS #11 library.

Page 62: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 62

4 Managing cards and softcards Creating Operator Card Sets

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

12. When you have created the Operator Card Set, the wizard displays the following window:

If you want to create another Operator Card Set, click the Back button.

When you have created all the Operator Card Sets that you require, click the Next button to install the CSP.

Creating the Operator Card Set from the command line

To create an Operator Card Set:

Page 63: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 63

4 Managing cards and softcards Creating Operator Card Sets

1. Use the command:

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

-N|--name=NAME [-M|--name-cards]

[[-p|--persist]|[-P|--no-persist]] [[-R|--no-pprecovery]|--pprecovery]

[-q|--remotely-readable] [-f|--force] [-T|--timeout=TIME]

In this command:

-m MODULE, --module=MODULE

These options specify the module number of the module to be used to create the token. If you only have one module, MODULE is 1.

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

In these options, K is the minimum required number of cards. If you do not specify the value K, the default is 1.

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

N is the total number of cards. If you do not specify the value N, the default is 1.

-N, --name=NAME

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

-M, --name-cards

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

Page 64: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 64

4 Managing cards and softcards Creating Operator Card Sets

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

-p, --persist

These options create a persistent card set.

-P, --no-persist

These options create a non-persistent card set.

-R, --no-pprecovery

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

-q, --remotely-readable

These options allow this card set to be read remotely. For information on configuring Remote Operator Card Sets, see the Administrator Guide.

-f, --force

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

-T, --timeout=TIME

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

Page 65: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 65

4 Managing cards and softcards Creating Operator Card Sets

Card never times out. Otherwise, the module automatically unloads the Operator Card Set TIME after the Operator Card was loaded.

If you have created a FIPS 140-2 level 3 compliant security world, you must provide authorization to create new Operator Cards; createocs prompts you to insert a card that contains this authorization. Insert any card from the Administrator Card Set or any Operator Card from the current security world.

When createocs has obtained the authorization from a valid card or if no authorization is required, it prompts you to insert a card into the module you specified.

2. Insert the smart card to use.

If you insert an Administrator Card from another security world or an Operator Card that you have just created, createocs displays the following message:

Module x slot n: unknown card

Module x slot n: Overwrite card ? (press Return)

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

Module x slot n: inappropriate Operator Card (TokenAuthFailed).

When you have inserted a valid card, createocs prompts you to type a pass phrase.

Note The nCipher PKCS #11 library requires Operator Cards with pass phrases.

Note Some applications do not have mechanisms for entering pass phrases. Do not give pass phrases to Operator Cards that are to be used with these applications.

Page 66: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 66

4 Managing cards and softcards Creating softcards

3. Type a pass phrase and press . Alternatively, press if you do not want this card to have a pass phrase.

A pass phrase can be up to 1024 characters long.

If you entered a pass phrase, createocs prompts you to confirm it.

4. Type the pass phrase again and press .

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

5. When the new card has been created, if you are creating a card set with more than one card in it, createocs prompts you to insert another card.

For each additional card in the Operator Card Set, follow the instructions from step 2 through step 4.

Creating softcards

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

A softcard is a file containing a logical token that cannot be loaded without a pass phrase; its logical token must be loaded in order to authorize the loading of any key that is protected by the softcard. Softcard files are stored in the kmdata directory and have names of the form softcard_hash (where hash is the hash of the logical token share). Softcards belong to the security world in which they are created.

Enter Enter

Enter

Page 67: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 67

4 Managing cards and softcards Creating softcards

A softcard’s pass phrase is set when you generate it, and you can use a single softcard to protect multiple keys. Softcards are persistent; after a softcard is loaded, it remains valid for loading the keys it protects until its KeyID is destroyed.

Note It is possible to generate multiple softcards with the same name or pass phrase. For this reason, the hash of each softcard is made unique (unrelated to the hash of its pass phrase).

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

As with Operator Card Sets, if debugging is enabled, a softcard’s pass phrase hash is available in the debug output (as a parameter to a ReadShare command).

You can create softcards from the command-line (see Creating softcards with ppmk on page 67) or with KeySafe (see Creating softcards with KeySafe on page 69).

Creating softcards with ppmk

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

Page 68: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 68

4 Managing cards and softcards Creating softcards

1. Decide whether you want the new softcard’s pass phrase to be recoverable or non-recoverable. To create a softcard with a recoverable pass phrase, give the command:

ppmk.exe --new --recoverable NAME

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

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

In these commands, NAME specifies the name of the new softcard to be created.

2. If you are working within a FIPS 140-2 level 3 compliant security world, you must provide authorization to create new softcards; ppmk prompts you to insert a card that contains this authorization. Insert any card from the Administrator Card Set or any Operator Card from the current security world. If you insert an Administrator Card from another security world, ppmk displays an error message and prompts you to insert a card with valid authorization. When ppmk has obtained the authorization from a valid card or if no authorization is required, it prompts you to type a pass phrase.

3. When prompted, type a pass phrase for the new softcard, and press . A pass phrase can contain any characters that you can type and can be up to 1024 characters long.

4. ppmk prompts you to confirm the pass phrase. Type the pass phrase again and press .

If the pass phrases do not match, ppmk prompts you to input and confirm the pass phrase again.

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

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

Enter

Enter

Page 69: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 69

4 Managing cards and softcards Creating softcards

Creating softcards with KeySafe

To create a softcard with KeySafe, follow these steps:

1. Start KeySafe. (For an introduction to KeySafe and information on starting the software, see Chapter 3: Using KeySafe.)

2. Click the Softcards menu button. KeySafe takes you to the Softcard Operations panel.

3. Click the Create New Softcard navigation button.

KeySafe takes you to the Create Softcard panel:

4. Choose parameters for the softcard:

a. Enter a name for the softcard.

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

Page 70: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 70

4 Managing cards and softcards Creating softcards

5. Click the Create Softcard! command button.

If you are creating the softcard in a FIPS 140-2 level 3 security world, insert an Administrator Card or an existing Operator Card when prompted.

KeySafe then takes you to Set Softcard Protection Pass Phrase pane:

6. Set a pass phrase for the softcard by entering the same pass phrase in both text fields.

A pass phrase can contain any characters you can type except for tabs or carriage returns (because these keys are used to move between data fields) and can be up to 1024 characters long. You can change a pass phrase at any time.

7. After entering your desired pass phrase in both text fields, click the OK button.

KeySafe displays a dialog box indicating that the softcard has been successfully created.

Page 71: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 71

4 Managing cards and softcards Erasing Operator Cards and softcards

8. Click the OK button.

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

Erasing Operator Cards and softcards

Erasing a card or softcard removes all the secret information from the card or softcard and deletes information about the card or softcard from the host. (For information about security world data and the remote file system, see the appropriate Administrator Guide for your module type.)

If you do not erase the smart cards that you have used as Operator Cards before you reinitialize your module, you must discard them because they cannot be used, erased, or reformatted without the old security world key.

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

Note None of these methods erases cards from the current Administrator Card Set.

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

FIPS 140-2 level 3-compliant security worlds

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

Page 72: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 72

4 Managing cards and softcards Erasing Operator Cards and softcards

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

Erasing card sets with KeySafe

To erase a card set using KeySafe use the following procedure:

1. Start KeySafe.

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

3. Click the Examine/Change Card navigation button. KeySafe takes you to the Examine/Change Card panel

4. Insert the Operator Card that you want to erase into the reader.

5. Click the Erase Card! button. You do not need to supply the pass phrase (if there is one) to erase an Operator Card.

6. KeySafe asks you to confirm that you want to erase this card. If you are sure that you want to erase it, click the Yes button.

Note Erasing a card does not erase the keys protected by that card. The keys are still listed on the keys panel but are unusable.

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

7. After erasing an card, KeySafe displays a dialog box to confirm that the card has been erased. Click OK to continue using KeySafe.

Page 73: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 73

4 Managing cards and softcards Erasing Operator Cards and softcards

Erasing card sets on the command line

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

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

This command uses the following options:

-m|--module=MODULE

These options specify the module number of the module. If you only have one module, MODULE is 1.

-e, --erase

These options indicate that you want to erase the card.

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

If you have created a FIPS 140-2 level 3 compliant security world, you must provide authorization in order to erase or create Operator Cards.

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

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

Cntrl X

Page 74: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 74

4 Managing cards and softcards Erasing Operator Cards and softcards

Erasing softcards

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

Erasing softcards with Keysafe

1. Stary Keysafe.

2. Click the Softcards menu button. KeySafe takes you to the Softcard Operations panel.

3. Click the List Softcards navigation button. KeySafe takes you to the List Softcards panel.

4. Select the softcard you want to erase from the list.

5. Click the Remove Softcard! button.

6. KeySafe asks you to confirm that you want to erase this card. Click Yes to confirm.

7. After erasing a softcard, KeySafe displays a dialog box to confirm that the card has been erased. Click OK to continue using Keysafe.

Erasing softcards with ppmk

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

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

In this command, you can identify the softcard to be erased either by its name (NAME) or by its logical token hash as listed by nfkminfo (IDENT).

Page 75: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 75

4 Managing cards and softcards Viewing cards and softcards

If you are working within a FIPS 140-2 level 3 compliant security world, you must provide authorization to erase softcards; ppmk prompts you to insert a card that contains this authorization. Insert any card from the Administrator Card Set or any Operator Card from the current security world. If you insert an Administrator Card from another security world or an Operator Card that you have just created, ppmk displays an error message and prompts you to insert a card with valid authorization. When ppmk has obtained the authorization from a valid card or if no authorization is required, it completes the process of erasing the softcard.

Viewing cards and softcards

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

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

To list all softcards in a security world or to show details of an individual softcard, you can use the ppmk or nfkminfo command-line utilities. To check which pass phrase is associated with a softcard, you can use the ppmk command-line utility.

Viewing card sets with KeySafe

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

Examining a Card

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

Page 76: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 76

4 Managing cards and softcards Viewing cards and softcards

1. Start KeySafe. (For an introduction to KeySafe and information on starting the software, see Chapter 3: Using KeySafe.)

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

3. Click the Examine/Change Card navigation button. KeySafe takes you to the Examine/Change Card panel.

4. Insert a card into the appropriate smart card slot. KeySafe displays information about the smart card currently in the slot. If there is no smart card in the slot, KeySafe displays a message Card slot empty - please insert the card that you want to examine.

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

• change a card’s pass phrase (if it has one)

• give a pass phrase to a card that does not already have one

• remove a pass phrase from a card that currently has one.

List an Operator Card Set

In order to view information about whole Operator Card Sets with KeySafe, follow these steps:

1. Start KeySafe. (For an introduction to KeySafe and information on starting the software, see Chapter 3: Using KeySafe.)

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

3. Click the List OCS navigation button. KeySafe takes you to the List Operator Card Sets panel, which displays information about all Operator Card Sets in the current security world.

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

Page 77: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 77

4 Managing cards and softcards Viewing cards and softcards

Viewing card sets from the command line

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

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

nfkminfo --cardset-list

In this command, --cardset-list specifies that you want to list the operator card sets in the current security world.

nfkminfo displays output information similar to the following:

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

Operator logical token hash k/n timeout name

hash 1/1 none-N name

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

nfkminfo TOKENHASH

In this command, TOKENHASH is the Operator logical token hash of the card (as listed when the command nfkminfo --cardset-list is run).

Page 78: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 78

4 Managing cards and softcards Viewing cards and softcards

This command displays output information similar to the following:

name "name"

k-out-of-n 1/1

flags NotPersistent

timeout none

card names ""

hkltu 794ada39038fa8c4e9ea46a24136bbb2b8b337f2

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

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

Viewing softcards

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

Viewing softcards with Keysafe

To view a softcard with Keysafe, follow these steps:

1. Start Keysafe.

2. Click the Softcards menu button. Keysafe takes you to the Softcard Operations panel.

3. Click the List Softcards navigation button. Keysafe takes you to the List Softcards panel, which displays information about all softcards in the current security world.

From the List Softcards panel, you can also choose to remove a softcard from the security world. See Erasing Operator Cards and softcards on page 71 for more information about this procedure.

Page 79: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 79

4 Managing cards and softcards Viewing cards and softcards

Viewing softcards with nfkminfo

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

nfkminfo --softcard-list

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

To show information for a specific softcard using the nfkminfo command-line utility, give the command:

nfkminfo --softcard-list IDENT

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

SoftCard

name "mysoftcard"

hkltu 7fb95888ea2850d4e3ffcc8f0c22100937344308

Keys protected by softcard 7fb95888ea2850d4e3ffcc8f0c22100937344308:

AppName simple Ident mykey

AppName simple Ident myotherkey

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

Viewing softcards with ppmk

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

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

Page 80: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 80

4 Managing cards and softcards Viewing cards and softcards

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

In order to view the details of a particular softcard using the ppmk command-line utility, give the command:

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

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

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

Verifying a card’s or softcard’s pass phrase

Verifying a card’s pass phrase with cardpp

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

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

This command uses the following options:

--check

This option tells cardpp to check the pass phrase.

--module=MODULE

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

Page 81: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 81

4 Managing cards and softcards Changing card and softcard pass phrases

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

Verifying a softcard’s pass phrase with ppmk

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

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

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

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

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

Changing card and softcard pass phrases

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

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

Page 82: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 82

4 Managing cards and softcards Changing card and softcard pass phrases

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

Changing pass phrases with KeySafe

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

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

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

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

Changing a card pass phrase with KeySafe

To change a pass phrase for an Operator Card using KeySafe:

1. Start KeySafe.

2. Click Cards. the Examine/Change panel is displayed.

3. Click Change Pass Phrase. The Set Card Protection Pass Phrase panel is displayed.

4. Enter the old pass phrase, and click the OK button.

Page 83: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 83

4 Managing cards and softcards Changing card and softcard pass phrases

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

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

7. Click OK.

Changing a softcard pass phrase with KeySafe

TO change a pass phrase for a softcard using KeySafe:

1. Start KeySafe.

2. Click the Softcards menu button. KeySafe takes you to the Softcard Operations panel.

3. Click the Change Passphrase navigation button. KeySafe takes you to the Change/Recover Softcard Passphrase panel.

4. Select the softcard whose pass phrase you want to change, and click the Change Passphrase button. KeySafe takes you to the Get Softcard Protection Pass Phrase panel.

5. Enter the old pass phrase and click OK. KeySafe either displays an error dialog (if the pass phrase is not correct) or takes you to the Set Softcard Protection Pass Phrase panel.

6. Enter your new pass phrase, and enter it again in the second box to confirm the pass phrase is correct.

7. Click OK.

8. After changing a pass phrase, KeySafe displays a dialog box to confirm that the pass phrase has been successfully changes. Click OK to continue using KeySafe.

Changing a card’s pass phrase with cardpp

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

Page 84: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 84

4 Managing cards and softcards Changing card and softcard pass phrases

1. Run the cardpp utility using the command:

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

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

2. If prompted, insert the card whose pass phrase you want to change. (If there is a card already in the slot, you are not prompted.)

3. If prompted, enter the existing pass phrase for the card (If the card has no current pass phrase you are not prompted.) If you enter the pass phrase correctly, cardpp prompts you to enter the new pass phrase.

4. Enter a new pass phrase, and then enter it again to confirm it.

After you have confirmed the new pass phrase, cardpp changes the card’s pass phrase.

Changing softcard pass phrases with ppmk

To change a softcard’s pass phrase when you know the pass phrase, follow these steps:

1. Give the following command:

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

In this command, you can identify the softcard whose pass phrase you want to change either by its name (NAME) or by its logical token hash as listed by nfkminfo (IDENT).

ppmk.exe prompts you to enter the old pass phrase.

2. Type the old pass phrase, and press . If you enter the old pass phrase correctly, ppmk.exe prompts you to enter the new pass phrase.

Enter

Page 85: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 85

4 Managing cards and softcards Lost cards

3. Type the old pass phrase, and press . Type the new pass phrase again, and press to confirm it.

After you have confirmed the new pass phrase, ppmk.exe then changes the softcard’s pass phrase.

Lost cards

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

nCipher recommends that after you have replaced an Operator Card Set, you then erase the remaining cards in the old card set (see Erasing Operator Cards and softcards on page 71) and remove the old card set from the security world (see the Administrator Guide).

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

EnterEnter

Page 86: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 86

Chapter 5: Working with keys

This chapter describes how to use the facilities provided by nCipher to work with keys. There is often more than one way of performing a particular task. The methods available for working with keys are:

• KeySafe

• generatekey and related utilities

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

Where commands are described in this chapter, it is assumed that you have installed the nCipher software in the default location, C:\nfast\. If you chose to install the nCipher software in another directory, replace references to C:\nfast\ with the name of the directory in which you installed the software.

Generating keys

Generating a key creates both a key and a certificate request for the following application types:

• embed (OpenSSL)

• ssleay

• iis34

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

Whenever possible, generate a new key instead of importing an existing key. Because existing keys have been stored in a known format on your hard disk, there is a risk that the existing key has been compromised. Key material can also persist on backup media.

Note Some applications can generate keys directly.

Page 87: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 87

5 Working with keys Generating keys

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

Generating keys on the command line

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

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

You can use generatekey in two ways:

• in interactive mode, by issuing commands without parameters and supplying the required information when prompted by the utility

• in batch mode, by supplying some or all of the required parameters on the command line (generatekey prompts interactively for any missing but required parameters).

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

Batch mode is useful for scripting. In batch mode, if any required parameters are omitted, generatekey does not prompt for the missing information but instead will either use available defaults or fail. If you specify one or more parameters incorrectly, an error is displayed and the command fails.

Page 88: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 88

5 Working with keys Generating keys

To generate a key, use the command:

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

This command use the following options:

--generate

This option specifies key generation.

OPTIONS

You can specify particular options when running generatekey that control details of key generation. See generatekey on page 200 for details of available options.

APPNAME

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

NAME=VALUE

This specifies a list of parameters for the application. See generatekey on page 200 for details of available parameters.

In interactive mode, generatekey prompts you for any required parameters or actions that have not been included in the command. When you give the command:

1. Enter parameters for the command, as requested. If you enter a parameter incorrectly, the request for that information is repeated and you can re-enter the parameter.

2. For jcecsp keys, you must input the key store password. In interactive mode, this is not echoed to the screen. When all the parameters have been collected, generatekey displays the final settings. In a FIPS 140-2 level 3 compliant security world, you are prompted to insert a card for FIPS authorization if no such card is present.

Page 89: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 89

5 Working with keys Generating keys

3. If prompted, insert an Administrator Card or an Operator Card from the current security world.

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

Example of key generation with generatekey

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

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

size=1024 plainname=keya ident=abc

The generatekey utility prompts you to insert a quorum of Operator Cards from the operatorone Operator Card Set. After you have inserted the appropriate number of cards, generatekey generates the key.

Although it is not explicitly specified, the created key is recoverable by default if recovery is enabled for the security world.

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

Generating keys with KeySafe

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

1. Start KeySafe. (For an introduction to KeySafe and for information on starting the software, see Chapter 3: Using KeySafe.)

2. Click the Keys menu button. KeySafe takes you to the Key Operations panel.

Page 90: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 90

5 Working with keys Generating keys

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

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

Page 91: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 91

5 Working with keys Generating keys

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

The types of information that you need to provide on the Key

Generation Parameters panel differs slightly depending on the application you selected on the Generate Key panel. Below, as an example, is the Key Generation Parameters panel associated with nCipher native applications:

6. When you have supplied your desired key generation parameters, click the Next button.

Note In order to generate a key protected by a FIPS 140-2 level 3 compliant security world, you need authorization from an Operator Card or Administrator Card from the current security world. Follow the onscreen instructions.

7. If you choose to generate a key that is protected by a smart card or softcard, KeySafe takes you to a panel from which you can load the protecting card or softcard. Follow the onscreen instructions, inserting any necessary Operator Cards and supplying any pass phrases as needed.

Page 92: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 92

5 Working with keys Generating keys

8. KeySafe displays a message indicating that the key has been successfully generated. Click the OK button.

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

Generating NVRAM-stored keys

NVRAM key storage provides a mechanism for generating keys stored in a module’s nonvolatile memory and hence within the physical boundary of an nCipher module. You can store only a few keys in this way: the number depends on the memory capacity of the module, the size of the key and whether the key has recovery data associated with it.

nCipher recommends that you do not store keys in NVRAM unless you must do so to satisfy regulatory requirements. nCipher introduced NVRAM key storage only for users who must store keys within the physical boundary of a module to comply with regulatory requirements. NVRAM-stored keys provide no additional security benefits and their use exposes your Administrator Card Set to increased risk. Storing keys in nonvolatile memory also reduces load balancing and recovery capabilities. Because of these factors, nCipher recommends you always use standard security world keys unless explicitly required to use NVRAM-stored keys.

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

• ensure that you have installed version 2.6.8 or greater of the nCipher server software. You can use the enquiry command-line utility to identify the installed version number.

• ensure that your module has module firmware version 2.12.0 or later installed. See the Administrator Guide for information on upgrading your module firmware.

• create a new security world.

Page 93: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 93

5 Working with keys Importing keys

When you generate an NVRAM-stored key, you must have sufficient nonvolatile memory available in the module or the command fails.

You need backup and recovery procedures to protect your NVRAM-stored keys.

Note An NVRAM-stored key can only be loaded successfully by using the with-nfast command-line utility on the generating module. Attempts to load such a key on other modules that have NVRAM fail with UnknownID errors.

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

Importing keys

Importing a key takes an unprotected key stored on the host and stores it in the security world in encrypted form.

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

The following key types can be imported by the tools nCipher provides:

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

• DES and 3DES keys (entered in hex).

Page 94: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 94

5 Working with keys Importing keys

Importing a key, like generating a key, creates both a key and a certificate request for the following application types:

• embed (OpenSSL)

• ssleay

• iis34

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

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

Importing keys from the command line

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

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

This command uses the following options:

--import

This option specifies key importation.

OPTIONS

You can specify particular options when running generatekey that control details of key importation. See generatekey on page 200 for details of available options.

APPNAME

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

Page 95: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 95

5 Working with keys Importing keys

NAME=VALUE

This specifies a list of parameters for the application. See generatekey on page 200 for details of available parameters.

For RSA keys, you can include pemreadfile=filename on the command line to specify the file name of the PEM file that contains the key. Otherwise, you are prompted for this information during import.

In interactive mode, you are prompted for any required parameters or actions that have not been included in the command:

• Enter parameters, as requested. If you enter a parameter incorrectly, the request for that information is repeated and you can re-enter the parameter.

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

• If prompted, insert an Administrator Card or an Operator Card from the current security world.

Example of key importation with generatekey

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

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

ident=abc protect=module

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

Although not explicitly specified, this key is, by default, recoverable if recovery is enabled for the security world.

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

Page 96: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 96

5 Working with keys Importing keys

Importing keys with KeySafe

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

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

1. Start KeySafe. (For an introduction to KeySafe and for information on starting the software, see Chapter 3: Using KeySafe.)

2. Click the Keys menu button. KeySafe takes you to the Key Operations panel.

3. Click the Import Key navigation button. KeySafe takes you to the Import Key panel:

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

Page 97: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 97

5 Working with keys Importing keys

5. Select and enter the desired parameters for the key that you want to import.

The types of information that you need to provide on the Key

Import Parameters panel will differ slightly depending on the application you selected on the Import Key panel. Below, as an example, is the Key Import Parameters panel associated with nCipher native applications:

6. When you have supplied parameters for the key that you want to import, click the Next button.

7. If you choose to import a key that is protected by a smart card, KeySafe takes you to the Load Operator Card Set panel. Follow the onscreen instructions, inserting the required number of Operator Cards and supplying any pass phrases as needed.

8. KeySafe displays a message indicating that the key has been successfully imported. Click the OK button.

9. KeySafe returns you to the Import Key panel, from which you can import another key or choose another operation.

Page 98: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 98

5 Working with keys Listing supported applications with generatekey

Listing supported applications with generatekey

To list supported applications, use the command:

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

Retargeting keys with generatekey

The --retarget option to takes an existing key in the security world and makes it available for use by another application as if it had been expressly generated for use by that application. Because no key material is exposed during retargeting, this operation is as secure as generating a new key.

Note When you retarget a key, generatekey does not remove the original key from the security world. If required, you can use KeySafe to discard the original key.

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

To retarget a key, use the command:

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

[from-ident=keyident]

In this command:

--retarget

specifies key importation.

OPTIONS

specifies any options to include when the command is run. See Options on page 201 for details of available options.

Page 99: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 99

5 Working with keys Viewing keys

APPNAME

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

from-application=appname

specifies the name of the application with which the key is currently associated.

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

from-ident=keyident

specifies the identifier of the key to be retargeted. You can find this identifier by using the nfkminfo command-line utility.

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

Viewing keys

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

Viewing keys with KeySafe

In order to view a list of keys with KeySafe, follow these steps:

1. Start KeySafe. (For an introduction to KeySafe and for information on starting the software, see Chapter 3: Using KeySafe.)

2. Click the Keys menu button. KeySafe takes you to the Key Operations panel.

Enter

Page 100: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 100

5 Working with keys Viewing keys

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

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

If you click a key’s listing, KeySafe displays additional information about that key, for example, the application with which the key is used, whether or not the key is recoverable, and the key’s name, creation date, hash, instance, and copy ID.

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

Page 101: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 101

5 Working with keys Viewing keys

Viewing keys on the command line

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

nfkminfo -k [APPNAME[IDENT]]

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

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

With either option, APPNAME is an optional application name. If you specify an application name, nfkminfo lists only the keys for that application. In general, APPNAME is one of:

• custom

• embed

• hwcrhk

• iis34

• nses35

• simple

• ssleay .

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

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

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

Key summary - 4 keys:

AppName appname Ident ident AppName appname Ident ident

AppName appname Ident ident AppName appname Ident ident

Page 102: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 102

5 Working with keys Viewing keys

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

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

nfkminfo then displays information in a format similar to this:

Key AppName appname Ident ident BlobKA length 752

BlobPubKA length 316

BlobRecoveryKA length 868

name "name"

hash hash recovery Enabled

protection CardSet

other flags PublicKey +0x0

cardset hash_ktBlobKA

format 6 Token

other flags 0x0

hkm hash_km hkt hash_kt hkr none

BlobRecoveryKA

format 8 Indirect

other flags 0x0

hkm none

hkt none

hkr hash_krBlobPubKA

format 5 Module

other flags 0x0

hkm hash_km hkt none

hkr none

No extra entries

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

Page 103: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 103

5 Working with keys Discarding keys

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

Key summary - 30 keys

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

key_appname_ident 'name '

key_appname_ident 'name '

key_appname_ident 'name '

key_appname_ident 'name '

key_appname_ident 'name '

key_appname_ident 'name '

key_appname_ident 'name '

Discarding keys

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

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

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

Restoring keys

nCipher does not supply tools for restoring a key that has been discarded. However if you have kept a backup of the host data for the security world, you can restore a key from the backup data.

Note If you have NVRAM-stored keys, you must additionally ensure you have a backup of the key data stored on the relevant modules.

Page 104: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 104

Chapter 6: nCipher application interfaces

This chapter describes how to use an nCipher module with the following types of application:

• Cryptographic Hardware Interface Library (CHIL) applications

• nCipherKM JCA/JCE CSP

• PKCS #11 applications

• nCipher native applications

• Custom external applications.

You can use KeySafe or the generatekey command-line utility to generate or import keys for use with your applications (see Chapter 5: Working with keys). By default, KeySafe uses the same mechanisms and supports the same applications as the generatekey command-line utility.

Note By default, any user is allowed to use any application that uses a module.

Where commands are described in this chapter, it is assumed that you have installed the nCipher software in the default location, C:\nfast\. If you chose to install the nCipher software in another directory, replace references to C:\nfast\ with the name of the directory in which you installed the software.

Cryptographic Hardware Interface Library (CHIL)

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

Page 105: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 105

6 nCipher application interfaces nCipherKM JCA/JCE CSP

If your application offers RSA/DSA keys in hardware support through the Cryptographic Hardware Interface Library, use the hwcrhk key type.

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

Using keys

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

Refer to the documentation for your application.

Generating keys

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

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

nCipherKM JCA/JCE CSP

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

Use of the nCipherKM JCA/JCE cryptographic service provider classes requires the presence of:

• the nCipher Java Key Management classes

• the nFast Java Generic stub classes.

Page 106: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 106

6 nCipher application interfaces nCipherKM JCA/JCE CSP

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

The nCipherKM JCA/JCE cryptographic service provider can be used with FIPS 140-2 level 3 compliant security worlds.

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

The nCipherKM JCA/JCE cryptographic service provider supports load sharing for keys that are stored in the nCipherKM keystore. The load sharing feature provides support for multiple modules that are connected to a single server, spreading the load of cryptographic operations between the modules in order to provide scalability in terms of performance.

Note nCipher recommends that you use load sharing unless you have existing code that is designed to run with multiple modules.

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

An additional JCE provider nCipherRSAPrivateEncrypt is supplied that is required for RSA encryption with a private key. Install this provider above the standard nCipherKM provider as follows:

security.provider.1=com.ncipher.fixup.provider.nCipherRSAPrivateEncrypt

security.provider.2=com.ncipher.provider.km.nCipherKM

Ensure that the file rsaprivenc.jar is in your CLASSPATH. nCipher has successfully tested SSLSocketClientWithClientAuth (JSSE sample code) with iPlanet 4.1 and 6.0 SP5 with this provider.

Page 107: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 107

6 nCipher application interfaces nCipherKM JCA/JCE CSP

Adding the nCipher Java classes to your class path

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

Add the required classes to your class path as follows:

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

t\java\classes\kmcsp.jar;.

In this class path, jceclasspath is the path to your JCE framework .jar file.

Note There is a dot, “.”, at the end of the first line of example code.

Note nCipher recommends that you use the Sun JCE framework which can be downloaded from http://java.sun.com/products/jce/.

Setting the nCipherKM engine classes as the preferred provider

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

JDK_HOME\jre\lib\security\java.security

This ensures that the nCipherKM engine classes are used in preference to any other providers that may be installed on your system. Edit the file java.security in such a way as to make the

Page 108: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 108

6 nCipher application interfaces nCipherKM JCA/JCE CSP

nCipherKM JCA/JCE cryptographic service provider your security.provider.1 by changing, for example, lines in the file java.security that resemble:

#

# List of providers and their preference orders (see above):

#

security.provider.1=sun.security.provider.Sun

to lines that resemble:

#

# List of providers and their preference orders (see above):

#

security.provider.1=com.ncipher.provider.km.nCipherKM

security.provider.2=sun.security.provider.Sun

Choosing functions

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

KeyPairGenerator

• RSA

- OID.1.2.840.113549.1.1.1

- 1.2.840.113549.1.1.1

• DSA

- OID.1.2.840.10040.4.1

- 1.2.840.10040.4.1

- 1.3.14.3.2.12

• DH

- Diffie-Hellman

Page 109: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 109

6 nCipher application interfaces nCipherKM JCA/JCE CSP

- DiffieHellman

KeyGenerator

• DESede

- TripleDES

- Triple-DES

- DES3

• Rijndael

- AES

• CAST

- CAST128

- CAST256

• Blowfish

• Serpent

• Twofish

• ArcFour

• HmacSHA1

• HmacSHA256

• HmacSHA384

• HmacSHA512

• HmacTiger

• HmacRIPEMD160

• HmacMD5

Signature

• MD5withRSA

- MD5/RSA

Page 110: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 110

6 nCipher application interfaces nCipherKM JCA/JCE CSP

- OID.1.2.840.113549.1.1.4

- 1.2.840.113549.1.1.4

- 1.3.14.3.2.25

• SHA1withRSA

• SHA1withDSA

- DSA

- DSS

- SHA/DSA

- SHA-1/DSA

- SHA1/DSA

- SHAwithDSA

- DSAWithSHA1

- OID.1.2.840.10040.4.3

- 1.2.840.10040.4.3

- 1.3.14.3.2.13

- 1.3.14.3.2.27

Cipher

• RSA

- Mode: ECB

- Padding: PKCS1Padding (PKCS1, PKCS#1)

• OID.1.2.840.113549.1.1.1

• DESede

- Mode: ECB, CBC

- NoPadding, PKCS5Padding (PKCS5, PKCS#5)

• TripleDES

• Triple-DES

Page 111: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 111

6 nCipher application interfaces nCipherKM JCA/JCE CSP

• DES3

• Rijndael

- Mode: ECB, CBC

- NoPadding, PKCS5Padding (PKCS5, PKCS#5)

• AES

• CAST

- Mode: ECB, CBC

- NoPadding, PKCS5Padding (PKCS5, PKCS#5)

• CAST128

• CAST256

• Blowfish

- Mode: ECB, CBC

- NoPadding, PKCS5Padding (PKCS5, PKCS#5)

• Serpent

- Mode: ECB, CBC

- NoPadding, PKCS5Padding (PKCS5, PKCS#5)

• Twofish

- Mode: ECB, CBC

- NoPadding, PKCS5Padding (PKCS5, PKCS#5)

• ArcFour

- Mode: None

- Padding: None

KeyStore

• nCipher.sworld

- jks

Page 112: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 112

6 nCipher application interfaces nCipherKM JCA/JCE CSP

SecureRandom

• RND

- SHA1PRNG

KeyAgreement

• DH

- Diffie-Hellman

- DiffieHellman

KeyFactory

• DH

- Diffie-Hellman

- DiffieHellman

• RSA

- OID.1.2.840.113549.1.1.1

- 1.2.840.113549.1.1.1

• DSA

- OID.1.2.840.10040.4.1

- 1.2.840.10040.4.1, 1.3.14.3.2.12

Mac

• HmacSHA1

• HmacMD5

• HmacTiger

• HmacRIPEMD160

• HmacSHA256

• HmacSHA384

Page 113: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 113

6 nCipher application interfaces nCipherKM JCA/JCE CSP

• HmacSHA512

Java system properties

The nCipherKM JCA/JCE cryptographic service provider uses the following Java system properties:

• JCECSP_DEBUG

• JCECSP_DEBUGFILE

• protect

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

JCECSP_DEBUG

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

java -DJCECSP_DEBUG=debuglevel myApp.

In this command, debuglevel is the numeral associated with the desired level of debugging.

By default, the debuglevel of JCECSP_DEBUG is set to 0. You should not have to reset JCECSP_DEBUG unless so directed by Support at nCipher.

JCECSP_DEBUGFILE

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

java -DJCECSP_DEBUGFILE=debugfile myApp.

Page 114: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 114

6 nCipher application interfaces nCipherKM JCA/JCE CSP

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

It is not necessary to set JCECSP_DEBUGFILE unless you have set JCECSP_DEBUG to a value other than its default of 0.

protect

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

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

If the Java system property seeintegname is set, the generated key is an SEE application key. The key will only be usable by an SEE application signed with the seeinteg key specified by seeintegname.

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

Checking the installation of the nCipherKM JCA/JCE CSP

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

cd C:\nfast\java\classes

java -classpath "%CLASSPATH%;." KmcspTest

Page 115: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 115

6 nCipher application interfaces PKCS #11

KmcspTest displays a message, similar to the following, showing the providers that are installed on your system:

1 - nCipherKM version version2 - SUN version 1.2

This message indicates that the nCipherKM provider is installed as the default provider.

PKCS #11

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

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

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

The PKCS #11 library supplied by nCipher has security options which you must configure before you use the PKCS #11 library. For full details, see PKCS #11 library with Security Assurance Mechanism on page 118.

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

Note nCipher recommends that you use load sharing unless you have existing code that is designed to run with multiple modules.

Page 116: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 116

6 nCipher application interfaces PKCS #11

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

Note If you are using the preload utility in conjunction with the nCipher PKCS #11 library, you can create K-of-N Operator Card Sets (see preload on page 277).

Choosing functions

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

The following paragraphs describe the functions that an nCipher module can provide.

Generating random numbers and keys

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

Digital signatures

The nCipher PKCS #11 library can use the nCipher module to sign and verify messages using the following algorithms:

• DSA

• RSA

• DES3_MAC

• AES

• CAST128_MAC.

Page 117: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 117

6 nCipher application interfaces PKCS #11

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

Asymmetric encryption

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

The nCipher module is specifically optimized for asymmetric algorithms, so you should always choose to perform asymmetric operations with the nCipher module.

Symmetric encryption

The nCipher PKCS #11 library can use the nCipher module to perform symmetric encryption with the following algorithms:

• DES

• Triple DES

• CAST128

• AES.

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

Page 118: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 118

6 nCipher application interfaces PKCS #11

Message digest

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

PKCS #11 library with Security Assurance Mechanism

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

The PKCS #11 library with the Security Assurance Mechanism (SAM), libcknfast, can help users to identify potential weaknesses, and help developers create secure PKCS #11 applications more easily.

The SAM in the PKCS #11 library is intended to detect operations that reveal questionable behavior by the application. If these occur, the application fails with an explanation of the cause of failure.

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

Note To ensure the security of your keys, you must review any messages returned by the PKCS #11 library before changing the settings of the CKNFAST_OVERRIDE_SECURITY_ASSURANCES environment variable.

Page 119: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 119

6 nCipher application interfaces PKCS #11

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

If no parameters, or the none parameter, are supplied to the CKNFAST_OVERRIDE_SECURITY_ASSURANCES #11 library fails to perform the operation in question, and issues a warning, when the following operations are detected:

• creating short term session keys as long term objects

• creating keys that can be exported as plain text

• importing keys from external sources

• creating or importing wrapping keys

• creating or importing unwrapping keys

• creating keys with weak algorithms (such as DES)

• creating keys with short key lengths.

See CKNFAST_OVERRIDE_SECURITY_ASSURANCES on page 126 for more information about parameters and diagnostic warnings.

Key security

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

An explicitly insecure PKCS #11 key is one where CKA_SENSITIVE is set to false. If an application uses a key that is insecure but CKA_SENSITIVE is not set to false, it is possible that the application is using an inadequate concept of key security, and that the library

Page 120: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 120

6 nCipher application interfaces PKCS #11

disallows use of that key by default. Use of insecure keys should, by default, be restricted to short term session keys, and applications should explicitly recognize the insecurity.

Using the nCipher PKCS #11 library

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

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

nCipher PKCS #11 library with load sharing

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

An additional virtual slot may be returned (with the label of accelerator ), depending on the value given to the variable CKNFAST_NO_ACCELERATOR_SLOTS (described in CKNFAST_NO_ACCELERATOR_SLOTS on page 125). Accelerator slots can:

• be used to support session objects

• be used to create module protected keys

• not be used to create private objects.

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

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

Page 121: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 121

6 nCipher application interfaces PKCS #11

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

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

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

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

nCipher PKCS #11 library without load sharing

There will be two entries for each module, unless you have set CKNFAST_NO_ACCELERATOR_SLOTS .

Note The entry called accelerator cannot be used to create private objects. It can be used to create module-protected keys.

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

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

Page 122: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 122

6 nCipher application interfaces PKCS #11

nCipher PKCS #11 library with the preload utility

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

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

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

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

A logical token pre-loaded by preload for use with nCipher’s PKCS #11 library is the only such token available to the application for the complete invocation of the library. You can use more than one module with the same card set.

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

Page 123: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 123

6 nCipher application interfaces PKCS #11

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

nCipher PKCS #11 library environment variables

The nCipher PKCS #11 library uses the following environment variables:

• CKNFAST_TOKENS_PERSISTENT

• CKNFAST_LOADSHARING

• CKNFAST_CARDSET_HASH

• CKNFAST_NO_ACCELERATOR_SLOTS

• CKNFAST_NO_SYMMETRIC

• CKNFAST_FAKE_ACCELERATOR_LOGIN

• CKNFAST_DEBUGDIR

• CKNFAST_ASSUME_SINGLE_PROCESS

• CKNFAST_OVERRIDE_SECURITY_ASSURANCES

• CKNFAST_USE_THREAD_UPCALLS

• CKNFAST_NVRAM_KEY_STORAGE

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

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

Each line of this file must be of the form:

variable=value

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

Page 124: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 124

6 nCipher application interfaces PKCS #11

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

CKNFAST_TOKENS_PERSISTENT

This variable controls whether Operator Cards that are created by your PKCS #11 application are persistent (see Persistent Operator Card Sets on page 50 for a description of persistence). If this variable is set when your application calls the PKCS #11 function that creates tokens, the Operator Card created is persistent.

Note Use of the nCipher PKCS #11 library to create tokens is deprecated, because it can only create 1-of-1 tokens in FIPS 140-2 level 2 security worlds. Use KeySafe or one of the command-line utilities to create Operator Card Sets.

CKNFAST_LOADSHARING

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

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

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

Page 125: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 125

6 nCipher application interfaces PKCS #11

CKNFAST_CARDSET_HASH

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

CKNFAST_NO_ACCELERATOR_SLOTS

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

Do not set this environment variable if you want to use the accelerator slot to create or load module protected keys.

Note Setting this environment variable has no effect on ckcheckinst because ckcheckinst needs to list accelerator slots.

CKNFAST_NO_SYMMETRIC

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

CKNFAST_NO_UNWRAP

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

Page 126: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 126

6 nCipher application interfaces PKCS #11

CKNFAST_FAKE_ACCELERATOR_LOGIN

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

Note The variable CKNFAST_FAKE_ACCELERATOR_LOGIN is only available for iPlanet Enterprise Edition 6.

CKNFAST_DEBUGDIR

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

CKNFAST_ASSUME_SINGLE_PROCESS

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

CKNFAST_ASSURANCES_LOG

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

CKNFAST_OVERRIDE_SECURITY_ASSURANCES

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

Page 127: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 127

6 nCipher application interfaces PKCS #11

• all

• none

• tokenkeys

• longterm [=days]

• explicitness

• import

• unwrap_mech

• unwrap_kek

• weak_algorithm

• shortkey_algorithm=bitlength

• silent

Each parameter specified is separated by a semicolon. On the command line, enter the following to set the variable:

CKNFAST_OVERRIDE_SECURITY_ASSURANCES="token1;token2=value3"

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

CKNFAST_OVERRIDE_SECURITY_ASSURANCES=token1;token2=value3

Unknown parameters generate a warning; see Diagnostic warnings about questionable operations on page 133.

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

Page 128: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 128

6 nCipher application interfaces PKCS #11

all

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

none

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

tokenkeys

This parameter permits applications to request that insecure keys are stored long-term by the cryptographic hardware and library.

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

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

Page 129: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 129

6 nCipher application interfaces PKCS #11

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

longterm[=days]

This parameter permits an insecure key to be used days days after it was created. Usually insecure keys may not be used more than 48 hours after their creation. If days is not specified, there is no time limit.

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

When longterm is set, the PKCS #11 API permits the use of the following functions with an insecure key up to the specified number of days after its creation:

• C_Sign and C_SignUpdate

• C_Verify and C_VerifyUpdate

• C_Encrypt and C_EncryptUpdate

• C_Decrypt and C_DecryptUpdate

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

When the longterm[=days] parameter is set, C_SignInit, C_VerifyInit, C_EncryptInit , C_DecryptInit, and a new read-only CKA_VENDOR_DEFINED attribute, CKA_CREATION_DATE are added to the key.

Page 130: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 130

6 nCipher application interfaces PKCS #11

explicitness

This parameter permits applications to create insecure keys without explicitly recognizing that they are insecure, by setting the flag that allows export as plain text. An insecure key is one whose plain text is available to an attacker on the host, so it makes no sense to restrict legitimate users’ access to the plain text of the key value.

Note Needing to set this variable usually indicates that the application designers were not familiar with the security properties of the PKCS #11 interface. It is not necessarily always a problem in itself, but it does indicate that a review of the application’s security policies and use of the PKCS #11 API should be carried out.

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

When explicitness is supplied as a parameter for the CKNFAST_OVERRIDE_SECURITY_ASSURANCES environment variable, attempts to create, generate, or unwrap insecure keys with CKA_SENSITIVE=true , or to set CKA_SENSITIVE=true on an existing key, are allowed.

import

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

Page 131: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 131

6 nCipher application interfaces PKCS #11

If you are migrating from software storage to hardware protection of keys you must enable this option once at the time of migration. You should then disable it.

Note Needing to set this variable at other times indicates either that the application designers thought that the key would be secure or that the library thinks the key is supposed to be secure even though it is not continuously kept in a secure environment.

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

unwrap_mech

This parameter treats keys transferred into the module in an insecurely encrypted form as if the encryption was secure. Strictly speaking, this parameter allows key-decryption-keys to be used for insecure decryption mechanisms as well as raw decryption.

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

Setting the unwrap_mech parameter is necessary at the time the wrapping key is created or imported.

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

Page 132: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 132

6 nCipher application interfaces PKCS #11

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

unwrap_kek

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

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

weak_algorithm

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

Page 133: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 133

6 nCipher application interfaces PKCS #11

shortkey_algorithm=bitlength

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

silent

This parameter turns off the warning output. Checking is still performed, and the check still returns failures correctly according to the other variables that are set.

Diagnostic warnings about questionable operations

When the CKNFAST_OVERRIDE_SECURITY_ASSURANCES environment variable is set to a value other than all, diagnostic messages are always generated for questionable operations. Each message contains the following elements:

• the PKCS #11 label of the key, if available

• the PKCS #11 identifier of the key, if available

• the hash of the key

• a summary of the problem. This may be a questionable operation that has been permitted because of a setting in CKNFAST_OVERRIDE_SECURITY_ASSURANCES or an operation that has failed. In this case, the setting required to authorize the operation is noted.

By default, these messages are sent to stderr. On Windows platforms, they are also always sent to the Event Viewer.

If a file is also specified in the CKNFAST_ASSURANCE_LOG environment variable, these messages are written to this file.

Page 134: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 134

6 nCipher application interfaces PKCS #11

If CKNFAST_DEBUG is 1 or greater and a file is specified in CKNFAST_DEBUGFILE #11 library Security Assurance Mechanism log information is sent to the specified file. These variables must be set whenever generatekey or KeySafe are used.

Note If a file is specified in CKNFAST_ASSURANCES_LOG and no file is specified in CKNFAST_DEBUGFILE (or if CKNFAST_DEBUG is 0), diagnostic messages are send to stderr as well as to the file specified in CKNFAST_ASSURANCES_LOG.

CKNFAST_USE_THREAD_UPCALLS

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

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

If neither mutex callbacks nor CKF_OS_LOCKING_OK is passed, this variable is ignored. Only a single connection is used because the application must be single threaded in this case.

CKNFAST_NVRAM_KEY_STORAGE

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

Page 135: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 135

6 nCipher application interfaces PKCS #11

Checking the installation of the nCipher PKCS #11 library

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

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

Page 136: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 136

6 nCipher application interfaces PKCS #11

1. Give the command ckcheckinst.

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

ckcheckinst: C_Initialize failed rv = 00000006

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

If your security world is valid, ckcheckinst displays information similar to the following:

PKCS#11 library interface version 2.01

flags 0

manufacturerID "nCipher Corp. Ltd "

libraryDescription "nFast PKCS#11 1.#.# "

implementation version 1.##

Strictfips 140 enabled

Load sharing and Failover enabled

slot Status Label

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

1 Operator card "card2 "

2 Operator card "card3 "

Select slot Number to run library test or 'R'etry or to 'E'xit:

In this output:

PKCS#11 library interface version 2.01

refers to the version of the PKCS #11 specification supported

implementation version 1.##

refers to the version of the nCipher PKCS #11 library

Loadsharing and Failover enabled

is shown if load sharing has been enabled.

Slots that contain a valid Operator Card are indicated by the status Operator card and the card’s label. In a FIPS 140-2 level 2 compliant security world, the available fixed tokens are also

Page 137: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 137

6 nCipher application interfaces PKCS #11

listed for selection.

If you insert a blank card or an unrecognized card (for example, an Operator Card from a different security world or an Administrator Card), this is indicated in the Status column. The corresponding slot number is not available.

Note If you are using the preload utility in conjunction with the nCipher PKCS #11 library, you can only see the token that you loaded with the preload utility. In load-sharing mode, the loaded card set is used to set the environment variable CKNFAST_CARDSET_HASH, so only this card set is visible as a slot.

If you have no available slots, ckcheckinst displays No token

present beside the relevant slot numbers.

ckcheckinst gives you the following choices:

No removable tokens present.

Please insert an operator card into at least one available slot and

enter 'R' retry.

If you have not created a an operator card, enter a fixed token slot

number (if available)

Or 'E' to exit this program and create a card set before continuing.

2. If there are no available slots with cards in them, you can do one of the following:

- insert a valid Operator Card, and press

- choose a fixed token slot

- press to quit, then create an Operator Card Set, and run ckcheckinst again.

When there is at least one slot with a valid token, input a slot number, and press . In a FIPS 140-2 level 3 compliant security world, ckcheckinst prompts you to enter the pass phrase for the selected Operator Card.

R

E

Enter

Page 138: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 138

6 nCipher application interfaces PKCS #11

3. Type the pass phrase, and press .

ckcheckinst displays the results of the tests:

Test Pass/Failed

---- -----------

1 Generate RSA key pair Pass

2 Generate DSA key pair Pass

3 Encryption/Decryption Pass

4 Signing/Verify Pass

Deleted test keys ok

PKCS11 Library test successful.

If any tests fail, ckcheckinst displays a message indicating the failure and quits. It does not run any subsequent tests.

If ckcheckinst fails:

• check that the nCipher server is running

• use the enquiry and nfkminfo world.

If all seems in order, reinstall the nCipher library.

How the nCipher PKCS #11 library protects keys

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

Enter

Smart card Slot Accelerator Slot

Private Token Object Operator Card Set not supported

Public Token Object security world security world

Public key well known module key well known module key

Page 139: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 139

6 nCipher application interfaces PKCS #11

Operator Card Set

The object is stored as an nCipher key blob encrypted by the Operator Card Set key. You must log in to this Operator Card Set before you can load this object.

security world

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

well-known module key

Public keys are encrypted under a well-known module key. This encryption is for programming convenience only and does not provide security. These keys can be loaded on any nCipher module.

API restrictions in FIPS mode

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

CKA_EXTRACTABLE must be false for all keys. CKA_Private must be true for all private keys and all secret keys.

Vendor specific error codes

nCipher defines the following vendor specific error codes:

CKR_FIPS_FUNCTION_NOT_SUPPORTED

This error code indicates that the function is not supported in FIPS 140-2 level 3 mode, although it is supported in the FIPS 140-2 level 2 mode.

Page 140: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 140

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

CKR_FIPS_TOKEN_NOT_PRESENT

This error code indicates that an Operator Card is required even though the card slot is not in use.

CKR_FIPS_MECHANISM_INVALID

This error code indicates that the current mechanism is not allowed in FIPS 140-2 level 3 mode.

Check Point VPN-1/Firewall-1

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

Before you use the Check Point configuration tool, you must have:

• installed nCipher hardware

• installed nCipher software

• set up an nCipher security world with an Operator Card Set

• installed the Check Point VPN-1/Firewall-1 software

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

nCipher native and Custom applications

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

Page 141: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 141

6 nCipher application interfaces Microsoft Cryptographic API

Use the Custom external application option for applications that were written using nCipher key management and that expect their keys to be in stand-alone files.

Note KeySafe does not place any restrictions on the Operator Card Set that is used to protect nCipher native or Custom application keys. You must make sure that your application is capable of loading the card set.

Microsoft Cryptographic API

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

Page 142: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 142

Chapter 7: nShield Operator Utilities

This chapter contains reference information about the utilities referred to in this manual. See the Administrator Guide for a full list of all the utilities supplied with the nCipher software.

Help options

If a utility has the standard help options, these are not included in the synopsis or in the description. The standard help options are as follows:

• -h, --help displays help for the utility

• -v, --version displays the version number of the utility

• -u, --usage displays a brief usage summary for the utility

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

Page 143: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 143

7 nShield Operator Utilities bulkerase

bulkerase

The bulkerase utility is used to erase large numbers of cards in the same session. You must be careful because the utility can erase any FEM activation cards. The bulkerase utility can only erase Operator Cards from a security world of which the module is a member.

bulkerase is a very powerful tool. You must be absolutely certain that the cards you intend to erase, particularly FEM enabling cards, are definitely no longer needed.

Usage

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

--module= MODULE

This option specifies that the module MODULE is to be used for erasing cards. Multiple modules can be specified. The default is to use all modules.

--verbose

This option specifies that verbose output is required.

Page 144: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 144

7 nShield Operator Utilities cardpp

cardpp

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

Usage

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

The cardpp command-line utility polls all available slots. If there is no card inserted, it prompts you to insert one.

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

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

Options

-e, --examine

These options tell cardpp to examine inserted cards.

-c, --change

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

-k, --check

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

-r, --recover

These options tell cardpp to recover the pass phrase from an Operator Card.

Page 145: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 145

7 nShield Operator Utilities cardpp

-m, --module=MODULE

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

Page 146: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 146

7 nShield Operator Utilities ckcerttool

ckcerttool

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

When ckcerttool imports a certificate, it correctly fills in the following CKC_X_509 certificate object attributes:

• CKA_SUBJECT

• CKA_ISSUER

• CKA_SERIAL_NUMBER

• CKA_LABEL.

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

CKA_LABEL and CKA_SUBJECT are applied to the corresponding private key specified on the command line.

Usage

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

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

-certname=NAME]

To import a module-protected certificate (without a pass phrase or card-set name), give a command of the form:

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

certname=NAME]

Page 147: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 147

7 nShield Operator Utilities ckcerttool

-c, --cardset=CARDNAME

These options specify the name (CARDNAME) of the card set or softcard that protects the certificate.

-f, --certfile FILENAME

These options specify the name (FILENAME) of the .pem format file containing the certificate.

-k, --keyident KMDATAKEYID

These options specify the NFKM key ident (KMDATAKEYID) of the corresponding key.

-n, --nopin

These options specify that the object is to be a public object (C_Login is not called).

-L, --certname NAME

These options specify a name (NAME) for the certificate that is stored as CKA_LABEL. If you do not specify CKA_LABEL, the default label is ncipher-cert.

Help options

-h, --help

These options display help for ckcerttool.

-V, --version

These options display the version number of ckcerttool.

-u, --usage

These options display a brief usage summary for ckcerttool.

Page 148: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 148

7 nShield Operator Utilities checkmod

checkmod

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

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

Usage

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

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

Several example test data files are provided in the C:\nfast\testdata directory. The name of each file starts with testdata.

Output

checkmod counts the number of successful commands, for example:

C:\nfast\bin\checkmod C:\nfast\testdata\testdata-s1024-n100

File C:\nfast\testdata\testdata-s1024-n100:

100 completed OK

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

Page 149: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 149

7 nShield Operator Utilities cksigtest

cksigtest

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

The default is 1024-bit RSA signature generation with a buffered output stream to stdout using 30 threads running for 60 seconds.

Usage

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

sig-type=TYPE] [-l|--key-size=BITS] [-m|--mech=MECH] [-c|--cardsets=NAME] [-j|--

threads=COUNT] [-B|--unbuffered-stdout] [-t|--stop-after=TIME] [-p|--pin-for-

testing=PIN] [-n|--nopin]

Options

Help options

-h, --help

These options display help for cksigtest

-V, --version

These options display the version number of cksigtest

-u, --usage

These options display a brief usage summary for cksigtest

Page 150: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 150

7 nShield Operator Utilities cksigtest

Program options

-s, --sign

This option tests the sign operation. This action is performed by default.

-v, --verify

This option tests the verify operation.

-d, --decrypt

This option tests the decrypt operation.

-e, --encrypt

This option tests the encrypt operation.

Key options

-S, --sig-type=TYPE

This option specifies the signature type to use. TYPE is one of RSA, DSA, EC (if available), and KCDSA (if available). The default is RSA.

Note The EC signature type is only available if you have enabled the Elliptic Curve feature. See the Administrator Guide for information about feature enabling.

-l, --key-size=BITS

This option specifies the length of the key in bits. The default is 1024. This parameter is not required for a DSA key, which is always 1024 bits long.

Note The module may run out of memory if you run cksigtest with sizes greater than 2048, especially if the module has any other keys or tokens loaded.

Page 151: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 151

7 nShield Operator Utilities cksigtest

-M, --mech=MECH

This option specifies the mechanism to use. MECH is one of DSA, DSA_SHA1, SHA1_RSA_PKCS, RSA_X_509, RSA_PKCS, EC_SHA1 (if available), and KCDSA_HAS160 (if available). The default is RSA_PKCS.

Note The EC_SHA1 mechanism is only available if you have enabled the Elliptic Curve feature. See the Administrator Guide for information about feature enabling.

Other options

-c, --cardset=NAME

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

-j, --threads=COUNT

This option specifies specifies the maximum number of threads. The default is 30.

-B, --unbuffered-stdout

This option turns off buffering for stdout.

-t, --stop-after=TIME

This option specifies the maximum time in seconds to run the command. The command quits after the first results announcement after TIME seconds The minimum is 1 second. The default is 60 seconds.

Page 152: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 152

7 nShield Operator Utilities cksigtest

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

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

-n, --nopin

This option specifies not to call C_Login. The object created will be a public object.

Output

cksigtest produces output similar to this:

Using slot[0] (label "accelerator ")

Using slot[1] (label "fred ")

Generating 1024-bit RSA key

testing signing

starting timing, timelimit 60s

total 2604, 260/s

total 5244, 264/s

total 7869, 262/s

total 10499, 263/s

total 13091, 259/s

timing done

15720 operations in 60 seconds, average 262 operations per second

OK

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

The first numeric column shows the total number of operations achieved so far.

The second numeric column shows the average number of operations achieved each second over the course of the previous minute.

Page 153: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 153

7 nShield Operator Utilities createocs

createocs

The createocs creates an Operator Card Set.

Usage

createocs -m|--module=MODULE -Q|--ocs-quorum=K/N-N|--name=NAME [-M|--name-cards]

[[-p|--persist]|[-P|--no-persist]] [[-R|--no-pprecovery]|--pprecovery]

[-q|--remotely-readable] [-f|--force] [-T|--timeout=TIME]

If you have created a FIPS 140-2 level 3 compliant security world, you must provide authorization to create new Operator Cards. createocs prompts you to insert a card that contains this authorization.

createocs prompts you to insert and remove cards as required.

Options

-m, --module=MODULE

These options specify the module number of the module to be used to create the token. If you only have one module, MODULE is 1.

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

In these options, N is the total number of cards and K is the minimum required number of cards. You can either specify K/N together or specify nothing, in which case the default of 1/1 is used.

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

Page 154: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 154

7 nShield Operator Utilities createocs

-N, --name=NAME

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

-M, --name-cards

These options enable you to name individual cards within the card set. You can only use this option after the card set has been named by using the --name=NAME option. createocs prompts for the names of the cards as they are created. Not all applications can display individual card names.

-p, --persist

These options create a persistent card set.

-P, --no-persist

These options create a non-persistent card set.

-R, --no-pprecovery

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

-q, --remotely-readable

These options allow this card set to be read remotely. For information on configuring Remote Operator Card Sets, see the Administrator Guide.

-f, --force

These options allow createocs to overwrite smart cards without prompting. If you do not specify the --force option, createocs prompts you if any smart card to use is not blank. You can only employ --force to reuse Operator Cards from the current security world, or cards containing unknown

Page 155: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 155

7 nShield Operator Utilities createocs

data. You cannot use the --force option either to force the reuse of Administrator Cards from the current security world without first erasing them or to force the reuse of Operator Cards from other security worlds.

-T, --timeout=TIME

These options set the time-out for the card set. Use the suffix s to specify seconds, m for minutes, h for hours, and d for days. If the timeout is set to 0, the Operator Card never times out. Otherwise, the module automatically unloads the Operator Card Set TIME after the Operator Card was loaded.

Page 156: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 156

7 nShield Operator Utilities cryptest

cryptest

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

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

If a mechanism is defined but not supported by the module, cryptest reports Unknown Mechanism.

Usage

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

E|--channel-encrypt]

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

Test options

-M, --module=MODULE

These options specify the module on which to perform tests.

-e, --encryption

These options test encryption mechanisms

-s, --signature

These options test signature mechanisms

-E, --channel-encrypt

This option specifies the use of channel commands to encrypt or sign

Page 157: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 157

7 nShield Operator Utilities cryptest

-S, --channel-decrypt

This option specifies the use of channel commands to decrypt or verify

-m, --max-size=BYTES

This option limits the size of the block to be encrypted to the number of bytes specified in BYTES

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

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

If neither the --encryption nor the --signature option is given, cryptest tests both encryption and signature mechanisms.

Output

cryptest returns output similar to this:

KeyType_DES:

Mech_Any:

encrypt 0 1 7 8 9 15 16 17 20 36 64 256 1025 2048 4096 8192 16384 65536

sign 0 1 7 8 9 15 16 17 20 36 64 256 1025 2048 4096 8192 16384 65536

Mech_DESmCBCi64pPKCS5:

encrypt 0 1 7 8 9 15 16 17 20 36 64 256 1025 2048 4096 8192 16384 65536

Mech_DESmECBpPKCS5:

encrypt 0 1 7 8 9 15 16 17 20 36 64 256 1025 2048 4096 8192 16384 65536

Mech_DESmECBpNONE:

encrypt 0 8 16 64 256 2048 4096 8192 16384 65536

Mech_DESmCBCpNONE:

encrypt 0 8 16 64 256 2048 4096 8192 16384 65536

Mech_DESmCBCMACi64pPKCS5:

sign 0 1 7 8 9 15 16 17 20 36 64 256 1025 2048 4096 8192 16384 65536

...

Page 158: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 158

7 nShield Operator Utilities cspcheck

cspcheck

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

Usage

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

There are no arguments for this utility.

Output from a sample cspcheck session looks something like:

cspcheck: warning: File key_mscapi_231cef632cf81a43e25eea7723235b91356f2db3 is a CSP key

that isn't used in any container

cspcheck: warning: File key_mscapi_user_name-ncsp-user-exchange is a CSP key that isn't

used in any container

cspcheck: information: 88 containers and 7 keys found.

cspcheck: warned about 2 problems

Page 159: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 159

7 nShield Operator Utilities cspimport

cspimport

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

Usage

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

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

TARGET_ID TYPE

If, when you import or migrate a key, the operation replaces an existing key, the old key file is retained. The cspimport utility prints out the name of the old key file. This can be deleted if you do not require it.

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

Import options

-i, --import

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

-k, --key=IDENT

These options specify the IDENT of the key to import.

-i, --import

These options specify the source application name .

Page 160: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 160

7 nShield Operator Utilities cspimport

Migrate options

-m, --migrate

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

-c, --container=SOURCE_ID

These options specify the source container from which to import the key.

--source-type=TYPE

This options specify the type of the source key.

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

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

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

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

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

Page 161: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 161

7 nShield Operator Utilities cspimport

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

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

Example - importing an NFKM key

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

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

1. Generate a key in some external program (for example, KeySafe or another developer library, or from a command-line utility). Make sure you know what the KM file name of the new key is.

For example, to generate a new RSA private key pair with file name key_simple_rsa-test, run the following command:

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

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

keytst -c import-test

Page 162: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 162

7 nShield Operator Utilities cspimport

3. Issue the csputils command to find the alphanumeric string that identifies your target container:

csputils -n import-test

This command produces output similar to the following:

File ID Container name Container owner DLL name S X

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

83ebe19c7a import-test DOMAIN\fred ncsp

1 container and 0 keys found.

In this example, the alphanumeric string 83ebe19c7a identifies the container import-test .

Page 163: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 163

7 nShield Operator Utilities cspimport

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

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

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

This command produces output similar to:

Source key:

Key file: key_simple_rsa-test

Key name: 'rsa-test'

Key hash: 0xd01ddd6e6c1482d70bbcc17808d8d261b7bf129c

Key is module protected.

Target container:

Container ID: #83ebe19c7a35ae3cefd1fced3b9a0aaaa778d80a

Container name: 'import-test'

User name = 'DOMAIN\\fred', CSP name = 'ncsp.dll'

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

b. Replying yes completes the import operation and produces output similar to:

New target key:

Key file: key_mscapi_cloned-key-0

Key name: 'rsa-test'

Key hash: 0xd01ddd6e6c1482d70bbcc17808d8d261b7bf129c

Key is module protected.

Page 164: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 164

7 nShield Operator Utilities cspimport

5. Issue the csputils command in order to verify that the target container now has a key:

csputils -n import-test

This produces output is similar to:

File ID Container name Container owner DLL name S X

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

83ebe19c7a import-test DOMAIN\fred ncsp *

1 container and 1 key found.

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

Example - moving CSP keys between users

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

Page 165: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 165

7 nShield Operator Utilities cspimport

1. Issue csputils commands in order to find the alphanumeric strings that identify the two containers. For alice, the following command:

csputils -U alice

produces output similar to the following:

File ID Container name Container owner DLL name S X

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

2526b6fb64 alice DOMAIN\alice ncsp

32a16394a3 test DOMAIN\alice ncsp * *

cbfb7b1190 foo DOMAIN\alice ncsp *

3 containers and 3 keys found

The alphanumeric string cbfb7b1190 identifies alice's source container foo. Issuing a similar csputils command for bob reveals 559376b4a2 as the alphanumeric string that identifies the destination container bar.

Page 166: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 166

7 nShield Operator Utilities cspimport

2. Issue the cspimport command in order to copy the key from alice’s container foo to bob’s container bar :

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

The output is similar to the following:

Source container:

Container ID: #cbfb7b1190653138bc660df491b5426c929034e5

Container name: 'foo'

User name = 'DOMAIN\alice', CSP name = 'ncsp.dll'

Source key:

Key file: key_mscapi_testencryption-ncsp-ujames-exchange

Key name: '(null)'

Key hash: 0x027ded7f23f4bf42248dc0cf9839e1c186c2fca5

Key is cardset protected

Cardset hash: 0x4eb80f966c13bd735cb50f29ef19e5ec730feb1f

Target container:

Container ID: #559376b4a2982f04fd1f7c9a1adacb192f5ac827

Container name: 'bar'

User name = 'DOMAIN\bob', CSP name = 'ncsp.dll'

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

3. Replying yes completes the import operation, producing output similar to the following:

New target key:

Key file: key_mscapi_cloned-key-1

Key name: '(null)'

Key hash: 0x027ded7f23f4bf42248dc0cf9839e1c186c2fca5

Key is cardset protected

Cardset hash: 0x4eb80f966c13bd735cb50f29ef19e5ec730feb1f

Page 167: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 167

7 nShield Operator Utilities cspimport

4. Issue the csputils command to verify that bob’s target container bar now has a key: csputils -U bob

The output is similar to the following:

File ID Container name Container owner DLL name S X

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

559376b4a2 bar DOMAIN\bob ncsp *

a76e313717 bob DOMAIN\bob ncsp *

da53753753 TestEncryption DOMAIN\bob ncsp *

3 containers and 3 keys found.

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

Page 168: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 168

7 nShield Operator Utilities cspmigrate

cspmigrate

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

Permissions

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

Calling cspmigrate with the -c parameter checks that the new container file’s owner, group, and auditing permissions match those in the old registry key, if necessary. However, calling cspmigrate with the -c parameter does not check the file’s ACL; registry key ACLs have no easy mapping to file ACLs. If you want to ensure that container files ACLs are correct, use csputils to find the desired file name and manually examine the container file’s permissions.

Note The cspmigrate utility can only be used if you have rights as a local administrator. It produces very wide output and also produces very long output if you have many containers.

Usage

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

-m

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

Page 169: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 169

7 nShield Operator Utilities cspmigrate

-c

This option cleans up old registry entries and key files. After you have used this option, the old CSP no longer works

Do not use the -c option until you are confident that the new CSP is working correctly with your old containers.

-d

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

-q

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

-v

This option produces verbose status output during the migration.

-f

This option forces new keys to be overwritten by old keys. If this option is passed in with -q , it always causes the old key to replace the new key in the container.

Note After using the -q option, some CSP-generated key files may exist without an associated container. If this is the case, issuing a cspmigrate -c command does not remove these key files; you must remove them manually.

Page 170: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 170

7 nShield Operator Utilities cspmigrate

Output

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

If a container with a specific key exists in both systems, by default the application asks you which you want to use.

Output from a sample session with cspmigrate -m looks something like:

Searching for user keys, version 1 system...

Found user 'NT AUTHORITY\\LOCAL SERVICE' (sid = S-1-5-19)

Found user 'NT AUTHORITY\\NETWORK SERVICE' (sid = S-1-5-20)

Found user 'DOMAIN\\user_name' (sid = S-1-5-21-1594850079-719136693-34565100-1111)

Found DLL 'ncsp' under keys.

Creating container: { container_name, ncsp, user_name } New container already exists!

Found plausible key exchange key for container.

Existing key file name is 'mscapi_user_name-ncsp-user-exchange'

...new container has key ident: mscapi_user_name-ncsp-user-exchange,

...old container has key ident: mscapi_231cef632cf81a43e25eea7723235b91356f2db3.

Do you want to replace the key in the new container with the one in the old

container? (yes/no):

Entering yes returns output similar to:

...key ident mscapi_231cef632cf81a43e25eea7723235b91356f2db3 is being replaced in the

container

but the key file will not be deleted

....Creating substitute key, new key file name is

'mscapi_7208b58427f9a7ddfd4ff8bf8ea29e434e32a5aa'

Set new key up in the container.

Creating container: { oldtest, ncsp, user_name } New container already

exists!

Found DLL 'ncspbase' under keys.

Creating container: { CSP test, ncspbase, user_name } New container created

successfully.

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

839522115-1007)

Page 171: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 171

7 nShield Operator Utilities cspmigrate

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

1580818891-839522115-500)

Searching for user keys, version 2 system...

Found DLL 'ncsp' under user keys.

Found user 'user_name'.

Creating container: { CSP test, ncsp, user_name } New container created

successfully.

Creating container: { container_name, ncsp, user_name } New container already

exists!

Creating container: { test, ncsp, user_name } New container already

exists!

Found user 'SYSTEM'.

Creating container: { SYSTEM, ncsp, SYSTEM } New container already exists!

Found DLL 'ncspdd' under user keys.

Found user 'user_name'.

Creating container: { container_name, ncspdd, user_name } New container

already exists!

Found user 'SYSTEM'.

Creating container: { SYSTEM, ncspdd, SYSTEM } New container already exists!

Found DLL 'ncspsigdd' under user keys.

Searching for machine keys, both systems...

Found DLL 'ncsp' under keys.

Creating container: { ASIGN_1012, ncsp, [machine] } New container created

successfully.

Creating container: { ASIGN_996, ncsp, [machine] } New container

created successfully.

Creating container: { CSP test, ncsp, [machine] } New container

created successfully.

Creating container: { old-machine, ncsp, [machine] } New container

created successfully.

Found plausible signature key for container.

Existing key file name is 'mscapi_old---2dmachine-ncsp-machine-sign'

Set new key up in the container.

Creating container: { oldtest-machine, ncsp, [machine] } New container

already exists!

Found DLL 'ncspbase' under keys.

Creating container: { CSP test, ncspbase, [machine] } New container created

successfully.

Found DLL 'ncspdd' under keys.

Creating container: { CSP test, ncspdd, [machine] } New container created

successfully.

Found DLL 'ncspsigdd' under keys.

Page 172: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 172

7 nShield Operator Utilities cspmigrate

At this point in the process, check that your new containers exist (by using csputils) and that the new CSPs have the same functionality as the old CSPs.

Note If you are using the Microsoft CA or IIS 5, you must reboot the machine in order to ensure that the newly installed CSPs are used by the system services.

After you are satisfied that the new CSPs are working correctly, you can clean up the container information from the registry; it is no longer needed. However, because there is no utility that regenerates old container information (registry-based) from new container information (security-world-based), only remove the old CSPs if you are sure they are no longer needed. It is not necessary to perform this step in order for the computer to operate correctly.

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

Searching for user keys, version 1 system...

Found user 'NT AUTHORITY\\LOCAL SERVICE' (sid = S-1-5-19)

Found user 'NT AUTHORITY\\NETWORK SERVICE' (sid = S-1-5-20)

Found user 'DOMAIN\\user_name' (sid = S-1-5-21-1594850079-719136693-34565100-1111)

Found DLL 'ncsp' under keys.

Checking container: { container_name, ncsp, user_name } New container exists.

Checking existence of plausible key exchange key for container.

Existing key file name is 'mscapi_user_name-ncsp-user-exchange'

Container contains a suitable key.

Removing registry key Software\\nCipher\\Cryptography\\UserKeys\\ncsp\\user_name.

Removing registry key Software\\nCipher\\Cryptography\\UserKeys\\ncsp.

Removing registry key Software\\nCipher\\Cryptography\\UserKeys.

Removing registry entry Software\\nCipher\\Cryptography.

Removing registry entry Software\\nCipher.

Found user 'MACHINE_NAME\\testuser' (sid = S-1-5-21-448539723-1580818891-839522115-1007)

Searching for user keys, version 2 system...

Found DLL 'ncsp' under user keys.

Found user 'user_name'.

Checking container: { CSP test, ncsp, user_name } New container exists.

Removing registry key

Software\\nCipher\\Cryptography\\ncsp\\UserKeys\\user_name_CSP_test.

Checking container: { container_name, ncsp, user_name } New container exists.

Page 173: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 173

7 nShield Operator Utilities cspmigrate

Removing registry key

Software\\nCipher\\Cryptography\\ncsp\\UserKeys\\container_name_user_name.

Checking container: { test, ncsp, user_name } New container exists.

Removing registry key Software\\nCipher\\Cryptography\\ncsp\\UserKeys\\user_name_test.

Found user 'SYSTEM'.

Checking container: { SYSTEM, ncsp, SYSTEM } New container exists.

Removing registry key Software\\nCipher\\Cryptography\\ncsp\\UserKeys\\SYSTEM_SYSTEM.

Removing registry key Software\\nCipher\\Cryptography\\ncsp\\UserKeys.

Removing registry key Software\\nCipher\\Cryptography\\ncsp.

Found DLL 'ncspdd' under user keys.

Found user 'user_name'.

Checking container: { container_name, ncspdd, user_name } New container exists.

Removing registry key

Software\\nCipher\\Cryptography\\ncspdd\\UserKeys\\container_name_user_name.

Found user 'SYSTEM'.

Checking container: { SYSTEM, ncspdd, SYSTEM } New container exists.

Removing registry key Software\\nCipher\\Cryptography\\ncspdd\\UserKeys\\SYSTEM_SYSTEM.

Removing registry key Software\\nCipher\\Cryptography\\ncspdd\\UserKeys.

Removing registry key Software\\nCipher\\Cryptography\\ncspdd.

Searching for machine keys, both systems...

Found DLL 'ncsp' under keys.

Checking container: { ASIGN_1012, ncsp, [machine] } New container exists.

Removing registry key Software\\nCipher\\Cryptography\\MachineKeys\\ncsp\\ASIGN_1024.

Checking container: { ASIGN_996, ncsp, [machine] } New container exists.

Removing registry key Software\\nCipher\\Cryptography\\MachineKeys\\ncsp\\ASIGN_996.

Checking container: { CSP test, ncsp, [machine] } New container exists.

Removing registry key Software\\nCipher\\Cryptography\\MachineKeys\\ncsp\\CSP_test.

Checking container: { old-machine, ncsp, [machine] } New container exists.

Checking existence of plausible signature key for container.

Existing key file name is 'mscapi_old---2dmachine-ncsp-machine-sign'

Container contains a suitable key.

Removing registry key Software\\nCipher\\Cryptography\\MachineKeys\\ncsp\\old-machine.

Checking container: { oldtest-machine, ncsp, [machine] } New container exists.

Removing registry key Software\\nCipher\\Cryptography\\MachineKeys\\ncsp\\oldtest-

machine.

Removing registry key Software\\nCipher\\Cryptography\\MachineKeys\\ncsp.

Found DLL 'ncspdd' under keys.

Checking container: { CSP test, ncspdd, [machine] } New container exists.

Removing registry key Software\\nCipher\\Cryptography\\MachineKeys\\ncspdd\\CSP_test.

Removing registry key Software\\nCipher\\Cryptography\\MachineKeys\\ncspdd.

Removing registry key Software\\nCipher\\Cryptography\\MachineKeys

Page 174: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 174

7 nShield Operator Utilities cspnvfix

cspnvfix

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

Usage

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

-c , --container=HASH

These options specify the hash of the target key container. Use csputils to retrieve the hash for a container of a specified name.

-t, --type=KEYTYPE

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

-m, --module=MODULE

These options specifies the module for NVRAM area regeneration.

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

Page 175: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 175

7 nShield Operator Utilities csptest

csptest

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

Usage

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

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

time=TIME]]

-f, --flood

These options perform a continuous signature test, similar to floodtest or sigtest.

-d, --dsa

These options specify the use of DSA signatures rather than RSA signatures.

-m, --ms

These options specify the use of the Microsoft provider (possibly with nCipher modexp offload) rather than the nCipher provider.

-C, --counters

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

Page 176: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 176

7 nShield Operator Utilities csptest

-K, --kitb

These options generate module-protected keys.

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

-n, --number=NUM

These options specify NUM number of simultaneous threads (the default is 100).

-l, length=LEN

These options specify the use of a key num -bits long. The default is 1024.

Note csptest reports errors if you attempt to generate keys whose length is not a multiple of 8 bits. This is because the CSP does not support lengths that are not a multiple of 8 bits. This behavior is consistent with that of the Microsoft CSP, although the error returned is different.

-k, --keys=KEYS

This option specifies the use of num number of keys simultaneously to soak (the default is 1).

Note The keys used to soak are shared between threads. Therefore, the number of keys must be less than or equal to the number of threads.

Note If the value you specify for keys or length is too large, the module runs out of memory and the command fails with the message:

nFastKM: error: MakeBlob (private key) failed; NoMemory unable to generate signature key

for context #16, last error was 0x80090020.

Note The maximum permitted value depends on the amount of memory on the module. If the command fails with the out of memory message, run the command again with a smaller number of keys.

Page 177: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 177

7 nShield Operator Utilities csptest

-s, sigs=SIGS

This option floods for num number of signatures and then stops.

-t, --time=TIME

These options run for TIME seconds and then stops.

Output

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

nCipher CSP test software

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

Found the nCipher domestic CSP named 'nCipher Enhanced Cryptographic Provider'

Provider name: nCipher Enhanced Cryptographic Provider

Version number: 1.9

Supported hash algorithms:

SHA-1 - hash length : 160 bits (supports SSL3 and TLS)

MD2 - hash length : 128 bits

MD5 - hash length : 128 bits (supports SSL3 and TLS)

SSL3 SHAMD5 - hash length : 288 bits (supports SSL3 and TLS)

MAC - hash length : 64 bits (supports SSL3 and TLS)

HMAC - hash length : 0 bits (supports SSL3 and TLS)

Supported data encryption algorithms:

RC2 - key lengths: 40-128 bits, default 128 bits. (supports SSL3 and TLS)

RC4 - key lengths: 40-128 bits, default 128 bits. (supports SSL3 and TLS)

DES - key length : 56-64 bits, default 64 bits. (supports SSL3 and TLS)

3DES - key length : 168-192 bits, default 192 bits. (supports SSL3 and TLS)

3DES_112 - key length : 112-128 bits, default 128 bits. (supports SSL3 and TLS)

Supported signature algorithms:

RSA_SIGN - key lengths: 384-16384 bits, default 1024 bits, in increments of 8 bits.

(supports SSL3 and TLS)

Supported key exchange algorithms:

RSA_KEYX - key lengths: 384-16384 bits, default 1024 bits, in increments of 8 bits.

(supports SSL3 and TLS)

User key containers:

Container 'fred' has a 1024-bit key exchange key.

Machine key containers:

Container 'fred\xd5 s computer' has no stored keys.

Container 'fred' has a 512-bit signature key.

Page 178: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 178

7 nShield Operator Utilities csptest

Testing signature operations:

Hashing data for signing - OK

Signing hash - OK

Exporting public key - OK

Importing public key - OK

Hashing data for verifying - OK

Verifying signature - OK

Testing key exchange operations:

Generating symmetric key - OK

Encrypting data - OK

Exporting symmetric key - OK

Getting salt value - OK

Importing symmetric key - OK

Encrypting data with imported key - OK

Checking two buffers are identical - OK

Timing signature operations (for 10 seconds): 41.1429 1024-bit signature operations per

second, averaged over 7 seconds.

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

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

1, 60 60, 60 overall

2, 130 70, 65 overall

3, 192 62, 64 overall

4, 263 71, 65.75 overall

5, 333 70, 66.6 overall

6, 396 63, 66 overall

Page 179: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 179

7 nShield Operator Utilities csputils

csputils

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

Usage

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

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

-l, --list

These options display a table of the selected containers using one line for each container

-d, detail

These options display detailed information about the selected containers.

-x, delete

These options delete the selected containers after prompting the user.

-c, --csp=CSP

These options select containers from the CSP named CSP

-U, --username=USER

These options select containers from the user named USER. If USER is specified as ALL, containers are selected from all users.

Note The -U ALL option does not display machine containers unless you also specify --machine.

Page 180: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 180

7 nShield Operator Utilities csputils

-m, --machine

These options select all machine containers.

-H, --hash=HASH

These options select containers with the hash HASH

-n, --name=NAME

These options select containers with the name NAME.

Note The hash and container name are treated as substrings.

Selection options ( -c , --username , --machine , --hash , and --name ) are additive. The output displays the union of all sets created by the selected options (for example, the command csputils --hash 3c4d --username bert lists both containers whose hash starts 3c4d and also those belonging to the user with user name bert). You cannot pass more than one of each option on the command line at a time. For example, attempting to issue a command likecsputils --username bert --username erniedoes not work.

Note You need administrative privileges in order to use the --delete , the -username , or the --machine options. Any other chosen selection options list only the containers that belong to the current user.

If you do not specify any of -l , -d , or -x , then -l is assumed. If you do not specify any selection options, csputils displays all containers from the current user.

Output

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

csputils --username ALL --machine

Page 181: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 181

7 nShield Operator Utilities csputils

This returns output similar to:

File ID Container name Container owner DLL name S X

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

05950465c5 CSP test DOMAIN\user_name ncsp *

1e6ff7b617 oldtest-machine MACHINE ncsp

2a27a30ff6 bd2769c6-403f-423... MACHINE ncsp

32a16394a3 container_name DOMAIN\user_name ncsp *

35f5fb00a3 oldtest DOMAIN\user_name ncsp

374b42557b CSP test MACHINE ncsp

4234b80bfc SYSTEM NT AUTHORITY\SYSTEM ncsp

6c400deafc SYSTEM NT AUTHORITY\SYSTEM ncspdd

748e8f42d3 CSP test MACHINE ncspbase

74cc603f6c CSP test MACHINE ncspdd

9c478d3429 container_name DOMAIN\user_name ncspdd

cccb69f1ab test DOMAIN\user_name ncsp

da493a4f56 CSP test DOMAIN\user_name ncspbase

13 containers and 1 key found.

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

File ID Container name Container owner DLL name S X

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

05950465c5 CSP test DOMAIN\user_name ncsp *

374b42557b CSP test MACHINE ncsp

748e8f42d3 CSP test MACHINE ncspbase

74cc603f6c CSP test MACHINE ncspdd

da493a4f56 CSP test DOMAIN\user_name nspbase

5 containers and 0 keys found.

Page 182: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 182

7 nShield Operator Utilities csputils

In order to display details about all containers whose hash contains 32 , issue the command:csputils --detail --hash 32which returns output similar to:

Detailed report for container ID #32a16394a3ffe52eb4db1127d87865ce6a42fa7c

Filename: key_mscapi_container-32a16394a3ffe52eb4db1127d87865ce6a42fa7c

Container name: container_name

User name: DOMAIN\user_name

User SID: s-1-5-21-1594850079-719136693-34565100-1111

CSP DLL name: ncsp.dll

No signature key.

Filename for key exchange key is key_mscapi_231cef632cf81a43e25eea7723235b91356f2db3

Key was generated by the CSP

Key hash: 231cef632cf81a43e25eea7723235b91356f2db3

Key is recoverable.

Key is module protected.

1 container and 1 key found.

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

File ID Container name Container owner DLL name S X

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

05950465c5 CSP test DOMAIN\user_name ncsp *

374b42557b CSP test MACHINE ncsp

748e8f42d3 CSP test MACHINE ncspbase

74cc603f6c CSP test MACHINE ncspdd

da493a4f56 CSP test DOMAIN\user_name ncspbase

5 containers and 1 key found.

This action cannot be undone - are you sure you want to delete

all these containers and their associated key files? (yes/no):

Page 183: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 183

7 nShield Operator Utilities csputils

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

Deleting container file mscapi_container-05950465c57b34bf82a5a6316f6726944091baf7

Deleting key file mscapi_bb7202b7f4f4224a6281ee0f3b679b03139704ac

Deleting container file mscapi_container-374b42557b912d5bdce885193d174969427b0e4d

Deleting container file mscapi_container-748e8f42d39c1058ce1444d71fc055ef168546b7

Deleting container file mscapi_container-74cc603f6c606accd82ec0cf2cb9e711737c13fc

Deleting container file mscapi_container-da493a4f56fea6ca35f2ff40e61b98756ed2b71f

5 containers and 1 key deleted.

Enter

Page 184: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 184

7 nShield Operator Utilities des_kat

des_kat

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

Usage

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

The options -m and --module=MODULE specify the module on which to perform the test. The default is the first module available.

Output

des_kat should return output:

DES known answer tests

Tests passed

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

Page 185: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 185

7 nShield Operator Utilities enquiry

enquiry

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

Usage

enquiry -m|--module=MODULE

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

Output

enquiry returns the following data for the server and each module:

enquiry reply flags

Failed indicates that the module has failed. This failure may be because the module is in the Error state or because there is a problem on the PCI bus.

enquiry reply level

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

serial number

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

mode

This is one of:

Page 186: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 186

7 nShield Operator Utilities enquiry

• operational

• initialisation

• maintenance

• pre-initialisation

• pre-maintenance

• uninitialised.

For the server, this is always operational.

version

This is the version of the nCipher server or firmware.

speed index

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

rec. queue

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

level one flags

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

Hardware

The Hardware flag is always set.

HasTokens

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

Page 187: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 187

7 nShield Operator Utilities enquiry

MaintenanceMode

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

InitialisationMode

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

PreMaintInitMode

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

version string

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

checked in

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

level two flags

This is for nCipher internal use only..

Note There should be no level two flags set. If any are set, contact Support at nCipher.

max write size

Currently, this is 8192 for nShield/payShield modules.

level three flags

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

Page 188: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 188

7 nShield Operator Utilities enquiry

level four flags

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

OrderlyClearUnit

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

HasRTC

The HasRTC flag is set if the module has a Real-Time Clock.

HasNVRAM

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

HasNSOPermsCmd

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

ServerHasPollCmds

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

Page 189: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 189

7 nShield Operator Utilities enquiry

FastPollSlotList

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

HasSEE

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

HasKLF

The HasKLF flag is set if the module has a long-term fixed signing key.

HasShareACL

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

HasFeatureEnable

The HasFeatureEnable flag is set if the module supports feature enabled functions. See the Administrator Guide for information on the features available and how to enable them.

HasFileOp

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

HasPCIPush

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

Page 190: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 190

7 nShield Operator Utilities enquiry

HasKernelInterface

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

HasLongJobs

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

SeverHasLongJobs

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

AESModuleKeys

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

NTokenCmds

The NTokenCmds flag is set if the module supports the commands necessary for nToken.

For the server, the level four flags field contains all the flags set for attached modules.

module type code

For modules that support enquiry level Five or greater, this field contains the numeric value of the module type. This can be:

• 0 for the server

• 5 for models nC3022W-nnn, nC4022W-nnn, and nC4032W-nnn

• 6 for models nC3022P-nnn, nC4022P-nnn, nC4032P-nnn, and nC4132P-nnn

Page 191: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 191

7 nShield Operator Utilities enquiry

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

• 11 for model nC4031Z-nnn.

product name

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

device name

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

EnquirySix version

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

impath kx groups

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

feature ctrl flags

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

Page 192: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 192

7 nShield Operator Utilities enquiry

features enabled

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

If no features are enabled, this field is set to StandardKM.

This field does not exist for the server.

version serial

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

remote server port

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

kneti hash

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

Value Feature that is enabled Feature name

ForeignTokenOpen Foreign Token access features (ISS). ISO Smart Card Support

RemoteShare Remote Operator Card support Remote Operator

KISAAlgorithms Support for KISA algorithm suite (KCDSA, SEED, HAS160 hash function)

Korean Algorithms.

GeneralSEE Allows any SEE machine to be loaded. Available only within CGEA locations.

SEE Activation (EU+10)

EllipticCurve Allows small key sizes to provide improved levels of security.

Elliptic Curve

Page 193: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 193

7 nShield Operator Utilities enquiry

rec. LongJobs queue

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

SEE machine type

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

Page 194: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 194

7 nShield Operator Utilities floodtest

floodtest

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

Usage

C:\nfast\bin\floodtest.exe [--crt|--no-crt] [-Q|--query] [-R|--no-round-robin] [-l|--

job-size=BITS]

[-t|--stop-after=TIME] [-j|--outstanding-jobs=COUNT] [-n|--jobs-count=COUNT]

[[[-K|--skew-check=SKEW ]| [-T|--min-check=COUNT ]] [-C|--check-start=TIME ]]

[--overprint][-o|--output=FILE] [-r|--report-interval=TIME]

Program options

--crt

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

--no-crt

This option specifies no use of CRT optimization

-Q, --query

These options specify use Query mode (spinlock) rather than Wait mode

-R, --no-round-robin

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

Page 195: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 195

7 nShield Operator Utilities floodtest

-l, --job-size=BITS

These options set the size of exponentiation modulus to the number of bits specified in BITS. The default is 1024. The value of BITS must be between 64 and 4096. BITS must be a multiple of 64

Note Certain older modules (with serial numbers beginning 01-52, 01-54, 01-56, 01-P2, 01-P4, or 01-P6) can run out of memory if you run floodtest with sizes greater than 2048, especially if the module has any keys or tokens loaded.

-j, --outstanding-jobs=COUNT

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

-t, --stop-after=TIME

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

-n, --jobs-count=COUNT

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

Automatic checking options

-T, min-check=COUNT

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

Page 196: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 196

7 nShield Operator Utilities floodtest

-K, --skew-check=SKEW

These options perform skew checking, after either 15 seconds or the time specified by --check-start. floodtest records the overall average number of modular exponentiations each second as rec_ave. Subsequently, when floodtest writes an output line, it quits with an error message if the average is outside the range rec_ave±SKEW.

Note The --min-check and --skew-check options are mutually exclusive.

-C, --check-start=TIME

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

Output options

--overprint

This option prints results all on one line, using \r rather than \n.

-o, --output=FILE

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

-r, --report-interval=TIME

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

Page 197: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 197

7 nShield Operator Utilities floodtest

Output

floodtest returns output similar to this:

hardware, speed index 296, using rec. max outstanding + 1 = 46

1, 148 59.2, 151 overall

2, 410 140.32, 206 overall

3, 677 190.992, 226 overall

4, 944 221.395, 267 overall

5, 1190 231.237, 256.5 overall

...

The first column, to the right of the line numbers, shows the number of seconds.

The second shows the total number of exponentiations performed.

The third column shows the number of exponentiations achieved this second.

The last column shows a moving average of the number of exponentiations achieved each second.

Page 198: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 198

7 nShield Operator Utilities fwcheck

fwcheck

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

Usage

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

file

Help options

-h, --help

This option displays help for fwcheck.

-V, --version

This option displays the version number of fwcheck.

-u, --usage

This option displays a brief usage summary for fwcheck.

-v, --verbose

This option displays all possible output for fwcheck.

Checking options

-m, --module=MODULE

This option checks the module number MODULE.

-c, --challenge=HEX

This option uses HEX as the challenge. If not specified, the challenge is a random value.

Page 199: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 199

7 nShield Operator Utilities fwcheck

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

fwcheck can be used with the following types of file:

fw_platform.nff

the regular application firmware file as supplied to loadrom

fw_platform.ftv

performs a “pseudo-random sequence generation” test on the application

In these file names, platform is the version number of the module, beginning with nC.

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

Page 200: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 200

7 nShield Operator Utilities generatekey

generatekey

You can use the generatekey utility to:

• generate new keys

• import existing keys into a security world

• retarget a key used by one application for use with a different application

• list supported applications.

You can use generatekey interactively by:

• issuing commands without parameters and supplying the required information when prompted by the utility

• supplying some or all of the required parameters on the command line. generatekey prompts for any missing parameters.

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

You can also use generatekey in batch mode, which is useful for scripting.

Note Because of changes to options and parameters in the current version of generatekey, scripts you run that use a previous version of generatekey may require changes before you can run them successfully.

In batch mode, you supply parameters in the command line. If you omit parameters, generatekey does not prompt for the missing information. Instead it uses available defaults or fails. If you specify one or more parameters incorrectly, an error is displayed and the command fails.

Note If a parameter’s argument contains spaces, you must enclose the argument within quotation marks (" ").

Page 201: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 201

7 nShield Operator Utilities generatekey

The generatekey utility takes the following form:

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

In this command:

OPTIONS

This represents the command-line options that determine how generatekey behaves. OPTIONS must always precede the application name (APPNAME) and parameters.

APPNAME

This represents the application with which you want to use the key. Specifying an application can restrict your choice of key type. APPNAME must follow any OPTIONS and precede any parameters specified for the key.

NAME=VALUE

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

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

Options

--generate

This option generates a new key. This is the default action if none of --generate, --import, or --retarget is specified.

Page 202: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 202

7 nShield Operator Utilities generatekey

--import

This option imports a key.

--retarget

This option transfers an existing key to another application.

--batch

This option runs generatekey in batch mode. If you specify --batch, you specify parameters as NAME=VALUE pairs on the command line; no parameters are prompted for. Where you do not specify parameters, generatekey uses available defaults or terminates with an error message. If you specify one or more parameters incorrectly, an error is displayed and the command fails.

For jcecsp keys, you must specify the key store’s pass phrase, and this is displayed on the command line. This risks revealing the password. Therefore, nCipher recommends that you do not use batch mode with jcecsp keys.

--interactive

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

--check, --check-props

These options tell generatekey to check parameters for validity only, without generating, importing, or retargeting the key.

--list-params, --list-props

These options list the parameters associated with a specific application.

Page 203: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 203

7 nShield Operator Utilities generatekey

--list-apps

This option lists the supported applications. Unlike other options, it is not necessary to specify an APPNAME with --list-apps.

--list-key-types

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

--module MODULE

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

• in batch mode, the only available or first usable module is used

• in interactive mode, the only available module is used or you are prompted to specify a module.

Note A module is usable if it is in the current security world and in the operational state.

The module may alternatively be specified with the module parameter.

--cardset NAME, --cardset HASH

For a token protected key, these options specify the Operator Card Set to use to protect the key, by its name or hash value, as returned by nfkminfo. If you do not specify one of these options and you specify Operator Card protection for the key:

• in batch mode, generatekey uses the Operator Card Set to which the Operator Card currently in the module belongs (or the first returned by nfkminfo)

Page 204: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 204

7 nShield Operator Utilities generatekey

• in interactive mode, if there is more than one Operator Card Set, you will be prompted to select the Operator Card Set to use at card-loading time.

generatekey only generates or imports the key if the smart card in the module is from this card set.

--verify

This option verifies the security of the generated, imported or retargeted key. This is the default mode of operation. If you specify --verify, only the following key types are available:

• DES2

• DES3

• DH

• DSA

• ECDH

• ECDSA

• HMACRIPEMD160

• HMACSHA1

• HMACSHA256

• HMACSHA384

• HMACSHA512

• HMACTiger

• KCDSA (if enabled)

• RSA

Page 205: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 205

7 nShield Operator Utilities generatekey

• Rijndael (AES)

--no-verify

This option disables the security check on the key. If you specify --no-verify, additional key types to those supported with --verify are available:

• ArcFour

• Blowfish

• CAST

• CAST256

• DES

• HMACMD2

• HMACMD5

• IDEA

• SEED

• Serpent

• Twofish Because there are no checks on the security of any key generated in

this manner and therefore no guarantee of its security, and because incorrectly constructed Access Controls Lists (ACLs) are not detected, nCipher recommends that you do not use the --no-verify option.

--debug

This option enables the display of debugging messages. nCipher recommends you do not use the option unless asked to do so by Support at nCipher.

--quiet

This option suppresses the display of all non-vital messages during operation.

Page 206: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 206

7 nShield Operator Utilities generatekey

--verbose

This option displays all messages during operation. This is the default.

Applications

With generatekey, APPNAME can be:

simple

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

custom

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

pkcs11

These keys are formatted suitably for use with PKCS #11 applications and are given a suitable identifier. The set of key types supported is currently limited to:

• DES

• DES2

• DES3

• DH

• DSA

• ECDH

• ECDSA

• HMACSHA1

Page 207: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 207

7 nShield Operator Utilities generatekey

• RSA

• KCDSA

• CAST

• HMACMD5

• Rijndael (AES)

embed

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

hwcrhk

This option generates a key for Cryptographic Hardware Interface Library (CHIL) applications that do not require the APPNAME embed. Only RSA, DSA, and DH key types are supported

jcecsp

for Java Cryptography architecture support. These keys are automatically added to an nCipher.sworld keystore.

kpm

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

Page 208: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 208

7 nShield Operator Utilities generatekey

Parameters

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

Page 209: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 209

7 nShield Operator Utilities generatekey

Parameter Purpose Action Application

generate

impo

rt

retarget

custom

embed

hwcrhk

jcecsp

pkcs11

seeconf

seeinteg

simple

kpm

alias This determines the alias to assign to the key.

X X X X

blobsavefile When using the custom application type, this specifies a file name of the form the form FILENAME.EXT to which to save the key blob. Additionally, text file containing information about the key is saved to a file whose name has the form ROOT_inf.txt; for asymmetric key types, the public key blob is also saved to a file whose name has the form ROOT_pub.EXT.

X X X X

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

X X X X X X X X X

Page 210: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 210

7 nShield Operator Utilities generatekey

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

X

Parameter Purpose Action Application

generate

impo

rt

retarget

custom

embed

hwcrhk

jcecsp

pkcs11

seeconf

seeinteg

simple

kpm

Page 211: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 211

7 nShield Operator Utilities generatekey

checks For RSA key generation only, this specifies the number of checks to be performed. Normally, you should leave this blank to let the module pick an appropriate default.

X X X X X X X X

curve For ECDH and ECDSA key generation only. This option specifies which of the range of supported curves to use. Supported curves are: NISTP192, NISTP224, NISTP256, NISTP384, NISTP521, NISTB163, NISTB233, NISTB283, NISTB409, NISTB571, NISTK163, NISTK233, NISTK283, NISTK409, NISTK571, ANSIB163v1, ANSIB191v1, SECP160r1

X X X X X X X X X

embedconvfile This specifies the name of the PEM file that contains the RSA key to be converted.

X X

Parameter Purpose Action Application

generate

impo

rt

retarget

custom

embed

hwcrhk

jcecsp

pkcs11

seeconf

seeinteg

simple

kpm

Page 212: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 212

7 nShield Operator Utilities generatekey

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

X X X X X

from-application For retargeting, this parameter specifies the application name of the key to be retargeted. Only applications for which at least one key exists are acceptable.

X X X X X X X X

from-ident This specifies the identifier of the key to be retargeted, as displayed by nfkminfo.

X X X X X X X X

Parameter Purpose Action Application

generate

impo

rt

retarget

custom

embed

hwcrhk

jcecsp

pkcs11

seeconf

seeinteg

simple

kpm

Page 213: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 213

7 nShield Operator Utilities generatekey

hexdata This specifies the hex value of DES/DES3 key to import. Note that the hex digits are echoed to the screen and are may be visible in process listings if specified on the command line.

X X X X X X X

ident This specifies a unique identifier for the key in the security world. For simple or hwcrhk applications, this is the key identifier to use (the exact identifier for simple, for hwcrhk the key type is implicitly included). For other application types, keys are assigned an automatically generated identifier and accessed by means of some application-specific name.

X X X X X

keystore This specifies the filename of the keystore to use. This must be an nCipher keystore.

X X X X

keystorepass This specifies the password to the keystore to use.

X X X X

Parameter Purpose Action Application

generate

impo

rt

retarget

custom

embed

hwcrhk

jcecsp

pkcs11

seeconf

seeinteg

simple

kpm

Page 214: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 214

7 nShield Operator Utilities generatekey

module This specifies the module to use for generating the key. If there is more than one usable module, this is prompted for. The module can also be specified with the --module option. The default is the first usable module (one in the current security world and in the operational state).

X X X X X X X X X

nvram This determines whether the key is stored in the kmdata directory of the host computer or in the module’s NVRAM. If set to yes, the key is stored in the module's NVRAM. If set to no, the key is stored on the host. The default is no. This parameter only works if your module's firmware supports it and if there is sufficient space in your module’s NVRAM. See Generating NVRAM-stored keys on page 92.

X X X X X X X X

paramsreadfile This specifies the name of the group parameters file that contains the discrete log group parameters for Diffie-Hellman keys only. This should be a PEM-formatted PKCS#3 file. If this parameter is omitted, the module uses a default file.

X X X X X X X X X

Parameter Purpose Action Application

generate

impo

rt

retarget

custom

embed

hwcrhk

jcecsp

pkcs11

seeconf

seeinteg

simple

kpm

Page 215: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 215

7 nShield Operator Utilities generatekey

pemreadfile This specifies the name of the PEM file that contains the key to be imported. When importing an RSA key, this is the name of the PEM-encoded PKCS #1 file to read it from. Password-protected PEM files are not supported.

X X X X X

plainname This specifies the key name within the security world. For some applications, the key identifier is derived from the name, but for others the name is just recorded in kmdata and not used otherwise.

X X X X X X X X X

protect This specifies the protection method, which can be module for security-world protection, softcard for softcard protection or token for Operator Card Set protection. The default is token, except for seeconf keys, where the default is module. seeinteg keys are always token-protected. The softcard option is only available when your system has at least one softcard present.

X X X X X X X X X X X

Parameter Purpose Action Application

generate

impo

rt

retarget

custom

embed

hwcrhk

jcecsp

pkcs11

seeconf

seeinteg

simple

kpm

Page 216: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 216

7 nShield Operator Utilities generatekey

pubexp For RSA key generation only, this specifies in hexadecimal format the public exponent to use when generating RSA keys. it is normally left blank. nCipher recommends you do not use this parameter unless asked to by Support at nCipher.

X X X X X X X X

qsize This specifies the size in bits of Q when generating KCDSA keys (if this feature is enabled). This parameter is normally invisible because it must always be set to 160 (which is therefore the default value). For information about enabling features, see the Administrator Guide appropriate to your module type.

X X X X X X X X

recovery This parameter enables recovery for this key and is only available for card-set protected keys in a recovery-enabled world. If set to yes, the key is recoverable. If set to no, key is not recoverable. The default is yes. Non-recoverable module-protected keys are not supported.

X X X X X X X X X X X

Parameter Purpose Action Application

generate

impo

rt

retarget

custom

embed

hwcrhk

jcecsp

pkcs11

seeconf

seeinteg

simple

kpm

Page 217: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 217

7 nShield Operator Utilities generatekey

seeintegname If present, this parameter identifies a seeinteg key. The ACL of the newly generated private key is modified to require a certificate from the seeinteg key for its main operational permissions, such Decrypt and Sign (DuplicateHandle, ReduceACL, and GetACL are still permitted without certification.)

X X

selfcert This parameter enables you to generate a self-signed certificate when generating a PKCS #11 key (RSA keys only). To generate a self-signed certificate request you must set selfcert to yes, which makes generatekey prompt you to fill in the extra fields required to generate a key with a self-signed certificate. The resultant certificatesaved to the current working directory with a file name of the form filename.ext. You can use this paramater with the --retarget option to generated a self-signed certificate for an existing key.

X

Parameter Purpose Action Application

generate

impo

rt

retarget

custom

embed

hwcrhk

jcecsp

pkcs11

seeconf

seeinteg

simple

kpm

Page 218: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 218

7 nShield Operator Utilities generatekey

size For key types with variable-sized keys, this specifies the key size in bits. The range of allowable sizes depends on key type and whether --no-verify was used. The default depends on the key type. See Appendix A: Cryptographic algorithms for information on available key types and sizes. This parameter does not exist for fixed-size keys, nor for ECDH and ECDSA keys which are specified using curve.

X X X X X X X X X X

strict For DSA key generation only, if set to yes this parameter enables strict verification, which also limits the size to exactly 1024 bits. The default is no.

X X X X X X X

Parameter Purpose Action Application

generate

impo

rt

retarget

custom

embed

hwcrhk

jcecsp

pkcs11

seeconf

seeinteg

simple

kpm

Page 219: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 219

7 nShield Operator Utilities generatekey

type This specifies the type of key. You must usually specify the key type for generation and import (though some applications only support one key type, in which case you are not asked to choose). Sometimes the type must also be specified for retargetting. See Appendix A: Cryptographic algorithms for information on available key types. The --verify option limits the available key types.

X X X X X X X X X X

x509country This specifies a country code, which must be a valid 2-letter code, for the certificate request.

X X X X X

x509dnscommon This specifies a site domain name, which can be any valid domain name, for the certificate request.

X X X X X

x509email This specifies an email address for the certificate request.

X X X X X

x509locality This specifies a city or locality for the certificate request.

X X X X X

Parameter Purpose Action Application

generate

impo

rt

retarget

custom

embed

hwcrhk

jcecsp

pkcs11

seeconf

seeinteg

simple

kpm

Page 220: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 220

7 nShield Operator Utilities generatekey

Note If a parameter’s argument contains spaces, you must enclose the argument within quotation marks (" ").

x509org This specifies an organization for the certificate request.

X X X X X

x509orgunit This specifies an organizational unit for the certificate request.

X X X X X

x509province This specifies a province for the certificate request.

X X X X X

xsize This specifies the private key size in bits when generating Diffie-Hellman keys. The default is 256 bits for a key size of 1500 bits or more and otherwise 160 bits.

X X X X X X X

Parameter Purpose Action Application

generate

impo

rt

retarget

custom

embed

hwcrhk

jcecsp

pkcs11

seeconf

seeinteg

simple

kpm

Page 221: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 221

7 nShield Operator Utilities hardserver

hardserver

The hardserver is the communications service between applications and nCipher modules.

You must be logged in as Administrator to use the command-line options for this command.

Usage

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

The hardserver is configured by means of configuration files. See the appropriate Administrator Guide for you module type.

The -c or --command-line options run the hardserver program as a command line program instead of as a service

Hardserver startup

The hardserver utility is the hardserver program. It is installed as a service and started automatically.

On startup, the hardserver looks for scripts in the %NFAST_HOME%\scripts\hardserver.d directory and executes them as follows:

• On hardserver startup, all batch files whose names begin with S are executed in strict lexicological order (for example, S01_myscript.bat followed by S02_myscript.bat).

• On module reset, if and only if the module is being reset into operation mode, all batch files whose names begin with M are executed in strict lexicological order (for example, M01_myscript.bat followed by M02_myscript.bat ).

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

Page 222: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 222

7 nShield Operator Utilities hardserver

Stopping the hardserver

1. Ensure that you are logged in as a user who is permitted to stop and that services (for example, a Local Administrator).

2. Open the Computer Management dialog. This is usually found by choosing Programs > Administrative Tools from the Start menu.

3. Highlight the Services entry under Services and Applications. nFast Server should be listed with the status Started.

4. Scroll down the list of services until you have highlighted the nFast Server entry, and click the Stop button in order to stop the server.

Restarting the nCipher server

1. Ensure that you are logged in as as a user who is permitted to create privileged connections.

2. Open the Computer Management dialog. This is usually found by choosing Programs > Administrative Tools > Computer Management from the Start menu.

3. Highlight the Services entry under Services and Applications. nFast Server should be listed with the status Stopped.

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

Page 223: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 223

7 nShield Operator Utilities initunit

initunit

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

Usage

In order to use initunit, you must be logged in to the host computer as root or as a user in the group nfast and must start the module in the pre-initialization state.For information about starting the module in the pre-initialization state, see the appropriate Administrator Guide for your module type.

C:\nfast\bin\initunit.exe [-m|--module=MODULE] [-n|--ntoken]

In this command:

-m, --module=MODULE

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

-n, --ntoken

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

Page 224: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 224

7 nShield Operator Utilities initunit

Output

If initunit is successful, it returns a message similar to this for each module that has been initialized:

Initialising Unit #

Setting dummy HKNSO

Module Key Info:

HKNSO ###################HKM ###################

Otherwise, it returns an error message that points to the reason for the initialization failure.

Page 225: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 225

7 nShield Operator Utilities keytst

keytst

The keytst utility displays information about existing CSP key containers. If you have the appropriate permissions, keytst allows you to create containers and their keys, and to delete containers.

Note The contents of a CSP key container do not necessarily reflect the key information that is held in the kmdata directory. However, all key container data that is held in the nCipher CSP is present in the kmdata directory. See the Administrator Guide for more details about the contents of these container files.

The keytst command-line utility works with the Microsoft CryptoAPI in conjunction with either the Microsoft or the nCipher CSPs, whereas most utilities (including csputils, cspmigrate, and cspcheck) work directly with the nCipher APIs.

Usage

The following options are available for the keytst utility:

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

[-d|--delete=containername]] [-p|--public] [-M|--mscsp] [-m|--machine] [-S|--schannel]

[-D|--dsa] [-V|--verify] [-x|--exchange] [-s|--signature] [-e|--export]

[-L|--length=bitlen] [-C|--counter] [-K|--kitb]

Operational options

-l, --list

These options list available container names. The default container must be present. If necessary, use the --create option without a container name to create the default container.

Page 226: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 226

7 nShield Operator Utilities keytst

-c, --create=containername

These options either create a container named containername or create one or both keys for this container

-d, --delete=containername

These options delete the container named containername.

-p, --public

These options shows public key material and counters (if they exist) for either or both keys.

CSP choice options

-M, --mscsp

These options use the Microsoft CSP instead of the nCipher CSP

-m, --machine

These options specify the use of a machine container instead of a user container. You must have administrative privileges to list machine keys.

-s, --schannel

These options specify the use of the SChannel provider instead of the normal provider.

-D, --dsa

These options specify the use of the DSA provider instead of the default RSA provider.

-V, --verify

These options specify the use of a CRYPT_VERIFYCONTEXT context

Page 227: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 227

7 nShield Operator Utilities keytst

Key creation options

-x, --exchange

These options can be set in combination with the --create or --public options to create or show the key-exchange key.

-s, --signature

These options specify the use of a machine container instead of a user container. You must have administrative privileges to list machine keys.

-s, --schannel

These options specify the use of the SChannel provider instead of the RSA provider.

-e, --export

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

-L, --length=bitlen

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

-C, --counter

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

Page 228: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 228

7 nShield Operator Utilities keytst

-K, --kitb

This option can be set in combination with the --create to create NVRAM protected keys, if these are supported. You must have the use of a quorum of the Administrator Card Set in order to use this option.

Output

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

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

This produces output similar to the following:

Available key containers:

oldtest-machine

bd2769c6-403f-4232-86e6-7fe47dcec690

CSP test

csrv-test

old-machine

container_nameAdministrator

To generate an exchange key and signature key in the container Administrator, issue the following command:

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

Page 229: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 229

7 nShield Operator Utilities keytst

This produces output similar to the following:

Generating key(s) for the 'Administrator' container.

New key exchange key generated OK.

New signature key generated OK.

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

Container 'Administrator':

Public half of key exchange key is:

06 02 00 00 00 A4 00 00 52 53 41 31 00 04 00 00

01 00 01 00 F3 77 04 B8 90 73 B5 3F 04 3A F3 9E

A4 72 08 55 A1 74 15 FD 7F 80 3D 0F 16 BA 22 F9

BE 30 7C E5 3C 44 B0 E9 53 53 8F 69 30 F7 E8 B3

52 F6 43 5F 5D 13 05 04 03 4C 55 17 91 FE 10 74

B3 48 72 1E 64 28 6B 62 24 04 C0 74 42 BD 67 91

44 EB 51 2D E3 B8 D5 37 DB 3C 02 AD 7C 2B F7 50

B4 0D 25 31 E0 00 AB 6C B0 1E 4E FB 65 4E 01 4E

AD FE 5E 66 84 23 19 A5 04 3C B2 95 ED 3D DE 2E

7D 60 98 B6

Public half of signature key is:

06 02 00 00 00 24 00 00 52 53 41 31 00 04 00 00

01 00 01 00 D3 D2 10 A1 C4 A8 AC 5A 29 97 D1 37

8E F6 E0 D7 FF 08 34 F1 73 1A 1A 54 4D 4B 8E 69

B4 2D 7B C7 9F F7 7B D1 D1 EE BB 9E 73 69 48 CF

04 83 BA 36 7F 70 A1 73 DA 25 47 94 D5 4B F6 F7

75 C1 50 1D 96 7D 73 70 33 D8 EE 1A 53 D5 ED 56

22 8E FF 39 B3 70 8A 98 13 02 3F EE 22 71 FC 29

F2 A8 FD 5A 48 47 5D 2D A8 88 B0 B6 99 41 F3 85

AE E0 C7 D4 9A F0 D1 66 34 A1 6C D1 E3 00 AE 37

F5 AE A6 D7

To delete a container Administrator, issue the command:

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

Page 230: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 230

7 nShield Operator Utilities keytst

This produces output similar to the following:

****************************************

* WARNING *

* You are about to delete a container! *

* This is a non-recoverable option. *

* *

****************************************

Do you wish to continue? (yes/no):

Answering yes produces the output:

Container 'Administrator' deleted

Page 231: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 231

7 nShield Operator Utilities kmfile-dump

kmfile-dump

The kmfile-dump utility displays detailed key-management information from a security world’s key-management data file. You can also display information about the status of your security world with the nfkminfo command-line utility.

Usage

kmfile-dump.exe [-b|--binary] [-p|--plain] [-v|--verbose] file [file ...]

In this command, file is the name of the file from which data is dumped. The key-management data files from which you can display data are located in the kmdata directory. They are:

Program options

-b, --binary

This entry displays all entries in binary.

-p, --plain

This option uses plain format for binary output with no offsets or ASCII.

Filename Contains data for...

module_ESN Module whose ESN is ESN

world Security world

card_HASH_NUM Card number NUMfrom card set whose hash is HASH

card_HASH Card set whose hash is HASH

key_APPNAME_IDENT Key of type APPNAME whose identifier is IDENT

Page 232: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 232

7 nShield Operator Utilities kmfile-dump

-v, --verbose

This option shows binary dumps of key blobs.

Page 233: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 233

7 nShield Operator Utilities kptest

kptest

The kptest utility tests the consistency of encryption and decryption, or signature and verification, with the RSA and DSA algorithms. It can also test key generation by regenerating the key pair used every given number of checks. kptest is not intended as a speed test.

Usage

C:\nfast\bin\kptest [-s|--sign-verify] [-e|--encrypt-decrypt] [-k|--key-

regenerate=CHECKS] [-i|--plain-size=SIZE] [-m|--module=MODULE] [-t|--stop-after=TIME] [-

c|--curve CURVE] [-n|--jobs-count=COUNT] [-S|--key-type=TYPE] [-l|--key-size=BITS] [-M|-

-mechanism=MECH] [-p|--plain-type=TYPE] [--strong] [--pairwise-check] [[[-K|--skew-

check=SKEW ]| [-T|--min-check=COUNT ]] [-C|--check-start=TIME]] [--overprint][-o|--

output=FILE] [-r|--report-interval=TIME]

Program options

-s, --sign-verify

These options test the sign/verify operation. This is the default for DSA, ECDSA and KCDSA.

-e, --encrypt-decrypt

These options test the encrypt/decrypt operation. This is the default for RSA.

-k, --key-regenerate=CHECKS

These options regenerate the key every CHECKS number of checks.

-i, --plain-size=SIZE

These options use a plain text of SIZE bytes.

Page 234: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 234

7 nShield Operator Utilities kptest

-m, --module=MODULE

These options use module number MODULE. The default is 1.

-t, --stop-after=TIME

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

-n, --jobs-count=COUNT

These options specify the maximum number of jobs to run. The default value of COUNT is infinite (that is, there is no limit to the maximum number of jobs to run).

Key options

-S, --key-type=TYPE

These options test the sign/verify operation. This is the default for DSA and KCDSA.

-l, --key-size=BITS

These options set the key size in bits. The default is 1024. This option will be ignored if the key type is ECDSA - for ECDSA keys use -c, --curve with one of the supported curves as the argument.

-c, --curve CURVE

These options specify which of the range of supported curves to use for testing with ECDSA. Supported curves are any of: NISTP192, NISTP224, NISTP256, NISTP384, NISTP521, NISTB163, NISTB233, NISTB283, NISTB409,

Page 235: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 235

7 nShield Operator Utilities kptest

NISTB571, NISTK163, NISTK233, NISTK283, NISTK409, NISTK571, ANSIB163v1, ANSIB191v1, SECP160r1.

Note The ECDSA algorithm is only available if you have enabled the Elliptic Curve feature. See the Administrator Guide for details of feature enabling.

-M, --mechanism=MECH

These options use plaintext of SIZE bytes.

-p, --plain-type=TYPE

These options use the plaintext type TYPE. Valid values are Bignum, Hash and Bytes.

--strong

For RSA, this option uses strong (ANSI X9.31) primes. For DSA, it uses the strict flag.

--pairwise-check

This option sets the PairwiseCheck flag in the key-generate option.

Automatic checking options

-K, --skew-check=SKEW

These options perform skew checking, after either 15 seconds or the time specified by --check-start. floodtest records the overall average number of modular exponentiations each second as average. Subsequently, when floodtest writes an output line, it quits with an error message if the average is outside the range average ±SKEW.

Note The --min-check and --skew-check options are mutually exclusive.

Page 236: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 236

7 nShield Operator Utilities kptest

-T, --min-check=COUNT

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

-C, --check-start=TIME

These options specify the time in seconds at which threshold or skew checking starts. The default value of TIME is 15.

Output options

--overprint

This option prints results all on one line, using \r rather than \n.

-o, --output=FILE

These options specify that results be written to FILE in addition to stdout.

-r, --report-interval=TIME

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

Page 237: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 237

7 nShield Operator Utilities kptest

Output

kptest displays a message similar to this:

Using default RSA key type

Using default keysize=1024

Using default Bytes plaintext type

Using default plaintext size=160

Using default RSApPKCS1 mechanism

Making 1024-bit RSAPrivate key on module #2

1 : 40

2 : 97

3 : 155

...

Subsequent lines show the time the test has been running and the total number of operations performed.

Page 238: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 238

7 nShield Operator Utilities mkaclx

mkaclx

The mkaclx utility generates a key with specified attributes on a one-off basis. It is useful for testing.

Usage

mkaclx [-m|--module=MODULE]

[-t|--type=KEYTYPE] [-b|--bits=BITS][-g|--group-size=BITS] [-k|--keygen-cert] [-K|--no-

keygen-cert] [-O|--deny-oppermissions=OPPERMS] [-C|--cardset-protected]

[-M|--module-protected] [-r|--recovery] [-R|--no-recovery] [-i|--kitb] [-a|--see-app-

key=IDENT[:MECH]]

[-N|--name=NAME] [-S|--softcard-protected=NAME] [-T|--timeout=SECS] [-U|--use-

limit=N] [-q|--quiet] [-v|--verbose] [-n|--name=NAME]

[--confirm]

Module selection options

-m, --module=MODULE

These options specify the module to generate the key. The default is the first available module.

Key generation parameters

-t, --type=KEYTYPE

These options specify the type of the generated key. The default is RSA.

Page 239: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 239

7 nShield Operator Utilities mkaclx

-b, --bits=BITS

These options specify the length in bits of the key to generate. The default for each key type is as follows:

-g, --group-size=BITS

These options specify the group size for Diffie-Hellman keys in bits. The default depends on the key type.

-k, --keygen-cert

These options specify that a key-generation certificate is stored. This is the default.

-K, --no-keygen-cert

These options specify that no key-generation certificate is stored.

-O, --deny-oppermissions=OPFLAGS

These options specify that the OpPermissions specified in OPFLAGS are disabled. OPFLAGS must be a comma separated list of OpPermissions.

Key type Default

RSA, DH, DSA 1024 bits

DES, DES3, Skipjack Key size fixed by algorithm

HMAC-MD5, HMAC-MD2, RC2, RC4, RC5, CAST128 128 bits

HMAC-SHA1, HMAC-RIPEMD160 160 bits

HMAC-SHA256, Serpent, Rijndael, Twofish, CAST256, Blowfish

256 bits

HMAC-SHA384 384 bits

HMAC-SHA512 512 bits

HMAC-Tiger 192 bits

Page 240: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 240

7 nShield Operator Utilities mkaclx

Key protection options

-C, --cardset-protected

These options specify that a card-set protected key is generated.

-M, --module-protected

These options specify that a module protected key is generated. This is the default.

-S, --softcard-protected=NAME

The options generate a softcard-protected module key using the softcard named NAME.

-r, --recovery

These options specify that the generated key is recoverable. This is the default.

-R, --no-recovery

These options specify that the generated key is not recoverable.

-i, --kitb

Write the encrypted data to the module’s NVRAM.

-a, --see-app-key=IDENT[:MECH]

These options specify that use of the generated key is restricted to SEE signed by the SEE integrity key IDENT, optionally with the mechanism MECH.

-T, --timeout=TIME

These options specify the time limit for main-use operations. Use the suffix s to specify seconds, m for minutes, h for hours, and d for days.

Page 241: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 241

7 nShield Operator Utilities mkaclx

-U, --use-limit=N

These options specify the per-authorization limit for main-use operations.

Other options

-q, --quiet

These options produce fewer messages on successful runs.

-v, --verbose

These options produce more messages on successful runs.

-N, --name=NAME

These options specify the name of the key. The default is that the key has no name.

--confirm

This option shows the command and requests confirmation.

Page 242: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 242

7 nShield Operator Utilities modstate

modstate

The modstate utility displays the signed module state.

Usage

C:\nfast\bin\modstate [-m|--module MODULE] [--kml|--klf]

Module options

-m, --module=MODULE

These options specify the module number.The default is 1.

--kml

This option specifies SignerType_KML. This is the default.

--klf

This option specifies SignerType_KLF.

Page 243: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 243

7 nShield Operator Utilities ncdate

ncdate

The ncdate example utility views, sets and adjusts the real-time clock in a module.

Usage

C:\nfast\bin\ncdate [-d|--display] [-m|--module=MODULE]

C:\nfast\bin\ncdate -a|--adjust [-m|--module=MODULE] hh:mm:ss [yyyy:mm:dd]

C:\nfast\bin\ncdate -s|--set [-m|--module=MODULE] hh:mm:ss [yyyy:mm:dd]

Action selection options

-d, --display

These options display the current module time.

-m, --module=MODULE

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

--set

This option sets the module time to the time specified

--adjust

This option adjusts the module time to the time specified.

To show the current time and date on module 1:

C:\nfast\bin\ncdate

Page 244: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 244

7 nShield Operator Utilities ncdate

To set the time and optionally the date on the module MODULE to the given time and date:

C:\nfast\bin\ncdate --module=MODULE --set hh:mm:ss [yyyy:mm:dd]

To update the time and optionally the date on the module MODULE to the given time and date:

C:\nfast\bin\ncdate --module=MODULE --adjust hh:mm:ss [yyyy:mm:dd]

Using the --adjust option makes the module compute the drift rate of the internal clock based on the interval between the present time and the time when the clock was last set or adjusted. The module remembers this rate and uses it to correct future readings. It is therefore important that the time is obtained from the same source as it was previously.

Note The --set and --adjust options do not work on a module that is included in a security world. Use the rtc utility for modules in a security world.

Note The rechargeable back-up battery in some nShield modules (used to maintain RTC operation when the module is unpowered) can last as long as two weeks without recharging. If the module is without power for longer than this, the battery is discharged and RTC time is lost; no other nonvolatile data is lost if this occurs. In such a case, however, attempts to read the clock (such as with ncdate) return a BadTokenData error status. You can resolve this by resetting the clock and leave the module powered up for at least 10 hours to recharge the battery to recharge.

Page 245: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 245

7 nShield Operator Utilities ncthread-test

ncthread-test

The ncthread-test utility stress tests modules and tests nCore API concurrent connection support.

Usage

C:\nfast\bin\ncthread-test [-d|--des-threads=THREADS] [-r|--rsa-threads=THREADS] [-s|--

check-every=PERIOD] [-c|--block-size=SIZE] [-b|--rsa-size=SIZE] [-q|--quiet]

Module options

-d, --des-threads=THREADS

These options create THREADS DES3 threads for symmetric encryption. The default is 4.

-r, --rsa-threads=THREADS

These options create THREADS RSA threads for digital signing. The default is 4.

-s, --check-every=PERIOD

These options check threads every PERIOD seconds. The default is 10.

Other options

-c, --block-size=SIZE

These options encrypt blocks of up to SIZE characters long. The default is 16384.

Page 246: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 246

7 nShield Operator Utilities ncthread-test

-b, --rsa-size=SIZE

These options use RSA key of size SIZE bits. The default is 1024.

-q, --quiet

These options run quietly, outputting only errors and warnings.

Note If any threads have not returned a value since the last thread check, a warning is generated. However, this may simply indicate that the interval between checks is too short. If a thread persistently fails to return a value, this indicates that an error has occurred.

Page 247: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 247

7 nShield Operator Utilities ncversions

ncversions

The ncversions utility displays installed nCipher support software components and their versions. The utility lists all components, whether installed individually or as part of a component bundle, and also the component bundles themselves.

Usage

C:\nfast\bin\ncversions.exe

Output

The following in an example of a component list produced by ncversions:

Comp Output Version Repository/Build no.

----------------------------------------------------------------

convrt user 1.1.0 cam/1

csee armdev 0.10.5 cam/3

csee seedev 0.10.5 cam/3

ctd agg 0.0.12 cam/4

ctls agg 0.0.13 cam/3

cutils devel 1.4.2 cam/8

emvjni user 0.2.2 cam/36

emvspj user 0.2.6 cam/20

emvspj devel 0.2.6 cam/20

emvspp user 1.5.10 cam/14

emvspp devel 1.5.10 cam/14

gcchk user 1.1.1 cam/2

... ... ... ...

... ... ... ...

ncversions displays a line of information for each component:

Page 248: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 248

7 nShield Operator Utilities ncversions

Comp

This gives the component's identifying code

Output

This identifies the type of component, such as:

• user for a user component

• devel for a developer component

• agg for a component bundle

Version

This identifies the version of the component

Repository/Build no.

This identifies the repository and build number.

Page 249: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 249

7 nShield Operator Utilities nfkminfo

nfkminfo

The nfkminfo utility displays information about the security world and the keys and card sets associated with it.

Usage

C:\nfast\bin\nfkminfo --cardset-list

[TOKENHASH] -key-list

[APPNAME[APPNAME]] |

-name-list

[APPNAME[IDENT...]]

Options

-c, --cardset-list [TOKENHASH]

If TOKENHASH is not specified, these options list the card sets associated with the security world.

The output is similar to this:

Cardset summary - 1 cardsets:

(in timeout, P=persistent, N=not) Operator logical token hash k/n

timeout name

hash 1/1 none-N

name

If TOKENHASH is specified, these options list the details of the card identified by hash.

Page 250: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 250

7 nShield Operator Utilities nfkminfo

The output is similar to this:

name

"name" k-out-of-n 1/1 flags NotPersistent timeout

none card names "" hkltu

794ada39038fa8c4e9ea46a24136bbb2b8b337f2

-k, --key-list [APPNAME[APPNAME]]

These options list keys without key names. If APPNAME is specified, only keys for these applications are listed.

-l, --name--list [APPNAME[IDENT]]

These options list keys with their names. If APPNAME is specified, only keys for these applications are listed. If IDENT is listed, only the keys with the specified identifier are listed.

Page 251: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 251

7 nShield Operator Utilities nfkmverify

nfkmverify

The nfkmverify utility verifies key generation certificates, and so allows you to confirm how a particular security world and key are protected. It also returns some information about the security world and key.

nfkmverify only works for:

• keys that were generated by generatekey or nfkmcmdadp from nftcl component version 1.81.0 or later

• security worlds generated by new-world from sworld component version 1.4.0 or later later, and keys generated by application programs and libraries that use the certificate storage features available from sworld component version 1.4.0 or later

• keys and security worlds generated on modules using firmware version 1.67.15 or later.

nfkmverify compares the details in the ACL of the key and those of the card set that currently protects the key.

A key that has been recovered to a different card set shows a discrepancy for every respect that the new cardset differs from the old one. For example, a key recovered from a 2-of-1 card set to a 1-of-1 card set has a different card-set hash and a different number of cards, so two discrepancies are reported. The discrepancy is between the cardset mentioned in the ACL of the key, and the cardset that the key is currently protected by (that is, the one mentioned in the key blobs).

A key that has been transferred from another security world will show discrepancies and fail to be verified. nCipher recommend that keys are verified in the original security world at the time of generation.

If you need to replace your security world or card set, nCipher recommend that new keys are generated where possible. If you need to transfer a key, verification should be performed immediately prior to transfer as verification after the change of protection to a new security world, or card set, is troublesome.

Page 252: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 252

7 nShield Operator Utilities nfkmverify

Usage

nfkmverify.exe [-f|--force] [-v|--verbose] [-U|--unverifiable] [-m|--module=MODULE]

[appname] [ident]

Help options

-h, --help

These options display help for nfkmverify.exe.

-V, --version

These options display the version number for nfkmverify.exe.

-u, --usage

These options display a brief usage summary for nfkmverify.exe.

Program options

-m, --module=MODULE

These options perform checks with module MODULE.

-f, --force

These options forces display of an output report that might be wrong.

-U, --unverifiable

These options proceed even if the security world is unverifiable.

Note If you need the --unverifiable option, there may be some serious problems with your security world.

Page 253: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 253

7 nShield Operator Utilities nfkmverify

-v, --verbose

These options proceed even if the security world is unverifiable.

-C, --certificate

These options check the original ACL for the key using the key generation certificate. This is the default.

-L, --loaded

These options check the ACL of a loaded key instead of the generation certificate.

-R, --recov

These options check the ACL of the key loaded from the recovery blob.

--allow-dh-unknown-sg-group

This option allows an operation to proceed even if a Diffie-Hellman key is using an unrecognized Sophie-Germain group.

Output

Returns from nfkmverify can take a variety of forms, depending on the parameters of the given key generation certificate, security world, and key concerned. Examples of possible output resulting from several different situations are provided below.

Under normal circumstances, issuing a command of the form:

nfkmverify --verbose --unverifiable myapp o20010621a13h25m02

Page 254: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 254

7 nShield Operator Utilities nfkmverify

returns output of the form:

** [Security world] **

1 Administrator Cards

(Currently in Module #1 Slot #0: Card #1)

Cardset recovery ENABLED

Passphrase recovery disabled

Strict FIPS 140-2 level 3 (does not improve security) disabled

SEE application nonvolatile storage disabled

real time clock setting disabled

SEE debugging disabled

Generating module ESN 0A42-E645-7A75 currently #1 (in same incarnation)

** [Application key myapp o20010621a13h25m02] **

[Named 'test Thu, 21 Jun 2001 13:25:02 +0100']

Useable by HOST applications.

Recovery ENABLED.

MODULE-ONLY protection

Type RSAPrivate 1024 bits keygenparams.type= RSAPrivate 2

.params.rsaprivate.flags= none 0x00000000

.lenbits= 0x00000400 1024

.given_e absent

.nchecks absent

Generating module ESN 0A42-E645-7A75 currently #1 (in same incarnation)

nCore hash 23a901f3329aa9e29cd79d3bb7b32d549b725fc3

public_half.type= RSAPublic 1

.data.rsapublic.e= 4 bytes

00010001

.n= 128 bytes

8a6ab219 183de558 48c8379e 840895ff 0ba64bae 392848c6 c0aeb7f9 d10b046d

4a214b70 4878b518 8e599c69 1cd61db0 bab4f852 425c70f5 b9c000e5 4ceda15f

c062b5dd 01852380 f70275a1 870a6947 68ef59f0 db5d2e84 d6ae8dc1 7542e94d

adedece8 cb3c9fb6 98fab8af 52c94137 a76ab7dd 38648134 0df55ca8 2f45e8b7

Verification successful, check details above.

Output of the form shown above indicates successful verification of the relevant key generation certificate.

Page 255: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 255

7 nShield Operator Utilities nfkmverify

The following examples indicate forms of output that could be returned if you try to verify the generation certificate of a key generated in a security world that was created with an insufficiently up-to-date version of nCipher software.

In such a case, issuing a command of the form:

nfkmverify --verbose myapp spong

returns output of the form:

PROBLEM: no world generation certificates

PROBLEM: application key myapp spong: no key generation signature

2 issues found, NOT VERIFIED

Adding the --unverifiable tag to the same command:

nfkmverify --verbose --unverifiable myapp spong

returns output of the form:

PROBLEM: application key myapp spong: no key generation signature

1 issues found, NOT VERIFIED

Then, also adding the --force tag to this same command:

nfkmverify --force --verbose --unverifiable myapp spong

Page 256: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 256

7 nShield Operator Utilities nfkmverify

returns output of the form:

PROBLEM: application key myapp spong: no key generation signature

PROBLEMS BUT FORCING POSSIBLY-WRONG OUTPUT

** [Security world] **

UNVERIFIED SECURITY WORLD !

proceeding anyway as requested

** [Application key myapp spong] **

[Not named]

Useable by HOST applications.

Recovery ENABLED.

MODULE-ONLY protection

1 issues found, NOT VERIFIED

Page 257: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 257

7 nShield Operator Utilities nopclearfail

nopclearfail

The nopclearfail utility clears a module, puts a module into the error state, or retries a failed module.

Note In order to recover a module from the error state, you must turn the power to the module off and then on. For internal modules, this may mean shutting down and then rebooting your computer.

Retrying a module causes the nCipher server to attempt reconnecting to a module to which the connection has previously failed. Retrying a module may cure some bus errors. You cannot attempt to reconnect to a module if it is in the error state.

Usage

C:\nfast\bin\nopclearfail.exe [[-n|--no-op]|[ -c|--clear]|[-f|--fail]|[-r|--retry]]

[[-a|--all]| [-m|--module=MODULE]]

Action selection options

-n, --no-op

These options send the NoOp command

-c, --clear

These options send the ClearUnit command. To use this option, you must be logged in as a user who is permitted to create privileged connections.

-f, --fail

These options send the Fail command. To use this option, you must be logged in as a user who is permitted to create privileged connections.

Page 258: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 258

7 nShield Operator Utilities nopclearfail

-r, --retry

These options send the RetryFailedModule command. To use this option, you must be logged in as a user who is permitted to create privileged connections.

Module selection options

-a, --all

These options send the command to all modules

-m, --module=MODULE

These options send the command to module MODULE.

Output

If you select the --no-op, --retry, or --clear option, nopclearfail returns the following for each selected module:

Module 1, command NoOp: OK

If you select the --fail option and logged in as a user who is permitted to create privileged connections, the Fail command causes the module to enter the error state. The status LED will flash SOS D (... --- ... -..) . In order to reset the module, you must turn the power to the module off and then on again. If you are not logged in as a user who is permitted to create privileged connections and you select the --fail option, the Fail command will fail and the module will itself continue as normal.

Note When your machine is connected to a remote slot, if you clear all the modules using nopclearfail --clear --all, the remote slot temporarily becomes unavailable. The slot is unavailable for about 5 minutes, after which it becomes available again automatically. There may be a

Page 259: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 259

7 nShield Operator Utilities nopclearfail

short delay before a message informs you of this. However, when the problem occurs the following message may appear after you run slotinfo:

bash-2.04$ slotinfo.exe 1 Module 1:

Slot Type Token IC Flags Details

#0 Smartcard - 0 A

#1 Software Tkn - 0

#2 Unconnected - 0 R RemoteServerFailed, <us >

(CrossModule,#1-ServerUnitReset,#2-ExplicitRequest,#3-ExplicitRequest)

Page 260: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 260

7 nShield Operator Utilities nvram-backup

nvram-backup

The nvram-backup utility copies files between a module’s nonvolatile memory and a smart card. It can be used to back up and restore files that are stored in NVRAM. Files you can back up and restore are data files stored in NVRAM by an SEE program and NVRAM-stored keys. See Generating NVRAM-stored keys on page 92 for more details.

Do not store keys in NVRAM unless you must do so to satisfy regulatory requirements.

Note nCipher introduced NVRAM key storage only for users who must store keys within the physical boundary of a module to comply with regulatory requirements. NVRAM-stored keys provide no additional security benefits and their use exposes your Administrator Card Set to increased risk. Storing keys in nonvolatile memory also reduces load-balancing and recovery capabilities. Because of these factors, nCipher recommends you always use standard security world keys unless explicitly required to use NVRAM-stored keys.

To use nvram-backup you specify an action and, optionally, the location of the files to be acted on. Available actions are list, copy and delete. You can list the contents of, and delete files from, a module’s NVRAM, and copy files from NVRAM to a smart card. You can list files on a smart card and copy from a card to a module’s NVRAM. You cannot use nvram-backup to delete files from a smart card.

Note Use the bulkerase utility to format cards for use with nvram-backup.

If you are using a FIPS 140-2 level 3 compliant security world, you will be prompted for an Administrator Card or Operator Card from the security world to authorize copying of files to or from NVRAM and deletion of files from the module’s NVRAM.

When you copy files to a module’s NVRAM or delete files from NVRAM, you are required to insert a quorum of Administrator Cards for NVRAM authentication.

Page 261: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 261

7 nShield Operator Utilities nvram-backup

Usage

C:\nfast\bin\nvram-backup.exe -l|--list -M|--from-module|-S|--from-smartcard [-m|--

module=MODULE] [-s|--slot=SLOT] [-f|--force] [-v|--verbose] [-x|--hex] [FILES]

C:\nfast\bin\nvram-backup.exe -c|--copy -M|--from-module|-S|--from-smartcard [-m|--

module=MODULE] [-s|--slot=SLOT] [-f|--force] [-v|--verbose] [-x|--hex] [FILES]

C:\nfast\bin\nvram-backup.exe -d|--delete -M|--from-module [-m|--module=MODULE] [-s|--

slot=SLOT] [-f|--force] [-v|--verbose] [-x|--hex] [FILES]]

Help options

-h, --help

These options display help for nvram-backup.exe.

-V, --version

These options display the version number for nvram-backup.exe.

-u, --usage

These options display a brief usage summary for nvram-backup.exe.

Action selection options

-l, --list

These options list files either on a module’s NVRAM or on a smart card. By default nvram-backuplists the contents of the module’s NVRAM.

Page 262: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 262

7 nShield Operator Utilities nvram-backup

-c, --copy

These options copy files between a module’s NVRAM and a smart card.

You cannot copy from a module’s NVRAM to a smart card those files whose ACL prohibits copying. Copying is prevented by use of the --no-copy option in the nvram-sw utility described in nvram-sw on page 266.

-d, --delete

These options delete files from a module’s NVRAM. You cannot use nvram-backup to delete files from a smart card. If you attempt to use nvram-backup to delete files from a smart card, a message displays and nvram-backup terminates..

Transfer direction options

-M, --from-module

These options read files from a module’s NVRAM for copying to a smart card or for listing, or deletes files from the module’s NVRAM.

-S, --from-smartcard

These options reads files from a smart card for copying to a module’s NVRAM or for listing.

Module selection options

-m, --module=MODULE

These options specify the module for nvram-backup to use. The default is 1.

Page 263: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 263

7 nShield Operator Utilities nvram-backup

-s, --slot=SLOT

These options identify the slot on the selected module for the specified nvram-backup action. The default is 0. You do not need to specify a slot when listing the contents of, or deleting files from, a module’s NVRAM.

File selection option

FILES

This specifies the files for nvram-backup to copy, list or delete. If you do not specify a file, nvram-backup performs the action on all available files. Wildcards are permitted in the file selection option, for example b* to select all NVRAM-stored keys. For information on identifying file types by their FileIDs, see nvram-sw on page 266.

General options

-f, --force

These options force nvram-backup to delete or overwrite a file without requesting confirmation.

-v, --verbose

These options provide verbose output.

-x, --hex

These options specify that hex notation is used for the file selection option.

--no-length

When used with the --list option, the --no-length option specifies that file lengths are not printed.

Page 264: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 264

7 nShield Operator Utilities nvram-backup

Output

To list the contents of the default module’s NVRAM, use the command:

C:\nfast\bin\nvram-backup.exe --list

nvram-backup displays file information in the following format:

File ID (hex) File ID (ASCII) File Length

------------- --------------- -----------

725178c71ba5cf959318fc

625178c71ba5cf959318fc

72d2fb7c9d0c58f6424855

62d2fb7c9d0c58f6424855

In this example, four files are stored in the module’s NVRAM, two NVRAM-stored keys and their associated recovery information. For information on identifying file types by their File IDs, see nvram-sw on page 266.

To obtain a listing of the contents of a module’s NVRAM with further information, including file size, use the nvram-sw utility.

To back up NVRAM-stored keys from the default module to a smart card, use the command:

C:\nfast\bin\nvram-backup.exe --copy --from-module b*

If you have a FIPS 140-2 level 3 compliant security world, you must provide authorization to back up files stored on NVRAM. nvram-backup prompts you to insert a smart card from this security world for authorization.

Page 265: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 265

7 nShield Operator Utilities nvram-backup

1. If prompted, insert a smart card from the current security world.

When nvram-backup has obtained authorization, it prompts you to insert a card into the module and slot you specified for nvram-backup actions.

2. Insert the smart card to use and press .

nvram-backup copies the specified file(s) and terminates.

You can check the success of the command by listing the contents of the smart card. Use the command:

C:\nfast\bin\nvram-backup.exe --list --from-smartcard

To delete NVRAM-stored keys from the default module, use the command:

C:\nfast\bin\nvram-backup.exe --delete *b

If you have a FIPS 140-2 level 3 compliant security world, you must provide authorization to delete files from the module’s NVRAM. nvram-backup prompts you to insert a smart card from this security world for authorization.

1. If prompted, insert a smart card from the current security world.

Deleting files from a module’s NVRAM requires authentication and you are prompted to insert Administrator Cards for NVRAM authentication.

2. Insert the required number of cards, each one in turn, into the authentication slot.

When authentication is complete, for each file that matches the specified criteria, nvram-backup prompts for confirmation.

3. Input yes to delete a file or no to retain it in NVRAM.

When all files have been listed for confirmation, nvram-backup terminates.

Enter

Page 266: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 266

7 nShield Operator Utilities nvram-sw

nvram-sw

The nvram-sw utility views and modifies NVRAM areas.

Usage

C:\nfast\bin\nvram-sw.exe -a|--alloc [-m|--module=MODULE] [-b|--bytes=BYTES] [-n|--

nvram-id=ID] [-k|--key=APPNAME,IDENT][--no-copy]

C:\nfast\bin\nvram-sw.exe -d|--delete [-m|--module=MODULE] [-n|--nvram-id=ID]

C:\nfast\bin\nvram-sw.exe -w|--write [-m|--module=MODULE] [-f|--file=FILE]

C:\nfast\bin\nvram-sw.exe -r|--read [-m|--module=MODULE] [-f|--file=FILE]

C:\nfast\bin\nvram-sw.exe -c|--delete-noadmin [-m|--module=MODULE] [-n|--nvram-id=ID]

C:\nfast\bin\nvram-sw.exe -i|--acl [-m|--module=MODULE] [-n|--nvram-id=ID]

C:\nfast\bin\nvram-sw.exe -l|--list [-m|--module=MODULE]

C:\nfast\bin\nvram-sw.exe -a|--alloc [-m|--module=MODULE] [-b|--bytes=BYTES] [-n|--

nvram-id=ID] [-k|--key=APPNAME,IDENT][--no-copy]

Help options

-h, --help

These options display help for nvram-sw.exe.

Page 267: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 267

7 nShield Operator Utilities nvram-sw

-V, --version

These options display the version number for nvram-sw.exe.

-u, --usage

These options display a brief usage summary for nvram-sw.exe.

Action selection options

-a, --alloc

These options allocate a new NVRAM area on the module specified in MODULE. An Administrator Card Set must be inserted to perform this action.

-d, --delete

These options delete the NVRAM area on the module specified in MODULE. An Administrator Card Set must be inserted to perform this action.

-w, --write

These options write data to the NVRAM area on the module specified in MODULE. The data is written from the file specified in FILE, if present. Otherwise, it is written from stin. If the ACL of the NVRAM area requires it, an Operator Card Set must be inserted to perform this action. This action may not be permitted by the ACL of the NVRAM area.

-r, --read

These options read data from the NVRAM area on the module specified in MODULE. The data is written to the file specified in FILE, if present. Otherwise it is written to stdout. If the ACL of the NVRAM area requires it, an Operator Card Set must be inserted to perform this action. This action may not be permitted by the ACL of the NVRAM area.

Page 268: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 268

7 nShield Operator Utilities nvram-sw

-c, --delete-noadmin

These options delete the NVRAM area on the module specified in MODULE when no Administrator Card Set is required. If the ACL of the NVRAM area requires it, an Operator Card Set must be inserted to perform this action.

-i, --acl

These options display the ACL of the NVRAM area on the module specified in MODULE. If the ACL of the NVRAM area requires it, an Operator Card Set must be inserted to perform this action.

-l, --list

These options list the entire contents of the NVRAM.

General options

-m, --module=MODULE

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

-v, --verbose

These option provides verbose output.

-x, --hex

These option specify that hex notation is used for the ID value supplied to the --nvram-id option.

Action specific options

-b, --bytes=BYTES

These option specify the number of bytes to allocate for --alloc or to read for --read. The default is 100.

Page 269: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 269

7 nShield Operator Utilities nvram-sw

-n, --nvram-id=ID

These option specify the identifier of the NVRAM file for all actions except --list. The default is test-file

-f, --file=FILE

These option specify the file to be read or written for the --read and --write options. If this option is not specified for these actions, stdin or stdout is used by default.

-k, --key=APPNAME, IDENT

These option specify a key during the --alloc action. This key is required for all subsequent --read or --write actions on the NVRAM area.

--no-copy

This option used with the --alloc option allocates a file with an ACL that does not allow copying.

Identifying files

Files created by nCipher security world tools often have a FileID that consists of a character identifying the type followed by a M_ShortHash. You can use this information to identify the type of files stored in NVRAM and for specifying types of files for use with an nCipher security world utility.

Page 270: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 270

7 nShield Operator Utilities nvram-sw

nCipher uses following identifying characters:

nCipher may define further file types in future, but the first byte is always in the range 0-127 (top bit clear). nCipher recommends that third party developers use FileIDs with a first byte in the range 128-255 (top bit set).

nCipher also uses the following specific FileIDs:

File type Description

0x1 Counter for a MSCAPI key-exchange key NVRAM-counted use limit. The hash is of the MSCAPI container.

0x2 Counter for a MSCAPI signature key NVRAM-counted use limit. The hash is of the MSCAPI container.

0x53 (S) Old PKCS #11 token identifier. If you have such tokens present, contact Support at nCipher.

0x62 (b) Working blob for a NVRAM-stored key.

0x72 (r) Recovery blob for a NVRAM-stored key.

0x74 (t) Logical token identifier. The hash of a logical token stored in a share on this smart card. The contents include the remaining 10 bytes of the full hash and other information about the token.

0x80 (z) Old PKCS #11 token identifier. If you have such tokens present, contact Support at nCipher.

Page 271: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 271

7 nShield Operator Utilities nvram-sw

FileID (hex) FileID (ascii) Description

5761726e 74496448 6c7475 WarntIdHltu Smart card file created by the nCipher Warranting server. Contains the hash of LTID.

5761726e 74496442 6c6f62 WarntIdBlob Smart card file created by the nCipher Warranting server. Contains a blob of KID under LTID.

74657374 2d66696c 650000 test-file NVRAM file. This is the default FileID for nvram-sw.

Page 272: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 272

7 nShield Operator Utilities pollbare

pollbare

Note This utility is deisgned as a test utility only, although it can also be used by nCipher support to obtain more information about your system. Unless you are a developer you are unlikely to need to understand it in detail; developers can find more complete information in the nCipher Developer Reference.

The pollbare example utility returns information about state changes. Its functionality depends on whether the server or any module supports nCore API poll commands. You can discover whether this is the case by using the enquiry utility, described in enquiry on page 185.

Usage

C:\nfast\bin\pollbare.exe [-q|--quiet] [-t|--time=TIME] [-m|--module=MODULE]

-q. --quiet

These options specify that pollbare run only once.

-t. --time=TIME

These options specify an update every TIME number of seconds. If you do not specify a value, the default is 1.

-m. --module=MODULE

These options specify that pollbare be applied only to a given module MODULE. If you do not specify a module, the default is all modules.

Page 273: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 273

7 nShield Operator Utilities postrocs

postrocs

The postrocs utility performs clean-up tasks after key-xfer-im has been used to transfer keys that protect PKCS #11 objects.

Usage

C:\nfast\bin\postrocs [-m|--module=MODULE] [-s|--slot=SLOT]

Help options

-h, --help

These options display help for postrocs.exe.

-V, --version

These options display the version number for postrocs.exe.

-u, --usage

These options display a brief usage summary for postrocs.exe.

Options

-m, --module=MODULE

These options specify the target module for the key transfer. The default is 1.

-s, --slot=SLOT

These options specify the target slot for the key transfer. The default is 0.

Page 274: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 274

7 nShield Operator Utilities ppmk

ppmk

This utility allows you to manage softcards. It can be used to perform the following tasks:

• listing softcards

• creating a new softcard

• checking or changing a softcard’s pass phrase

• recovering a softcard’s pass phrase

• deleting a softcard.

Usage

C:\nfast\bin\ppmk.exe --new [-r|-R] NAME

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

C:\nfast\bin\ppmk.exe -icCpr|--delete [PRELOAD-OPTIONS] NAME|IDENT

NAME

This option specifies the name of a new or existing softcard.

IDENT

This option specifies the identifier of an existing softcard

-n, --new

These options create a new softcard. When creating a new softcard with these options, the -r/--recover options make the pass phrase of the new softcard recoverable, while the -R/--non-recoverable options make it unrecoverable.

-l, --list

These options list all softcards in the current security world.

Page 275: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 275

7 nShield Operator Utilities ppmk

-i, --info NAME|IDENT

These options show the details of the softcard specified by NAME or IDENT.

-c, --check NAME|IDENT

These options check the pass phrase of the softcard specified by NAME or IDENT.

-C, --change NAME|IDENT

These options change the pass phrase of the softcard specified by NAME or IDENT.

-p, --preload [PRELOAD-OPTIONS]

This option preloads a softcard. PRELOAD-OPTIONS are as follows:

• -m, --module=MODULE preloads a softcard on the specified module number. The default value for MODULE is all.

• -f, --preload-file=FILE specifies the location of an alternative loaded objects file.

-r, --recover

These options allow you to recover the pass phrase of a softcard (if it was created with a recoverable pass phrase).

--recoverable

This options specifies that the pass phrase of a new softcard is to be recoverable; this is the default, so it is not normally necessary to specify this option in order to create a softcard with a recoverable pass phrase. The pass phrase recovery key Krp be loaded in order to create a softcard with a recoverable pass phrase.

Page 276: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 276

7 nShield Operator Utilities ppmk

-R, --non-recoverable

These options specify that the pass phrase of a new softcard is to be non-recoverable.

--delete NAME|IDENT

This option deletes the softcard specified by NAME or IDENT.

Page 277: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 277

7 nShield Operator Utilities preload

preload

The preload command-line utility enables keys to be loaded onto a module before an application is run. The application can be run immediately in the same session or the first session can be paused and the application can be run in a separate session. Additional keys can be loaded while a session is running.

For applications that do not support K-of-N Operator Card Sets, preload enables K-of-N Operator Card Sets and module-protected keys to be loaded before the application is run. You can use the preload command to preload K-of-N Operator Card Sets before running PKCS #11 applications.

Some command-line options may cause preload to function interactively by prompting for Operator Cards.

Note Currently, preload can be used only with command-line utilities.

Usage

C:\nfast\bin\preload.exe [-m MODULE|--module=MODULE] [-c IDENT|--cardset=IDENT] [--

cardset-name=NAME] [-s IDENT|--softcard=IDENT] [-o|--any-one] [-i|--interactive] [-A

APP|--appname=APP] [-K PATTERN|--key-ident=PATTERN] [-n PATTERN| --name-pattern=PATTERN]

[--name-exact=NAME] [-M|--module-prot] [--no-cardset-keys] [--admin=NAME] [-F|--require-

fips] [-N|--no-fips] [-f PRELOADFILE|--preload-file=PRELOADFILE] [-R|--reload-

everything] | pause | exit

Module selection options

-m MODULE, --module=MODULE

These options select the module (where MODULE is a module number) onto which keys are to be loaded. Repeating the option with different values for MODULE enables a number of selected modules to be used. By default, preload loads keys on all usable modules.

Page 278: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 278

7 nShield Operator Utilities preload

Card set selection options

Note The current release of the preload command-line utility cannot load softcards; use the ppmk command-line utility to load softcards (see ppmk on page 274). However, the preload command can load softcard-protected keys; see Key selection options on page 279.

-c IDENT, --cardset=IDENT

These options specify that all Operator Card Sets that match IDENT are to be loaded. The IDENT variable can be the hash or the name of a card set; the preload command tries to guess whether IDENT is a hash or a name based on the form you supply.

If you definitely want to preload a named card set, use the --cardset-name=NAME option instead.

Use KeySafe or the nfkminfo command-line utility to identify keys and cards that are used by particular applications. See Viewing cards and softcards on page 75 for further information. Card set patterns or names are treated as substrings.

--cardset-name=NAME

This option specify an Operator Card Set with the given name NAME to be loaded.

-o, --any-one

This option loads a single Operator Card Set and then stops.

-i, --interactive

This option causes preload to load Operator Card Sets interactively until you tell it to stop.

Page 279: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 279

7 nShield Operator Utilities preload

Key selection options

Note If you specify keys and do not explicitly select Operator Card Sets with --cardset, or use --module-prot, then preload loads only the Operator Card Sets that are required by the specified keys. By default, if no key selection options are used, preload loads all keys on the loaded Operator Card Set(s) and, if --module-prot is specified, all module-protected keys.

-A APP, --appname=APP

These options specify the application to be used by a subsequent --key-ident or --name-exact options. You can set multiple instances of the --appname option to specify more than one application. Examples of APPNAME include:

• custom

• embed

• hwcrhk

• netscape

• simple

• ssleay

-K PATTERN, --key-ident=PATTERN

These options load all keys whose ident includes or matches PATTERN for the application previously specified by APP. PATTERN is treated as a substring. You can set multiple instances of these options to load keys that match more than one pattern.

-K, --key-ident=PATTERN

These options load all keys with an ident that includes or matches PATTERN for the application previously specified by APP. You can set multiple instances of the --key-ident option to load more than one key. Use KeySafe or the

Page 280: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 280

7 nShield Operator Utilities preload

nfkminfo command-line utility in order to identify keys that are used by particular applications. See Viewing cards and softcards on page 75 for further information.

-n PATTERN, --name-pattern=PATTERN

These options load all keys (for the APP specified by --appname) whose name includes or matches PATTERN. PATTERN is treated as a substring. You can set multiple instances of these options to load keys that match more than one pattern.

If you want to load a particular named key, use the --name-exact=NAME option instead.

--name-exact=NAME

This option loads the key whose name is specified by NAME for the APP specified by --appname.

-s IDENT, --softcard=IDENT

These options load all keys protected by softcards matching IDENT. The IDENT variable can be the hash or the name of a softcard; the preload command tries to guess whether IDENT is a hash or a name based on the form you supply.

Note The current release of the preload command-line utility can only load softcard-protected keys, not softcards themselves. To load softcards, use the ppmk command-line utility; see ppmk on page 274.

If you definitely want to preload a named softcard, use the --softcard-name=NAME option instead.

Use the ppmk or nfkminfo command-line utilities to identify keys and softcards that are used by particular applications. See Viewing cards and softcards on page 75 for further information. Softcard patterns or names are treated as substrings.

Page 281: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 281

7 nShield Operator Utilities preload

--softcard-name=NAME

This option loads all keys protected by softcards matching NAME.

Note The current release of the preload command-line utility can only load softcard-protected keys, not softcards themselves. To load softcards, use the ppmk command-line utility; see ppmk on page 274.

Use the ppmk or nfkminfo command-line utilities to identify keys and softcards that are used by particular applications. See Viewing cards and softcards on page 75 for further information. Softcard patterns or names are treated as substrings.

-M, --module-prot

These options load module-protected keys in addition to any keys specified by other options.

--no-cardset-keys

This option specifies that keys protected by the requested Operator Card Sets are not automatically loaded.

--admin=KEYS

This option loads the administrator keys specified by KEYS; to load more than one administrator key, the value of KEYS can be a comma-separated list, or you can. specify all to load all administrator keys. Allow administrator keys are: NSO, M, RA, P, NV, RTC, FIPS, MC, RE, DSEE, and FTO.

Note When using preload to load non-persistent tokens, you must ensure that you have enough remaining Operator Cards in order to load the token onto the final module. Usually, this means you need one or more cards than you have modules, depending on the circumstances. For example, if you have 4 modules and K is 3, then N must be at least 6 so that there are at least 3 cards remaining to load the token onto the final module.

Page 282: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 282

7 nShield Operator Utilities preload

FIPS options

-F, --require-fips

These options specify that FIPS authorization is required.

-N, --no-fips

These options specify that FIPS authorization must never be loaded. The default is to load FIPS authorization if possible but not to fail if loading FIPS authorization is not possible.

Loading options

-f PRELOADFILE, --preload-file=PRELOADFILE

These options specify a preloaded objects file to be used.

-R, --reload-everything

These options specify the reloading of keys and tokens that are already loaded.

Output examples

If you want to load keys from a number of Operator Card Sets in module 2 and use them immediately in an application, for example, with nfkminfo, give the following command:

C:\nfast\bin\preload -R -m 2 nfkminfo

If there is no card in the specified module, preload displays the following message:

Loading cardset(s):

Module 2 slot 0: empty

Module 2 slot 2: empty

Insert/change card(s) (or change module mode).

Page 283: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 283

7 nShield Operator Utilities preload

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

Loading cardset(s):

Module 2 slot 0: empty

Module 2 slot 2: empty

Module 2 slot 0: 'pt2' #1

Module 2 slot 0: Enter passphrase:

Enter the appropriate pass phrase, and preload displays:

Loading cardset(s):

Module 2 slot 0: empty

Module 2 slot 2: empty

Module 2 slot 0: 'pt2' #1

Module 2 slot 0:- passphrase supplied - reading card

Module #2 Slot #0: Remove card.

If you insert a card that has no pass phrase, preload displays:

Loading cardset(s):

Module 2 slot 0: empty

Module 2 slot 2: empty

Module 2 slot 0: 'pt2' #1

Module 2 slot 0:- passphrase supplied - reading card

Module 2 slot 0: empty

Module 2 slot 0: 'ct' #1

Module 2 slot 0: Read this card? (press Return)

Page 284: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 284

7 nShield Operator Utilities preload

Press to confirm reading this card, and preload displays:

Loading cardset(s):

Module 2 slot 0: empty

Module 2 slot 2: empty

Module 2 slot 0: 'pt2' #1

Module 2 slot 0:- passphrase supplied - reading card

Module 2 slot 0: empty

Module 2 slot 0: 'ct' #1

Module 2 slot 0:- confirmed - reading card

Module #2 Slot #0: Remove card.

Being finished, now press - , and preload displays:

Loading cardset(s):

Loaded seeconf testconf key (DES3) on modules 2

Loaded seeinteg testinteg key (RSAPrivate) on modules 2

Loaded simple cs key (DES3) on modules 2

Loaded simple test12 key (RSAPrivate) on modules 2

Loaded simple test3 key (RSAPrivate) on modules 2

Loaded simple test4 key (RSAPrivate) on modules 2

Loaded simple test5 key (RSAPrivate) on modules 2

Loaded simple test6 key (RSAPrivate) on modules 2

Loaded simple test7 key (RSAPrivate) on modules 2

Loaded simple test8 key (RSAPrivate) on modules 2

Loaded simple test9 key (RSAPrivate) on modules 2

Executing nfkminfo

To preload a specific key with an ident of mykey for the application seeconf on all modules, give the following command:

C:\nfast\bin\preload -A seeconf -K mykey pause

Enter

Ctrl D

Page 285: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 285

7 nShield Operator Utilities preload

The preload command then displays the following message:

Loading 'pt2':

Module 1 slot 0: empty

Module 2 slot 0: empty

Module 2 slot 2: empty

Insert/change card(s) (or change module mode).

Insert a card in module 1, and preload displays:

Loading `pt2':

Module 1 slot 0: empty

Module 2 slot 0: empty

Module 2 slot 2: empty

Module 1 slot 0: `pt2' #1

Module 1 slot 0: Enter passphrase:

Enter the appropriate pass phrase, and preload displays:

Loading 'pt2':

Module 1 slot 0: empty

Module 2 slot 0: empty

Module 2 slot 2: empty

Module 1 slot 0: 'pt2' #1

Module 1 slot 0:- passphrase supplied - reading card

Module 1: completed.

Module #1 Slot #0: Remove card.

Remove the card, and preload displays:

Loading 'pt2':

Module 1 slot 0: empty

Module 2 slot 0: empty

Module 2 slot 2: empty

Module 1 slot 0: 'pt2' #1

Module 1 slot 0:- passphrase supplied - reading card

Module 1: completed.

Module #1 Slot #0: Insert appropriate card.

Page 286: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 286

7 nShield Operator Utilities preload

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

Loading 'pt2':

Module 1 slot 0: empty

Module 2 slot 0: empty

Module 2 slot 2: empty

Module 1 slot 0: 'pt2' #1

Module 1 slot 0:- passphrase supplied - reading card

Module 1: completed.

Module 2 slot 0: 'pt2' #1

Module #1 Slot #0: Insert appropriate card.

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

Loading 'pt2':

Module 1 slot 0: empty

Module 2 slot 0: empty

Module 2 slot 2: empty

Module 1 slot 0: 'pt2' #1

Module 1 slot 0:- passphrase supplied - reading card

Module 1: completed.

Module 2 slot 0: 'pt2' #1

Module 2 slot 0: Enter passphrase:

Enter the appropriate pass phrase, and preload displays:

Loading 'pt2':

Module 1 slot 0: empty

Module 2 slot 0: empty

Module 2 slot 2: empty

Module 1 slot 0: 'pt2' #1

Module 1 slot 0:- passphrase supplied - reading card

Module 1: completed.

Module 2 slot 0: 'pt2' #1

Module 2 slot 0:- passphrase supplied - reading card

Card reading complete.

Loaded seeconf testconf key (DES3) on modules 1, 2

Loading complete; now pausing

Page 287: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 287

7 nShield Operator Utilities preload

You can use the preloaded keys and tokens when running commands in a separate command window. For example, to load keys for generatekey that were preloaded in the preceding example, open second command window and give the command:

C:\nfast\bin\preload generatekey hwcrhk

In such an example, the preloaded keys and cards remain loaded at least until the open preload -A seeconf -K mykey pause command is terminated in the first window.

Page 288: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 288

7 nShield Operator Utilities pubkey-find

pubkey-find

The pubkey-find utility returns information about the contents of a .pem file, which may be a private key, a certificate, or a certificate request.

Usage

C:\nfast\bin\pubkey-find.exe [--cert|--certreq|--privkey|--auto] [--summary] [--hash]

[--fingerprint] [--thumbprint] [--identify] [--verify] [--info] [--augment]

[--match-appname PATTERN] [--match-ident PATTERN] [--all|--latest|--earliest] [--module

MODULE] [--verbose][--nfkmverify-options OPTIONS]CERT-OR-KEY-FILE

In this command CERT-OR-KEY-FILE specifies a .pem file.

This utility has the help option -h. It does not have other help options.

Input format options

--cert

This option specifies that the input file is a certificate.

--certreq

This option specifies that the input file is a certificate request.

--privkey

This option specifies that the input file is a private key.

--auto

This option specifies that the type of the input file is not known. pubkey-find attempts to identify the input format. This is the default if no input file type option is specified.

The input file type should be specified if it is known.

Page 289: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 289

7 nShield Operator Utilities pubkey-find

Output format options

--summary

This option generates summary output in human-readable format. Summary information includes the nCore hash and the identities of any matching key files in the kmdata area. If the file is in private key format but is actually an embed key indicator (or ssleay encapsulated blob), this is also reported.

The information displayed by the --summary option is the default if no output format options are specified. Summary information is not printed if another output format option is specified and --summary is not.

--hash

This option prints the nCore key-pair hash.

--fingerprint

This option prints the certificate’s MD5 hash (its fingerprint).

--thumbprint

This option prints the certificate’s SHA-1 hash (its thumbprint).

The --hash, --fingerprint, and --thumbprint options print not just the key, but the cryptographic checksum of the entire certificate.

--identify

This option prints the key’s security world appname and idents.

Page 290: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 290

7 nShield Operator Utilities pubkey-find

Further processing options

--verify

This option uses nfkmverify to verify that the key was securely generated.

--info

This option displays extensive general information about the key (nfkminfo -k)

--augment

This option augments the kmdata file with the public key blob from the imported key. You can only augment a single key at a time.

Other options

--match-appname PATTERN

This option limits processing to the application name that matches the specified PATTERN. (The default is no restriction).

--match-ident PATTERN

This option limits processing to the idents that match the specified PATTERN. (The default is no restriction).

Note Pattern matching in --match-appname and --match-ident uses the syntax of the UNIX glob command.

--all

This option reports and processes all key files in the kmdata directory that match CERT-OR-KEY-FILE. This is the default if none of --all, --latest or --earliest is specified.

Page 291: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 291

7 nShield Operator Utilities pubkey-find

--latest

This option reports and processes the most recently modified file.

--earliest

This option reports and processes the file that has the earliest modification time.

--module MODULE

This option selects the module to use.

--verbose

This option reports more details if the input cannot be parsed.

--nfkmverify-option OPTIONS

This option passes OPTIONS to nfkmverify. OPTIONS must be a Tcl list. See nfkmverify on page 251.

If several kmdata files match, for example if the key has been retargeted, pubkey-find processes all of them. The --latest and --earliest options can be used to select one file only to process. The --earliest option is likely to work best with nfkmverify (that is, the --verify option). --latest is likely to work best otherwise.

Page 292: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 292

7 nShield Operator Utilities pubkey-find

Output

pubkey-find returns information similar to the following:

$ C:\nfast\bin\pubkey-find cert.pem

input format cert

nCore hash 7e259da3d7e78d8ad0b9375e5b99d2d4ad0de7a8

no matching key in current security world host data area

$ C:\nfast\bin\pubkey-find embed.pem

PEM 'key' file really contains only key indicator

input format privkey

nCore hash 750749f62b640132c4b05fa552f49fea3785d01a

name 'plainname'

appname embed

ident 1038030e0e3f21d709817e049eec575a33faa2f2

$ C:\nfast\bin\pubkey-find embed_req.pem

input format certreq

nCore hash 750749f62b640132c4b05fa552f49fea3785d01a

name 'plainname'

appname embed

ident foo

name 'plainname'

appname embed

ident 1038030e0e3f21d709817e049eec575a33faa2f2

$ C:\nfast\bin\pubkey-find --fingerprint embed_selfcert.pem

47:3d:8f:f8:2c:7a:64:23:f9:5a:53:c4:1c:39:3b:2c

$ C:\nfast\bin\pubkey-find --thumbprint embed_selfcert.pem

52:ab:8c:fa:13:a6:ce:43:69:70:87:36:d1:eb:73:71:3e:ba:98:e8

$

Page 293: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 293

7 nShield Operator Utilities randchk

randchk

The randchk utility runs an n-bit, or an n-to-m-bit, Maurer’s Universal Statistical Test on random numbers returned by the module.

Maurer’s Universal Statistical Test is documented in “A universal statistical test for random bit generations”, Advances in Cryptology—CRYPTO ’90 (LNCS) 408-420, 1991.

Usage

C:\nfast\bin\randchk.exe [L-min [L-max]]

If specified, the value of L-min is the number of the lowest bit to be used in the test and L-max is the number of the upper bit to be used in the test. These numbers must be between 1 and 16. If you do not enter a number, randchk performs a 6-bit test.

You can specify a single number, L-min, or a range of numbers, L-min to L-max. If you specify numbers from L-min to L-max inclusive, randchk performs statistical tests for a range of random numbers with these lengths. The second number, L-max, must be larger than the first number, L-min.

Output

randchk displays a message similar to this:

Initialising 6-bit Universal Statistical Test Processing... 46K 6-bit test results:

5.221070 = 0.003365 from mean (0.507348 s.d.'s)

Page 294: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 294

7 nShield Operator Utilities rfs-setup

rfs-setup

This utility creates a default remote file system on the client. You run rfs-setup when you first configure a client. See the Administrator Guide for details of client configuration.

Usage

C:\nfast\bin\rfs-setup.exe [-c|--configfile=FILENAME] [-f|--force]

C:\nfast\bin\rfs-setup.exe <ADDRESS> module_ESN keyhash

C:\nfast\bin\rfs-setup.exe --gang-client module_ip_address module_ESN keyhash

C:\nfast\bin\rfs-setup.exe --gang-client --write-noauth module_IP_address

Options

-c, --configfile=FILENAME

These options specify a configuration file named FILENAME to use.

-f, --force

These options specify that any existing remote file system is to be overwritten.

--gang-client

This option configures the remote file system to accept connections from a cooperating client. For this option, module_IP_address is the IP address of the cooperating client while module_ESN and keyhash are respectively the electronic serial number (ESN) and key hash for the local module.You must supply values for module_ESN and keyhash when using the --gang-client option unless you also pass the --write-no-auth option.

Page 295: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 295

7 nShield Operator Utilities rfs-setup

--write-noauth

This option allows cooperating clients to access the remote file system without HKNETI authorization. You do not need to supply module_ESN or keyhash with this option.

nCipher does not recommend using the --write-noauth option except on completely secure networks.

module_IP_address

This option specifies the IP address of the module.

module_ESN

This option specifies the ESN of the module.

keyhash

This option specifies the HKNETI (key hash) of the module.

You can obtain the ESN and HKNETI of the module from the module’s front panel. You can also obtain it with the anonkneti utility. See bulkerase on page 143 for details.

Page 296: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 296

7 nShield Operator Utilities rfs-sync

rfs-sync

This utility synchronises the kmdata between a cooperating client and the remote file system it is configured to access. It should be run when a cooperating client is initialised in order to retrieve data from the remote file system and also whenever a client needs to update its local copy of the data or, if the client has write access, to commit changes to the data. See the Administrator Guide for more details about client cooperation.

Usage

C:\nfast\bin\rfs-sync.exe [-U|--update] [-c|--commit] [-s|--show] [--remove] [--setup

[setup_options] ip_address]

Options

-U, --update

These options update local key-management data from the remote file system.

Note If a cooperating client has keys in its kmdata/local directory that are also on the remote file system, if these keys are deleted from the remote file system and then rfs-sync --update is run on the client, these keys remain on the client they are until manually removed.

-c, --commit

These options commit local key-management data changes to the remote file system.

-s, --show

These options display the current synchronisation configuration.

Page 297: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 297

7 nShield Operator Utilities rfs-sync

--setup

This option sets up a new synchronisation configuration. Specifics of the configuration can be altered using setup_options as follows:

-a, --authenticate

These set-up options specify use of KNETI authentication. This is the default.

--no-authenticate

This set-up option specifies that KNETI authentication should not be used.

-m, --module=module

These options select which module to use for KNETI authorisation. The default is module 1. This option can only be used with with the --authenticate option.

-p, --port=port

These options specify the port on which to connect to the remote file system. The default is 9004.

ip_address

This option specifies the IP address of the remote file system.

--remove

This option removes the synchronisation configuration.

The rfs-sync command also has additional administrative options for examining and removing lock files that have been left behind by failed rfs-sync --commit operations. Using the --who-has-lock option displays

Page 298: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 298

7 nShield Operator Utilities rfs-sync

the task ID of the lock owner. As a last resort, you can use the rfs-sync command-line utility to remove lock files. In such a case, the --kill-lock option forcibly removes the lock file.

Page 299: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 299

7 nShield Operator Utilities sigtest

sigtest

The sigtest utility measures the module speed using RSA, DSA or ECDSA signatures or signature verifications.

Usage

sigtest [[-s|--sign]|[-v|--verify]|[-d|--decrypt][-m|--module=MODULE][-c|--curve

CURVE][-j|--outstanding-jobs=COUNT]-t|--stop-after=TIME][[-n|--jobs-count=COUNT][-S|--

key-type=TYPE][-l|--key-size=BITS][-M|--mechanism=MECH][-p|--plain-type=TYPE] [--

strong] [--pairwise-check] [-K|--skew-check=SKEW][-T|--min-check=COUNT][-C|--check-

start=TIME][--overprint] [-o|--output=FILE][-r|--report-interval=TIME]

Help options

-h, --help

These options display help for sigtest.

-V, --version

These options display the version number for sigtest.

-u, --usage

These options display a brief usage summary for sigtest.

Program options

-s, --sign

These options test the Sign operation. This is the default if no program option is specified.

-v, --verify

These options test the Verify operation.

Page 300: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 300

7 nShield Operator Utilities sigtest

-d, --decrypt

These options test the Decrypt operation.

-m, --module=MODULE

These options specify the module number. Multiple modules may be specified, for example, --module=1 --module=2. If no module is specified, all module are tested by default.

-j, --outstanding-jobs=COUNT

These options set the maximum number of outstanding jobs. The default value of COUNT is the maximum number of jobs recommended for the hardserver, plus one. If -m is used to limit the testing to a single module when using ECDSA, limit the maximum number of jobs to 100 using -j 100 as the algorithm is currently slower than RSA or DSA and single modules may become overloaded by the test.

-t, --stop-after=TIME

These options specify the maximum time to run the test. Use the suffix s to specify seconds, m for minutes, h hours, and d for days. The default value of TIME is infinity, that is, the test runs forever.

-n, --jobs-count=COUNT

These options specify the maximum number of jobs to run. The default value of COUNT is infinity, that is, there is no limit to the number of jobs run.

Key options

-S, --key-type=TYPE

These options select the signature type to use. Valid values are RSA, DSA, ECDSA and KCDSA. The default is RSA.

Page 301: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 301

7 nShield Operator Utilities sigtest

-l, --key-size=BITS

These options set the key size in bits. The default is 1024. This option is ignored if the key type is ECDSA; for elliptic curve keys. use the -c or --curve options with one of the supported curves as the argument.

-c, --curve CURVE

These options specify which of the range of supported curves to use for testing with ECDH and ECDSA. Supported curves are any of: NISTP192, NISTP224, NISTP256, NISTP384, NISTP521, NISTB163, NISTB233, NISTB283, NISTB409, NISTB571, NISTK163, NISTK233, NISTK283, NISTK409, NISTK571, ANSIB163v1, ANSIB191v1, SECP160r1 .

-M, --mech=MECH

These options specify the mechanism to use. Valid values are RSApPKCS1, DSA, ECDSA and KCDSAHAS160.

Note The KCDSA algorithm and the KCDSAHAS160 mechanisms are available only if you have enabled the KCDSA feature. See the Administrator Guide for details of feature enabling. Similarly, the ECDSA mechanism is only available if you have enabled the Elliptic Curve feature.

-p, --plain-type=TYPE

These options use the plaintext type TYPE. Valid values are Bignum, Hash and Bytes.

--strong

For RSA, this option uses strong (ANSI X9.31) primes. For DSA, it uses the strict flag.

--pairwise-check

This option sets the PairwiseCheck flag during key generation.

Page 302: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 302

7 nShield Operator Utilities sigtest

Automatic checking options

-T, --min-check=COUNT

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

-K, --skew-check=SKEW

These options perform skew checking, after either 15 seconds or the time specified by --min-check. sigtest records the overall average number of modular exponentiations each second as average. Subsequently, when sigtest writes an output line, it quits with an error message if the average is outside the range average SKEW.

Note The --min-check and --skew-check options are mutually exclusive.

-C, --check-start=TIME

These options specify the time in seconds at which threshold or skew checking starts. The default value of TIME is 15.

Output options

--overprint

This option prints results all on one line, using \r rather than \n.

-o, --output=FILE

These options specify that results be written to FILE in addition to stdout.

Page 303: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 303

7 nShield Operator Utilities sigtest

-r, --report-interval=TIME

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

Output

sigtest produces output similar to this:

number of modules: 1

Making 1024-bit RSA Private key on module #1...

1, 148 59.

2, 151 overall 2, 410 140.32, 206 overall

3, 677 190.992, 226 overall

4, 944 221.395, 267 overall

5, 1190 231.237, 256.5 overall ...

The first column shows the number of seconds.

The second shows the total number of exponentiations performed.

The third column shows the number of exponentiations achieved this second.

The last column shows a moving average of the number of exponentiations achieved each second.

Page 304: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 304

7 nShield Operator Utilities slotinfo

slotinfo

The slotinfo utility returns information about the tokens that are present in a module. slotinfo can also be used to format a token.

Usage

C:\nfast\bin\slotinfo -m|--module=MODULE [-s|--slot=SLOT]

Module selection

-m, --module=MODULE

These options specify the module number of the module to be used. You must specify a module number.

-s, --slot=SLOT

These options specify the number of the slot to be used. If this option is set, slotinfo returns information about the files on the token. If, however, you do not specify --slot, slotinfo returns information about all slots.

--format

This option tells slotinfo to format the token that is currently in the slot. You must specify a slot number if you want to format a token. The token is formatted without a challenge response key.

Note Use of the --format option is deprecated. If you use slotinfo with the --format option to format a token, it does not remove the card from the security world lists and cannot erase cards in FIPS 140-2 level 3 compliant security worlds.

slotinfo does not update the security world host data. If you are using an nCipher security world:

Page 305: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 305

7 nShield Operator Utilities slotinfo

• Use createocs to format Operator Cards

• Use KeySafe or createocs to erase cards.

Output

slotinfo --module=1 returns information in the format:

Slot Type Token IC Flags Details

#0 Smartcard present 1 A

#1 Software Tkn - 0

In this output:

• Type Unconnected means that the slot is a remote slot for this module, but the hardserver has failed to import it. The reason for the failure is given in the Details field.

• An A in the Flags field means that the token supports token authentication in a call to format token.

• An R in the Flags. field means that the slot is a remote slot.

slotinfo --module=1 --slot=0 returns information in the format:

Module # slot #:

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

No data on token

3698 bytes free

slotinfo --module=1 --slot=0 --format returns:

Formatting token in module 1 slot 0:

Formatted token OK

Page 306: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 306

7 nShield Operator Utilities stattree

stattree

The stattree utility returns the statistics gathered by the nCipher server and modules.

Usage

C:\nfast\bin\stattree [<node> [<node> [...]]]

Output

Running the stattree utility displays a snapshot of statistics currently available on the host machine. Statistics are gathered both by the hardserver (relating to the server itself, and its current clients) and by each attached module.

Statistics are displayed in the form of a tree. At each node in the tree, either a set of statistics or a list of sub-categories is displayed. Each node has a label which consists of one of the following:

• a tag that identifies its contents as described in Node tags on page 308.

• a number the corresponds to an instance in the category, for example, a module identifier or a client connection identifier

Times are listed in seconds. Other numbers are integers, which are either real numbers, IP addresses, or counters. For example, a result -CmdCount 74897 means that there have been 74,897 commands submitted.

Page 307: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 307

7 nShield Operator Utilities stattree

A typical fragment of output from stattree looks like this:

+PerModule:

+#1:

+ModuleObjStats:

-ObjectCount 4

-ObjectsCreated 4

-ObjectsDestroyed 0

+ModuleEnvStats:

-MemTotal 14389248

-MemAllocKernel 86016

-MemAllocUser 0

-CurrentTempC 39.50

-MaxTempC 39.50

-MinTempC 39.50

PerModule, ModuleObjStats, and ModuleEnvStats are node tags that identify classes of statistics. #1 identifies an instance node.

ObjectCount, MemTotal, and the remaining items at the same level are statistics IDs. Each has a corresponding value.

If node is provided, stattree uses the value given as the starting point of the tree and displays only information at or below that node in the tree. Values for node can be numeric or textual. For example, to view the object counts for local module number 3:

$ stattree PerModule 3 ModuleObjStats

+#PerModule:

+#3:

+#ModuleObjStats:

-ObjectCount 6

-ObjectsCreated 334

-ObjectsDestroyed 328

Page 308: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 308

7 nShield Operator Utilities stattree

The value of node must be a node tag; it must identify a node in the tree and not an individual statistic. Thus, the following command does not work:

$ stattree PerModule 3 ModuleObjStats ObjectCount

+#PerModule:

+#3:

+#ModuleObjStats:

Unable to convert 'ObjectCount' to number or tag name.

Node tags

These hold statistics for each module:

Category Contains

ModuleJobStats This tag holds statistics related to the nCipher commands handled by this module.

ModulePCIStats This tag is for nCipher PCI and netHSM modules only. It holds statistics related to the PCI connection between this card and the host computer.

ServerGlobals Aggregate statistics for all commands processed by the hardserver since it started.The standard statistics (as described below) apply to the commands sent from the hardserver to modules. Commands processed internally by the server are not included here. The Uptime statistic gives the total running time of the server so far.

Connections Statistics for connections between clients and the hardserver. There is one node for each currently active connection. Each node has an instance number that matches the log message generated by the server when that client connected. For example, when the hardserver message is Information: New client #24 connected, the client’s statistics appear under node #24 in the stattree output.

PerModule Statistics kept by the modules. There is one instance node for each module, numbered using the standard module numbering. The statistics provided by each module depend on the module type and firmware version.

Page 309: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 309

7 nShield Operator Utilities stattree

Statistics IDs

ModuleJobStats Statistics for the commands (jobs) processed by a module. Appears under the PerModule category.

ModulePCIStats Statistics from the module’s PCI host interface. Appears only on PCI-interfaced modules.

ModuleObjStats Statistics for the module’s Object Store, which contains keys and other resources. These statistics may be useful in debugging applications that leak key handles, for example.

ModuleEnvStats General statistics for the module’s operating environment.

Category Contains

ID Value

Uptime The length of time (in seconds) since a module was last reset, the hardserver was started, or a client connection was made.

CmdCount The total number of commands sent for processing from a client to the server, or from the server to a module. Contains the number of commands currently being processed.

ReplyCount The total number of replies returned from server to client, or from module to server.

CmdBytes The total length of all the command blocks sent for processing.

ReplyBytes The total length of all the reply block received after completion.

CmdMarshalErrors The number of times a command block was not understood when it was received. A nonzero value indicates either that the parties at each end of a connection have mismatched version numbers (for example, a more recent hardserver has sent a command to a less recent module that the module does not understand), or that the data transfer mechanism is faulty.

Page 310: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 310

7 nShield Operator Utilities stattree

ReplyMarshalErrors The number of times a reply was not understood when it was received. A nonzero value indicates either that the parties at each end of a connection have mismatched version numbers (for example, a more recent hardserver has sent a command to a less recent module that the module does not understand), or that the data transfer mechanism is faulty.

ClientCount The number of client connections currently made to the server. This appears in the hardserver statistics.

MaxClients The maximum number of client connections ever in use simultaneously to the hardserver. This gives an indication of the peak load experienced so far by the server.

DeviceFails The number of times the hardserver has declared a device to have failed. The hardserver provides a diagnostic message when this occurs.

DeviceRestarts The number of times the hardserver has attempted to restart a module after it has failed. The hardserver provides a Notice message when this occurs. The message does not indicate that the attempt was successful.

QOutstanding The number of commands waiting for a module to become available on the specified client connection. When a module accepts a command from a client, this number decreases by 1 and DevOutstanding increases by 1. Commands that are processed purely by the server are never included in this count.

DevOutstanding The number of commands sent by the specified client that are currently executing on one or more modules. When a module accepts a command from a client, QOutstanding decreases by 1 and this number increases by 1. Commands that are processed purely by the server are never included in this count.

LongOutstanding The number of LongJobs sent by the specified client that are currently executing on one or more modules. When a module accepts a LongJobs command from a client, QOutstanding decreases by 1 and this number increases by 1. Commands that are processed purely by the server are never included in this count.

ID Value

Page 311: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 311

7 nShield Operator Utilities stattree

RemoteIPAddress The remote IP address of a client who has this connection. A local client has the address 0.0.0.0.

HostWriteCount The number of write operations (used to submit new commands) that have been received by the module from the host machine. One write operation may contain more than one command block. The operation is most efficient when this is the case.

HostWriteErrors The number of times write data from the host was rejected by the module. A nonzero value may indicate that data is being corrupted in transfer, or that the hardserver/device driver has got out of sync with the module’s interface.

HostWriteBadData Not currently reported by the module. Attempts to write bad data to the module are reflected in HostWriteErrors.

HostWriteOverruns Not currently reported by the module. Write overruns are reflected in HostWriteErrors.

HostWriteNoMemory Not currently reported by the module. Write failures due to lack of memory are reflected in HostWriteErrors.

HostReadCount The number of times a read operation to the module was attempted. The module can defer a read if it has no replies at the time, but expects some to be available later. Typically the module reports HostReadCount in two places: the number under ModuleJobStats counts a deferred read twice, once when it is initially deferred, and once when it finally returns some data. The number under ModulePCIStats counts this as one operation.

HostReadErrors The number of times a read to a module failed because the parameters supplied with the read were incorrect. A nonzero value here typically indicates some problem with the host interface or device driver.

HostReadEmpty The number of times a read from the module returned no data because there were no commands waiting for completion. In general, this only happens a small number of times during module startup or reset. It can also happen if PauseForNotifications is disabled.

HostReadUnderruns Not currently reported by the module.

ID Value

Page 312: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 312

7 nShield Operator Utilities stattree

HostReadDeferred The number of times a read operation to the module was suspended because it was waiting for more replies to become available. When the module is working at full capacity, a sizeable proportion of the total reads are likely to be deferred.

HostReadTerminated The number of times a module had to cancel a read operation which has been deferred. This normally happens only if the clear key is pressed while the module is executing commands. Otherwise it might indicate a device driver, interface, or firmware problem.

PFNIssued The number of PauseForNotifications commands accepted by the module from the hardserver. This normally increases at a rate of roughly one every two seconds. If the hardserver has this facility disabled (or a very early version), this will not occur.

PFNRejected The number of PauseForNotifications commands rejected by the module when received from the hardserver. This can happen during module startup or reset, but not in normal use. It indicates a hardserver bug or configuration problem.

PFNCompleted The number of PauseForNotifications commands that have been completed by the module. Normally, this is one less than the PFNIssued figure, since there is normally one such command outstanding.

ANIssued The number of Asynchronous Notification messages issued by the module to the hardserver. These messages indicate such things as the clear key being pressed and the module being reset. In later firmware revisions inserting or removing the smartcard or changing the non-volatile memory also generate asynchronous notifications.

ChanJobsIssued The number of fast channel jobs issued to the module. The fast channel facility is unsupported on current modules. This number should always be zero.

ChanJobsCompleted The number of fast channel jobs completed by the module.The fast channel facility is unsupported on current modules. This number should always be zero.

ID Value

Page 313: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 313

7 nShield Operator Utilities stattree

CPULoadPercent The current processing load on the module, represented as a number between 0 and 100. Because a module typically contains a number of different types of processing resources (for example, main CPU, and RSA acceleration), this figure is hard to interpret precisely. In general, modules report 100% CPU load when all RSA processing capacity is occupied; when performing non-RSA tasks the main CPU or another resource (such as the random number generator) can be saturated without this statistic reaching 100%.

HostIRQs On PCI modules, the total number of interrupts received from the host. On current modules, approximately equal to the total of HostReadCount and HostWriteCount.

ChanJobErrors The number of low-level (principally data transport) errors encountered while processing fast channel jobs. Should always be zero on current modules.

HostDebugIRQs On PCI modules, the number of debug interrupts received. This is used only for driver testing, and should be zero in any production environment.

HostUnhandledIRQs On PCI modules, the number of unidentified interrupts from the host. If this is nonzero, a driver or PCI bus problem is likely.

HostReadReconnect On PCI modules, the number of deferred reads that have now completed. This should be the same as HostReadDeferred, or one less if a read is currently deferred.

ObjectsCreated The number of times a new object has been put into the object store. This appears under the module’s ModuleObjStats node.

ObjectsDestroyed The number of items in the module’s object store that have been deleted and their corresponding memory released.

ObjectCount The current number of objects (keys, logical tokens, buffers, SEE Worlds) in the object store. This is equal to ObjectsCreated minus ObjectsDestroyed. An empty module contains a small number of objects that are always present.

ID Value

Page 314: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 314

7 nShield Operator Utilities stattree

CurrentTempC The current temperature (in degrees Celsius) of the module main circuit board. First-generation modules do not have a temperature sensor and do not return temperature statistics.

MaxTempC The maximum temperature recorded by the module’s temperature sensor. This is stored in non-volatile memory, which is cleared only when the unit is initialized. First-generation modules do not have a temperature sensor and do not return temperature statistics.

MinTempC The minimum temperature recorded by the module’s temperature sensor. This is stored in non-volatile memory, which is cleared only when the unit is initialized. First-generation modules do not have a temperature sensor and do not return temperature statistics.

MemTotal The total amount of RAM (both allocated and free) available to the module. This is the installed RAM size, minus various fixed overheads.

MemAllocKernel The total amount of RAM allocated for kernel (that is, non-SEE) use in a module. This is principally used for the object store (keys, logical tokens, and similar) and for big-number buffers.

MemAllocUser The total amount of RAM allocated for user-mode processes in the module; will be zero for non-SEE use. This includes the size of the SEE Machine image, and the total heap space available to it. The module’s kernel does not know (and does not report in the statistics) how much of the user-mode’s heap is currently free, and how much is in use.

ID Value

Page 315: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 315

Appendix A: Cryptographic algorithms

This appendix describes the algorithms supported by nCipher modules.

In the following tables, the column labelled nfkmverify documents the implemented behaviour of the nfkmverify command-line utility (and its underlying library). An entry N in this column means that nfkmverify always rejects the algorithm, while Y means that nfkmverify always accepts the algorithm. A constraint on the number of bits means that nfkmverify only accepts keys of at least that many bits.

Symmetric Algorithms

AlgorithmF

IPS

approvalKey length in bits Use for ...

nfkmverify

Autho

rization

Digital S

ignatures

Encryptio

n

Other

AES Y 128, 192, 256 Y Y Y

Arcfour 192 Y N

Blowfish 8 to 448 Y Y N

CAST 5 up to 128 Y Y N

CAST 6 up to 256 Y Y N

DES 56 Y Y N

MD2 HMAC 8 to 2048 Y N

MD5 HMAC 8 to 2048 Y N

RIPEMD160 HMAC

8 to 2048 Y ≥80 bits

SEED 128 Y Y N

Serpent up to 256 Y Y N

Page 316: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 316

A Cryptographic algorithms Cryptographic algorithms

SHA-1 HMAC Y 8 to 2048 Y ≥80 bits

SHA-256 HMAC Y 8 to 2048 Y ≥80 bits

SHA-384 HMAC Y 8 to 2048 Y ≥80 bits

SHA-512 HMAC Y 8 to 2048 Y ≥80 bits

Tiger HMAC 8 to 2048 Y ≥80 bits

Triple DES Y 112, 168 Y Y Y

Twofish up to 256 Y Y N

Symmetric Algorithms

Algorithm

FIP

S approval

Key length in bits Use for ...

nfkmverify

Autho

rization

Digital S

ignatures

Encryptio

n

Other

Page 317: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 317

A Cryptographic algorithms FIPS Information

Note The RSA algorithm is based on the factorization of integers.

Note The Diffie-Hellman, DSA, El-Gamal, ECDSA, ECDH, and KCDSA algorithms are all based on discrete logarithms in a multiplicative group of a finite field.

FIPS Information

The latest guidance from the National Institute of Standards and Technology (NIST) is that

Asymmetric Algorithms

Algorithm

FIP

S approval

Key length in bits Use for ...

nfkmverify

Autho

rization

Digital S

ignatures

Encryption

Other

RSA Y ≥512 Y Y Y ≥1024 bits

Diffie-Hellman Y ≥1024

Key exchange

≥1024 bits

DSA Y 512 to 1024Y Y

≥1024 bits

El-Gamal ≥1024Y

KCDSA ≥1024Y Y

≥1024 bits

ECDSA Y ≥224Y Y

≥1024 bits

ECDH Y ≥224Y Y

≥1024 bits

Page 318: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 318

A Cryptographic algorithms FIPS Information

• a module is only operating in FIPS mode when it uses NIST-approved algorithms

• a module operating at FIPS 140-2 level 3 must not only indicate whether it is in FIPS mode but also actively prevent use of algorithms not approved by NIST in FIPS-approved mode.

Thus, with the current release of firmware, when a module is initialized into FIPS 140-2 level 3 mode, you are only offered NIST-approved algorithms. If you have a security world created to comply with FIPS 140-2 level 3 and have any protocols that use algorithms not approved by NIST, you must either migrate to a FIPS 140-2 level 2 security world or change your protocols. If you have a security world created to comply with FIPS 140-2 level 3 and have existing long-term keys for non-approved algorithms, then these keys cannot be used with the current firmware. In such a case, nCipher recommends that you either migrate your security world to a FIPS 140-2 level 2 security word or replace these keys with approved keys before upgrading to the current firmware.

These changes do not affect security worlds that were created to comply with FIPS 140-2 level 2, nor do they affect systems that use the nCipher module to protect long-term keys but perform encryption with session keys on the host (as is the case with nCipher’s MSCAPI, CHIL, and PKCS #11 libraries).

The NIST-approved algorithms that nCipher modules offer are:

• DSA

• ECDSA

• RSA

• Diffie-Hellman

• Triple DES

• AES

• SHA-1

• SHA-256

Page 319: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

nShield/payShield Operator Guide Windows v5.5 319

A Cryptographic algorithms FIPS Information

• SHA-384

• SHA-512

• TLS key derivation

• HMAC (SHA-1, SHA-256, SHA-384, SHA-512)

The algorithms not approved by NIST that nCipher modules offer are:

• KCDSA

• ECDH

• Arc Four

• Blowfish

• CAST 5

• CAST 6

• DES

• Serpent

• SEED

• Twofish

• SHA-160

• MD2

• MD5

• RIPEMD 160

• HMAC (MD2, MD5, RIPEMD160)

Page 320: nShield/payShield Operator Guide Windowskifri.fri.uniza.sk/~chochlik/epodpis/nCipher... · payShield modules. In this guide, the term nShield refers to any of the nShield, payShield

Internet addresses

Note nCipher also maintain international sales offices. Please contact the UK, or the US, head office for details of your nearest nCipher representative.

nCipher Corporation Ltd. nCipher Inc.

Cambridge, UK

Jupiter HouseStation RoadCambridgeCB1 2JDUK

Boston Metro Region, USA

92 Montvale Avenue, Suite 4500Stoneham, MA 02180USA

Tel:Fax:

+44 (0) 1223 723600+44 (0) 1223 723601

Tel:

Fax:

800-NCIPHER800-6247437+1 (781) 994 4000+1 (781) 994 4001

E-mail:[email protected]@ncipher.com

E-mail:[email protected]@ncipher.com

Web Site: http://www.ncipher.com/

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

nCipher addresses


Recommended