Customizing access control to the openCryptoki tokens

Edit online
An openCryptoki administrator can individually customize access control to one or more openCryptoki users, that is, access control to the token directories (including the respective token object repositories), such that a user can access the token directory of one token, but not the token directory of another token. Even if you plan to configure individual access control, each openCryptoki user must be a member of the pkcs11 group.

General access control

To properly configure the system, and to be authorized for performing the openCryptoki processes, for example, running the slot manager pkcsslotd, the pkcs11 group must be defined in file /etc/group of the system. Every openCryptoki user (including the pkcsslotd user running the slot manager, and including the users configuring openCryptoki and its tokens) must be members of this pkcs11 group. Use standard Linux® management operations to create the pkcs11 group if needed, and to add users to this group as required. Normally, the pkcs11 group is automatically created when installing openCryptoki from an RPM or DEB package.

You may also refer to the man page of openCryptoki (man openCryptoki) which has a SECURITY NOTE section that is important from the security perspective.

Individual access control

You can protect a token with its token directories and token objects so that only those users that are a member of a certain token-specific user group are allowed to access the token.

For a user who is a member of such a token specific user group, there are no differences in using openCryptoki. Users that are not a member of a token specific group, have no access to that token. They will not even see that token being available with pkcsconf -t or using the C_GetTokenInfo() function. Users must still be members of the pkcs11 group to be able to use openCryptoki in general. By default, all tokens remain to be owned by the pkcs11 group. If a token shall be access-protected, then an administrator with root access must explicitly configure that. The administrator must create a token-specific user group, add the desired users into it, and then configure openCryptoki and the token directories appropriately, as shown in the following procedure:

  1. Create a token-specific user group.
  2. Add all desired users into that group.

    Make sure that all those users are also a member of the pkcs11 group.

  3. Stop the pkcsslotd daemon.
  4. Edit the opencryptoki.conf file residing in /etc/opencryptoki and add the keyword usergroup = <group-name> to the slot definition (also see Figure 1).

    This allows openCryptoki to set the owners correctly when creating new files (for example, new token objects). It also allows to verify - during startup of the slot daemon, as well as during C_Initialize() done by an application - that the token directory ownership matches the desired token-specific user group. If inconsistencies are detected, they are reported and the startup of the slot daemon fails, or the token is not available for applications.

    If the usergroup keyword is omitted (which is the default), then the token is owned by the pkcs11 group.

  5. Use the pkcstok_admin utility with the chown command to change the owner of a token to the specified group (see Customizing token access control - pkcstok_admin utility).

    This changes the owner of all directories, files, shared memory segments, and so on, that belong to the token to the specified group. The pkcstok_admin tool must be run by the root user and the pkcsslotd daemon must not be running while the pkcstok_admin tool is used.

  6. Restart the pkcsslotd daemon.
Note: Be careful when removing users from a token-specific group. If such a user did create files (that is, token objects) with that token while they were still a member of the token group, then these files are owned by that user (and the token group). Thus even when the user is removed from the token group, they may still have access to the files they created. To prevent that undesired access, an administrator should run the pkcstok_admin tool with the chown command again on the token after members were removed. This fixes those files that are still owned by users that are no longer members of the token group.

Besides changing user access of an existing token, you can also add a new token and configure access right away using the pkcstok_admin tool.