Controlling access to cryptographic objects with session modes

Edit online

You can decide to activate available session modes to limit the access to cryptographic objects in order to improve security. The available session modes are the strict session mode, the virtual HSM mode (VHSM mode), or the FIPS session mode. All of these modes generate an EP11 session. An EP11 session is a state on the EP11 cryptographic coprocessor and must not be confused with a PKCS #11 session.

You can configure the EP11 token to run in one of the allowed session mode combinations:

Protecting cryptographic objects with the FIPS session mode

Add a FIPS session mode to the openCryptoki EP11 token to use only FIPS 140-2 (2021) compliant secure keys. When an EP11 APQN is in FIPS-compliant mode, it allows only session-bound EP11 secure keys, and the EP11 session login is performed using a FIPS-compliant login method.

To enable the FIPS session mode, specify keyword FIPS_SESSION_MODE in the EP11 token configuration file.

Protecting cryptographic objects with the strict session mode

This mode prohibits that a session key, copied from a PKCS #11 session that generated this key, is still valid even if the generating session has ended. Also, when this mode is used, session keys generated with this token can no longer be passed to other sessions of the same token.

To enable the strict session mode, specify keyword STRICT_MODE in the EP11 token configuration file.

Protecting cryptographic objects with the VHSM mode

This mode is applicable when the same EP11 cryptographic coprocessors are used by multiple EP11 tokens. In such environments, a key generated by one token might be used by another token which uses the same domain on multiple EP11 cryptographic coprocessors. This is possible, because all keys are wrapped by the same master key. Now, this mode prohibits that a key, generated by one token, is used by any other token (on the same system or on another system or z/VM or KVM guest), even if the same master key is used.

When this mode is used, session and token keys generated with this token can no longer be passed to other tokens using domains on the same or on different EP11 cryptographic coprocessors.

To enable the virtual HSM (VHSM) mode, specify keyword VHSM_MODE in the EP11 token configuration file.

General considerations

The number of simultaneously supported EP11 sessions is limited on an EP11 cryptographic coprocessor. Programs that use a large number of sessions simultaneously should not use the strict session mode or the VHSM mode, because otherwise the EP11 cryptographic coprocessor may run out of session resources.

Therefore, it is important to delete any finished EP11 session, that is no longer required, in particular when the program for which it was logged in, terminated unexpectedly. For the purpose of a required session clean up, you can use the pkcsep11_session utility. With this tool you can delete EP11 sessions from the EP11 cryptographic coprocessor that are left over by programs that did not terminate normally (see Managing EP11 sessions - pkcsep11_session utility).

The pkcsep11_session tool also allows to display any currently stored EP11 sessions, and can also log out of those sessions.

Note: Strict session mode and virtual HSM (VHSM) mode only work for R/W or R/O user sessions. For public sessions or security officer (SO) sessions, the strict session mode and the virtual HSM (VHSM) mode are not used.

Prerequisites for using the FIPS session mode

The FIPS session mode internally uses a FIPS-compliant login method, which requires that a certain EP11 firmware level is installed on all APQNs confirmed for the EP11 token, depending on the Crypto Express adapter generation:

  • for CEX8 adapters: firmware level v8.23
  • for CEX7 adapters: firmware level v8.14

Older Crypto Express generations are not supported.

To enable the FIPS session mode for the EP11 token, the APQNs configured for the EP11 token may or may not operate in FIPS-compliant mode. Even if an APQN does not operate in FIPS-compliant mode, it can still be used with the FIPS session mode.

However, if at least one of the APQNs configured for the EP11 token is in FIPS-compliant mode, then the FIPS-compliant EP11 token also must be configured to use the FIPS session mode. An APQN in FIPS-compliant mode can not be used with an EP11 token without the FIPS session mode. Whether an APQN operates in FIPS-compliant mode is determined by the setting of the following control points: 


48 XCP_CPB_ALLOW_NONSESSION          If this control point is OFF, then only session-bound 
                                     EP11 secure keys are allowed.

73 XCP_CPB_ALLOW_LOGIN_PRE_F2021     If this control point is OFF, then only the FIPS-compliant 
                                     login method (m_LoginExtended) is allowed.

The APQNs configured for the token are queried and checked if the control point setting and the firmware versions are according to the selected mode. Token initialization fails if this is not the case.

If an APQN operates in FIPS-compliant mode, both control points are OFF. However, even if just one of these control points is OFF, the EP11 token must be configured with the FIPS session mode being enabled.

Furthermore, the EP11 host library must be version 4.1.0 or later which supports the required FIPS-compliant login method m_LoginExtended(). The EP11 host library is checked if it supports the required features when the FIPS session mode is enabled. Token initialization fails if the support is not available.

Details of the FIPS session mode

In the FIPS session mode, only FIPS 140-2 compliant secure keys are used. An EP11 APQN in FIPS compliant mode requires the use of the FIPS session mode.

For the FIPS session mode, one EP11 session is logged-in using the FIPS-conforming login method (m_LoginExtended) on all APQNs configured for the token when the very first PKCS #11 User session is opened, and is logged out when the very last PKCS #11 User session is closed. The FIPS session is logged in using the FIPS PIN that has been set for a certain EP11 token using the fipspin command from the pkcsep11_session utility (see Managing EP11 sessions - pkcsep11_session utility).

All keys created or used by the token are bound to the FIPS session, because an APQN in FIPS mode only allows session-bound keys.

Because the FIPS session mode requires that all EP11 secure keys are session-bound, and an EP11 session can only be logged in when a PKCS #11 User session is logged in, an EP11 token in FIPS session mode allows the use or creation of key objects only if a PKCS #11 User session is logged in. That is, no key objects can be used or created in public sessions, nor in security officer (SO) sessions (even if the SO is logged in). This applies to all kinds of key objects, regardless if they are token objects (CKA_TOKEN=TRUE) or session objects (CKA_TOKEN=FALSE), and also regardless if they are private (CKA_PRIVATE=TRUE) or public (CKA_PRIVATE=FALSE) objects.

Note: This is a restriction compared to the PKCS #11 standard, where public objects (CKA_PRIVATE=FALSE) can be used and created in public or security officer (SO) sessions. This restriction only applies to key objects, but not to objects of other classes, for example, certificates. For strict session mode and VHSM mode, objects that are created in a situation where no EP11 session can be logged in, are simply not session-bound. This is not possible when in FIPS session mode. Thus, the use and creation of key objects must be restricted to cases where a PKCS #11 User session is logged in.

A FIPS session is only logged-out when the last application that uses the FIPS session closes its PKCS #11 session.

If an operation with a session-bound key internally fails with CKR_SESSION_CLOSED, then the FIPS session is re-logged in on all APQNs configured for this token in a way that is transparent for the user. This can happen when a new APQN becomes online, that has not yet logged into the session.

Details of the strict session mode

To enable a strict implementation of the PKCS #11 session semantics, a strict session mode is available on a per token instance basis.

In strict session mode, for each new PKCS #11 session, a unique EP11 session ID is generated. Then the EP11 session is logged in on all adapter/domain pairs (adjunct processor queue numbers, APQNs) that are configured for the token.

During further processing, all private session key objects (that is, key objects where attribute CKA_TOKEN is FALSE and CKA_PRIVATE is TRUE) are bound to that EP11 session. Public objects (CKA_PRIVATE is FALSE) are not bound to that session.

At session end, the EP11 session with regards to the PKCS #11 session is logged out on all APQNs belonging to the token.

An APQN that comes online after an EP11 session has started, is also logged in internally if a request to that APQN is encountered.

Details of the virtual HSM mode

To restrict keys to only that token that was used to generate it, the virtual HSM mode (VHSM mode) is available on a per-token basis.

Similar to the strict session mode, for each new PKCS #11 session, a unique EP11 session ID is generated. However, an additional VHSM PIN is required to log into an EP11 session in VHSM mode.

The VHSM PIN used with the VHSM mode must be set using the command vhsmpin from the pkcsep11_session tool (see Managing EP11 sessions - pkcsep11_session utility). It takes a slot ID, the User PIN, and the VHSM PIN as input. The VHSM PIN is stored in a special token object in the token directory. It must be between 8 and 16 characters in length.

That way, after setting the VHSM PIN, an EP11 session can log in on all configured APQNs.

During further processing, all private key objects (session key objects as well as token key objects, where CKA_PRIVATE is TRUE) are bound to that EP11 session. Public objects (CKA_PRIVATE is FALSE) are not bound to that session.

At session end, the EP11 session with regards to the PKCS #11 session is logged out from all APQNs.

When the VHSM mode is enabled, but no VHSM PIN has been set, then the PKCS #11 session login fails, and an appropriate message is logged to syslog.

Combined strict session mode and virtual HSM (VHSM) mode

The strict session mode can be combined with the VHSM mode. This binds all private key objects (that is, key objects where attribute CKA_PRIVATE is TRUE) to the VHSM PIN, and additionally binds private session key objects (that is, objects where attribute CKA_TOKEN is FALSE and CKA_PRIVATE is TRUE) to the PKCS #11 session.

Strict session mode VHSM mode Private session key objects Private token key objects
off off not bound not bound
on off bound to PKCS #11 session not bound
off on bound to token by VHSM PIN bound to token by VHSM PIN
on on bound to PKCS #11 session and token by VHSM PIN bound to token by VHSM PIN

Public and private key pair parts bound to different sessions

When keys are generated using the C_GenerateKeyPair() function, you can specify separate templates for the public key and the private key and thus use different attributes. This may lead to a situation, where the public key and the private key are to be bound to different sessions. If, for example, the public key template has CKA_PRIVATE=FALSE, but the private key template has CKA_PRIVATE=TRUE, then, dependent on the enabled modes, the private key is to be bound to a session, and the public key is to be bound to another session or to no session at all.