Managing EP11 sessions - pkcsep11_session utility

Edit online

An EP11 session is a state on the EP11 cryptographic coprocessor and must not be confused with a PKCS #11 session. An EP11 session is generated by the strict session mode or the VHSM mode. They are implicitly stored and deleted by openCryptoki if the according modes are set. So under normal circumstances, you need not care about the management of these EP11 sessions. But in some cases, for example, when programs crash or when programs do not close their sessions or do not call C_Finalize() before exiting, some explicit EP11 session management may be required.

EP11 sessions are a limited resources shared by all domains of an EP11 cryptographic coprocessor and must be closed when no longer needed to avoid situations where the EP11 cryptographic coprocessor runs out of session resources. Therefore the usage of the strict session mode and the VHSM mode is only recommended in environments where all systems accessing EP11 cryptographic coprocessors can be trusted to cooperate to not open or keep open EP11 sessions unnecessarily.

For more information about EP11 sessions, read Exploiting Enterprise PKCS #11 using openCryptoki.

The pkcsep11_session tool allows to delete an EP11 session from the EP11 cryptographic coprocessors left over by programs that did not terminate normally. An EP11 cryptographic coprocessor supports only a certain number of EP11 sessions at a time. Because of this, it is important to delete any EP11 session, in particular when the program for which it was logged in, terminated unexpectedly. The pkcsep11_session tool is also used to set the VHSM PIN required for the VHSM mode.

pkcsep11_session syntax

To see all available sub commands of the pkcsep11_session utility, request help with the pkcsep11_session -h or pkcsep11_session --help command:

# pkcsep11_session -h

usage:  pkcsep11_session show|logout|vhsmpin|fipspin|status [-date <yyyy/mm/dd>] 
                         [-pid <pid>] [-id <sess-id>] [-slot <num>] [-force] [-h]

pkcsep11_session sub-command usage examples

show: Show all left over sessions:
```
pkcsep11_session show
```
A sample output for two left-over EP11 sessions could look as shown:
```
# pkcsep11_session show -slot 4
Using slot #4...

Enter the USER PIN:
List of EP11 sessions:

30D5457762D8DDC158B558FCCC79FAB6:
        Pid:    48196
        Date:   2018/ 7/12
30D5457762D8DDC158B558FCCC79FAB6:
        Pid:    48196
        Date:   2018/ 7/12

2 EP11-Sessions displayed
```
Note that only the first 16 bytes of the EP11 session ID are stored in the session object and therefore, the session IDs are displayed only partially. Otherwise, a user would be able to re-login on an EP11 adapter and re-use keys generated with this EP11 session, when the full EP11 session ID would be visible to the outside. Thus there may be identical session IDs when the strict session mode and the virtual HSM (VHSM) mode are combined for a session, as shown in the example.
show: Show all left over EP11 sessions that belong to a specific process ID (pid):
```
pkcsep11_session show -pid 1234
```
show: Show all left over EP11 sessions that have been created before a specific date:
```
pkcsep11_session show -date 2018/06/29
```
logout: Logout all left over EP11 session:
```
pkcsep11_session logout
```
logout: Logout all left over EP11 session that belong to a specific process id (pid):
```
pkcsep11_session logout -pid 1234
```
logout: Logout all left over EP11 session that have been created before a specific date:
```
pkcsep11_session logout -date 2018/07/27
```
logout: Logout all left over EP11 session even when the logout does not succeed on all adapters:
```
pkcsep11_session logout -force
```
vhsmpin: Every EP11 token running in virtual HSM (VHSM) mode (with VHSM_MODE configuration option set) requires a VHSM PIN. The vhsmpin subcommand sets this VHSM PIN used for the VHSM mode.
In VHSM mode, all keys generated by the EP11 token strictly belong to the EP11 token instance that created it.
Note: When changing the VHSM PIN, all existing keys stored as token objects become unusable. The VHSM PIN must be set before the token is changed to the VHSM mode, that is, before this mode is enabled with the VHSM_MODE option in the EP11 token configuration file.
See also Defining an EP11 token configuration file or read topic Controlling access to cryptographic objects with session modes.
```
# pkcsep11_session vhsmpin -slot 4
Using slot #4...

Enter the USER PIN:
Enter the new VHSM PIN:
Re-enter the new VHSM PIN:
VHSM PIN successfully set.
```
The VHSM PIN must contain between 8 and 16 alphanumeric characters.
fipspin: Every EP11 token running in FIPS session mode (FIPS_SESSION_MODE configuration option) requires a FIPS PIN which you can set using the fipspin subcommand. This FIPS PIN is used for the FIPS session mode.
The fipspin subcommand prompts for a new FIPS PIN for the token specified with the -slot option and stores it persistently in the respective token’s object repository. It can only be read when a PKCS #11 User session is logged in, thus only by users that know the PKCS #11 User PIN.
The FIPS PIN must be set before the token is changed to the FIPS session mode, that is, before this mode is enabled with the FIPS_SESSION_MODE option in the EP11 token configuration file.
The FIPS PIN must contain between 8 and 16 alphanumeric characters.
```
# pkcsep11_session fipspin -slot 4
Using slot #4...

Enter the USER PIN:
Enter the new FIPS PIN:
Re-enter the new FIPS PIN:
FIPS PIN successfully set.
```
See also Controlling access to cryptographic objects with session modes and Defining an EP11 token configuration file.

status: Query the maximum and currently available number of EP11 sessions for each available EP11 APQN. :

pkcsep11_session status

See the following sample output:

APQN 0b.0024:
  Max Sessions:        1024
  Available Sessions:  234
APQN 0a.0024:
  Max Sessions:        1024
  Available Sessions:  0

The pkcsep11_session tool provides its own man page that is installed as part of the EP11 package.