IBM-specific mechanisms

IBM-specific key-types

• CKK_IBM_PQC_DILITHIUM
• CKK_IBM_DILITHIUM
• CKK_IBM_PQC_KYBER
• CKK_IBM_KYBER

CKM_IBM_DILITHIUM

Availability:

The CKM_IBM_DILITHIUM mechanism is available with the EP11 token, the CCA token and the Soft token.

Description:

Dilithium is a post-quantum signature scheme. That is, it can generate signatures that resist attacks from quantum computers, but also from classical computers. Dilithium is one of the candidate algorithms submitted to the NIST post-quantum cryptography project.

The CCA, EP11, and Soft tokens provide one single mechanism for three operations: key generation, sign, and verify. Soft tokens additionally require an OQS provider which still supports Dilithium.

With the EP11 token, you can also import and export Dilithium keys by wrapping or unwrapping them using AES or TDES key encrypting keys (KEKs). That is, you can protect Dilithium keys that are sent to another system, received from another system, or stored with data in a file. Use any mechanism to wrap or unwrap IBM Dilithium keys that is convenient for your purposes, for example:

• CKM_AES_CBC_PAD
• CKM_DES3_CBC_PAD

On the TKE workstation, you must enable Dilithium processing by setting domain (access) control point 65 on the used cryptographic coprocessors :

65    XCP_CPB_ALG_PQC           enable support for post quantum cryptographic algorithms

The CCA token supports to import Dilithium keys from clear key values, as well as to import and export an existing CCA secure key token (key blob) via the CKA_IBM_OPAQUE attribute.

Due to the large key sizes, the CCA token does not support to wrap or unwrap Dilithium keys.

Prerequisites:

Using the CKM_IBM_DILITHIUM mechanism requires the following prerequisites:

• EP11 token: For Dilithium (6,5) Round 2, the EP11 host library 3.0 or later is required. For all other IBM Dilithium keys available with openCryptoki 3.20 or later, the EP11 host library 4.0 or later is required.
• CCA token: CCA release 7.1 or later is required to support Dilithium (6,5) Round 2. CCA release 8.0 or later is required to support Dilithium (8,7) Round 2, Dilithium (6,5) Round 3, and Dilithium (8,7) Round 3.
• If a Dilithium key is to be generated that is not supported by the used token, then the key generation fails with error code CKR_KEY_SIZE_RANGE.
• A Crypto Express7S feature or later, configured as Crypto Express EP11 coprocessor (CEX7P) with firmware level 7.15 or later is required.
• Not all firmware versions of EP11 cryptographic coprocessors support all Round 2 and Round 3 variants. Thus, a specific variant can only be used when all APQNs configured for the EP11 token support the desired variant. The EP11 token checks if all configured APQNs support the desired variant, and only then it allows to generate, import, or use an IBM Dilithium key with the desired variant.

Key type:

The IBM-specific key type for an IBM Dilithium key object is:

#define CKK_IBM_PQC_DILITHIUM    CKK_VENDOR_DEFINED + 0x10023
#define CKK_IBM_DILITHIUM        CKK_IBM_PQC_DILITHIUM

Key form:

The EP11 host library uses the following key form for IBM Dilithium public and private keys:

• Public key

  
  DilithiumPublicKey ::= BIT STRING {
     SEQUENCE {
        rho BIT STRING, [2]  -- nonce
        t1 BIT STRING [3]    -- from vector(L)
     }
  }

• Private key

  
  DilithiumPrivateKey ::= SEQUENCE {
     version INTEGER,   -- v0, reserved 0
     rho BIT STRING,    -- nonce
     key BIT STRING,    -- key/seed/D
     tr BIT STRING,     -- PRF bytes (’CRH’ in specification)
     s1 BIT STRING,     -- vector(L)
     s2 BIT STRING,     -- vector(K)
     t0 BIT STRING,     -- low bits(vector L)
     t1 [0] IMPLICIT OPTIONAL {
        t1 BIT STRING,  -- high bits(vector L) 
                        -- see also public key/SPKI
     }
  }
  

The currently supported key forms are:

Attributes:

PKCS #11 Cryptographic Token Interface Base Specification Version 3.0.

When generating Dilithium keys, an application can specify the CKA_IBM_DILITHIUM_KEYFORM or CKA_IBM_DILITHIUM_MODE attribute and thus select the variant to be used. For backward compatibility, if neither the CKA_IBM_DILITHIUM_KEYFORM nor CKA_IBM_DILITHIUM_MODE attribute is specified, it defaults to IBM_DILITHIUM_KEYFORM_ROUND2_65.

Key generation and unwrap operations supply the public Dilithium key attributes CKA_IBM_DILITHIUM_RHO and CKA_IBM_DILITHIUM_T1, as well as attributes CKA_IBM_DILITHIUM_KEYFORM and CKA_IBM_DILITHIUM_MODE to both, the public and the private key.

The SPKI is supplied in attribute CKA_VALUE to the public key.

When importing Dilithium keys from clear key values, you have two options:

• Specify the CKA_IBM_DILITHIUM_KEYFORM or CKA_IBM_DILITHIUM_MODE attribute together with the other public or private Dilithium key attributes. In this case, openCryptoki supplies the SPKI in the CKA_VALUE attribute to the public key during import.
• Specify the CKA_VALUE attribute to contain the SPKI or PKCS#8 encoding of the public or private key to import. In this case, CKA_IBM_DILITHIUM_KEYFORM and CKA_IBM_DILITHIUM_MODE must not be specified, since the OID is contained within the SPKI and PKCS#8 encoded key material.

Attributes CKA_IBM_DILITHIUM_KEYFORM and CKA_IBM_DILITHIUM_MODE are supplied to both, the public key and the private key during import.

The different Dilithium variants have different cryptographic strengths associated. The strength calculation used for openCryptoki policies and statistics take the used variant into consideration.

Functions for IBM Dilithium key creation and unwrapping:

Use function C_GenerateKeyPair() to create an IBM Dilithium key object consisting of a public/private key pair. Note that the CKM_IBM_DILITHIUM mechanism has no mechanism-specific parameters. The following is a sample for key object creation:

CK_BBOOL true = CK_TRUE;
CK_ATTRIBUTE public_template[] = {
    {CKA_VERIFY, &true, sizeof(true)},
};
CK_ATTRIBUTE private_template[] = {
    {CKA_SIGN, &true, sizeof(true)},
};

CK_MECHANISM mech;
CK_SESSION_HANDLE session;
CK_OBJECT_HANDLE publ_key = CK_INVALID_HANDLE, priv_key = CK_INVALID_HANDLE;
...
mech.mechanism = CKM_IBM_DILITHIUM;
mech.ulParameterLen = 0;
mech.pParameter = NULL;
CK_RV rv;

rv = C_GenerateKeyPair(session, &mech,
                   public_template, 1,
                   private_template, 1,
                   &publ_key, &priv_key);
if (rv == CKR_OK) {
...
}

Use functions C_WrapKey() and C_UnwrapKey() if you need to transport IBM Dilithium keys. See the following sample of an unwrapping operation:

CK_MECHANISM wrap_mech;
CK_OBJECT_HANDLE secret_key = CK_INVALID_HANDLE;
CK_BYTE_PTR wrapped_key = NULL;
CK_ULONG wrapped_keylen;
CK_OBJECT_HANDLE unwrapped_key = CK_INVALID_HANDLE;

CK_OBJECT_CLASS class = CKO_PRIVATE_KEY;
CK_KEY_TYPE key_type = CKK_IBM_PQC_DILITHIUM;
CK_OBJECT_HANDLE priv_key = CK_INVALID_HANDLE;
CK_BYTE unwrap_label[] = "unwrapped_private_Dilithium_Key";
CK_BBOOL true = TRUE;
CK_RV rv;

CK_ATTRIBUTE unwrap_tmpl[] = {
    {CKA_CLASS, &class, sizeof(class)},
    {CKA_KEY_TYPE, &key_type, sizeof(key_type)},
    {CKA_TOKEN, &true, sizeof(true)},
    {CKA_LABEL, &unwrap_label, sizeof(unwrap_label)},
    {CKA_SENSITIVE, &true, sizeof(true)},
    {CKA_DECRYPT, &true, sizeof(true)},
    {CKA_SIGN, &true, sizeof(true)},
};

wrap_mech.mechanism = CKM_AES_CBC_PAD;
wrap_mech.pParameter = "0123456789abcdef";
wrap_mech.ulParameterLen = 16;

/* Generate wrapping key */
...

/* Wrap Dilithium key with wrapping key */
...

/* Unwrap Dilithium key */
rv = funcs->C_UnwrapKey(session, &wrap_mech, secret_key,
                        wrapped_key, wrapped_keylen,
                        unwrap_tmpl,
                        sizeof(unwrap_tmpl) / sizeof(CK_ATTRIBUTE),
                        &priv_key);
if (rv != CKR_OK) {
   ...
}

Restrictions for using IBM Dilithium keys:

• IBM Dilithium keys cannot actively be used to transport (wrap and unwrap) other keys, but they can be wrapped and unwrapped for being transported using standard key types (AES, TDES).
• IBM Dilithium keys cannot be derived from given keys. They can only be generated or imported from given key values.
• Only SignInit() and Sign() (single-part operations) is supported by the EP11 host library. SignUpdate() and SignFinal() functions are not supported. The same restrictions apply for verify operations accordingly.

CKM_IBM_KYBER

Availability:

The CKM_IBM_KYBER mechanism is available with the EP11 token.

Description:

You can use this mechanism to generate quantum-safe Kyber key pairs as well as to perform encryption and decryption operations using Kyber keys. In addition, this mechanism offers methods to encapsulate or decapsulate (wrap or unwrap) keys (key encapsulation methods, KEM) which you can use to create shared secrets between to communicating parties.

On the TKE workstation, you must enable Kyber processing by setting domain (access) control point 65 on the used cryptographic coprocessors :

65    XCP_CPB_ALG_PQC           enable support for post quantum cryptographic algorithms

Prerequisites:

Using the CKM_IBM_KYBER mechanism has the following prerequisites:

• The EP11 host library 4.0 or later is required.
• A Crypto Express8S feature, configured as Crypto Express EP11 coprocessor (CEX8P) with firmware level 8.9 or later is required.
• Not all firmware versions of EP11 cryptographic coprocessors support all Round 2 and Round 3 variants. Thus, a specific variant can only be used when all APQNs configured for the EP11 token support the desired variant. The EP11 token checks if all configured APQNs support the desired variant, and only then it allows to generate, import, or use an IBM Kyber key with the desired variant.
• If a Kyber key is to be generated that is not supported by the token, then the key generation fails with error code CKR_KEY_SIZE_RANGE.

Key type:

The IBM-specific key type for an IBM Kyber key object is:

#define CKK_IBM_PQC_KYBER       CKK_VENDOR_DEFINED + 0x00010024
#define CKK_IBM_KYBER           CKK_IBM_PQC_KYBER

Key form:

Kyber keys consist of a private key component sk and public key component pk, as defined by the ANS1 encodings:

KyberPublicKey ::= BIT STRING { 
    SEQUENCE { 
        pk BIT STRING -- public key 
    } 
} 

KyberPrivateKey := SEQUENCE { 
    version INTEGER,      -- v0; reserved 0 
    sk      BIT STRING    -- secret key material
            [0] IMPLICIT OPTIONAL {
                pk||rs BIT STRING 
                 -- public key (pk) concatenated with 2x32 bytes rs (rs = 64 times 0x30)
            }
    }

The currently supported key forms are:

Attributes:

According to the key components, the following Kyber key component attributes are defined:

When generating Kyber keys, an application can specify the CKA_IBM_KYBER_KEYFORM or CKA_IBM_KYBER_MODE attribute and thus select the variant to be used. If neither the CKA_IBM_KYBER_KEYFORM nor CKA_IBM_KYBER_MODE attribute is specified, it defaults to CK_IBM_KYBER_KEYFORM_ROUND2_HIGH.

Key generation and unwrap operations supply the public Kyber key attribute CKA_IBM_KYBER_PK, as well as attributes CKA_IBM_KYBER_KEYFORM and CKA_IBM_KYBER_MODE to both, the public and the private key.

The SPKI is supplied in attribute CKA_VALUE to the public key.

When importing Kyber keys from clear key values, an application must either specify the CKA_IBM_KYBER_KEYFORM attribute together with the other public or private Kyber key attribute(s), or the application must specify CKA_VALUE containing the SPKI or PKCS#8 encoding of the public or private key to import. In this case, CKA_IBM_KYBER_MODE must not be specified, since the OID is contained within the SPKI and PKCS#8 encoded key material.

Import supplies the SPKI in CKA_VALUE to the public key, if the public key is imported from the individual Kyber key component attributes. Attributes CKA_IBM_KYBER_KEYFORM and CKA_IBM_KYBER_MODE are supplied to both, the public key and the private key during import.

Kyber offers both encryption/decryption and encapsulation/decapsulation mechanisms.

Encapsulation or decapsulation mechanisms, also summarized by the term key encapsulation mechanisms (KEM) can be used for creating shared secrets between two parties. Respective functionality is implemented using the C_DeriveKey() interface for key encapsulation and decapsulation.

The base key argument to C_DeriveKey() is either a public or a private Kyber key, respectively. Encapsulation generates a new secret and encrypts it using Kyber encryption. Both, the cipher text used for exchanging the generated secret as well as a handle of a new key are output from the encapsulation operation.

Kyber KEM functions

Use the following functions and parameters for Kyber KEM processing.

#define CKD_IBM_HYBRID_NULL          CKD_VENDOR_DEFINED + 0x00000001UL
#define CKD_IBM_HYBRID_SHA1_KDF      CKD_VENDOR_DEFINED + 0x00000002UL
#define CKD_IBM_HYBRID_SHA224_KDF    CKD_VENDOR_DEFINED + 0x00000003UL
#define CKD_IBM_HYBRID_SHA256_KDF    CKD_VENDOR_DEFINED + 0x00000004UL
#define CKD_IBM_HYBRID_SHA384_KDF    CKD_VENDOR_DEFINED + 0x00000005UL
#define CKD_IBM_HYBRID_SHA512_KDF    CKD_VENDOR_DEFINED + 0x00000006UL

typedef struct CK_IBM_KYBER_PARAMS {
    CK_ULONG ulVersion;
    CK_IBM_KYBER_KEM_MODE mode;
    CK_IBM_KYBER_KDF_TYPE kdf;
    CK_BBOOL bPrepend;
    CK_BYTE *pCipher;
    CK_ULONG ulCipherLen;
    CK_BYTE *pSharedData;
    CK_ULONG ulSharedDataLen;
    CK_OBJECT_HANDLE hSecret;
} CK_IBM_KYBER_PARAMS;

The mechanism parameter CK_IBM_KYBER_PARAMS is used with the C_DeriveKey() function to provide Kyber-KEM parameters. For encapsulation with a public key, field mode is set to CK_IBM_KYBER_KEM_ENCAPSULATE. Fields pCipher and ulCipherLen are output in this case, and must specify a buffer large enough to hold the returned cipher text. A symmetric key with a key type according to attribute CKA_KEY_TYPE in the derive template is returned, together with the cipher text in field pCipher. Field ulCipherLen is updated to hold the size of the returned cipher text. If the supplied cipher text buffer is too small to hold the returned cipher text, CKR_BUFFER_TOO_SMALL is returned.

For decapsulation with a private key, field mode is set to CK_IBM_KYBER_KEM_DECAPSULATE. Fields pCipher and ulCipherLen are input in this case and must specify the cipher text that was generated by the encapsulation step. A symmetric key with a key type according to attribute CKA_KEY_TYPE in the derive template is returned.

Hybrid key generation or derivation can be performed to concatenate multiple secrets into a generic secret key.

Initialize a hybrid secret using either an ECDH key derivation, or a Kyber KEM using CKD_IBM_HYBRID_NULL as key derivation function (KDF) in field kdf of CK_IBM_KYBER_PARAMS or CK_ECDH1_DERIVE_PARAMS.

It can then be concatenated with other secrets using Kyber KEM by specifying the hybrid secret in field hSecret together with a CKD_IBM_HYBRID_SHAxxx key derivation function in field kdf, and set field bPrepend to CK_TRUE to prepend the secret specified in hSecret with the Kyber secret. Or set the bPrepend field to CK_FALSE to concatenate the two secrets the other way round. Optionally you can specify additional shared data in fields pSharedData and ulSharedDataLen for the ANSI 9.63 key derivation.

For key encapsulation, the derive template for the resulting key must have CKA_EXTRACTABLE = CK_TRUE. All Kyber keys used in the derivation must have CKA_DERIVE = CK_TRUE. Hybrid secrets used in hybrid key derivation must have CKA_IBM_USE_AS_DATA = CK_TRUE.

The different Kyber variants have different cryptographic strength associated. The strength calculation used for openCryptoki policies and statistics must be adjusted to additionally take the used variant or key form into consideration.

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