Managing card sets and softcards

This chapter describes how to create and manage card sets and softcards, using a Security World.

When you create a Security World, an Administrator Card Set (ACS) is created at the same time. You use the ACS to:

Control access to Security World configuration
Authorize recovery and replacement operations.

The Security World is used to create and manage keys, and the Operator Card Sets (OCSs) and softcards you create with the Security World are used to protect those keys.

A Security World offers three levels of key protection:

Level of protection	Description
Direct protection	Keys that are directly protected by the Security World are usable at any time without further authorization.
Softcard	Keys that are protected by a softcard can only be used by the operator who possesses the relevant passphrases.
OCS	Keys that are protected by an OCS can only be used by the operator who possesses the OCS and any relevant passphrases (if set).

Level of protection

Description

Direct protection

Keys that are directly protected by the Security World are usable at any time without further authorization.

Softcard

Keys that are protected by a softcard can only be used by the operator who possesses the relevant passphrases.

OCS

Keys that are protected by an OCS can only be used by the operator who possesses the OCS and any relevant passphrases (if set).

For more information about creating a Security World, see Creating and managing a Security World.

For more information about key management, see Working with keys.

After a Security World has been created, you can use it to create and manage OCSs and softcards (as described in this chapter), as well as to create and manage the keys it protects (see Working with keys).

To perform the tasks described in this chapter, we recommend using the unit front panel or a client on the same computer that contains the RFS. To perform these tasks on a different client, you must transfer the card data to the RFS.

If you are sharing the Security World across several client computers, you must ensure that the changes are propagated to all your computers. One way to achieve this is to use client cooperation. For more information, see Setting up client cooperation.

If you want to use the Remote Operator feature to configure smart cards for use with a remote unit, see Remote Operator.

Creating Operator Card Sets (OCSs)

You can use an Operator Card Set (OCS) to control access to application keys. OCSs are optional, but if you require one, create it before you start to use the hardware security module with applications. You must create an OCS before you create the keys that it is to protect.

You can create OCSs that have:

Names for individual cards, as well as a name for the whole card set
Specific K/N policies
Optional passphrases for any card within a given set
Formal FIPS 140 Level 3 compliance.

Some third-party applications impose restrictions on the OCS smart card quorums (K/N) or the use of smart card passphrases. For more information, see the appropriate integration guide for the application. Integration guides for third-party applications are available from https://nshieldsupport.entrust.com/.

OCSs belong to the Security World in which they are created. When you create an OCS, the smart cards in that set can only be read by hardware security modules belonging to the same Security World.

Creating (and managing) OCSs can be done with the unit front panel, as described in Creating an Operator Card Set using the nShield HSM front panel. However, you can also use the following tools to create an OCS:

The createocs command-line utility, as described in Creating an Operator Card Set using the command line
KeySafe, as described in Creating an Operator Card Set with KeySafe

Persistent Operator Card Sets

If you create a standard (non-persistent) OCS, the keys it protects can only be used while the last required card of the quorum remains loaded in the local slot of the HSM, or one of its Dynamic Slots. The keys protected by this card are removed from the memory of the device as soon as the card is removed from the smart card reader. If you want to be able to use the keys after you have removed the last card, you must make that OCS persistent.

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

For more information about persistent OCSs, see Using persistent Operator Card Sets.

An OCS to be used to authorize login on a unit must be persistent and not loadable remotely. It is recommended that such an OCS is not used to protect sensitive keys.

Time-outs

OCSs can be created with a time-out, so that they can only be used for limited time after the OCS is loaded. An OCS is loaded by most applications at start up or when the user supplies the final required passphrase. After an OCS has timed out, it is not loadable by another application unless it is removed and reinserted. Time-outs operate independently of OCS persistence.

FIPS 140 Level 3-compliant Security Worlds

When you attempt to create an OCS for a Security World that complies with FIPS 140 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 using the nShield HSM front panel

To create an OCS, follow these steps:

From the main menu, select Security World mgmt > Cardset operations > Create OCS.

You are prompted to enter the name of the OCS.
Enter a name and press right-hand navigation button.
Enter the quorum for the OCS, using the touch wheel to move from one field to the other. The quorum consists of:
- The maximum number of cards from the OCS required by default for an operation. This number must be less than or equal to the total number of cards in the set.
- The total number of cards to be used in the OCS. This must be a value in the range 1 – 64.
Press the right-hand navigation button to move to the next screen.
If you wish to specify a time out for the card set, enter the time out in seconds.
Choose whether to create a persistent card set. You can select:
- Not persistent (which is the default)
- Persistent
- Remoteable/Persistent
Choose whether to name individual cards and enable passphrase replacement by answering Yes or No to each question and then pressing the right-hand navigation button.
Insert a smart card to be formatted for the OCS.

If the card is not blank, choose whether to overwrite it or to use a different card. (If the card is an Operator Card from another Security World, you cannot overwrite it and are prompted to enter a different card.)
If you have chosen to name individual cards, you are prompted to enter the name for the card.
You are asked whether you wish to specify a passphrase for the card. If you choose Yes, you are prompted to enter the passphrase twice.

While the Operator Card is being created, the screen displays the message Processing.

If there are further cards from this OCS to be processed, the screen changes to Waiting. Remove the card, and repeat steps 8 through 10 for each of the remaining cards.

When all the cards in the set have been processed, you are told that the card set has been created successfully.

Creating an Operator Card Set using the command line

To create an OCS from the command line:

Run the command:

createocs -m <MODULE>|--module=<MODULE> -Q|--ocs-quorum=<K>/<N> +
-N|--name=<NAME> [-M|--name-cards] +
[[-p|--persist]|[-P|--no-persist]] [[-R|--no-pp-recovery]|--pp-recovery] +
[-q|--remotely-readable] [-T|--timeout=<TIME>] [-e|--erase]

This command uses the following options:

Option Description

-m <MODULE>|--module=<MODULE>

This option specifies the number of the hardware security module to be used to create the token. If you only have one hardware security module, <MODULE> is 1.

-Q|--ocs-quorum=<K>/<N>

In this option, <K> is the minimum required number of cards. If you do not specify the value <K>, the default is 1.

Some applications do not have mechanisms for requesting that cards be inserted. Therefore any OCSs 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>

This option specifies a name for 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

Specifying this option allows 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

This option creates a persistent card set.

-P|--no-persist

This option creates a non-persistent card set.

-R|--no-pp-recovery

This option specifies that passphrase replacement for this OCS is disabled. Setting this option overrides the default setting, which is that the card passphrases are replaceable. You can specify the enablement of passphrase replacement explicitly by setting the --pp-recovery option.

-q|--remotely-readable

This option allows this card set to be read remotely. For information on configuring Remote OCSs, see Remote Operator.

Not required for Remote Administration.

-T|--timeout=<TIME>

This option sets 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 time-out is set to 0, the OCS never times out. Otherwise, the hardware security module automatically unloads the OCS when the amount of time specified by TIME has passed since the OCS was loaded.

-e|--erase

Specifying this option erases a card (instead of creating a card set). You can specify this option twice in the form -ee to repeatedly erase cards.

With Security World Software v11.72 and later, passphrases are limited to a maximum length of 254 characters, when using createocs. See Maximum passphrase length.

If you have created a FIPS 140 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.

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 hardware security 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 insert a valid card, createocs prompts you to type a passphrase.

The nShield PKCS #11 library requires Operator Cards with passphrases.

Some applications do not have mechanisms for entering passphrases. Do not give passphrases to Operator Cards that are to be used with these applications.
Type a passphrase and press Enter. Alternatively, press Enter if you do not want this card to have a passphrase.

A passphrase can be of any length and can contain any character that you can type.

If you entered a passphrase, createocs prompts you to confirm it.
Type the passphrase again and press Enter.

If the passphrases do not match, createocs prompts you to input and confirm the passphrase again.
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 OCS, follow the instructions from step 2 through 4.

Creating an Operator Card Set with KeySafe

KeySafe enables you to create OCSs with:

Their own names
K/N policies
Optional passphrases for any card within the OCS
Formal FIPS 140 Level 3 compliance.

To create an OCS with KeySafe:

Start KeySafe. (For an introduction to KeySafe and information on starting the software, see Using KeySafe.)
Click the Card sets menu button, or select Card sets from the menu.

The List Operator Card Sets panel is displayed.
Select an HSM within the Security World from the Security World status pane.
Click the Create new card set button to open the Create Operator Card Set panel. You can specify the following options:
1. A name for the card set.
2. Whether passphrase recovery will be enabled for the OCS. (Only available if the Security World has passphrase recovery enabled.)
3. Whether the card set can be used remotely. (Only available if the Security World has remote sharing available.) For more information, see Remote Operator.
4. Whether this OCS will be persistent.
5. Whether this OCS will have a time-out (a period after which the card set must be inserted again).
6. The value for the time-out, in seconds.
7. The total number of Operator Cards (N) that you want this OCS to have. This must be a value in the range 1 – 64.
8. The number of Operator Cards needed to re-create a key (K). K must be less than or equal to N.

When you have entered all the details, click Commit. KeySafe takes you to a new Create Operator Card Set panel.

If K is equal to N, a message is displayed:

The total number of cards is equal to the required number of cards. – If the total and required number of cards are equal, losing one card will render any nonrecoverable keys unusable. Is this what you want?

Click Yes to confirm the values for K and N, or No to change them.

If you are creating the card set in a FIPS 140 Level 3 Security World, insert an Administrator Card or an existing Operator Card when prompted.

Insert a blank, unformatted card into the reader.

A message is displayed, confirming that the card is blank. Click OK to open the Set Card Protection passphrase panel.

If you insert a card from another OCS, 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. If you insert an OCS card from another Security World you will get the message:

Error. Unreadable card - may be incorrectly inserted or be from another Security World’s operator card set. Please check.

To overcome this you must replace the card you have inserted with another card that is readable (or blank).

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.

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

If setting a passphrase for the currently inserted card, enter the same passphrase in both text fields. A passphrase 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 passphrase at any time. If you do not set a passphrase now, you can use the KeySafe Change passphrase option (on the Examine/Change Card panel) to add one later. Likewise, if you later decide that you do not need a passphrase on a card, you can use this option to remove it.

After entering your desired passphrase (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.
After KeySafe has written the details of the last smart card in the set, it displays a dialog indicating that the OCS has been successfully created. Click the OK button, and KeySafe returns you to the Create Operator Card Set panel, where you can create another OCS or choose a different operation by clicking one of the menu buttons.

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 passphrase; 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 Key Management Data 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.

A softcard’s passphrase 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.

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

Softcards are not supported for use with the nCipherKM JCA/JCE CSP in Security Worlds that are compliant with FIPS 140 Level 3.

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 OCSs, if debugging is enabled, a softcard’s passphrase hash is available in the debug output (as a parameter to a ReadShare command).

You can create softcards from either:

The command-line (see Creating a softcard with ppmk)
KeySafe (see Creating softcards with KeySafe)

Creating a softcard with ppmk

To create a new softcard using the ppmk command-line utility:

Decide whether you want the new softcard’s passphrase to be replaceable or non-replaceable. To create a softcard with a replaceable passphrase, run the command:
```
ppmk --new --recoverable <NAME>
```
To create a softcard with a non-replaceable passphrase, run the command:
```
ppmk --new --non-recoverable <NAME>
```
In these commands, <NAME> specifies the name of the new softcard to be created.
When prompted, type a passphrase for the new softcard, and press Enter.

A passphrase can be of any length and contain any characters that you can type except for tabs or carriage returns (because these keys are used to move between data fields).
When prompted, type the passphrase again to confirm it, and press Enter.

If the passphrases do not match, ppmk prompts you to input and confirm the passphrase again.

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

Creating softcards with KeySafe

To create a softcard with KeySafe:

Start KeySafe. (For an introduction to KeySafe and information on starting the software, see Using KeySafe.)
Click the Softcards menu button, or select Softcards from the Manage menu. KeySafe takes you to the List Softcards panel.
Click Create New Softcard to open the Create Softcard panel.

Choose parameters for the softcard:

Enter a name for the softcard. You must provide a valid name for each softcard.

Choose whether you want passphrase replacement to be enabled for the softcard.

In a Security World with passphrase recovery enabled the Yes radio button is selected as default and the selection can be changed between Yes and No. In a Security World with passphrase recovery disabled the No button is selected, and cannot be changed to Yes.

Click Commit.

If you are creating the softcard in a FIPS 140 Level 3 Security World, insert an Administrator Card or an existing Operator Card when prompted.

The Set Softcard Protection passphrase pane is displayed.
Set a passphrase for the softcard by entering the same passphrase in both text fields.

A passphrase 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 passphrase at any time. You must provide a passphrase for each card.
After entering your desired passphrase in both text fields, click the OK button.

KeySafe displays a dialog indicating that the softcard has been successfully created.
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 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.

In the case of an OCS that uses nShield Remote Administration Cards, it is possible to reformat the cards at any time using slotinfo --ignoreauth. In the case of an OCS that uses standard nShield cards, it is only possible to erase or format the cards within the Security World in which they were created.

You can erase Operator Cards using the unit front panel, KeySafe or the createocs utility. You can also use these methods to erase Administrator Cards other than those in the current Security World’s ACS (for example, you could use these methods to erase the remaining Administrator Cards from an incomplete set that has been replaced or Administrator Cards from another Security World).

None of these tools erases cards from the current Security World’s ACS.

If you erase an Operator Card that is the only card in an OCS, information about the card set is deleted. However, if you erase one card from an OCS of multiple cards, you must remove the card information from the opt/nfast/kmdata/local/ directory after you have erased the last card.

You can erase an entire card set at one time with the KeySafe Remove OCS! feature. For more information, see List an Operator Card Set.

FIPS 140 Level 3-compliant Security Worlds

When you attempt to erase cards for a Security World that complies with FIPS 140 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. You can therefore use one of the cards that you are about to erase.

Erasing card sets using the nShield HSM front panel

To erase a card set using the front panel, follow this procedure:

From the main menu select: Security World mgmt > Card operations > Erase card
Insert the card set that you want to erase. The card is read.
You are asked to confirm that you want to erase this card from the card set.
To confirm, press the right-hand navigation button.
You are asked once again if you want to erase this card.
To confirm, press the right-hand navigation button.

Erasing cards with KeySafe

To erase a card using KeySafe use the following procedure:

Start KeySafe. (For an introduction to KeySafe and information on starting the software, see Using KeySafe.)
Click the Card Sets menu button. KeySafe takes you to the Card Operations panel.
Click the Examine/Change Card navigation button. KeySafe takes you to the Examine/Change Card panel.
Insert the card that you want to erase into the reader.
Click the Erase Card button. You do not need to supply the passphrase (if there is one) to erase an Operator Card.
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.

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 OCS, KeySafe deletes information about that card set. However, if you erase one card from an OCS of multiple cards, you must remove the card information from the opt/nfast/kmdata/local after you have erased the last card.
After erasing a card, KeySafe displays a dialog to confirm that the card has been erased. Click OK to continue using KeySafe.

You can erase an entire card set at one time with the KeySafe Discard Card Set(s) feature.

Erasing cards using the command line

To erase a card from the command line, run the command:

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

This command uses the following options:

Option Description

Option	Description
`-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 specify that you want to erase a card (rather than create an OCS).

-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 specify that you want to erase a card (rather than create an OCS).

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 [Ctrl][X] to switch between cards.

If you have created a FIPS 140 Level 3 compliant Security World, you must provide authorization in order to erase or create Operator Cards. You can obtain this authorization from any card in the ACS or from any Operator Card in the current Security World, including cards that are to be erased. After you insert a card containing this authorization, createocs prompts you to insert the card to be erased.

As an alternative, you can reformat using slotinfo --format.

Erasing softcards

Erasing a softcard deletes all information about the softcard from the host. You can erase softcards using KeySafe or with the ppmk command-line utility.

Erasing softcards with KeySafe

To erase softcards with KeySafe:

Start KeySafe.
Click the Softcards menu button. KeySafe takes you to the Softcard Operations panel.
Select the softcard you want to erase from the list.
Click the Discard Softcard button.
KeySafe asks you to confirm that you want to erase this card. Click Yes to confirm.
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:

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

If you are working within a FIPS 140 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 ACS 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 the front panel, KeySafe or the nfkminfo command-line utility. To check which passphrase is associated with a card, you can use the front panel or 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 passphrase is associated with a softcard, you can use the ppmk command-line utility.

Viewing card sets using the nShield HSM front panel

You can use the unit front panel to view details of all the Operator Cards in a Security World or to view details of an individual Operator Card.

To view a list of all the card sets in the Security World, from the front panel select Security World mgmt > Cardset operations > List cardsets.

To view details of a single card using the unit front panel:

Insert the card into the unit.
From the main menu, select Security World mgmt > Card operations > Card details.
The type of the card (Administrator or Operator) is displayed with the number of the card in the card set.

Viewing card sets with KeySafe

You can use KeySafe to view details of all the Operator Cards in a Security World, details of individual OCSs or details of an individual Operator Card.

Examining a Card

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

Start KeySafe. (For an introduction to KeySafe and information on starting the software, see Using KeySafe.)
Click the Card Sets menu button, or select the Card sets menu item from the Manage menu. KeySafe takes you to the List Operator Card Sets panel.
Click Examine/Change Card to open the Examine/Change Card panel.
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 passphrase (if it has one)
Give a passphrase to a card that does not already have one
Remove a passphrase from a card that currently has one
Erase the card.

List an Operator Card Set

In order to view information about whole OCSs with KeySafe, follow these steps:

Start KeySafe. (For an introduction to KeySafe and information on starting the software, see Using KeySafe.)
Click the Card Sets menu button, or select the Card sets menu item from the Manage menu. KeySafe takes you to the List Operator Card Sets panel, which displays information about all OCSs in the current Security World.

From the List Operator Card Sets panel, you can also:

Examine / change a card (see Examining a Card)
Create a new card set (see Creating an Operator Card Set with KeySafe)
Replace an Operator Card Set (see Replacing OCSs with KeySafe)
Discard a card set (see Erasing cards with KeySafe).

Viewing card sets using 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 OCSs 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).

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

Not all software can give names to individual cards.

Viewing softcards

To view softcards, use KeySafe or the command line. The command line provides several options for viewing softcard information.

Viewing softcards with KeySafe

To view a softcard with KeySafe, follow these steps:

Start KeySafe.
Click the Softcards menu button. KeySafe takes you to the Softcard Operations panel.
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. For more information about this procedure, see Erasing 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

Viewing softcards with ppmk

To list the softcards in the current Security World using the ppmk command-line utility, use the command:

ppmk --list

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:

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

Verifying the passphrase of a card or softcard

Verifying the passphrase of a card using the nShield HSM front panel

To verify the passphrase associated with a card using the unit front panel:

Insert the card into the unit.
From the main menu, select Security World mgmt > Card operations > Check PIN.

The type of the card (Administrator or Operator) is displayed with the number of the card in the card set.
If this is the card that you want to check, press the right-hand navigation to confirm.
Enter the passphrase.

If the passphrase that you entered is correct, a confirmation message is shown. Otherwise, an error is reported.

Verifying the passphrase of a card with cardpp

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

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

This command uses the following options:

Option Description

Option	Description
`--check`	This option checks the passphrase.
`--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.

--check

This option checks the passphrase.

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

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 passphrase is set or prompts you to enter the passphrase and checks to see if it is correct.

Verifying the passphrase of a softcard with ppmk

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

ppmk --check <NAME>|<IDENT>

In this command, you can identify the softcard whose passphrase 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 passphrase and then tells you whether the passphrase you entered is correct for the specified softcard.

Changing card and softcard passphrase

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

Normally, in order to change the passphrase of a card or softcard, you need the card or softcard and the existing passphrase. Known card passphrase can be changed using the front panel, KeySafe or the cardpp command-line utility; softcard passphrase can be changed using KeySafe or the ppmk command-line utility. You can also add a passphrase to a card or softcard that currently does not have one or remove a passphrase from a card that does currently have one.

If you generated your Security World with the passphrase replacement option, you can also replace the passphrase of a card or softcard even if you do not know the existing passphrase. Such a passphrase replacement operation requires authorization from the ACS.

Changing known passphrase

To change a card passphrase, you need the card and the old passphrase.

Each card in a set can have its own individual passphrase. You can even have a set in which some cards have a passphrase and others do not.

Prior to Security World Software v11.72, we set no absolute limit on the length of a passphrase. However, some applications may not accept a passphrase 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. Entrust recommends that your password only contains 7-bit ASCII characters:

A-Z, a-z, 0-9, ! @ # $ % ^ & * - _ + = [ ] { } | \ : ' , . ? / ` ~ " < > ( ) ;

See Maximum passphrase length for more about passphrase length when using Security World Software v11.72.

Changing known passphrase from the unit front panel

To change the passphrase of a card using the unit front panel:

Insert the card.
From the main menu, select Security World mgmt > Card operations > Change PIN.
Select the card whose passphrase you want to change.
Enter the old passphrase, and then enter it again to confirm it.
Enter the new passphrase. If you do not want this card to have a passphrase, select NO at the prompt.

Changing known passphrase with KeySafe

To change a known passphrase for an Operator Card using KeySafe:

Start KeySafe. (For an introduction to KeySafe and information on starting the software, see Using KeySafe.)
Click Card sets, or select Card sets from the Manage menu. The List Operator Card Sets panel is displayed.
Click Examine / change card to open the Examine / Change Card panel.
Click Change passphrase. The Set Card Protection passphrase panel is displayed.
Enter the old passphrase, and click the OK button.
A screen is displayed asking Do you want to set a passphrase?. Select Yes.
Enter your new passphrase, and enter it again in the second box as confirmation of the change.
Click OK.

Changing a known softcard passphrase with KeySafe

To change a known passphrase for a softcard using KeySafe:

Start KeySafe. (For an introduction to KeySafe and information on starting the software, see Using KeySafe.)
Click the Softcards menu button, or select Softcards from the Manage menu. KeySafe takes you to the List Softcards panel.
Select the softcard for which you want to change the passphrase, and click the Change passphrase button. KeySafe takes you to the Change/Recover Softcard passphrase panel.

If a softcard is listed as PIN Recovery Enabled = No, then you will be unable to change the passphrase.
Select the softcard whose passphrase you want to change, and click the Change passphrase button. KeySafe takes you to the Get Softcard Protection passphrase panel.
Enter the old passphrase, and click the OK button.

KeySafe either displays an error dialog (if the passphrase is not correct) or takes you to the Set Softcard Protection passphrase panel.
Enter your new passphrase, and enter it again in the second field to confirm the passphrase is correct.
Click the OK button.

After changing a passphrase, KeySafe displays a dialog to confirm that the passphrase has been successfully changes.
Click the OK button to continue using KeySafe.

Changing known passphrase with cardpp

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

With Security World Software v11.72 and later, passphrases are limited to a maximum length of 254 characters, when using cardpp. See Maximum passphrase length.

To change a known card’s passphrase with the cardpp command-line utility, take the following steps:

Run the cardpp utility using the command:
```
cardpp --change [-m|--module=<MODULE>]
```
If you only have one HSM, <MODULE> is 1. If you do not specify an HSM number, cardpp uses all HSMs by default.
If prompted, insert the card whose passphrase you want to change. (If there is a card already in the slot, you are not prompted.)
If prompted, enter the existing passphrase for the card (If the card has no current passphrase you are not prompted.) If you enter the passphrase correctly, cardpp prompts you to enter the new passphrase.
Enter a new passphrase, and then enter it again to confirm it.

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

Changing known softcard passphrase with ppmk

With Security World Software v11.72 and later, passphrases are limited to a maximum length of 254 characters, when using ppmk. See Maximum passphrase length for more information.

To change a known softcard’s passphrase when you know the passphrase, follow these steps:

Give the following command:
```
ppmk --change <NAME>|<IDENT>
```
In this command, you can identify the softcard whose passphrase you want to change either by its name (<NAME>) or by its logical token hash as listed by nfkminfo (<IDENT>).

ppmk prompts you to enter the old passphrase.
Type the old passphrase, and press Enter. If you enter the old passphrase correctly, ppmk prompts you to enter the new passphrase.
Type the old passphrase, and press Enter. Type the new passphrase again, and press Enter to confirm it.

After you have confirmed the new passphrase, ppmk then changes the softcard’s passphrase.

Changing unknown or lost passphrase

Changing unknown card passphrase with cardpp

If you generated your Security World with the passphrase replacement option, you can change the passphrase of a card even if you do not know its existing passphrase. Such a passphrase replacement operation requires authorization from the ACS.

To change an unknown card passphrase with the cardpp command-line utility:

Run a command of the form:
```
cardpp --recover [--module=<MODULE>]
```
In this command, <MODULE> specifies the number of the hardware security module to use. If you only have one hardware security module, <MODULE> is 1. If you do not specify a number, cardpp uses all hardware security modules by default.
As prompted, insert the appropriate number of cards from the ACS required to authorize passphrase replacement.
When prompted, insert the Operator Card whose passphrase you want to replace. To replace its passphrase:
1. When prompted, type the new passphrase, and then press Enter.
2. When prompted, type the new passphrase again to confirm it, and then press Enter.
  
  cardpp sets the new passphrase, and then prompts you for another Operator Card.
Repeat the process in the previous step to change the passphrase on further cards, or press Q to quit.

Only insert Administrator Cards into a hardware security module that is connected to a trusted server.

Replacing unknown passphrase with ppmk

If you generated your Security World with the passphrase replacement option, you can change the passphrase of a softcard even if you do not know its existing passphrase. Such a passphrase replacement operation requires authorization from the ACS.

To change an unknown softcard passphrase with the ppmk command-line utility:

Run a command of the form:
```
preload --admin=p ppmk --recover <NAME>|<IDENT>
```
In this command, you can identify the softcard by its <NAME> or by its <IDENT> (its logical token hash as shown in output from the nfkminfo command-line utility).
As prompted, insert the appropriate number of cards from the ACS required to authorize passphrase replacement.
When prompted, type the new passphrase, and then press Enter.
When prompted, type the new passphrase again to confirm it, and then press Enter.

If the passphrase does not match, ppmk prompts you to input and confirm the passphrase again.

After you successfully confirm the new passphrase, ppmk finishes configuring the softcard to use the new passphrase.

Only insert Administrator Cards into a hardware security module that is connected to a trusted server.

Replacing Operator Card Sets

Replacing an OCS requires authorization from the ACS of the Security World to which it belongs. You cannot replace an OCS unless you have the required number of cards from the appropriate ACS.

If you have lost a card from a card set, or you want to migrate from standard nShield cards to nShield Remote Administration Cards, you should use one of the following:

The rocs utility
The KeySafe Replace Operator Card Set option.

Accessed from the Card Operations panel.

You cannot mix standard nShield cards with nShield Remote Administration Cards. in the same set.

We recommend that after you have replaced an OCS, you then erase the remaining cards in the old card set and remove the old card set from the Security World. For more information, see Erasing cards and softcards.

Deleting the information about an OCS from the client does not remove the data for keys protected by that card set. On the KeySafe Key Operations panel), such keys are listed as being protected by Deleted Card Set.

To prevent you from losing access to your keys if the smart card you are using as the Operator Card is lost or damaged, Entrust supplies several utilities that can recover the keys protected by the lost Operator Card to another OCS

Replacing one OCS with another OCS also transfers the keys protected by the first OCS to the protection of the new OCS.

When you replace an OCS or softcard and recover its keys to a different OCS or softcard, the key material is not changed by the process. The process deletes the original Security World data (that is, the encrypted version of the key or keys and the smart card or softcard data file) and replaces this data with host data protected by the new OCS or softcard.

To replace an OCS or softcard, you must:

Have enabled OCS and softcard replacement when you created the Security World

If you did not enable OCS and softcard replacement, you cannot recover keys from lost or damaged smart cards or softcards.

Have created the original OCS using the front panel of the unit, createocs, createocs-simple, KeySafe, or the nShield PKCS #11 library version 1.6 or later

If you initialized the token using ckinittoken from the nShield PKCS #11 library version 1.5 or earlier, you must contact Support to arrange for them to convert the token to the new format while you still possess a valid card.

Have a sufficient number of cards from the ACS to authorize recovery and replacement

All recovery and replacement operations require authorization from the ACS. If any of the smart cards in the ACS are lost or damaged, immediately replace the entire ACS.
Have initialized a second OCS using the front panel of the unit, createocs, createocs-simple, KeySafe, or the nShield PKCS #11 library version 1.6 or later.

The new OCS need not have the same K/N policy as the old set.

If you are sharing the Security World across several client computers, you must ensure that the changes to the host data are propagated to all your computers. One way to achieve this is to use client cooperation. For more information, see Setting up client cooperation.

Replacing OCSs from the unit front panel

To replace an OCS from the unit front panel, follow these steps:

From the main menu, select Security World mgmt > Admin operations > Recover keys.
Select all to recover all keys in the Security World, or select the application for which you want to recover the keys.
If you selected an application, select the keys that you want to recover.
Insert the required number of Administrator Cards to recover keys, and enter their passphrases if required.
Insert the required number of Operator Cards, and enter their passphrases if required.

When you have inserted the required number of cards, details of the recovered key are displayed.
Check the key details are correct and then scroll down and select Recover key.

You can also select More info to see more information about the keys.

A message is displayed when the keys are recovered.

Replacing OCSs with KeySafe

In order to replace an OCS, you must have another OCS onto which to copy the first set’s data. If you do not already have an existing second OCS, you must create a new one. For more information, see Creating Operator Card Sets (OCSs).

When you have a second OCS ready, follow these steps in order to replace the first OCS:

Start KeySafe. (For an introduction to KeySafe and information on starting the software, see Using KeySafe.)
Click the Card Sets menu button, or select Card Sets from the Manage menu. KeySafe takes you to the List Operator Card Sets panel.

Click Replace card set. KeySafe takes you to the Replace card set panel.

This panel lists existing OCSs in tabular form. For each card set it displays:

Attribute	Description
Name	The name of the card set.
Required (K)	The number of cards needed to re-create a key.
Total (N)	The total number of cards in the set.
Persistent	Indicates whether or not the card set is persistent.
Timeout	The timeout value of the card, in seconds
Recoverable Key Count	The number of private keys protected by this card set that are recoverable.
Nonrecoverable Key Count	The number of private keys protected by this card set that are not recoverable.

Attribute

Description

Name

The name of the card set.

Required (K)

The number of cards needed to re-create a key.

Total (N)

The total number of cards in the set.

Persistent

Indicates whether or not the card set is persistent.

Timeout

The timeout value of the card, in seconds

Recoverable Key Count

The number of private keys protected by this card set that are recoverable.

Nonrecoverable Key Count

The number of private keys protected by this card set that are not recoverable.

You can click and drag with your mouse in order to resize the column widths and to rearrange the column order of this table. Clicking a column heading sorts the rows in ascending order based on that column heading.

Select an OCS that you want to replace, and click Replace card set.

If an OCS does not have any recoverable keys, it cannot be replaced.
KeySafe takes you to the Load Administrator Card Set panel, where it prompts you to insert cards from the ACS in order to authorize the action. Each time you insert an Administrator Card into the smart card of the hardware security module slot, you must click the OK button to load the card.

Only insert your ACS into a module that is connected to a trusted server.
When you have loaded enough cards from the ACS to authorize the procedure, KeySafe takes you to the Load Operator Card Set panel, where it prompts you to insert the OCS that is to protect the recoverable keys (this is the OCS onto which you are copying data from the OCS you are replacing). Each time you insert a card from the new OCS into the smart card slot of the hardware security module, you must click the OK button.

When you have loaded enough cards from the new OCS, KeySafe creates new working versions of the recoverable keys that are protected by this card set.

KeySafe deletes the original host data for all recovered keys and replaces this data with host data that is protected by the new OCS. If there are no nonrecoverable keys protected by the card set, KeySafe also removes the old card set from the Security World. However, if the OCS has nonrecoverable keys, the host data for the original card set and for the nonrecoverable keys is not deleted. These keys can only be accessed with the original OCS. If you want to delete these files, use the Remove OCS option.
When the process is complete, KeySafe displays a dialog indicating that the OCS has been successfully replaced. Click the OK button. KeySafe returns you the Replace Operator Card Set panel, where you may replace another OCS or choose a different operation.

Replacing OCSs or softcards with rocs

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

Using rocs interactively

To use the rocs command-line utility interactively, run it without any parameters:

rocs

rocs displays the following prompt:

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

In order to use rocs to replace an OCS or recover keys to a softcard, take the following steps:

You must select a hardware security module to use by using the module command, which is described in the section module <number>.
List the OCSs and softcards in the current Security World by using the list cardsets command, which is described in the section list cardsets.
Select the OCS or softcard to which you want to transfer the keys by using the target command, which is described in the section target <cardset-spec>.

Keys protected by an OCS can only be recovered to another OCS, and not to a softcard. Likewise, softcard-protected keys can only be recovered to another softcard, and not to an OCS.
List the keys in the current Security World using the list keys command, which is described in the section list keys.
Select the keys that are to be recovered (from a different OCS or softcard than the one you selected for key transfer) by using the mark command, which is described in the section mark <key-spec>.
If you have selected any keys by mistake, deselect them by using the unmark command, which is described in the section unmark <key-spec>.
After you have selected the keys that are to be recovered, transfer these keys by using the recover command, which is described in the section recover.

rocs prompts you to insert a card from the ACS.
Insert a card from the ACS.

rocs prompts you for the passphrase for this card. This action is repeated until you have loaded the required number of cards from the ACS.

If you do not have the required number of cards from the ACS, press Q and then Enter. The rocs utility returns you to the rocs > prompt without processing any keys.

Only insert Administrator Cards into a hardware security module that is connected to a trusted server.
If you are recovering keys to an OCS:
1. rocs prompts you to insert a card from the first OCS that you have selected as the target. OCSs are processed in ascending numerical order as listed by the list cardsets command.
2. Insert a card from this OCS.
3. rocs prompts you for the passphrase for this card. This action is repeated until you have loaded the required number of cards from the OCS.
If you are recovering keys to a softcard, rocs prompts you for the passphrase for the softcard that you have selected as the target.

If you decide that you do not want to transfer the keys to the selected card set or softcard, press Q and then Enter to quit. rocs returns you to the rocs > prompt and does not process any further OCSs or softcards.

When you have loaded the target softcard or the required number of cards from the target OCS, rocs transfers the selected keys to the target OCS or softcard.

If you have selected other target OCSs or softcards, rocs prompts for a card from the next OCS.
Repeat step 9 for each selected target.
If you have transferred the correct keys, write the key blobs to disk by using the save function (described in the section save <key-spec>). If you have transferred a key by mistake, you can restore it to its original protection by using the revert command (described in the section revert <key-spec>).

At the rocs prompt, you can use the following commands:

help <topic>
help intro
list cardsets
list keys
mark <key-spec>
module <number>
quit
recover
rescan
revert <key-spec>
save <key-spec>
status
target <cardset-spec>
unmark <key-spec>

You can specify a command by typing enough characters to identify the command uniquely. For example, for the status command, you can type st and then press Enter.

help

With no arguments specified, help shows a list of available commands with brief usage messages and a list of other help topics. With an argument, help shows detailed help information about a given topic.

help intro displays a brief step-by-step guide to using rocs.

list cardsets

This command lists the OCSs and softcards in the current Security World.

For example:

No.
Name                    Keys (recov) Sharing
 1 test                    6 (6)        3 of 5; 20 minute timeout
 2 test2                   3 (2)        2 of 3
 3 test3                   1 (1)        1 of 1; persistent

In this output:

Output Description

Output	Description
`No.`	The card set or softcard number, which you can use to identify this card set in `rocs` commands.
`Name`	The OCS or softcard name.
`Keys`	The number of keys protected by this OCS or softcard.
`(recov)`	The number of keys protected by this OCS or softcard.
`Sharing`	The K of N parameters for this OCS.
`persistent`	The OCS is persistent and does not have a time-out set.
### `minute timeout`	The OCS is persistent and has a time-out set.

No.

The card set or softcard number, which you can use to identify this card set in rocs commands.

Name

The OCS or softcard name.

Keys

The number of keys protected by this OCS or softcard.

(recov)

The number of keys protected by this OCS or softcard.

Sharing

The K of N parameters for this OCS.

persistent

The OCS is persistent and does not have a time-out set.

### minute timeout

The OCS is persistent and has a time-out set.

list keys

This command lists the keys in the current Security World, as in the following example:

No.
Name                     App        Protected by
 1 rsa-test                 hwcrhk     module
 2 Id: uc63e0ca3cb032d71c1c pkcs11     test2
R 3 Server-Cert              pkcs11     test --> test2
 4 Id: uc63e0ca3cb032d71c1c pkcs11     test --> test3
 5 Server-Cert              pkcs11     module (test ---> fred2)

In this output:

Output Description

Output	Description
`No.`	The key number, which you can use in `mark` and `unmark` commands.
`Name`	The key name.
`App`	The application with which the key is associated.
`Protected by`	This indicates the protection method (see table below).

No.

The key number, which you can use in mark and unmark commands.

Name

The key name.

App

The application with which the key is associated.

Protected by

This indicates the protection method (see table below).

In this output, the protection methods include:

Method

Description

module

Key protected by the Security World.

name

Key protected by the named OCS or softcard.

name-->name2

Key protected by the OCS or softcard name1 marked for recovery to OCS or softcard name2.

module (name)

PKCS #11 public object. These are protected by the Security World but associated with a specific OCS or softcard.

module (name-->name2)

PKCS #11 public object marked for recovery.

mark <key-spec>

This command marks the listed keys that are to be recovered to the target OCS or softcard. You can mark one or more keys by number, ident, OCS or softcard, or hash. For more information, see Specifying keys.

To mark more than one key at a time, ensure that each key-spec is separated from the other by spaces, as in the following example:

mark key-spec1 key-spec2 key-spec3

If you have not selected a target OCS or softcard, or if rocs cannot parse the key-spec, then rocs displays an error message.

You can mark and remark the keys to be recovered to various target OCSs or softcards. Remarking a key displaces the first target in favor of the second target.

Keys protected by an OCS can only be recovered to another OCS, and not to a softcard. Likewise, softcard-protected keys can only be recovered to another softcard, and not to an OCS.

module <number>

This command selects the hardware security module to be used. The module number must correspond to a hardware security module in the current Security World. If the hardware security module does not exist, is not in the Security World, or is otherwise unusable, then rocs displays an error message and does not change to the selected module.

quit

This command allows you to leave rocs. If you attempt to quit when you have recovered keys but have not saved them, rocs displays a warning.

recover

This command transfers the marked keys to their target OCSs or softcards. This operation is not permanent until you save these keys by using the save command.

rescan

This command updates the card set and key information.

revert <key-spec>

This command returns keys that have been recovered, but not saved, to being protected by the original protection method. If the selected keys have not been recovered, rocs displays an error message.

save <key-spec>

This command writes the new key blobs to disk. If you specify a key-spec, only those keys are saved. Otherwise, all recovered keys are saved.

status

This command lists the currently selected hardware security module and target OCS or softcard.

target <cardset-spec>

This command selects a given OCS or softcard as the target. You can specify the card set or softcard name, the number returned by list cardsets, or the hash.

unmark <key-spec>

This command unmarks the listed keys. Unmarked keys are not recovered.

Using rocs from the command line

You can select all the options for rocs using the command line by running a command of the form:

rocs -m|--module=<MODULE> [-t|--target=<CARDSET-SPEC>] [-k|--keys=<KEYS-SPEC>] [-c|--cardset=<CARDSET-SPEC>] [-i|--interactive]

In this command:

Option Description

-m|--module=<MODULE>

These options specify the number of the hardware security module to use.

-t|--target=<CARDSET-SPEC>

These options specify the OCS or softcard to be used to protect the keys. For more information, see Specifying card sets.

-k|--keys=<KEYS-SPEC>

These options select the keys to be recovered. For more information, see Specifying keys.

-c|--cardset=<CARDSET-SPEC>

These options select all keys that are protected by the given OCS or softcard. For more information, see Specifying card sets.

-i|--interactive

These options force rocs to start interactively even if you have already selected keys.

You must specify the target before you specify keys.

You can use multiple --keys=<KEYS-SPEC> and --cardset=<CARDSET-SPEC> options, if necessary.

You can specify multiple targets on one command line by including separate --keys=<KEYS-SPEC> or --cardset=<CARDSET-SPEC> options for each target. If a key is defined by --keys=<KEYS-SPEC> or --cardset=<CARDSET-SPEC> options for more than one target, it is transferred to the last target for which it is defined.

If you have selected a hardware security module, a target OCS or softcard, and keys to recover but have not specified the --interactive option, rocs automatically recovers the keys. rocs prompts you for the ACS and OCS or softcard. For more information, see Using rocs interactively.

If you use rocs from the command line, all keys are recovered and saved automatically. You cannot revert the keys unless you still have cards from the original OCS.

If you do not specify the target and keys to recover, or if you specify the --interactive option, rocs starts in interactive mode with the selections you have made. You can then use further rocs commands to modify your selection before using the recover and save commands to transfer the keys.

Specifying card sets

The value of <CARDSET-SPEC> identifies one or more OCSs or softcards. It may have any of the following forms:

Value Description

[number] cardset-number

A value of this form selects the OCS or softcard with the given number from the list produced by the list cardsets command.

[name] cardset-name

A value of this form selects card sets or softcards by their names (the card set or softcard name may be a wildcard pattern in order to select all matching OCSs or softcards).

hash cardset-hash

A value of this form selects the OCS or softcard with the given hash.

In order to specify multiple OCSs or softcards, include several CARDSET-SPEC's using the command line.

Keys protected by an OCS can only be recovered to another OCS, and not to a softcard. Likewise, softcard-protected keys can only be recovered to another softcard, and not to an OCS.

Specifying keys

The --keys=<KEYS-SPEC> option identifies one or more keys. It may have any of the following forms:

Value Description

mark key-number

A value of this form selects the key with the given number from the list produced by the list keys command. Examples of usage are:

rocs -t <target_OCS> -k <key_number>

and

rocs -t <target_OCS> -k "mark 56"

appname_:keyident

A value of this form selects keys by their internal application name and ident. You must supply at least one of appname or keyident, but you can use wildcard patterns for either or both in order to select all matching keys. An example of usage is:

rocs -t <target_OCS> --keys="simple:simplekey"

hash keyhash

A value of this form selects the key with the given key hash. An example of usage is:

rocs -t <target_OCS> --keys="hash e364[...]"

--cardset cardset-spec

A value of this form selects all keys protected by a given card set.

Replacing the Administrator Card Set

Replacing the ACS requires a quorum of cards from the current ACS (K/N) to perform the following sequence of tasks:

loading the secret information that is to be used to protect the archived copy of the Security World key.
creating a new secret that is to be shared between a new set of cards.
creating a new archive that is to be protected by this secret.

If you discover that one of the cards in the current ACS has been damaged or lost, or you want to migrate from standard nShield cards to nShield Remote Administration Cards, you should use one of the following to create a new set:

The racs utility.

When using the racs utility, you cannot redefine the quantities in a K of N relationship for an ACS. The K of N relationship defined in the original ACS persists in the new ACS.
The front panel of the nShield HSM.
The KeySafe Replace Administrator Card Set option.

Accessed from the Card Operations panel.

If further cards are damaged, you may not be able to re-create your Security World.

You cannot mix nShield cards with nShield Remote Administration Cards in the same set.

Replacing the ACS modifies the world file. In order to use the new ACS on other machines in the Security World, you must copy the updated world file to all the machines in the Security World after replacing the ACS. Failure to do so could result in loss of administrative access to the Security World.

We recommend that you erase your old Administrator Cards as soon as you have created the new ACS. An attacker with the old ACS and a copy of the old host data could still re-create all your keys. With a copy of a current backup, they could even access keys that were created after you replaced the ACS.

Before you start to replace an ACS, you must ensure that you have enough blank cards to create a complete new ACS. If you start the procedure without enough cards, you will have to cancel the procedure part way through.

Replacing an Administrator Card Set using the nShield HSM front panel

To replace an ACS:

From the main menu, select Security World mgmt > Admin operations > Replace ACS.
Insert one of the remaining cards from the card set that you want to replace and press the right-hand navigation button.

Continue to insert cards until you have inserted the number of cards required to authorize the process.
When prompted, insert a card for the replacement card set and press the right-hand navigation button.
If required, specify a passphrase for the card.
Insert cards until the card set is complete. A message confirms that the card set has been created.
At this point the modified world file has been pushed to the RFS, so make a backup of the modified world file on the RFS, preferably in a way that distinguishes it from previous backups.
Copy the world file to any other HSMs in the same Security World, either using the Security World mgmt > RFS operations > Update World files option on the HSM concerned or using the nethsmadmin utility, see Using nethsmadmin to copy a Security World to a nShield HSM and check the current version.
If client cooperation is not enabled, copy the modified world file onto any client machines where it is needed.
Check that the new Administrator Cards are usable and that their passphrases have been set as intended, see Verifying the passphrase of a card or softcard
Erase the Administrator Cards from the old card set. For more information, see Erasing cards and softcards.

Replacing an ACS with KeySafe

When you have enough cards to create a complete new ACS ready and a quorum of the ACS you want to replace, follow these steps:

Start KeySafe. (For an introduction to KeySafe and information on starting the software, see Using KeySafe).
Click the Card sets menu button, or select Card sets from the Manage menu. KeySafe takes you to the List Operator Card Sets panel.
Click the Replace ACS navigation button, and KeySafe takes you to the Replace Administrator Card Set panel.
If you are sure that you want to replace the ACS, click the Replace ACS command button
KeySafe takes you to the Load Administrator Card Set panel, where it prompts you to insert cards from the ACS in order to authorize the action. Each time you insert an Administrator Card into the module’s smart card slot, you must click the OK button to load the card.

Only insert cards from your ACS into a module that is connected to a trusted server.

When you have loaded enough Administrator Cards to authorize the action, KeySafe takes you to the Create Administrator Card Set panel, where it prompts you to insert the cards that are to form the ACS. These must be blank cards or cards that KeySafe can erase. KeySafe will not let you use cards from the existing ACS. If you do not have enough cards to form a complete new ACS, cancel the operation now.

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

When you insert a blank card, KeySafe takes you to the Set Card Protection passphrase panel.
If you want to set a passphrase for this Administrator Card:
1. Select the Yes option.
2. Enter the same passphrase in both text fields.
3. Click the OK button.
KeySafe then prompts you for the next card (if any). A given passphrase is associated with a specific card, so each card can have a different passphrase. You can change these passphrases at any time by using the KeySafe Examine/Change Card option (available from the List Operator Card Sets panel) or the cardpp command-line utility.
If you do not want to set a passphrase for this Administrator Card:
1. Select the No option.
2. Click the OK button.
After you have created all the Administrator Cards, KeySafe displays a message confirming that the ACS has been successfully replaced.
Click the OK button, and KeySafe returns you to its introduction panel.

When you have finished replacing the ACS:

If you ran KeySafe on a client machine, ensure that there is a copy of the modified world file on the RFS.
Make a backup of the world file, preferably in a way that distinguishes it from previous backups.
Copy the world file to any other HSMs in the same Security World, for example using the nethsmadmin utility, see Using nethsmadmin to copy a Security World to an nShield HSM and check the current version.
If client cooperation is not enabled, copy the modified world file onto any other client machines where it is needed.
Check that the new Administrator Cards are usable and that their passphrases have been set as intended, see Verifying the passphrase of a card or softcard.
Erase the old Administrator Cards; for more information, see Erasing cards and softcards.

Replacing an Administrator Card Set using racs

The racs utility creates a new ACS to replace a set that was created on the module with the new-world utility.

When using the racs utility, you cannot redefine the quantities in a K of N relationship for an ACS. The K of N relationship defined in the original ACS persists in the new ACS.

Ensure the hardware security module is in operational mode.
Run a command of the form:
```
racs [-m|--module=<MODULE>]
```
In this command, the -m|--module=<MODULE>` option specifies the ModuleID (<MODULE>) of the module to use.
When prompted, insert the appropriate quorum of Administrator Cards to authorize the replacement.
When prompted that racs is writing the new ACS, insert blank cards as necessary on which to write the replacement Administrator Cards.
If you ran racs on a client machine, ensure that there is a copy of the modified world file on the RFS.
Make a backup of the world file, preferably in a way that distinguishes it from previous backups.
Copy the world file to any other HSMs in the same Security World, for example using the nethsmadmin utility, see Using nethsmadmin to copy a Security World to an nShield HSM and check the current version.
If client cooperation is not enabled, copy the modified world file onto any other client machines where it is needed.
Check that the new Administrator Cards are usable and that their passphrases have been set as intended, see Verifying the passphrase of a card or softcard.
Erase the old Administrator Cards; for more information, see Erasing cards and softcards.