Support of IBM-specific mechanisms - p11-kit

Edit online

You can use the p11-kit command line tool to perform operations on PKCS #11 tokens configured on the system. It can especially be used to provide remote PKCS #11 API access to openCryptoki tokens through an RPC-like communication protocol.

The p11-kit tool is enhanced so that it supports IBM®-specific mechanisms and attributes used by openCryptoki. You should verify which mechanisms and attributes are exactly supported by the p11-kit version packaged by your distribution.

Using p11-kit to access an openCryptoki token from a remote system

On the client side, a p11-kit client library acts as a PKCS #11 interface for the application. It forwards all API calls to a p11-kit server over a network connection. On the server side, the API calls are then passed to another PKCS #11 interface library, that is, to openCryptoki’s API library.

The communication between p11-kit client and p11-kit server is based on UNIX domain sockets, which are forwarded through an SSH tunnel from the client to the server. Because an SSH tunnel is used, the communication is encrypted and authenticated by means of regular SSH authentication.

The client side may run on a different architecture than the server, because the RPC protocol is endianess-save. It is for example possible to run the client application on an x86-Linux, connecting to an s390x-Linux running openCryptoki with the EP11 token.

The p11-kit tool needs to explicitly know all mechanisms and attributes in order to support them. For mechanisms, it needs to know if a mechanism uses a mechanism parameter, and if so, how to serialize the mechanism parameter. Some complex mechanism parameters require specific serialization, especially when the mechanism parameter structure contains pointers to other buffers.

Mechanisms that are not known by p11-kit on the client side are filtered out. The mechanism list retrieved by the application only contains those mechanisms that are supported by both sides.

For attributes, the p11-kit tool needs to know the data type of each attribute, that is, if the attribute contains a boolean value, an ULONG value, or a byte array (binary) value, in order to serialize it properly (that means,. endianess for ULONG attributes).

Support for the following mechanisms (including mechanism parameter serialization support as needed) is added:

  • CKM_IBM_ATTRIBUTEBOUND_WRAP (mechanism parameter: CK_IBM_ATTRIBUTEBOUND_WRAP_PARAMS)
  • CKM_IBM_BTC_DERIVE.
  • CKM_IBM_CMAC
  • CKM_IBM_DILITHIUM
  • CKM_IBM_ECDSA_OTHER
  • CKM_IBM_EC_X448 (mechanism parameter: CK_ECDH1_DERIVE_PARAMS)
  • CKM_IBM_EC_X25519 (mechanism parameter: CK_ECDH1_DERIVE_PARAMS)
  • CKM_IBM_ED448_SHA3
  • CKM_IBM_ED25519_SHA512
  • CKM_IBM_KYBER
  • CKM_IBM_SHA3_224
  • CKM_IBM_SHA3_256
  • CKM_IBM_SHA3_384
  • CKM_IBM_SHA3_512
  • CKM_IBM_SHA3_224_HMAC
  • CKM_IBM_SHA3_256_HMAC
  • CKM_IBM_SHA3_384_HMAC
  • CKM_IBM_SHA3_512_HMAC

Support for the following attributes is added:

  • CKA_IBM_OPAQUE (binary)
  • CKA_IBM_RESTRICTABLE (boolean)
  • CKA_IBM_NEVER_MODIFIABLE (boolean)
  • CKA_IBM_RETAINKEY (boolean)
  • CKA_IBM_ATTRBOUND (boolean)
  • CKA_IBM_KEYTYPE (ULONG)
  • CKA_IBM_CV (binary)
  • CKA_IBM_MACKEY (binary)
  • CKA_IBM_USE_AS_DATA (boolean)
  • CKA_IBM_STRUCT_PARAMS (binary)
  • CKA_IBM_STD_COMPLIANCE1 (ULONG)
  • CKA_IBM_PROTKEY_EXTRACTABLE (boolean)
  • CKA_IBM_PROTKEY_NEVER_EXTRACTABLE (boolean)
  • CKA_IBM_DILITHIUM_KEYFORM (ULONG)
  • CKA_IBM_DILITHIUM_RHO (binary)
  • CKA_IBM_DILITHIUM_SEED (binary, sensitive)
  • CKA_IBM_OPAQUE_REENC
  • CKA_IBM_OPAQUE_OLD
  • CKA_IBM_DILITHIUM_MODE
  • CKA_IBM_CCA_AES_KEY_MODE

Support for the following key type is added:

  • CKK_IBM_PQC_DILITHIUM

Besides the previously listed IBM-specific mechanisms, support for the following standard mechanisms is added, which require special mechanism parameter serialization support:

  • CKM_ECDH1_DERIVE (Mechanism parameter: CK_ECDH1_DERIVE_PARAMS)
  • CKM_SHA1_RSA_PKCS_PSS
  • CKM_SHA224_RSA_PKCS_PSS
  • CKM_SHA256_RSA_PKCS_PSS
  • CKM_SHA384_RSA_PKCS_PSS
  • CKM_SHA512_RSA_PKCS_PSS
  • CKM_AES_CBC (mechanism parameter: 16 bytes IV)
  • CKM_AES_CBC_PAD (mechanism parameter: 16 bytes IV)
  • CKM_AES_OFB (mechanism parameter: 16 bytes IV)
  • CKM_AES_CFB1 (mechanism parameter: 16 bytes IV)
  • CKM_AES_CFB8 (mechanism parameter: 16 bytes IV)
  • CKM_AES_CFB64 (mechanism parameter: 16 bytes IV)
  • CKM_AES_CFB128 (mechanism parameter: 16 bytes IV)
  • CKM_AES_CTS (mechanism parameter: 16 bytes IV)
  • CKM_AES_CTR (mechanism parameter: CK_AES_CTR_PARAMS)
  • CKM_AES_GCM (mechanism parameter: CK_GCM_PARAMS)
  • CKM_DES_CBC (mechanism parameter: 8 bytes IV)
  • CKM_DES_CBC_PADC (mechanism parameter: 8 bytes IV)
  • CKM_DES3_CBCC (mechanism parameter: 8 bytes IV)
  • CKM_DES3_CBC_PADC (mechanism parameter: 8 bytes IV)
  • CKM_DES_CFB8C (mechanism parameter: 8 bytes IV)
  • CKM_DES_CFB64C (mechanism parameter: 8 bytes IV)
  • CKM_DES_OFB64C (mechanism parameter: 8 bytes IV)
  • CKM_SHA_1_HMAC_GENERAL (mechanism parameter: CK_MAC_GENERAL_PARAMS, which is a CK_ULONG)
  • CKM_SHA224_HMAC_GENERAL (mechanism parameter: CK_MAC_GENERAL_PARAMS, which is a CK_ULONG)
  • CKM_SHA256_HMAC_GENERAL (mechanism parameter: CK_MAC_GENERAL_PARAMS, which is a CK_ULONG)
  • CKM_SHA384_HMAC_GENERAL (mechanism parameter: CK_MAC_GENERAL_PARAMS, which is a CK_ULONG)
  • CKM_SHA512_HMAC_GENERAL (mechanism parameter: CK_MAC_GENERAL_PARAMS, which is a CK_ULONG)
  • CKM_SHA512_224_HMAC_GENERAL (mechanism parameter: CK_MAC_GENERAL_PARAMS, which is a CK_ULONG)
  • CKM_SHA512_256_HMAC_GENERAL (mechanism parameter: CK_MAC_GENERAL_PARAMS, which is a CK_ULONG)
  • CKM_AES_MAC_GENERAL (mechanism parameter: CK_MAC_GENERAL_PARAMS, which is a CK_ULONG)
  • CKM_AES_CMAC_GENERAL (mechanism parameter: CK_MAC_GENERAL_PARAMS, which is a CK_ULONG)
  • CKM_DES3_MAC_GENERAL (mechanism parameter: CK_MAC_GENERAL_PARAMS, which is a CK_ULONG)
  • CKM_DES3_CMAC_GENERAL (mechanism parameter: CK_MAC_GENERAL_PARAMS, which is a CK_ULONG)
  • CKM_DH_PKCS_DERIVE (mechanism parameter: public value of the other party)

The following features of openCryptoki are not supported by the p11-kit:

  • Attribute templates are not supported by p11-kit (CKA_WRAP_TEMPLATE, CKA_UNWRAP_TEMPLATE, CKA_DERIVE_TEMPLATE).
  • PKCS #11 version 3.0 interfaces are not supported (C_GetInterfaceList(), C_GetInterface()).
  • C_IBM_ReencryptSingle() is not supported because it is available only via a vendor specific interface obtainable from C_GetInterface().