Controlling access to cryptographic objects

You must configure the EP11 token to use either one of the available modes, or both.

• 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 virtual HSM (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. 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).

  To enable the virtual HSM (VHSM) mode, specify keyword VHSM_MODE in the configuration file. 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 EP11 cryptographic coprocessors.

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 virtual HSM 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 cleanup, you can use the pkcsep11_session utility. With this tool you can delete EP11 sessions from the EP11 cryptographic coprocessors that are left over by programs that did not terminate normally. The pkcsep11_session utility is described in openCryptoki - An Open Source Implementation of PKCS #11).

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

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. For each logged-in session, the returned session pin-blob (derived from the EP11 session ID) is stored in a special token object in the token directory.

During further processing, all session keys (that is, objects where attribute CKA_TOKEN is CK_FALSE) are bound to the session pin-blob that was created when the session was logged on.

At session end, the EP11 session with regards to the PKCS #11 session is logged out on all APQNs belonging to the token. The token object representing this EP11 session ID is deleted from the token directory.

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

If multiple APQNs are available in the system, then all pin-blobs returned by the EP11 session login for the individual APQNs must be equal. Otherwise an error is returned and logged in the SYSLOG.

Virtual HSM (VHSM) 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 card-PIN is required to log into an EP11 session in VHSM mode.

The card-PIN used with VHSM mode must be set using the command cardpin from the pkcsep11_session tool (see openCryptoki - An Open Source Implementation of PKCS #11). It takes a slot ID, the user PIN, and the card-PIN as input. The card-PIN is stored in a special token object in the token directory. The card-PIN must be between 8 and 16 characters in length.

That way, after setting the card-PIN, an EP11 session can log in on all configured APQNs. The returned pin-blob derived from the card-PIN is stored in a special token object in the token directory (separately from the token object for the card-PIN), the same way as for strict session mode.

During further processing, all keys (session keys as well as token keys) are bound to the pin-blob that was derived from the card-PIN when the session was logged in.

At session end, the EP11 session with regards to the PKCS #11 session is logged out from all APQNs and the token object representing this EP11 session ID is deleted from the token directory. In contrast to the session pin-blob, the card-PIN remains persistent and thus can be used for future sessions in VHSM mode.

When the VHSM mode is enabled, but no card-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 mode

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