nCipher SSL card

For the nCipher SSL accelerator cards, only the nShield card is supported under 64-bit NAM Probe.

Before you begin

  • If a new nCipher accelerator card has been added to your NAM Probe (inserted into a free PCI slot), you must install the appropriate software. See Upgrading the NAM Probe software for information about upgrading your NAM Probe. Execute the upgrade with the nCipher card already physically present in the machine. If the appropriate upgrade is executed, but without the physical card being present, and the card is added later, you will need to execute the /opt/nfast/sbin/install command as user root :

NFAST_USER=nfast NFAST_GROUP=nfast /opt/nfast/sbin/install

  • The nCipher nShield requires that the computer on which they are installed has a "security world" installed on it, which is a collection of security files. The following procedure includes creating security world files for the nCipher card and initializing the card with the security world. If you have already created a suitable security world on another computer and wish to move the card from it to a new machine, you can copy the files to the new NAM Probe and install the card in it. You can also initialize the card on the other system before installing it in the NAM Probe. For details about creating a security world and initializing an accelerator card with a given security world, refer to the nCipher documentation.

Installing and configuring

Follow this procedure to install and configure an nCipher SSL card on a 64-bit NAM Probe.

Configure the security world and initialize the card (for nShield only).

To copy the security world from another system, copy the host data directory, kmdata, from that system to the /opt/nfast directory on the NAM Probe machine.

To define a new security world perform the following actions.

Note

To configure the card, change the settings of the M-O-I slider on the outside of the card to make the card go into pre-initialization mode or operational mode. However, the function of the slider may be overridden by an M-O-I override mechanism, that is found on the card itself, in the form of two little (most likely yellow) switches. When they are in the On position, the M-O-I slider switch on the outside of the card is not functional and the card is locked in operational mode. The M-O-I override switches are intended to prevent switching the card into a different mode by accident. When you are configuring the card, the override switches must be in the Off position.

More details about the override switches can be found in the nCipher documentation.

Log in to the host computer as user root .

Select pre-initialization mode.

Set the module switch on the back panel of the card to the I position.

Clear the module.

/opt/nfast/bin/nopclearfail ca

Create the security world.

/opt/nfast/bin/new-world -m 1 -s 0 -Q 2/3 -k rijndael

The above command creates a FIPS Level 2 compliant security world with OCS recovery and replacement enabled and a 2/3 ACS. The security world is protected by an AES key.

Note

If the new-world or nopclearfail utility returns an error, check that the mode switch on the back panel is fully in the correct position and then re-run the command.

If the error is persistent, reboot the NAM Probe device.

The new-world utility prompts you to insert a smart card to be written as an Administrator Card.

Insert a blank smart card and then press [Enter] .

Enter the pass phrase.

When prompted by the new-world utility, type a pass phrase for the Administrator Card and then press [Enter] .

Confirm the pass phrase.

When prompted by the new-world utility, confirm the pass phrase.

The new-world utility displays a message confirming that the card has been written and prompts you to insert the next smart card.

Continue the process until the required number of smart cards are written.

After the required number of smart cards are written, the new-world utility displays a message saying that the security world has been generated.

Select operational mode.

Set the module switch on the back panel of the card to the O position.

Clear the module.

/opt/nfast/bin/nopclearfail ca

For additional details about creating a security world and initializing an accelerator card with a given security world, refer to the nCipher documentation.

Check the status of the security world.

/opt/nfast/bin/nfkminfo

The World and Module should show as Usable in the state field, as on the following example output:

[root@NAM Probe bin]# /opt/nfast/bin/nfkminfo
World
 generation  2
 state       0x17270000 Initialized Usable Recovery !PINRecovery !ExistingClient RTC NVRAM FTO SEEDebug
 n_modules   1
 hknso       2f8bd0927068618e257a4560ff713840f741dd57
 hkm         86cb6d0125ae2e00b19e8ce2cfce55c7a7383ced (type Rijndael)
 hkmwk       1d572201be233ebc89f30fdd8f3fac6ca3395bf0
 hkre        ff96d3d69cc320ab6888cef38dfeac8e7875c2d4
 hkra        a228ebadeec32ce65bc47787dd85ce4d4b1e295b
 hkmc        ec303befbdae88b3d241fe8399fcccf7183f6741
 hkrtc       1ee7f656958c74f7ab435bbbd292859825939f69
 hknv        93a18da953d98850137dfe241c0b660ebde73417
 hkdsee      c40cd7127ebc544d162681db602a8b10cd2d8b9d
 hkfto       c0b65dfe6ce2ae268b3ba4683f2a282c1ce07ae3
 hkmnull     0100000000000000000000000000000000000000
 ex.client   none
 k-out-of-n  1/1
 other quora m=1 r=1 nv=1 rtc=1 dsee=1 fto=1
 createtime  2010-10-19 12:39:46
 nso timeout 10 min

Module #1
 generation 2
 state      0x2 Usable
 flags      0x10000 ShareTarget
 n_slots    2
 esn        77C2-2D3A-808B
 hkml       b09f35252189ecf88857c3cb21b53d2276eb7382

Module #1 Slot #0 IC 0

Add SSL private keys to the card.

If your SSL card is configured to read keys from the card and not from the keylist file, edit the file /usr/adlex/config/rtm.config, and set the following properties the following property to true:

ssl.import.all.keys.from.token=true

To add SSL private keys to an nShield accelerator card (to a card that is capable of storing SSL key information), use the generatekey command. For details on how to use this command, please refer to the nCipher documentation.

Figure 1. Example of Adding a New Private Key to an nCipher Card

Place the file containing the key (for example, s1.key) in /usr/adlex/config/keys

Change directory to /opt/nfast/bin :

cd /opt/nfast/bin

Run the command to store the key on the card:

./generatekey --import pkcs11 pemreadfile=/usr/adlex/config/keys/s1.key plainname=s1name ident=s1 protect=module type=RSA nvram=no

pemreadfile (entered as /usr/adlex/config/keys/s1.key in the above example) is the path to the SSL key you are importing. The value of plainname can then be used for the creation of a keylist file, if the search mechanism is set to label (searchKeyBy parameter set to label). It can be composed of any number of digits and lowercase letters; it cannot contain spaces, underscores (_), or hyphens (-).

The above command produces output of the following layout:

key generation parameters:
operation Operation to perform import
application Application pkcs11
verify Verify security of key yes
type Key type RSA
pemreadfile PEM file containing RSA key /usr/adlex/config/keys/s1.key
ident unknown parameter s1
plainname Key name s1name
nvram Blob in NVRAM (needs ACS) no
Key successfully imported.
Path to key: /opt/nfast/kmdata/local/key_pkcs11_uacce696c77c25cbb1fecbecef0adbac4bae54e63b

If you do not supply all of the necessary parameters to the above command, you are prompted for additional information. For example:

 Key type? (RSA, DES3, DES2) [RSA] >

Input the type of key you are importing. Most commonly this is an RSA key, so type RSA, then press [Enter] .

 plainname key name? [] >

Enter a name for the key you are importing and press [Enter] .

 Blob in NVRAM (needs ACS)? (yes/no) [no] >

You are prompted if you need to save the key blob in NVRAM. We recommend that you answer no, then press [Enter] . This is for ease and simplicity of administration. Answering yes requires you to insert the Administrator smart card for this step and potentially any subsequent operation performed on this key.

After answering all the above prompts correctly, a message appears:

 Key successfully imported

List the keys stored on the card (for nShield only).

To obtain a key identifier for the NAM Probe configuration, list the keys currently stored on the card and in the security world . Use the following utilities to obtain the information about available keys:

  •   The `list` `keys`  command from the command-line utility `/opt/nfast/bin/rocs` .
    

Figure 2. Example Output of the list keys Command
``` rocs> list keys No. Name App Protected by 1 s1name pkcs11 module 2 s2name pkcs11 module

  ```
  •   The `pkcsmgr`  command.
    

Figure 3. Example Output of the pkcsmgr Command
``` # /usr/adlex/rtm/bin/pkcsmgr list Using PKCS11 engine: ncipher_pkcs11 getting slotId from slotNum

pkcsmgr slot #492971157, token (accelerator) listing keys

type: CKO_PRIVATE_KEY/CKK_RSA, id: 2235e9df23d481260323868b77ce5bb134d97f1c, label: host2048-2, size: 256B type: CKO_PRIVATE_KEY/CKK_RSA, id: aa8458ed54ff9cf0a73a20aec4364aaaa32dea15, label: b02, size: 512B ```

Modify NAM Probe configuration settings.

Verify the SSL engine setting.

If the NAM Probe software has been upgraded correctly for the given nCipher card (see prerequisites above), the configuration file /usr/adlex/config/rtm.config contains the appropriate engine name:

ssl.engine=ncipher_pkcs11

Verify that this entry has been set correctly.

Append a new entry for your key in the /usr/adlex/config/keys/keylist file.

If you have configured your NAM Probe to use the keylist file to store the list of keys, append a new entry for your key to the file. The default full path to the file is /usr/adlex/config/keys/keylist .

In the keylist file, set the key_type attribute as token for a hardware key stored on the accelerator card. The key identifier value should be specified as given by the utilities that list keys. Note that the ncipher_pkcs11 engine distinguishes between key identifiers and key labels. Both of these identification methods can be used in the keylist file. However, you may need to specify the type of identification used by setting the searchKeyBy parameter of the ssl.engine.param property to id or label, as appropriate. For ncipher_pkcs11 the default is label.

See Management of RSA private keys on NAM Probe for information on configuring the NAM Probe to use the keylist file or token and for information on how to format entries in the keylist file.

See Selecting and configuring SSL engine for information on configuring the ssl.engine.param property.

Verify the installation

Example output from the enquiry command; the hardserver module is loaded:

nServer:
 enquiry reply flags  none
 enquiry reply level  Six
 serial number....
...
Module #1:
 enquiry reply flags  none
 enquiry reply level  Six
 serial number...
...

Removing nCipher security world

To remove the security world, follow one of these procedures, depending on whether you need to create a new security world afterwards or not.

If you need to remove a security world and replace it with a new one:

  1. Delete the files in the directory to which the NFAST_KMDATA environment variable points.
  2. Create a new security world.
  3. Add all your modules to this world.

If you need to completely remove a security world without replacing it with a new one:

  1. Remove all the modules from the security world.
  2. Delete the files in the directory to which the NFAST_KMDATA environment variable points.

For additional information, refer to the nCipher documentation.