pkcstok_admin - Man Page
utility to administrate token directories of the Opencryptoki token repository.
Synopsis
pkcstok_admin command [Options]
Description
The pkcstok_admin utility can be used to administrate token directories of the Opencryptoki token repository with proper permissions and owners. By default token directories are owned by the pkcs11 group, and every user that is a member of the pkcs11 group has access to the token and its token objects (i.e. keys, certificates, etc.).
A token directory can alternatively be owned by a token specific group. Specify the group name with keyword usergroup in the slot definition in the opencryptoki.conf configuration file located in /etc/opencryptoki/. With that, only users that are members of the configured token specific group have access to the token and its token objects. Users that are only members of the pkcs11 group, but are not also members of the token specific group do not have access to the token. Users of the token specific group must still also be members of the pkcs11 group to be able to use Opencryptoki.
Token specific files are usually stored in /var/lib/opencryptoki/<token-name>/. Additionally token specific lock files are stored in /var/lock/opencryptoki/<token-name>/. Furthermore, a token specific POSIX shared memory segment exists under /dev/shm/. All files and directories within these token specific directories as well as the shared memory segment are owned by the token specific group, or by the pkcs11 group if no token specific group has been configured.
The pkcstok_admin utility must be run as root, and the pkcsslotd must be stopped before running this utility.
Note: Do not use the pkcstok_admin utility on a TPM token. The TPM token uses a different directory structure, and stores token objects on a per user basis. The pkcstok_admin utility is not capable of setting the owners correctly on such a directory structure. Furthermore, the TPM token is deprecated, because it supports only TPM version 1.2. It does not work with TPM version 2.0.
Commands
The pkcstok_admin tool supports various commands to administrate token directories.
Creating a new token and its directories
pkcstok_admin create --token|-t TOKNAME [--group|-g GROUP] [--force] [--verbose]
Use the create command to create a new token and its directories.
Use the --token|-t TOKNAME option to specify the name of the token to create. The token name must also be specified in the slot definition in the opencryptoki.conf configuration file located in /etc/opencryptoki/ with keyword tokname.
Use the [--group|-g GROUP] option to specify the token specific user group used as group owner of the token directories. If no group is specified, the token directories will be owned by the pkcs11 group. If a group is specified, then it must also be specified in the slot definition in the opencryptoki.conf configuration file located in /etc/opencryptoki/ with keyword usergroup.
The pkcstok_admin tool prompts for a confirmation before the token directories are created. To omit the prompt, specify the --force option. Use this option with care!
Specify the --verbose option to see more detailed messages about the actions the tool is performing.
Changing the owner of an existing token and its directories
pkcstok_admin chown --token|-t TOKNAME [--group|-g GROUP] [--force] [--verbose]
Use the chown command to change the owner of an existing token and its directories.
Use the --token|-t TOKNAME option to specify the name of the token to change the owner for. The token name is usually specified in the slot definition in the opencryptoki.conf configuration file located in /etc/opencryptoki/ with keyword tokname. If the slot definition does not specify a tokname keyword, then a default token name is used, dependent on the token model. The ICA token uses lite as default token name, the CCA token uses ccatok, the Soft token uses swtok, the EP11 token uses ep11tok, the ICSF token uses icsf, and the TPM token (deprecated) uses tpm.
Use the [--group|-g GROUP] option to specify the token specific user group to set as group owner of the token directories. If no group is specified, the token directories will be changed to be owned by the pkcs11 group. If a group is specified, then it must also be specified in the slot definition in the opencryptoki.conf configuration file located in /etc/opencryptoki/ with keyword usergroup. If no group is specified, then remove the usergroup keyword from the slot definition, or change its value to pkcs11.
The pkcstok_admin tool prompts for a confirmation before the owner of the token directories is changed. To omit the prompt, specify the --force option. Use this option with care!
Specify the --verbose option to see more detailed messages about the actions the tool is performing.
Removing an existing token and its directories
pkcstok_admin remove --token|-t TOKNAME [--force] [--verbose]
Use the remove command to remove an existing token and its directories. This also removes all token objects of that token. Use with care!
Use the --token|-t TOKNAME option to specify the name of the token to remove. You must also remove the corresponding slot definition from the opencryptoki.conf configuration file located in /etc/opencryptoki/. The token name is usually specified in the slot definition in the opencryptoki.conf configuration file. If the slot definition does not specify a tokname keyword, then a default token name is used, dependent on the token model. The ICA token uses lite as default token name, the CCA token uses ccatok, the Soft token uses swtok, the EP11 token uses ep11tok, the ICSF token uses icsf, and the TPM token (deprecated) uses tpm.
The pkcstok_admin tool prompts for a confirmation before the token directories are removed. To omit the prompt, specify the --force option. Use this option with care!
Specify the --verbose option to see more detailed messages about the actions the tool is performing.
Resetting a token to its initial state
pkcstok_admin reset --token|-t TOKNAME [--force] [--verbose]
Use the reset command to reset a token to its initial state. This also resets all PINs and removes all token objects. Use with care!
Resetting a token can be required if you forgot the SO pin, or the SO pin got locked due to too many login attempts using a wrong SO PIN.
Use the --token|-t TOKNAME option to specify the name of the token to reset. The token name is usually specified in the slot definition in the opencryptoki.conf configuration file located in /etc/opencryptoki/ with keyword tokname. If the slot definition does not specify a tokname keyword, then a default token name is used, dependent on the token model. The ICA token uses lite as default token name, the CCA token uses ccatok, the Soft token uses swtok, the EP11 token uses ep11tok, the ICSF token uses icsf, and the TPM token (deprecated) uses tpm.
The pkcstok_admin tool prompts for a confirmation before the token is resetted. To omit the prompt, specify the --force option. Use this option with care!
Specify the --verbose option to see more detailed messages about the actions the tool is performing.
After resetting a token, it must be initialized freshly using pkcsconf -I, setting the SO pin using pkcsconf -P and then initializing the USER pin using pkcsconf -uP.
Options
- --token|-t TOKNAME
Specifies the name of the token to operate on. The token name must also be specified in the slot definition in the opencryptoki.conf configuration file located in /etc/opencryptoki/ with keyword tokname. If the slot definition does not specify a tokname keyword, then a default token name is used, dependent on the token model. The ICA token uses lite as default token name, the CCA token uses ccatok, the Soft token uses swtok, the EP11 token uses ep11tok, the ICSF token uses icsf, and the TPM token (deprecated) uses tpm.
- --group|-g GROUP
Specifies the token specific user group used as group owner of the token directories. If this option is omitted, the token directories will be owned by the pkcs11 group. If a group is specified, then it must also be specified in the slot definition in the opencryptoki.conf configuration file located in /etc/opencryptoki/ with keyword usergroup.
- --force|-f
The pkcstok_admin tool prompts for a confirmation before the token directories are created. To omit the prompt, specify this option. Use this with care!
- --verbose|-V
Turn on verbose mode to see more detailed messages about the actions the tool is performing.
- --help|-h
Prints help for the usage of the pkcstok_admin tool and then exits.
- --version|-v
Prints the version of the pkcstok_admin tool and then exits.
Files
/var/lib/opencryptoki/<token-name>/
Contains the token specific data, like the token's master key encrypted with the SO and USER PINs (MK_SO and MK_USER), as well as the non volatile token state data (NVTOK.DAT). Subdirectory TOK_OBJ contains the token objects and an index file (OBJ.IDX).
/var/lock/opencryptoki/<token-name>/
Contains a token specific lock file (LCK..<tokname>) that is used to synchronize access to the token data across multiple processes.