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.