
README for the CCA secure-key token migration utility

The CCA secure-key token migration utility consists of two programs:

	pkcscca_migrate.sh	A shell script that invokes the pkcscca_migrate
				utility.  The script does some data location
				validation, token validation and token data
				backup.  It is recommended that this script be
				used to perform the migration.

	pkcscca_migrate		A utility that will migrate all of the CCA
				token data to the new CCA master key.

To use the migration utility, make sure that there are no applications
actively using the PKCS#11 interface to the CCA secure-key token by stopping
any applications that use the PKCS#11 interface to the CCA secure-key token.


Using the pkcsconf64 utility, find/verify the slot number of the CCA secure-key
token:

	pkcsconf64 -s
	pkcsconf64 -t

The CCA secure-key token will have "(CCA)" at the end of the slot description
and the token information will identify the token as the "IBM CCA Token."


Once you have determined the proper slot number of the CCA secure-key token,
invoke the CCA secure-key token migration script:

	pkcscca_migrate.sh --slot-id X
		where "X" is the slot number of the CCA secure-key token

Optionally, you can specify the "--dry-run" and/or "-v" options on the script
invocation.

	--dry-run	This will cause the migration utility to perform all
			of the steps in the migration but will not commit the
			changes needed to run under the new CCA master key.
			Any errors encountered will be reported.

	-v		This will increase the verbosity of the migration
			utility.  Multiple "-v" arguments can be specified to
			increase the amount of verbose information displayed.


Using the pkcscca_migrate.sh script will create a backup copy of the CCA secure-key
token data in the openCryptoki main data store directory.  Should any errors
be encountered during the migration, the original data will be restored.

Here is a description of the steps involved in the migration:

	- The script will check to see if you are running as root or that you are
	  a member of the "pkcs11" group.  If neither of these is the case, the
	  script will exit.

	- The script will look for the pkcsconf64 utility in two locations:
		/usr/lib/pkcs11/methods  or  /usr/sbin
	  If the utility is not found, the script will exit.

	- The script will look for the CCA token data store in two locations:
		/etc/pkcs11/ccatok  or  /var/lib/opencryptoki/ccatok
	  If the data store is not found, the script will exit.

	- The script will then validate the slot number:
		- If a slot number has been supplied as an argument to the script,
		  it will be verified as a valid slot number.

		- If a slot number was not supplied as an argument to the script,
		  then the pkcsconf64 utility will be used to display a list of
		  valid slots.  You must then choose the slot you wish to migrate.

	- The Security Office (SO) pin and the User pin are both required for the
	  migration.  You will be prompted for both of these pins.

	- The selected slot information will be displayed and you will be prompted
	  to verify that you want to perform the migration.

	- The current CCA token data store will be backed up in the current directory.
	  Be sure that you have write access to the current directory.  If the backup
	  file cannot be created, the script will exit.

	- The migration utility, pkcscca_migrate, will be invoked to perform the
	  actual migration.  Any errors encountered will be reported.

	- Should an error have been encountered during the migration, the CCA token
	  data store will be restored from the backup that was created earlier.

	- If no errors have been encountered, then the migration has been successful.
