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.