CCA TOKEN

Overview

--------

The CCA token is a secure key token.

A Secure key - key value does not exist in the clear outside of the HSM

(secure, tamper-resistent boundary of the card). It is a clear key wrapped

with the appropriate MasterKey that has been installed into the secure hardware.

A clear key is generated in the hardware, wrapped with the appropriate

master key that has been installed into the hardware. The wrapped key is then

passed back to the invoker. Upon an encryption and/or decryption request,

the wrapped key and the data to be encrypted are passed into the hardware.

The wrapped key is verified, and the clear key is used to encrypt and/or

decrypt the data. All this is done in the CCA hardware.

Within openCryptoki, this wrapped key value is stored in the CKA_IBM_OPAQUE

attribute rather than the CKA_VALUE attribute.

Pre-requisites:

The CCA token requires cca library, libcsulcca.so, which is part of the

csulcca rpm.

It also requires proper configuration and installation of the MK keys into

the hardware which is outside the scope of this document.

Configuration

-------------

To use the CCA token a slot entry must be defined in the

opencryptoki.conf configuration file that sets the stdll attribute to

libcsulcca.so.

The CCA token also requires that the appropriate master keys have

been installed into the hardware. The corresponding driver must also be

loaded, i.e. modprobe z90crypt.

CCA Token Objects

-------------------------

openCryptoki stores token objects on disk. Public token objects are not

encrypted. Private token objects are encrypted.

Versions of openCryptoki prior to version 3, used a CCA generated secure key

(des3 key) and the crypto adapter to encrypt the private token object's data.

In version 3, a clear key (des3 key) and software crypto (openssl) are used

to encrypt this data.

Migration Information

---------------------

Migrating version 2 private token objects to version 3 is ONLY required if

the system will run openCryptoki version 3 and will use private token

objects saved or preserved from version 2.

Note, public token objects do not need to be migrated.

If there are no private token objects from version 2, then the version 3

does not require any migrating.

In version 2 private token objects are encrypted and decrypted with a secure

key in the crypto adapter. In version 3, this encryption and decryption is

done with a clear key using software crypto. Therefore, openCryptoki

version 3, will not successfully decrypt a version 2 private token object.

Version 2 private token objects must be "migrated" to version 3 so that

openCryptoki version 3 can access these objects. This migration will

decrypt the objects using the CCA call, CSNBDEC and the current

openCryptoki key stored in MK_USER. The objects will then be re-encrypted

using software crypto. The key bits that are stored in MK_USER will then be

used as a clear key.

Once the migration has completed, these private token objects should then be

accessible to version 3.

Migration Steps

---------------

1. Either update or install version 3.

a. Update to openCryptoki version 3. In most Linux distributions, an update

from version 2 to version 3 will preserve the contents of the CCA data-store.

b. Install openCryptoki version 3. In most distributions, an install will

remove the contents of the CCA data-store. You will essentially be starting

from the beginning and have to initialize the CCA token.

In this scenario, if a prior version of openCryptoki had been running on the

system, and you wanted to preserve your token objects, you will have saved

or backed them up somewhere.

2. Backup the CCA data-store before migrating. It is always a good idea to

back up the data in case the migration is unsuccessful or data is corrupted.

The data-store is the directory in which the CCA token information is stored

on disk. In most distributions it can be found in /var/lib/opencryptoki/ccatok.

Within this directory there is,

MK_USER: The des3 key used for internal on-disk encryption, encrypted

         under the USER's PIN by software routines

MK_SO: The des3 key used for internal on-disk encryption, encrypted

         under the SO's PIN by software routines

NKTOK.DAT: Token information.

TOK_OBJ: The directory in which token objects are stored.

TOK_OBJ/OBJ.IDX: A list of current token objects.

**NOTE: MK_USER and MK_SO contain the same key, encrypted under

different PINs

3. Ensure no openCryptoki processes are running. Stop the pkcsslotd daemon

if it is running.

4.  Run the pkcscca tool to perform the migration.

For example,

	pkcscca -m v2objectsv3 -v

Note that the "-v" option will allow you to see which objects did and did not

get migrated. Specify the "-d" flag if you wish to migrate CCA token objects

stored in a data-store different from the default, /var/lib/opencryptoki/ccatok.

5. (Optional) Removing shared memory may be required to pick up

the newly migrated objects.

CCA token's shared memory segment tracks its token objects.

Token objects stored on disk are only loaded into shared memory

when the shared memory is created. The shared memory is usually

created after a reboot, an install, or an update of the openCryptoki package.

If another openCryptoki process accessed the CCA token after install

or update, then openCryptoki will have loaded all the token objects into

shared memory, except for the private token objects requiring migration,

since they will have failed decryption. Subsequent calls to the

openCryptoki api will not find these objects since they have not

been loaded into shared memory. openCryptoki won't read the

objects from disk and load into shared memory again until the next time

shared memory is created.

So, in this case, shared memory must be removed and created again so

that openCryptoki can successfully load all the token objects including the

newly migrated private token objects into CCA token's shared memory segment.

Remove shared memory if,

 - after updating or installing, any openCryptoki processes or tools tried

   to access the CCA token before migrating CCA token's private token

   objects. For example, the pkcsconf command was run.

   The pre-migrated objects will have failed decryption and not

   been loaded into shared memory. A reboot or removing shared memory

   will cause the token to create shared memory again and load the newly

   migrated private token objects into it.

CCA's shared memory can be removed two ways.

	1. a reboot

	2. remove the shared memory file,

 	   i.e. "rm  /dev/shm/var.lib.opencryptoki.ccatok"

	   Notes: (1). Ensure that no openCryptoki processes are running

	   before removing the shared memory. Otherwise, you risk corrupting

	   any running openCryptoki processes.

	   (2). If you have installed openCryptoki manually (not via a distro

	   rpm) the CCA token shared memory segment may be named

	   usr.local.var.lib.opencryptoki.ccatok.

The next openCryptoki process to run will cause openCryptoki to create

a shared memory segment for the token and load the newly migrated objects

as well as any other token objects for the token.

6. After a successful migration, the CCA private token objects should be

encrypted and ready to be accessed by openCryptoki version 3.

TroubleShooting:

1. If version 3 cannot find the newly migrated CCA private token objects,

reboot or remove the shared memory file. This will cause token to create

shared memory again and load the newly migrated private token objects

into shared memory.

Key Migration Information

-------------------------

There may be situations when CCA master keys must be changed. All CCA secret

and private keys are enciphered (wrapped) with a master key (MK). After a CCA

master key is changed, the keys wrapped with an old master key need to be

re-enciphered with the new master key. Only openCryptoki keys with attribute

CKA_EXTRACTABLE=TRUE can be migrated.

Key Migration Steps

-------------------

The key migration tool pkcscca can be used to perform the migration of the

old CCA master key to the new master key. After a new master key is loaded

and set, perform the following steps:

1. Stop all processes that are currently using openCryptoki with the

CCA token.

2. Make sure pkcsslotd is running.

3. Back up the token object repository of the CCA token. For example, you can

use the following commands:

	cd /var/lib/opencryptoki/cca/

	tar -cvzf ~/cca/TOK_OBJ_backup.tgz TOK_OBJ

4. Migrate the keys of the CCA token object repository with the pkcscca

migration tool.

	pkcscca -m keys -s <slotid> -k <aes|apka|asym|sym>

The following parameters are mandatory:

-s

	- slot number for the CCA token

-k

	- master key type to be migrated: aes, apka, asym, or sym

All the specified token objects representing extractable keys that are

found for the CCA token, are re-encrypted and ready for use. Keys with an

attribute CKA_EXTRACTABLE=FALSE are not migratable.The keys that failed to

migrate are displayed to the user.

5. Re-start the previously stopped openCryptoki processes.