Vendor-defined mechanisms

The following vendor-defined mechanisms are also available. The numeric values of vendor-defined key types and mechanisms can be found in the supplied pkcs11extra.h header file.

Some mechanisms may be restricted from use in Security Worlds conforming to FIPS 140 Level 3. See the User Guide for your HSM for more information.

CKM_SEED_ECB_ENCRYPT_DATA and CKM_SEED_CBC_ENCRYPT_DATA

This mechanism derives a secret key by encrypting plain data with the specified secret base key. This mechanism takes as a parameter a CK_KEY_DERIVATION_STRING_DATA structure, which specifies the length and value of the data to be encrypted by using the base key to derive another key.

If no length or key type is provided in the template, the key produced by this mechanism is a generic secret key. Its length is equal to the length of the data.

If a length, but no key type, is provided in the template, the key produced by this mechanism is a generic secret key of the specified length.

If a key type, but no length, is provided in the template, the key type must have a well-defined length. If the length is well defined, the key produced by this mechanism is of the type specified in the template. If the length is not well defined, a CKR_TEMPLATE_INCOMPLETE error is returned.

If both a key type and a length are provided in the template, the length must be compatible with that key type, and CKR_TEMPLATE_INCONSISTENT is returned if it is not.

The key produced by the CKM_SEED_ECB_ENCRYPT_DATA or CKM_SEED_CBC_ENCRYPT_DATA mechanisms is of the specified type and length.

CKM_CAC_TK_DERIVATION

This mechanism uses C_GenerateKey to perform an Import operation using a Transport Key Component.

The mechanism accepts a template that contains three Transport Key Components (TKCs) with following attribute types:

  • CKA_TKC1

  • CKA_TKC2

  • CKA_TKC3.

These attributes are all in the CKA_VENDOR_DEFINED range.

Each TKC should be the same length as the key being created. TKCs used for DES, DES2, or DES3 keys must have odd parity. The mechanism checks for odd parity and returns CKR_ATTRIBUTE_VALUE_INVALID if it is not found.

The new key is constructed by an XOR of the three TKC components on the module.

Although using C_GenerateKey creates a key with a known value rather than generating a new one, it is used because C_CreateObject does not accept a mechanism parameter.

CKA_LOCAL, CKA_ALWAYS_SENSITIVE, and CKA_NEVER_EXTRACTABLE are set to FALSE, as they would for a key imported with C_CreateObject. This reflects the fact that the key was not generated locally.

An example of the use of CKM_CAC_TK_DERIVATION is shown here:

CK_OBJECT_CLASS class_secret = CKO_SECRET_KEY;
        CK_KEY_TYPE key_type_des2 = CKK_DES2;
        CK_MECHANISM mech = { CKM_CAC_TK_DERIVATION, NULL_PTR, 0 };
        CK_BYTE TKC1[16] = { ... };
        CK_BYTE TKC2[16] = { ... };
        CK_BYTE TKC3[16] = { ... };
        CK_OBJECT_HANDLE kHey;
        CK_ATTRIBUTE pTemplate[] = {
                { CKA_CLASS, &class_secret, sizeof(class_secret) },
                { CKA_KEY_TYPE, &key_type_des2, sizeof(key_type_des2) },
                { CKA_TKC1, TKC1, sizeof(TKC1) },
                { CKA_TKC2, TKC1, sizeof(TKC2) },
                { CKA_TKC3, TKC1, sizeof(TKC3) },
                { CKA_ENCRYPT, &true, sizeof(true) },
        ....
        };

        rv = C_GenerateKey(hSession, &mechanism, pTemplate,
                (sizeof(pTemplate)/sizeof((pTemplate)[0])), &hKey);

CKM_SHA*_HMAC and CKM_SHA*_HMAC_GENERAL

This version of the library supports the following mechanisms:

  • CKM_SHA_1_HMAC

  • CKM_SHA_1_HMAC_GENERAL

  • CKM_SHA224_HMAC

  • CKM_SHA224_HMAC_GENERAL

  • CKM_SHA256_HMAC

  • CKM_SHA256_HMAC_GENERAL

  • CKM_SHA384_HMAC

  • CKM_SHA384_HMAC_GENERAL

  • CKM_SHA512_HMAC

  • CKM_SHA512_HMAC_GENERAL

  • CKM_SHA3_224_HMAC

  • CKM_SHA3_224_HMAC_GENERAL

  • CKM_SHA3_256_HMAC

  • CKM_SHA3_256_HMAC_GENERAL

  • CKM_SHA3_384_HMAC

  • CKM_SHA3_384_HMAC_GENERAL

  • CKM_SHA3_512_HMAC

  • CKM_SHA3_512_HMAC_GENERAL

For security reasons, the Security World Software supports these mechanisms only with their own specific key type. Thus, you can only use an HMAC key with the HMAC algorithm and not with other algorithms.

The key types provided for use with SHA<n> HMAC mechanisms are:

  • CKK_SHA_1_HMAC

  • CKK_SHA224_HMAC

  • CKK_SHA256_HMAC

  • CKK_SHA384_HMAC

  • CKK_SHA512_HMAC

  • CKK_SHA3_224_HMAC

  • CKK_SHA3_256_HMAC

  • CKK_SHA3_384_HMAC

  • CKK_SHA3_512_HMAC

To generate the key, use the appropriate key generation mechanism (which does not take any mechanism parameters):

  • CKM_NC_MD5_HMAC_KEY_GEN

  • CKM_NC_SHA_1_HMAC_KEY_GEN

  • CKM_NC_SHA224_HMAC_KEY_GEN

  • CKM_NC_SHA256_HMAC_KEY_GEN

  • CKM_NC_SHA384_HMAC_KEY_GEN

  • CKM_NC_SHA512_HMAC_KEY_GEN

  • CKM_SHA3_224_KEY_GEN

  • CKM_SHA3_256_KEY_GEN

  • CKM_SHA3_384_KEY_GEN

  • CKM_SHA3_512_KEY_GEN

CKM_NC_ECKDF_HYPERLEDGER

This version of the library supports the vendor-defined CKM_NC_ECKDF_HYPERLEDGER mechanism. This key derivation function is used in the user/client enrolment process of a hyperledger system to generate transaction certificates by using the enrolment certificate as one of the inputs to the key derivation.

The parameters for the mechanism are defined in the following structure:

typedef struct CK_ECKDF_HYPERLEDGERCLIENT_PARAMS {
    CK_OBJECT_HANDLE hKeyDF_Key;
    CK_MECHANISM_TYPE HMACMechType;
    CK_MECHANISM_TYPE TCertEncMechType;
    CK_ULONG ulEksize;
    CK_BYTE_PTR pEncTCertData;
    CK_ULONG ulEvsize;
    CK_ULONG ulEndian;
} CK_ECKDF_HYPERLEDGERCLIENT_PARAMS

Where:

  • hKeyDF_key is KeyDF_Key

  • HMACMechType is Hmac

  • TCertEncMechType is Decrypt_Mech

  • ulEksize is Eksize

  • pEncTCertData is a pointer to encrypted data containing TCertIndex together with padding and IV

  • ulEvsize is Evsize

  • ulEndian is Big_Endian

The function is then called as follows:

C_DeriveKey(
    hSession,
    &mechanism_hyperledger,
    EnrollPriv_Key,
    TCertPriv_Key_template,
    NUM(TCertPriv_Key_template,
    &TCertPriv_Key);

A Template_Key will be used to supply key attributes for the resulting derived key. The derived key can then be used in the normal way.

Derived keys can be exported and used outside the HSM only if the template key was created with attributes which allow export of its derived keys.

CKM_HAS160

This version of the library supports the vendor-defined CKM_HAS160 hash (digest) mechanism for use with the CKM_KCDSA mechanism. For more information, see KISAAlgorithm mechanisms.

CKM_HAS160 is a basic hashing algorithm. The hashing is done on the host machine. This algorithm can be used by means of the standard digest function calls of the PKCS #11 API.

CKM_PUBLIC_FROM_PRIVATE

CKM_PUBLIC_FROM_PRIVATE is a derive key mechanism that enables the creation of a corresponding public key from a private key. The mechanism also fills in the public parts of the private key, where this has not occurred.

CKM_PUBLIC_FROM_PRIVATE is an nShield specific nCore mechanism. The C_Derive function takes the object handle of the private key and the public key attribute template. The creation of the key is based on the template but also checked against the attributes of the private key to ensure the attributes are correct and match those of the corresponding key. If an operation that is not allowed or is not set by the private key is detected, then CKR_TEMPLATE_INCONSISTANT is returned.

Before you can use this mechanism, the HSM must already contain the private key. You must use C_CreateObject, C_UnWrapKey, or C_GenerateKeyPair to import or generate the private key.
If you use C_GenerateKeyPair, you always generate a public key at the same time as the private key. Some applications delete public keys once a certificate is imported, but in the case of both C_GenerateKeyPair and C_CreateObject you can use either the CKM_PUBLIC_FROM_PRIVATE mechanism or the C_GetAttributeValue to recreate a deleted public key.

CKM_NC_AES_CMAC

CKM_NC_AES_CMAC is based on the Mech_RijndaelCMAC nCore level mechanism, a message authentication code operation that is used with both C_Sign and C_SignUpdate, and the corresponding C_Verify and C_VerifyUpdate functions.

In a similar way to other AES MAC mechanisms, CKM_NC_AES_CMAC takes a plaintext type of any length of bytes, and returns a M_Mech_Generic128MAC_Cipher standard byte block. CKM_NC_AES_CMAC is a standard FIPS 140 Level 3 approved mechanism, and is only usable with CKK_AES key types.

CKM_NC_AES_CMAC has a CK_MAC_GENERAL_PARAMS which is the length of the MAC returned (sometimes called a tag length). If this is not specified, the signing operation fails with a return value of CKR_MECHANISM_PARAM_INVALID.

CKM_NC_AES_CMAC_KEY_DERIVATION and CKM_NC_AES_CMAC_KEY_DERIVATION_SCP03

This mechanism derives a secret key by validating parameters with the specified 128-bit, 192-bit, or 256-bit secret base AES key. This mechanism takes as a parameter a CK_NC_AES_CMAC_KEY_DERIVATION_PARAMS structure, which specifies the length and type of the resulting derived key.

CKM_NC_AES_CMAC_KEY_DERIVATION_SCP03 is a variant of CKM_NC_AES_CMAC_KEY_DERIVATION: it reorders the arguments in the CK_NC_AES_CMAC_KEY_DERIVATION_PARAMS according to payment specification SCP03, but is otherwise identical.

The standard key attribute behavior with sensitive and extractable attributes is applied to the resulting key as defined in PKCS #11 standard version 2.20 and later. The key type and template declaration is based on the PKCS #11 standard key declaration for derive key mechanisms.

If no length or key type is provided in the template, the key produced by this mechanism is a generic secret key. Its length is equal to the length of the data.

If a length, but no key type, is provided in the template, the key produced by this mechanism is a generic secret key of the specified length.

If a key type, but no length, is provided in the template, the key type must have a well-defined length. If the length is well defined, the key produced by this mechanism is of the type specified in the template. If the length is not well defined, a CKR_TEMPLATE_INCOMPLETE error is returned.

If both a key type and a length are provided in the template, the length must be compatible with that key type, and CKR_TEMPLATE_INCONSISTENT is returned if it is not.

The key produced by the CKM_NC_AES_CMAC_KEY_DERIVATION mechanism is of the specified type and length. If a DES, DES2, DES3, or CDMF key is derived with this mechanism, the parity bits of the key are set properly. If the requested type of key requires more bytes than are available by concatenating the original key values, an error is generated.

This mechanism has the following rules about key sensitivity and extractability:

Attribute If the attributes for the original keys are…​ The attribute for the derived key is…​

CKA_SENSITIVE

CK_TRUE for either one

CK_TRUE

CKA_EXTRACTABLE

CK_FALSE for either one

CK_FALSE

CKA_ALWAYS_SENSITIVE

CK_TRUE for both

CK_TRUE

CKA_NEVER_EXTRACTABLE

CK_TRUE for both

CK_TRUE

CK_NC_AES_CMAC_KEY_DERIVATION_PARAMS

typedef struct CK_NC_AES_CMAC_KEY_DERIVATION_PARAMS {
    CK_ULONG ulContextLen;
    CK_BYTE_PTR pContext;
    CK_ULONG ulLabelLen;
    CK_BYTE_PTR pLabel;
  } CK_NC_AES_CMAC_KEY_DERIVATION_PARAMS;

The fields of the structure have the following meanings:

Argument Meaning

ulContextLen

Context data: the length in bytes.

pContext

Some data info context data (bytes to be CMAC’d).

ulContextLen must be zero if pContext is not provided.

Having pContext as NULL will result in the same predictable key each time not additional data to add to the mix when carrying out the CMAC.

ulLabelLen

The length in bytes of the other party EC public key

pLabel

Key derivation label data: a pointer to the other label to identify new key. ulLabelLen must be zero if the pLabel is not provided.

CKM_COMPOSITE_EMV_T_ARQC, CKM_WATCHWORD_PIN1 and CKM_WATCHWORD_PIN2

These mechanisms allow the module to act as a SafeSign Cryptomodule (SSCM). To obtain support for your product, visit https://nshieldsupport.entrust.com.

CKM_NC_ECIES

This version of the library supports the vendor defined CKM_NC_ECIES mechanism. This mechanism is used with C_WrapKey and C_UnwrapKey to wrap and unwrap symmetric keys using the Elliptic Curve Integrated Encryption Scheme (ECIES).

The parameters for the mechanism are defined in the following structure:

typedef struct CK_NC_ECIES_PARAMS {
       CK_MECHANISM_PTR <pAgreementMechanism>;
       CK_MECHANISM_PTR <pSymmetricMechanism>;
       CK_ULONG         <ulSymmetricKeyBitLen>;
       CK_MECHANISM_PTR <pMacMechanism>;
       CK_ULONG         <ulMacKeyBitLen>;
} CK_NC_ECIES_PARAMS;

Where:

  • <pAgreementMechanism> is the key agreement mechanism, which must be CKM_ECDH1_DERIVE or CKM_ECDH1_COFACTOR_DERIVE

  • <pSymmetricMechanism> is the confidentiality mechanism, currently only CKM_XOR_BASE_AND_DATA is supported

  • <ulSymmetricKeyBitLen> is the confidentiality key length (in bits) and must be a multiple of 8. For CKM_XOR_BASE_AND_DATA the key length is irrelevant and can be set to zero.

  • <pMacMechanism> is the integrity mechanism, currently only CKM_SHA<n>_HMAC_GENERAL is supported and <n> can be _1, 224, 256, 384 or 512

  • <ulMacKeyBitLen> is the integrity key length (in bits) and must be a multiple of 8

The following example shows how to use CKM_NC_ECIES to wrap a symmetric key:

/* session represents an existing open session */
CK_SESSION_HANDLE session;

/* symmetric_key and wrapping_key represent existing keys. The code to import or
 * generate them is not shown here. Note wrapping_key must be a public EC key
 * with CKA_WRAP set to true */
CK_OBJECT_HANDLE symmetric_key;
CK_OBJECT_HANDLE wrapping_key;

CK_ECDH1_DERIVE_PARAMS ecdh1_params = { CKD_SHA256_KDF };
CK_MECHANISM agreement_mech = {
       CKM_ECDH1_DERIVE,
       &ecdh1_params,
       sizeof(CK_ECDH1_DERIVE_PARAMS)
};
CK_MECHANISM symmetric_mech = { CKM_XOR_BASE_AND_DATA };
CK_MAC_GENERAL_PARAMS mac_params = 16;
CK_MECHANISM mac_mech = {
       CKM_SHA256_HMAC_GENERAL,
       &mac_params,
       sizeof(CK_MAC_GENERAL_PARAMS)
};
CK_NC_ECIES_PARAMS ecies_params = {
       &agreement_mech,
       &symmetric_mech,
       0,
       &mac_mech,
       256
};
CK_MECHANISM ecies_mech = {
       CKM_NC_ECIES,
       &ecies_params,
       sizeof(CK_NC_ECIES_PARAMS)
};

/* Typical convention is to call C_WrapKey with the pWrappedKey parameter set to
 * NULL_PTR to determine the required size of the buffer - see Section 5.2 of
 * the PKCS#11 Base Specification - but for brevity we allocate a 1KB buffer */
CK_BYTE wrapped_key[1000] = { 0 };
CK_ULONG wrapped_len = sizeof(wrapped_key);
CK_RV rv = C_WrapKey(session, &ecies_mech, wrapping_key, symmetric_key,
                                               wrapped_key, &wrapped_len);

CKM_NC_MILENAGE_OPC

Derive CKK_NC_MILENAGEOPC key from CKK_NC_MILENAGEOP and CKK_NC_MILENAGESUBSCRIBER keys for use in the 3GPP mechanisms defined in ETSI TS 135 206 s4.1.

A C_DeriveKey function call is made. The function takes the CKK_NC_MILENAGESUBSCRIBER key handle as the base key and the CKK_NC_MILENAGEOP key handle as the mechanism parameter.

To generate the subscriber and OP keys, use the corresponding vendor-defined key generation mechanisms (which do not take any mechanism parameters):

  • CKM_NC_MILENAGESUBSCRIBER_KEY_GEN

  • CKM_NC_MILENAGEOP_KEY_GEN

CKM_NC_MILENAGE, CKM_NC_MILENAGE_AUTS, CKM_NC_MILENAGE_RESYNC

3GPP mechanisms for 5G mobile networks as defined by ETSI TS 135 206. Used with C_SignInit and C_Sign function calls. The parameters for these mechanisms are defined in the following structure:

typedef struct CK_MILENAGE_SIGN_PARAMS {
  CK_ULONG ulMilenageFlags;
  CK_ULONG ulEncKiLen;            /* not used - must be 0 */
  CK_BYTE_PTR pEncKi;             /* not used */
  CK_ULONG ulEncOPcLen;           /* not used - must be 0 */
  CK_BYTE_PTR pEncOPc;            /* not used */
  CK_OBJECT_HANDLE hSecondaryKey; /* CKK_NC_MILENAGE_OPC key handle */
  CK_OBJECT_HANDLE hRCKey;        /* optional CKK_NC_MILENAGE_RC key handle */
  CK_BYTE sqn[6];                 /* sequence number */
  CK_BYTE amf[2];                 /* authentication management field */
} CK_MILENAGE_SIGN_PARAMS;

ulMilenageFlags can consist of the following flags:

#define CKF_NC_MILENAGE_OPC                 0x00000001  /* secondary key is OPC (not OP) */
#define CKF_NC_MILENAGE_OP_OBJECT           0x00000004  /* secondary key is supplied by object handle */
#define CKF_NC_MILENAGE_USER_DEFINED_RC     0x00000010  /* MilenageRC key is present (hRC) */

Both the CKF_NC_MILENAGE_OPC and CKF_NC_MILENAGE_OP_OBJECT flags must be present. The nShield PKCS #11 library currently only supports passing the OPC key handle to the mechanism.

If the CKF_NC_MILENAGE_USER_DEFINED_RC flag is set, hRCKey must point to a CKK_NC_MILENAGE_RC key object handle.

CKM_NC_MILENAGE

Computes the MILENAGE f1/f2/f3/f4/f5 functions as defined in ETSI TS 135 206 s4.1 and thus generates the Authentication Vector (AV) as defined in the ETSI Authentication and Key Agreement (AKA) protocol. This single output vector is the concatenated values RAND||XRES||CK||IK||XOR(SQN,AK)||AMF||MAC.

The following example shows how to use CKM_NC_MILENAGE:

/* session represents an existing open session */
CK_SESSION_HANDLE session;

/* subscriber_key, opc_key and rc_key represent existing keys */
CK_OBJECT_HANDLE subscriber_key, opc_key, rc_key;

/* sqn, amf and rand represent existing byte arrays holding the sequence number,
 * authentication management field and RAND challenge respectively
 * rand is optional */
CK_BYTE sqn[6], amf[2], rand[16];

CK_MILENAGE_SIGN_PARAMS milenage_params;
milenage_params.ulMilenageFlags = CKF_NC_MILENAGE_OP_OBJECT | CKF_NC_MILENAGE_OPC;
milenage_params.hSecondaryKey = opc_key;
memcpy(&(milenage_params.sqn), sqn, 6);
memcpy(&(milenage_params.amf), amf, 2);

/* a user-defined RC key is optional */
milenage_params.ulMilenageFlags |= CKF_NC_MILENAGE_USER_DEFINED_RC;
milenage_params.hRCKey = rc_key;

CK_MECHANISM milenage_mech = {CKM_NC_MILENAGE, &milenage_params, sizeof(milenage_params)};

/* Typical convention is to call C_Sign with the pData parameter set to
 * NULL to determine the required size of the buffer - see Section 5.2 of
 * the PKCS#11 Base Specification - but for brevity we allocate a 72 byte buffer
 * since CKM_NC_MILENAGE output length is constant. */

CK_RV rv;
CK_BYTE milenage_result[72] = {0};
CK_ULONG milenage_len = sizeof(milenage_result);
rv = C_SignInit(session, &milenage_mech, subscriber_key);
if (rv != CKR_OK) return rv;
rv = C_Sign(session, rand, 16, milenage_result, &milenage_len);
if (rv != CKR_OK) return rv;

The RAND value passed to C_Sign is optional and can be left as NULL. A user-defined RC key is also optional and can be omitted by removing the CKF_NC_MILENAGE_USER_DEFINED_RC flag and leaving hRCKey as NULL.

An RC key can be generated using CKM_NC_MILENAGERC_KEY_GEN or created using custom values with C_CreateObject (see Object management functions for details). If no RC key is supplied, the default values defined in ETSI TS 135 206 s4.1 will be used.

CKM_NC_MILENAGE_RESYNC

Performs part of the resynchronization procedure as described in the AKA protocol. This computes the MILENAGE f1*/f5* functions as defined in ETSI TS 135 206 s4.1 and verifies AUTS (i.e. XOR(SQN_UE,AK)||MAC-S). If successful, the mechanism returns the sequence number SQN_UE.

The calls to C_SignInit and C_Sign are the same as during authentication, except the second argument passed to C_Sign is the concatenated vector RAND||AUTS instead of RAND. The sqn value in the parameters structure for this mechanism is not required and will be ignored.

CKM_NC_MILENAGE_AUTS (testing only)

This mechanism is only for testing the resynchronization operation. It computes the MILENAGE f1*/f5* functions as defined in ETSI TS 135 206 s4.1 and returns RAND||AUTS (required as an input to CKM_NC_MILENAGE_RESYNC).

The calls to C_SignInit and C_Sign are the same as during authentication. The RAND value is optional.

CKM_NC_TUAK_TOPC

Derive CKK_NC_TUAKTOPC key from CKK_NC_TUAKTOP and CKK_NC_TUAKSUBSCRIBER keys for use in the 3GPP mechanisms defined in ETSI TS 135 231 s6.1.

A C_DeriveKey function call is made. The function takes the CKK_NC_TUAKSUBSCRIBER key handle as the base key and the following structure as the mechanism parameter:

typedef struct CK_NC_TUAK_DERIVE_PARAMS {
  CK_OBJECT_HANDLE hTOPKey;   /* CKK_NC_TUAK_TOP key handle */
  CK_ULONG ulIterations;      /* number of Keccak iterations (1 or 2) */
} CK_NC_TUAK_DERIVE_PARAMS;

To generate the subscriber and TOP keys, use the corresponding vendor-defined key generation mechanisms (which do not take any mechanism parameters):

  • CKM_NC_TUAKSUBSCRIBER_KEY_GEN

  • CKM_NC_TUAKTOP_KEY_GEN

CKM_NC_TUAK, CKM_NC_TUAK_AUTS, CKM_NC_TUAK_RESYNC

3GPP mechanisms for 5G mobile networks as defined by ETSI TS 135 231. Used with C_SignInit and C_Sign function calls. The parameters for these mechanisms are defined in the following structure:

typedef struct CK_TUAK_SIGN_PARAMS {
  CK_ULONG             ulTuakFlags;
  CK_ULONG             ulEncKiLen;     /* not used - must be 0 */
  CK_BYTE_PTR          pEncKi;         /* not used */
  CK_ULONG             ulEncTOPcLen;   /* not used - must be 0 */
  CK_BYTE_PTR          pEncTOPc;       /* not used */
  CK_ULONG             ulIterations;   /* number of Keccak iterations (1 or 2) */
  CK_OBJECT_HANDLE     hSecondaryKey;  /* existing CKK_NC_TUAK_TOPC key handle */
  CK_ULONG             ulResLen;       /* length of expected response (4, 8, 16 or 32 bytes) */
  CK_ULONG             ulMacALen;      /* length of MAC (8, 16 or 32 bytes) */
  CK_ULONG             ulCkLen;        /* length of crypto key CK (16 or 32 bytes) */
  CK_ULONG             ulIkLen;        /* length of identity key IK (16 or 32 bytes) */
  CK_BYTE              sqn[6];         /* sequence number */
  CK_BYTE              amf[2];         /* authentication management field */
} CK_TUAK_SIGN_PARAMS;

The ulTuakFlags can consist of the following flags:

#define CKF_NC_TUAK_TOPC                 0x00000001  /* secondary key is TOPC (not TOP) */
#define CKF_NC_TUAK_TOP_OBJECT           0x00000004  /* secondary key is supplied by object handle */

Both the CKF_NC_TUAK_TOPC and CKF_NC_TUAK_TOP_OBJECT flags must be present. The nShield PKCS #11 library currently only supports passing the TOPC key handle to the mechanism.

CKM_NC_TUAK

Computes the TUAK f1/f2/f3/f4/f5 functions as defined in ETSI TS 135 231 s6.2/s6.4 and thus generates the Authentication Vector (AV) as defined in the ETSI Authentication and Key Agreement (AKA) protocol. This single output vector is the concatenated values RAND||XRES||CK||IK||XOR(SQN,AK)||AMF||MAC.

The following example shows how to use CKM_NC_TUAK:

/* session represents an existing open session */
CK_SESSION_HANDLE session;

/* subscriber_key and topc_key represent existing keys */
CK_OBJECT_HANDLE subscriber_key, topc_key;

/* sqn, amf and rand represent existing byte arrays holding the sequence number,
 * authentication management field and RAND challenge respectively
 * rand is optional */
CK_BYTE sqn[6], amf[2], rand[16];

CK_TUAK_SIGN_PARAMS tuak_params;
tuak_params.ulTuakFlags = CKF_NC_TUAK_TOP_OBJECT | CKF_NC_TUAK_TOPC;
tuak_params.hSecondaryKey = topc_key;
tuak_params.ulIterations = 1;         // 1 or 2
tuak_params.ulResLen = 32;            // 4, 8, 16 or 32
tuak_params.ulMacALen = 32;           // 8, 16 or 32
tuak_params.ulCkLen = 32;             // 16 or 32
tuak_params.ulIkLen = 32;             // 16 or 32
memcpy(&(tuak_params.sqn), sqn, 6);
memcpy(&(tuak_params.amf), amf, 2);

CK_MECHANISM tuak_mech = {CKM_NC_TUAK, &tuak_params, sizeof(tuak_params)};

/* Typical convention is to call C_Sign with the pData parameter set to
 * NULL to determine the required size of the buffer - see Section 5.2 of
 * the PKCS#11 Base Specification - but for brevity we allocate a 1KB buffer */

CK_RV rv;
CK_BYTE tuak_result[1000] = {0};
CK_ULONG tuak_len = sizeof(tuak_result);
rv = C_SignInit(session, &tuak_mech, subscriber_key);
if (rv != CKR_OK) return rv;
rv = C_Sign(session, rand, 16, tuak_result, &tuak_len);
if (rv != CKR_OK) return rv;

The RAND value passed to C_Sign is optional and can be left as NULL.

CKM_NC_TUAK_RESYNC

Performs part of the resynchronization procedure as described in the AKA protocol. This computes the TUAK f1*/f5* functions as defined in ETSI TS 135 231 s6.3/s6.5 and verifies AUTS (i.e. XOR(SQN_UE,AK)||MAC-S). If successful, the mechanism returns the sequence number SQN_UE.

The calls to C_SignInit and C_Sign are the same as during authentication, except the second argument passed to C_Sign is the concatenated vector RAND||AUTS instead of RAND. The sqn value in the parameters structure for this mechanism is not required and will be ignored.

CKM_NC_TUAK_AUTS (testing only)

This mechanism is only for testing the resynchronization operation. It computes the TUAK f1*/f5* functions as defined in ETSI TS 135 231 s6.3/s6.5 and returns RAND||AUTS (required as an input to CKM_NC_TUAK_RESYNC).

The calls to C_SignInit and C_Sign are the same as during authentication. The RAND value is optional. Only the sqn, amf, ulMacALen and ulIterations parameters are required. The remainder will be ignored.