Managing EP11 sessions with the pkcsep11_session tool

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.

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 card-PIN required for the VHSM mode.

pkcsep11_session usage examples

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 sessions 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 all left over EP11 sessions that belong to a specific process id (pid):
```
pkcsep11_session show -pid 1234
```
Show all left over EP11 sessions that have been created before a specific date:
```
pkcsep11_session show -date 2018/06/29
```
Logout all left over EP11 sessions:
```
pkcsep11_session logout
```
Logout all left over EP11 sessions that belong to a specific process id (pid):
```
pkcsep11_session logout -pid 1234
```
Logout all left over EP11 sessions that have been created before a specific date:
```
pkcsep11_session logout -date 2018/07/27
```
Logout all left over EP11 sessions even when the logout does not succeed on all adapters:
```
pkcsep11_session logout -force
```
Set a card-PIN:
```
pkcsep11_session cardpin
```
The card-PIN must be between 8 and 16 characters in length.

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