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 pkcsconf utility, find/verify the slot number of the CCA secure-key

token:

    pkcsconf -s

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