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