Managing tokens - pkcsconf utility

Edit online

openCryptoki provides a command line program (/sbin/pkcsconf) to configure and administer tokens that are supported within the system. The pkcsconf capabilities include token initialization, and security officer (SO) PIN and User PIN initialization and maintenance. These PINs are required for token initialization.

pkcsconf operations that address a specific token must specify the slot that contains the token with the -c option. You can view the list of tokens present within the system by specifying the -t option. Type pkcsconf --help or pkcsconf -h into a command line to show the options for the pkcsconf command:

# pkcsconf -h 
usage: pkcsconf [-itsmlIupPh] [-c slotnumber -U user-PIN -S SO-PIN -n new PIN]

The available options have the following meanings:

-i: display PKCS #11 info
-t: display token info
-s: display slot info
-m: display mechanism list
-l: display slot description
-I: initialize token
-u: initialize User PIN
-p: set the User PIN
-P: set the SO PIN
-h | --help | ?: show this help
-c: specify the token slot ID
-U: the current User PIN (for use when changing the user PIN with -u and -p options). If not specified, user is prompted.
-S: the current security officer (SO) PIN (for use when changing the SO PIN with -P option). If not specified, user will be prompted.
-n: the new PIN (for use when changing either the User PIN or the SO PIN with -u, -p or -P options). If not specified, user is prompted.

The pkcsconf functions for obtaining PKCS #11 information (pkcsconf -i), token information (pkcsconf -t), and slot information (pkcsconf -s) also display the current information in form of a PKCS #11 Unified Resource Identifier (URI).

Examples:

$ pkcsconf -s
Slot #0 Info
        Description: Linux             
        Manufacturer: IBM
        Flags: 0x1 (TOKEN_PRESENT)
        Hardware Version: 0.0
        Firmware Version: 0.0
        URI: pkcs11:slot-id=0;slot-description=Linux;slot-manufacturer=IBM

$ pkcsconf -t
Token #0 Info:
        Label: softtok
        Manufacturer: IBM
        Model: Soft
        Serial Number:
        Flags: 0x44D (RNG|LOGIN_REQUIRED|USER_PIN_INITIALIZED|CLOCK_ON_TOKEN|TOKEN_INITIALIZED)
        Sessions: 0/[effectively infinite]
        R/W Sessions: [information unavailable]/[effectively infinite]   
        PIN Length: 4-8
        Public Memory: [information unavailable]/[information unavailable]
        Private Memory: [information unavailable]/[information unavailable]
        Hardware Version: 0.0
        Firmware Version: 0.0
        Time: 2022042908395700
        URI: pkcs11:manufacturer=IBM;model=Soft;token=softtok

For more information about the pkcsconf command, see the pkcsconf man page.

Initializing a token with pkcsconf

Once the openCryptoki configuration file and, if applicable, token-specific configuration files are set up, and the pkcsslotd daemon is started, the token instances must be initialized. Use the pkcsconf command as shown to perform this task.

Note: As mentioned in Roles and sessions, PKCS #11 defines a security officer (SO) and a (standard) User for each token instance. openCryptoki requires that for both a log-in PIN is defined as part of the token initialization.

The following command provides some useful slot information:

# pkcsconf -s

Slot #1 Info
        Description: ICA Token
        Manufacturer: IBM
        Flags: 0x1 (TOKEN_PRESENT)
        Hardware Version: 4.0
        Firmware Version: 2.11
...
...
Slot #4 Info
        Description: EP11 Token
        Manufacturer: IBM
        Flags: 0x1 (TOKEN_PRESENT)
        Hardware Version: 4.0
        Firmware Version: 2.10

Receive more detailed information about a token using the following command:

Figure 1. Token information with pkcsconf -t

# pkcsconf -t
...
...
Token #4 Info:
        Label: ep11tok
        Manufacturer: IBM
        Model: EP11
        Serial Number: 93AABC5H53107366
        Flags: 0x880045 (RNG|LOGIN_REQUIRED|CLOCK_ON_TOKEN|USER_PIN_TO_BE_CHANGED|SO_PIN_TO_BE_CHANGED)
        Sessions: 0/[effectively infinite]
        R/W Sessions: [information unavailable]/[effectively infinite]
        PIN Length: 4-8
        Public Memory: [information unavailable]/[information unavailable]
        Private Memory: [information unavailable]/[information unavailable]
        Hardware Version: 7.24
        Firmware Version: 3.1
        Time: 2021031912021700

Find the token instance you want to initialize in the output list and note the correct slot number. This number is used in the next initialization steps to identify your token:

$ pkcsconf -I -c <slot>   /* Initialize the Token and set up a Token Label */

$ pkcsconf -P -c <slot>   /* change the SO PIN (recommended) */

$ pkcsconf -u -c <slot>   /* Initialize the User PIN (SO PIN required) */

$ pkcsconf -p -c <slot>   /* change the User PIN (optional) */

pkcsconf -I: During token initialization, you are asked for a token label. Provide a meaningful name, because you may need this reference for identification purposes.
pkcsconf -P: For security reasons, openCryptoki requires that you change the default SO PIN (87654321) to a different value. Use the pkcsconf -P option to change the SO PIN.
pkcsconf -u: When you enter the User PIN initialization you are asked for the newly set SO PIN. The length of the User PIN must be 4 - 8 characters.
pkcsconf -p: You must at least once change the User PIN with pkcsconf -p option. After you completed the PIN setup, the token is prepared and ready for use.

Note: Define a User PIN that is different from 12345678, because this pattern is checked internally and marked as default PIN. A log-in attempt with this User PIN is recognized as not initialized.