NAME

       pkcstok_admin - utility to administrate token directories of the Opencryptoki token repository.

SYNOPSIS

       pkcstok_admin command [OPTIONS]

       pkcstok_admin --help|-h
       pkcstok_admin --version|-v

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.

   Token specific POSIX shared memory segment under /dev/shm/
       Contains  token  specific  shared state data for tracking updates to token objects done by processes. Its
       name is derived from the token specific directory under /var/lib/opencryptoki/.

SEE ALSO

       opencryptoki.conf(5).

@PACKAGE_VERSION@                                   July 2024                                   pkcstok_admin(1)