IBM-specific mechanisms

IBM-specific key-types

• CKK_IBM_PQC_DILITHIUM
• CKK_IBM_DILITHIUM
• CKK_IBM_PQC_KYBER
• CKK_IBM_KYBER

CKM_IBM_SHA3_nnn

Availability:

The following SHA3 mechanisms are available for all openCryptoki tokens (CCA token, ICA token, EP11 token, and Soft token):

• CKM_IBM_SHA3_224
• CKM_IBM_SHA3_256
• CKM_IBM_SHA3_384
• CKM_IBM_SHA3_512

Description:

Use the listed mechanisms from the supporting tokens to perform the appropriate digest operations using the secure hash algorithm SHA3, which is the latest version of the Secure Hash Algorithm family as released by the National Institute of Standards and Technology (NIST).

CKM_IBM_SHA3_nnn_HMAC

Availability:

The following SHA3 - HMAC mechanisms are available for the ICA token, the EP11 token, and the Soft token:

• CKM_IBM_SHA3_224_HMAC
• CKM_IBM_SHA3_256_HMAC
• CKM_IBM_SHA3_384_HMAC
• CKM_IBM_SHA3_512_HMAC

Description:

Use the listed mechanisms from the supporting tokens to perform hash-based message authentication using the secure hash algorithm SHA3. The length of the HMAC output is according to the SHA3 hash sizes:

• CKM_IBM_SHA3_224_HMAC: 28 byte
• CKM_IBM_SHA3_256_HMAC: 32 byte
• CKM_IBM_SHA3_384_HMAC: 48 byte
• CKM_IBM_SHA3_512_HMAC: 64 byte

CKM_IBM_CMAC

Availability:

The CKM_IBM_CMAC mechanism is available with the EP11 token.

Description:

Use the CKM_IBM_CMAC mechanism to produce a block cipher-based message authentication code (CMAC) to assure the authenticity and integrity of a message. You can use this mechanism with AES or TDES keys (according to the PKCS #11 mechanisms CKM_AES_CMAC or CKM_DES3_CMAC).

The length of the output MAC is according to either the AES block size (16 bytes) or the TDES block size (8 bytes).

Flags and functions:

The CKF_SIGN and CKF_VERIFY flags are set to true for this mechanism. Therefore, the functions C_SignInit() and C_VerifyInit() accept the CKM_IBM_CMAC mechanism.

Mechanisms for Edwards Curves 25519 and 448 for ECDH and EdDSA

Availability:

The following mechanisms for Edwards Curves 25519 and 448 for ECDH and EdDSA are available with the EP11 token.

• CKM_IBM_EC_C448 (synonym: CKM_IBM_EC_X448)
• CKM_IBM_EC_C25519 (synonym: CKM_IBM_EC_X25519)
• CKM_IBM_ED448_SHA3
• CKM_IBM_ED25519_SHA512 (synonym: CKM_IBM_EDDSA_SHA512)

Description:

The CKM_IBM_EC_* mechanisms are used for key derivation with function C_DeriveKey(), and use the CK_ECDH1_DERIVE_PARAMS structure (same as for the CKM_ECDH1_DERIVE mechanism).

Mechanisms CKM_IBM_ED25519_SHA512 and CKM_IBM_ED448_SHA3 are used for sign/verify actions using the functions C_SignInit()/C_Sign() and C_VerifyInit()/C_Verify(). These mechanisms do not have a mechanism parameter.

Keys for use with these IBM-specific mechanisms are generated using mechanism CKM_EC_KEY_PAIR_GEN with function C_GenerateKeyPair(), just like ECC keys. Attribute CKA_EC_PARAMS specifies the OID of the curves to generate keys for. Importing known clear key values works the same as for ECC keys.

No special key type is defined for keys for Edwards curves with above mechanisms. Key type CKK_EC is also used for those keys. This is different to what is defined with the PKCS #11 version 3 standard, where additional key types are defined for such keys (CKK_EC_EDWARDS and CKK_EC_MONTGOMERY). Also PKCS #11 version 3 defined new mechanisms for generating such keys (CKM_EC_EDWARDS_KEY_PAIR_GEN and CKM_EC_MONTGOMERY_KEY_PAIR_GEN). Although different to PKCS #11 version 3, key type CKK_EC is used with these IBM-specific mechanisms as long as openCryptoki does not support the key types of PKCS #11 version 3.

CKM_IBM_ATTRIBUTEBOUND_WRAP

Availability:

The CKM_IBM_ATTRIBUTEBOUND_WRAP mechanisms is available with the EP11 token.

Description:

Keys may have attributes bound to them that control the usage of these key, for example, restrictions on operations, like exportability. Attribute-bound keys provide a different format for key wrapping and unwrapping, where attributes cannot be separated from the key during transport and thus must be contained in the wrapped format of the key. Therefore, you cannot use an attribute-bound key to wrap a classical key or the other way round. For all operations except key wrapping and unwrapping, attribute-bound keys behave exactly like regular keys. The CKM_IBM_ATTRIBUTEBOUND_WRAP mechanism supports the wrapping of such attribute-bound keys.

As a prerequisite, you must specify attribute CKA_IBM_ATTRBOUND with value CK_TRUE when creating a new key with bound attributes (default is CK_FALSE).

The goal of attribute-bound keys is to bind attributes to the key during transport via wrap and unwrap. Additionally, the CKM_IBM_ATTRIBUTEBOUND_WRAP mechanism adds a signing/verification processing to the wrapping/unwrapping actions. Part of the wrapped blob is signed and the signature is appended to the blob. When unwrapping the transported key, the signature is verified. For both actions, wrapping and unwrapping, the signing and verification key is propagated to the mechanism using a parameter (see the description of the CK_IBM_ATTRIBUTEBOUND_WRAP parameter later in this topic). To this end, you need both, a wrapping/unwrapping key pair and a signing/verification key pair for the key transport. Therefore, to transport an attribute-bound key using asymmetric keys for all involved operations, both sender and receiver create a key pair each, setting CKA_IBM_ATTRBOUND to CK_TRUE for both the public and the private keys.

Thereafter, sender and receiver exchange the public keys via the usual public key transport and then import this key using C_CreateObject(). Then, the sender applies wrapping using the CKM_IBM_ATTRIBUTEBOUND_WRAP mechanism on the attribute-bound key and sends the resulting blob to the receiver. The key is wrapped with the public key created by the receiver and signed by the private key created by the sender.

The receiver can unwrap the blob with its own private key and verify the signature with the public key created by the sender. Both, unwrapping and signature verification is done by the attribute-bound unwrapping mechanism CKM_IBM_ATTRIBUTEBOUND_WRAP.

Only symmetric keys and RSA key(pairs) are supported as wrapping keys, also called key encrypting keys (KEKs). The signing/verifying key can be a symmetric key, an RSA key, an ECC key, or a DSA key.

Attribute-bound keys contain a number of Boolean attributes, controlling the usage and trust inside the key blob. The attributes bound to the key are the following:

• CKA_EXTRACTABLE
• CKA_NEVER_EXTRACTABLE
• CKA_MODIFIABLE
• CKA_SIGN
• CKA_SIGN_RECOVER
• CKA_DECRYPT
• CKA_ENCRYPT
• CKA_DERIVE
• CKA_UNWRAP
• CKA_WRAP
• CKA_VERIFY
• CKA_VERIFY_RECOVER
• CKA_LOCAL
• CKA_WRAP_WITH_TRUSTED
• CKA_TRUSTED
• CKA_IBM_NEVER_MODIFIABLE (unsupported by openCryptoki)
• CKA_IBM_RESTRICTABLE (unsupported by openCryptoki)
• CKA_IBM_ATTRBOUND
• CKA_IBM_USE_AS_DATA
• CKA_KEY_TYPE
• CKA_VALUE_LEN

Following key types are supported as attribute-bound keys:

• CKK_AES
• CKK_DES2
• CKK_DES3
• CKK_GENERIC_SECRET
• CKK_RSA
• CKK_EC
• CKK_DSA
• CKK_DH
• CKK_IBM_PQC_DILITHIUM

Attempts to create an attribute-bound key of an unsupported type returns CKR_TEMPLATE_INCONSISTENT.

Key and key-pair generation You can specify the attribute CKA_IBM_ATTRBOUND only during key creation (for key pairs in both templates, private and public). If the attribute is specified as TRUE, the attribute CKA_SENSITIVE must be set to CK_TRUE in the attribute template for the public key as well. This can be implicitly done by the EP11 token configuration option FORCE_SENSITIVE. If, however, the option has its default value CK_FALSE, key or key pair generation fails with CKA_TEMPLATE_INCONSISTENT. Otherwise, attribute-bound keys behave exactly like non-attribute-bound keys.

Key derivation You can only use attribute-bound input keys to produce attribute-bound derived keys. That is, if the input key is not attribute-bound, but the attribute CKA_IBM_ATTRBOUND is set to CK_TRUE in the template for the derived key, derivation fails with return code CKR_TEMPLATE_INCONSISTENT.

By default, a derived key inherits from the input key. That is, if CKA_IBM_ATTRBOUND is not specified in the derivation template, it defaults to the value of the input key, or, if the input key does not specify CKA_IBM_ATTRBOUND, it defaults to CK_FALSE. Thus, you can derive attribute-bound keys from attribute-bound keys without specifying CKA_IBM_ATTRBOUND in the template for the derived key. However, it is possible to derive classical PKCS #11 keys from attribute-bound keys. To do this, set the attribute CKA_IBM_ATTRBOUND to FALSE in the template for the derived key. If CKA_IBM_ATTRBOUND is specified when deriving asymmetric keys, it must be specified for both templates with the same value. Otherwise, CKR_TEMPLATE_INCONSISTENT is returned.

Object creation Attribute-bound public keys can be created with C_CreateObject() by setting the CKA_IBM_ATTRBOUND attribute to TRUE. Attribute-bound private keys or secret keys can only be generated with the following functions:

• C_GenerateKey()
• C_GenerateKeyPair()
• C_DeriveKey()
• C_UnwrapKey()

C_CreateObject() returns CKR_ATTRIBUTE_VALUE_INVALID on an attempt to create attribute-bound private keys.

Object copy When copying an object, the attribute CKA_IBM_ATTRBOUND cannot be changed. An attempt to change it results in error CKA_ATTRIBUTE_READ_ONLY.

Attribute setting Since some boolean attributes, mostly key usage attributes, are bound to the key, the key blob changes when changing those attributes. This change is reflected in the value of the CKA_IBM_OPAQUE attribute. The attribute CKA_IBM_ATTRBOUND is read-only and cannot be changed. Attempts to change it returns error CKA_ATTRIBUTE_READ_ONLY. All other attributes follow standard PKCS #11 rules. However, attribute-bound keys must have CKA_SENSITIVE set to CK_TRUE and thus have additional restrictions according to PKCS #11.

How to use the CKM_IBM_ATTRIBUTEBOUND_WRAP mechanism:

The mechanism requires a parameter of type CK_IBM_ATTRIBUTEBOUND_WRAP.

typedef struct CK_IBM_ATTRIBUTEBOUND_WRAP {
  CK_OBJECT_HANDLE hSignVerifyKey;
} CK_IBM_ATTRIBUTEBOUND_WRAP_PARAMS;

This parameter provides the key for signing and verifying the wrapped key.

The CKM_IBM_ATTRIBUTEBOUND_WRAP mechanism has the following restrictions:

• All keys involved (target, wrapping/unwrapping, signature/verification) must be attribute-bound keys (CKA_IBM_ATTRBOUND = CK_TRUE). Otherwise:
  • For the target key on C_WrapKey(), CKR_KEY_NOT_WRAPPABLE is returned.
  • For the wrapping and unwrapping keys and the signature and verification keys, CKR_KEY_FUNCTION_NOT_PERMITTED is returned.
• On C_WrapKey(), the signing private key must be capable of signing (CKA_SIGN = CK_TRUE). Otherwise CKR_KEY_FUNCTION_NOT_PERMITTED is returned.
• On C_UnwrapKey(), the verification public key must be capable of verifying (CKA_VERIFY = CK_TRUE). Otherwise CKR_KEY_FUNCTION_NOT_PERMITTED is returned.

Only RSA and symmetric keys are supported as wrapping keys. Usage of other key types returns CKR_WRAPPING_KEY_TYPE_INCONSISTENT for wrapping, and CKR_UNWRAPPING_KEY_TYPE_INCONSISTENT for unwrapping.

Since the input blob to be unwrapped contains both the key and the attributes, C_UnwrapKey() also recreates all attributes bound to the key, except the ones flagged as not supported by openCryptoki (see the previous list of attributes).

For unwrapping, CKA_KEY_TYPE must be specified in the unwrap template and must match the value bound to the key. If the values do not match, unwrapping fails with CKR_TEMPLATE_INCONSISTENT. Any key attribute of the wrapped key that is not specified in the unwrap template, is ignored. After a successful unwrapping of the key and its attributes, the attributes are available via the standard PKCS #11 methods. Remember that attribute-bound keys are sensitive keys and have additional restrictions on attribute visibility.

Flags and functions:

CKF_WRAP and CKF_UNWRAP flags are set to true for this mechanism. Therefore, the functions C_WrapKey() and C_UnwrapKey accept the CKM_IBM_ATTRIBUTEBOUND_WRAP mechanism.

CKM_IBM_BTC_DERIVE

Availability:

The CKM_IBM_BTC_DERIVE mechanism is available with the EP11 token. On the TKE workstation, you must enable bitcoin derivation by setting the following access control point 66 on the used cryptographic coprocessors:

66  XCP_CPB_BTC   enable bitcoin (BTC) derivation with the CKM_IBM_BTC_DERIVE mechanism
 

Description:

You can use the CKM_IBM_BTC_DERIVE mechanism to derive a number of child keys from parent ECC keys generated from certain elliptic curves. The derived keys can be applied for encryption used by bitcoin. This mechanism in turn uses the methods described in BIP-0032 and SLIP-0010.

With method BIP-0032 you can derive keys from SECP256K1 curve ECC keys. With method SLIP-0010 you can derive ECC keys from secp256k1, prime256v1, or ED25519 curves.

Derivation is furthermore restricted to keys bearing the attributes CKA_IBM_USE_AS_DATA and CKA_DERIVE. For SLIP-0010 key derivation, ECC keys on different curves can be derived. Thus, the CKA_EC_PARAMS attribute needs to be present in the key attribute templates of both base and child key. The only exception is SLIP-0010 master key derivation for which the key type is determined solely from the attributes of the child key.

Each parent key can derive 2³¹ normal and 2³¹ hardened child keys given by a child key index.

In order to prevent the derived keys from depending solely on the parent key itself, both private and public keys are at first extended with an entropy of 256 bits (32 bytes). This extension, called the chain code, is identical for corresponding private and public keys.

The following derivation types are supported:

• Private parent key derives private child keys
• Public parent key derives public child keys
• Private parent key derives public child keys
• Master key derivation

The output of this mechanism contains the derived key, public or private, and the corresponding chain code.

For master key derivation, a generic secret key (CKK_GENERIC_SECRET) must be specified as base key. The mechanism parameter called CK_IBM_BTC_DERIVE_PARAMS (see Figure 1) must specify a buffer of 32 bytes size for the returned chain code, but the chain code length field within this parameter must be zero, because no chain code is input to the operation.

For child key derivation, an EC private or public key (CKK_EC) must be specified as base key. The CK_IBM_BTC_DERIVE_PARAMS mechanism parameter must specify a buffer of 32 bytes size containing the chain code corresponding to the base key. The chain code of the derived child key is also returned in this buffer. Thus you can use the derived child key again as a base key. The chain code length field must be 32 bytes.

For SLIP-0010 key derivation with ED25519 curves, only hardened key generation from private parent key to private or public child key is supported.

The following definitions are provided in header file pkcs11types.h which is in turn included in file pkcs11.h (see also Sample openCryptoki program).

#define CKM_IBM_BTC_DERIVE   CKM_VENDOR_DEFINED + 0x70001

typedef struct CK_IBM_BTC_DERIVE_PARAMS {
    CK_ULONG type;
    CK_ULONG childKeyIndex;
    CK_BYTE_PTR pChainCode;
    CK_ULONG ulChainCodeLen;
    CK_ULONG version;
} CK_IBM_BTC_DERIVE_PARAMS;

typedef CK_IBM_BTC_DERIVE_PARAMS   CK_PTR CK_IBM_BTC_DERIVE_PARAMS_PTR;

#define CK_IBM_BIP0032_HARDENED 0x80000000 // key index flag

#define CK_IBM_BIP0032_PRV2PRV 1
#define CK_IBM_BIP0032_PRV2PUB 2
#define CK_IBM_BIP0032_PUB2PUB 3
#define CK_IBM_BIP0032_MASTERK 4
#define CK_IBM_SLIP0010_PRV2PRV 5
#define CK_IBM_SLIP0010_PRV2PUB 6
#define CK_IBM_SLIP0010_PUB2PUB 7
#define CK_IBM_SLIP0010_MASTERK 8

#define CK_IBM_BTC_CHAINCODE_LENGTH 32

#define CK_IBM_BTC_DERIVE_PARAMS_VERSION_1 1
 

CKM_IBM_ECDSA_OTHER

Availability:

The CKM_IBM_ECDSA_OTHER mechanism is available with the EP11 token.

Description:

You can use this mechanism to generate Schnorr signatures, that is, EC-based signatures that are not produced using the ECDSA or the EDDSA digital signature algorithms.

On the TKE workstation, you must enable non-ECDSA and non-EdDSA elliptic curve signature algorithms, by setting the following access control point 67 on the used cryptographic coprocessors:

67  XCP_CPB_ECDSA_OTHER   enable non-ECDSA and non-EdDSA elliptic 
                          curve signature algorithms with the CKM_IBM_ECDSA_OTHER mechanism

The CKM_IBM_ECDSA_OTHER mechanism is a multi-variant signature mechanism for algorithms used by crypto-currency applications which differ from ECDSA or EDDSA. Several of these elliptic curve signature algorithms are generally variations of Schnorr signatures. The CKM_IBM_ECDSA_OTHER mechanism uses a mechanism parameter CK_IBM_ECDSA_OTHER_PARAMS that specifies the sub-mechanism to perform:

• CKM_IBM_ECSDSA_RAND: Randomized Schnorr signatures (BSI TR03111 ECSDSA, no pre-hashing, SHA-256 only)
• CKM_IBM_ECSDSA_COMPR_MULTI: Randomized Schnorr signatures (BSI TR03111 ECSDSA 2012, internally using compressed key format, and including signing party’s public key, no pre-hashing, SHA-256 only)

Only 256-bit elliptic curves are supported, in particular secp256k1, prime256v1, brainpoolP256r1, and brainpoolP256t1 curves.

The following definitions are provided in header file pkcs11types.h which is in turn included in file pkcs11.h (see also Sample openCryptoki program).

#define CKM_IBM_ECDSA_OTHER            CKM_VENDOR_DEFINED + 0x00010031

typedef struct CK_IBM_ECDSA_OTHER_PARAMS {
    CK_MECHANISM_TYPE submechanism;
} CK_IBM_ECDSA_OTHER_PARAMS;

typedef CK_IBM_ECDSA_OTHER_PARAMS CK_PTR CK_IBM_ECDSA_OTHER_PARAMS_PTR;

/* CKM_IBM_ECDSA_OTHER sub-mechanisms */
#define CKM_IBM_ECSDSA_RAND                3
#define CKM_IBM_ECSDSA_COMPR_MULTI         5