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.