You are on page 1of 6

Working with nCipher keys and operator

Last update November 19, 2014


 Retargeting the web server private key

 Removing the pass phrase from an operator card

 Creating a new operator card set

 Consolidating operator card sets

This section is intended to provide information about how the web server private key can be prepared
for use with the TIM. The Thales-nCipher utilities operations described herein should be executed on
the web server.

Important! Before you start, make a backup copy

of /opt/nfast/kmdata/local (or %NFAST_KMDATA%\local on Windows). This is important for both the
TIM machine and for the web server.

Retargeting the web server private key

Note: This section assumes that you have a private key, which was generated by nCipher, for your
web server.

The nCipher security world can make keys available to a variety of Application Programming Interfaces
(APIs) such as PKCS#11, Java JCE, OpenSSL, Microsoft CAPI (on Windows) and the nCipher native
API. Depending on the application type chosen when generating the key, different information is
stored with the actual encrypted key material to facilitate access from that API.

Existing keys can be made available to other applications. This process is called retargeting. The
retargeting operation saves a new key blob to the file system, containing the same encrypted key
material and new access information specific to the new application type.

The following is a non-exhaustive list of APIs used by various web server software packages:

Server Platforms API Application

Apache All OpenSSL embed

Sun ONE All PKCS#11 pkcs11

MS IIS Windows MS CAPI mscapi

Tomcat All (Java) JCE jce

The TIM machine requires keys of application type embed. Besides the encrypted key blob in
the /opt/nfast/kmdata/local directory, an embed key comes with an embedsavefile, a file that points
OpenSSL to the specific key blob to use.

To convert a Sun ONE web server key from application type pkcs11 to embed:

 To retarget a key of application type pkcs11 to type embed, refer to the example below.
For this example, the 1/N operator card named MyOCS which protects the key in question is
sitting in the HSM card reader. Use the Enter or Return key to accept default values.

$ /opt/nfast/bin/generatekey --retarget embed

from-application: Source application? (custom, embed, hwcrhk, pkcs11, simple)
[default custom] > pkcs11
from-ident: Source key identifier?
[default uc66d0f2df3103e32c5703e8de0cfb172a1b35cf82-
embedsavefile: Filename to write key to? []
> /tmp/webserver1.pem
plainname: Key name? [] > webserver1
key generation parameters:
operation Operation to perform retarget
application Application embed
slot Slot to read cards from 0
verify Verify security of key yes
from-application Source application pkcs11
ident Source key identifier uc66d0f2df3103e32c5703e8de0cfb172a1b35cf82-
embedsavefile Filename to write key to /tmp/webserver1.pem
plainname Key name webserver1

Loading `MyOCS':
Module 1: 0 cards of 1 read
Module 1 slot 0: `MyOCS' #1
Module 1 slot 0:- passphrase supplied - reading card
Card reading complete.
Key successfully retargetted.
Path to key: /opt/nfast/kmdata/local/key_embed_b4c36e18ff38d2d45a2df425abd9febfaf873d

Removing the pass phrase from an operator

To run the TIM unattended with OCS protected keys, one possibility is to remove the pass phrase from
the OCS card that sits in the TIM card reader.

Follow these steps:

 Use cardpp:

$ /opt/nfast/bin/cardpp --change -m 1

Checking/changing passphrase(s):
Module 1 slot 0: `MyOCS' #1
Module 1 slot 0: Enter passphrase: [^D: don
Module 1 slot 0:- passphrase supplied - reading card
Module 1 slot 0: Enter new passphrase: <return> [^D: don
Module 1 slot 0:- no passphrase specified - removing passphrase
Module #1 Slot #0: Processing ... [^D: don
Module 1 slot 0: `MyOCS' #1: Passphrase removed
Insert/change card in module (or change module mode) [^D: done


Note: The TIM can run with an OCS card without a pass phrase; however, the web server software
might not support this.

Creating a new operator card set

If the existing operator card set (OCS) is not large enough to accommodate the TIM, you can create a
new set.
For example, if you have an existing web server with a card set of one, you will need to create a new
set (of at least two cards) to allow for the TIM machine’s card as well.

Note: Do this on the TIM machine, on the retargeted key, using a local copy
of /opt/nfast/kmdata/local.

Follow these steps:

 Use createocs:

/opt/nfast/bin/createocs -Q 1/n -N name

where n is the card set size and name is the name to give your card set.
Once the new operator card set is created, keys can be recovered to it as described in Consolidating
operator card sets.

Consolidating operator card sets

If multiple keys are to be used by the TIM, it might be advantageous if they are protected by the
same operator card set (OCS). If you have multiple keys that are protected by different
OCS and those keys are part of the same security world and Recovery is enabled on those keys, you
can recover them all to the same OCS so they can be loaded and made accessible through a single

Follow these steps:

Note: This operation requires access to a quorum of the administrator card set (ACS) for

Important! Do not perform the rocs operation on a live web server key. Work on a copy, on the TIM

Note: If you need to retarget a key, do this before you manipulate the OCS. See Retargeting the web
server private key for more information.

1. To check whether a key has Recovery enabled, use nfkminfo:

$ /opt/nfast/bin/nfkminfo -k embed
Key listing AppName embed (1 keys):
AppName embed Ident 5dce27b0a84b517b0db7b5aa2f09452e27a13d38
$ /opt/nfast/bin/nfkminfo -k embed 5dce27b0a84b517b0db7b5aa2f09452e27a13d38
Key AppName embed Ident 5dce27b0a84b517b0db7b5aa2f09452e27a13d38
BlobKA length 1052
BlobPubKA length 444
BlobRecoveryKA length 1208
name "MyKey"
hash d96ee8282cc7f76ea32df1ce299ab087a206e530
recovery Enabled

2. Copy the identifier from the first invocation into the second. The recovery Enabled line shows
that the key can be recovered to a new OCS.

$ /opt/nfast/bin/rocs -i
`rocs' key recovery tool
Useful commands: `help', `help intro', `quit'.
rocs> list cardsets
No. Name Keys (recov) Sharing
1 iWorld1of1 0 (0) 1 of 1; persistent
2 NonPersistentOCS 9 (9) 1 of 1
rocs> target 1
rocs> list keys
No. Name App Protected by
1 MyKey caping module
2 MyKey caping module
3 MyKey embed module
4 Example label pkcs11 NonPersistentOCS
rocs> mark 4
rocs> recover

Authorising OCS replacement:

Module 1: 0 cards of 1 read
Module 1 slot 0: empty
Module 1 slot 0: Admin Card #1
... prompt for the ACS passphrase ...
Module 1 slot 0:- passphrase supplied - reading card
Card reading complete.

Loading `iWorld1of1':
Module 1: 0 cards of 1 read
Module 1 slot 0: Admin Card #1
Module 1 slot 0: empty
Module 1 slot 0: `iWorld1of1' #1
... prompt for the OCS passphrase ...
Module 1 slot 0:- passphrase supplied - reading card
Card reading complete.

rocs> save 4
rocs> quit