Migrating to FIPS compliance - pkcstok_migrate utility

Use the pkcstok_migrate tool to migrate the data stores of an EP11 token, a CCA token, an ICA token, or a Soft token to a FIPS compliant format. This FIPS compliant data format is available starting with openCryptoki version 3.12. You can use this tool to migrate tokens created with all versions of openCryptoki, because also for version 3.12 or later, the old non-compliant format is the default. Being FIPS compliant, the token data is stored in a format that is better protected against attacks than the previously used data format.

For further information, read the pkcstok_migrate man page.

Parameters


# pkcstok_migrate -h

Help:         pkcstok_migrate -h
-h, --help    Show this help

Options:

-s, --slotid SLOTID            PKCS slot number (required)
-d, --datastore DATASTORE      token datastore location (required)
-c, --confdir CONFDIR          location of opencryptoki.conf (required)
-u, --userpin USERPIN          token user pin (prompted if not specified)
-p, --sopin SOPIN              token SO pin (prompted if not specified)
-v, --verbose LEVEL            set verbose level (optional):
                               none (default), error, warn, info, devel, debug

Functionality

The utility:

  • directly accesses the token objects via file operations;
  • assumes that no other action is currently running. It checks if the slot manager pkcsslotd is running and asks the user to end it if yes.

Before making any changes to the repository, a temporary copy is created. Migration takes place on this copy. The copied folder is suffixed with _PKCSTOK_MIGRATE_TMP. If the migration fails, the old repository is still available.

Running a migration again, would remove any remaining backups from previous runs, create a new backup, and then do the migration.

  • After successfully migrating all token objects, the original repository folder is renamed by appending the suffix _BAK, and the new repository folder gets the name of the original one.
  • Also, the opencryptoki.conf file is updated by inserting (or updating) the tokversion parameter in the token’s slot configuration. The old configuration file is still available with the same suffix _BAK.

This makes the new repository immediately usable after restarting the pkcsslotd daemon, but also allows the user to switch back manually to the old token format.

Example: To transform a CCA token into the FIPS compliant data format perform a sequence of commands with your adequate input, similar to the following:


systemctl stop pkcsslotd.service /* for Linux distributions providing systemd */
/* or */
service pkcsslotd stop

# pkcstok_migrate --slot 2 --sopin 76543210 --userpin 12345678 
                  --confdir /etc/opencryptoki 
                  --datastore /var/lib/opencryptoki/ccatok


service pkcsslotd start

The output may look similar to the following:


pkcstok_migrate:
Summary of input parameters:
  datastore = /var/lib/opencryptoki/ccatok
  confdir = /etc/opencryptoki
  slot ID = 2
  user PIN specified
  SO PIN specified

Slot ID 2 points to DLL name libpkcs11_cca.so, which is a CCA token.
Data store /usr/local/var/lib/opencryptoki/ccatok points to this token info:
  label           : IBM CCA PKCS #11
  manufacturerID  : IBM
  model           : CCA
  serialNumber    :
  hardwareVersion : 0.0
  firmwareVersion : 0.0
Migrate this token with given slot ID? y/n
y
Migrated 2 object(s) out of 2 object(s).
Pre-migration data backed up at '/usr/local/var/lib/opencryptoki/ccatok_BAK'
Config file backed up at '/usr/local/etc/opencryptoki/opencryptoki.conf_BAK'
Remove these backups manually after testing the new repository.
pkcstok_migrate finished successfully.