Customizing token access control - pkcstok_admin utility

Edit online

openCryptoki provides a command line program called pkcstok_admin to enable an administrator to correctly configure user access to the token directories (including the respective token object repositories) in a way that a certain user can access the token directory of one token but not the token directory of another token.

The pkcstok_admin tool is intended to be used by an administrator with root access only for administrative tasks for tokens and its directories. All tokens to be managed (even the ones to be created) must have an entry in the openCryptoki configuration file opencryptoki.conf.

In contrast to the pkcsconf utility that you can use to administrate a token on the PKCS#11 level, the pkcstok_admin utility operates on the file system level.

Figure 1. pkcstok_admin syntax - Customizing token access control

1  pkcstok_admin
2.1 create
2.1 chown
2.1 remove
2.1 reset
1 --token
1? --group
1? --force
1? --help
1? --version
1? --verbose
Use the create sub-command to create a new token (optionally with a token group assigned right away). This creates all required token directories and sets the owner correctly. The corresponding slot definition in the opencryptoki.conf file must specify the
  • tokname = <token-name> and
  • usergroup = <group-name>
keywords appropriately.

Use the chown sub-command to change the owner of a token to the specified group. This changes the owner of all directories, files, shared memory segments, and so on, that belong to the token accessible by users of the specified group. When the owner is changed, it is verified that the user or owner of each file is also a member of the token-specific group. If a file was originally created by a user who is not a member of the token-specific group, then the user or owner of the file is changed to root. This prevents that a user who is not member of the token-specific group can still access token-specific files, if that user created that file.

The remove sub-command removes all files and directories of the specified token. Use this sub-command if you want to completely remove a token. Use with care, because it also removes all token objects. You must as well manually remove the corresponding slot definition in the opencryptoki.conf file.

The reset sub-command resets the token to its initial state. This also resets the token’s PINs to the factory default, and removes all token objects. Afterward, the token must be freshly initialized using pkcsconf -I, the SO PIN must be set using pkcsconf -P, and the User PIN must be initialized using pkcsconf -u. Resetting a token can be required if you forgot the SO PIN, or the SO PIN got locked due to too many invalid login attempts.

The following options are available:

-t, --token <token_name>
The name of the token to operate on. This option is mandatory.
-g, --group <group_name>
The name of the user group owning the token. This option is optional, if omitted, the group pkcs11 is assumed.
-f, --force
Do not ask for confirmations. Use with care!
-h, --help
Print this help, then exit.
-v, --version
Print version information, then exit.
-V, --verbose
Print verbose messages.