Filtering mechanisms

An EP11 cryptographic coprocessor can be configured by means of ACPs, which restrict the use of certain mechanisms within a domain of this coprocessor. Restricted mechanisms are not visible in the mechanism list returned. Some ACPs restrict certain attributes of mechanisms (such as key sizes). Such restrictions are not reflected in the returned list.

You can use functions C_GetMechanismList, C_GetMechanismInfo, as well as the command pkcsconf -m -c n to produce a list of accessible mechanisms. Function C_GetMechanismInfo returns CKR_MECHANISM_INVALID when the examined mechanism is restricted by the current ACP settings.

Since the EP11 token can use multiple EP11 cryptographic coprocessors and also multiple domains on a coprocessor, the access control points of all cryptographic coprocessors and domains are queried. Ideally, all coprocessors and domains should have identical ACP settings. If differences are detected, a message is issued to the SYSLOG, and the minimum ACP setting of all coprocessors and domains is used.

If multiple cryptographic coprocessors with different firmware levels are used, then only the mechanisms allowed by the ACP setting from the cryptographic coprocessor with the lowest firmware level are returned.

When the EP11 token configuration file specifies the APQN_ANY keyword, then the sysfs directories under /sys/devices/ap/ are scanned to find all available EP11 cryptographic coprocessors. If an APQN_WHITELIST is specified, then only those coprocessors specified in the white-list are used.

The associations of access control points with certain mechanisms are read from the so-called access control point filter configuration file. This allows to change the associations easily, when additional mechanisms or ACPs are added.

A default access control point filter configuration file is provided as part of the EP11 token. If the access control point filter configuration file is not found or is empty, then no ACP filter is applied.

The access control point filter configuration file that contains the definitions for the ACP filter is called ep11cpfilter.conf per default, and is located at the same place as the EP11 token configuration files. To choose a different name or location of the access control point filter configuration file, specify the CPFILTER keyword followed by the name and path of the access control point filter configuration file in the EP11 token configuration file, for example:

CPFILTER /etc/opencryptoki/ep11cpfilter.conf

In the access control point filter configuration file, each line specifies the number of an ACP, followed by a colon and a comma-separated list of mechanisms that are not available when this ACP is not set:

<cp>: <mech1, mech2, ...>

Both, the ACP number and the mechanisms can be specified as name, in decimal, octal (with leading 0), or hexadecimal (with leading 0x), for example:

XCP_CPB_SIGN_SYMM: CKM_SHA256_HMAC, CKM_SHA256_HMAC_GENERAL
4: 0x00000251, 0x00000252

The shown example filters out the mechanisms CKM_SHA256_HMAC (0x00000251) and CKM_SHA256_HMAC_GENERAL (0x00000252) when access control point (ACP) XCP_CPB_SIGN_SYMM (3) or XCP_CPB_SIGVERIFY_SYMM (4) is not set. In the first line, both the ACP and the affected mechanisms are specified as name, and in the second line, the ACP is specified by a decimal number and the mechanisms are identified by their hexadecimal values.

A list of ACPs can be found in document Enterprise PKCS#11 (EP11) Library structure (Table 11: Control points) that is provided as part of the EP11 library.

Note that you must not change the access control point filter configuration file shipped with openCryptoki unless you are advised to do so by IBM®.

The access control point filter configuration file is read once during token initialization (that is, within the C_Initialize function). It is kept in memory for the whole lifetime of the token. When changes are made to this configuration file, the token must be terminated and initialized again to have it read the file and activate the changes.