KISAAlgorithm mechanisms

If you are using version 1.20 or greater and you have enabled the KISAAlgorithms feature, you can use the following mechanisms through the standard PKCS #11 API calls.

KCDSA keys

The CKM_KCDSA mechanism is a plain general signing mechanism that allows you to use a CKK_KCDSA key with any length of plain text or pre-hashed message. It can be used with the standard single and multipart C_Sign and C_Verify update functions.

The CKM_KCDSA mechanism takes a CK_KCDSA_PARAMS structure that states which hashing mechanism to use and whether or not the hashing has already been performed:

typedef struct CK_KCDSA_PARAMS {
        CK_MECHANISM_PTR digestMechanism;
        CK_BBOOL dataIsHashed;
}

The following digest mechanisms are available for use with the digestMechanism:

  • CKM_SHA_1

  • CKM_HAS160

  • CKM_RIPEMD160

The dataIsHashed flag can be set to one of the following values:

  • 1 when the message has been pre-hashed (pre-digested)

  • 0 when the message is in plain text.

The CK_KCDSA_PARAMS structure is then passed in to the mechanism structure.

Pre-hashing

If you want to provide a pre-hashed message to the C_Sign() or C_Verify() functions using the CKM_KCDSA mechanism, the hash must be the value of h(z||m) where:

  • h is the hash function defined by the mechanism

  • z is the bottom 512 bits of the public key, with the most significant byte first

  • m is the message that is to be signed or verified.

The hash consists of the bottom 512 bits of the public key (most significant byte first), with the message added after this.

If the hash is not formatted as described when signing, then incorrect signatures are generated. If the hash is not formatted as described when verifying, then invalid signatures can be accepted and valid signatures can be rejected.

CKM_KCDSA_SHA1, CKM_KCDSA_HAS160, CKM_KCDSA_RIPEMD160

These older mechanisms sign and verify using a CKK_KCDSA key. They now work with the C_Sign and C_Update functions, though they do not take the CK_KCDSA_PARAMS structure or pre-hashed messages. These mechanisms can be used for single or multipart signing and are not restricted as to message size.

CKM_KCDSA_KEY_PAIR_GEN

This mechanism generates a CKK_KCDSA key pair similar to that of DSA. You can supply in the template a discrete log group that consists of the CKA_PRIME, CKA_SUBPRIME, and CKA_BASE attributes. In addition, you must supply CKA_PRIME_BITS, with a value between 1024 and 2048, and CKA_SUBPRIME_BITS, which must have a value of 160. If you supply CKA_PRIME_BITS and CKA_SUBPRIME_BITS without a discrete log group, the module generates the group. CKR_TEMPLATE_INCOMPLETE is returned if CKA_PRIME_BITS and CKA_SUBPRIME_BITS are not supplied.

CKA_PRIME_BITS must have the same length as the prime and CKA_SUBPRIME-BITS must have the same length as the subprime if the discrete log group is also supplied. If either are different, PKCS #11 returns CKR_TEMPLATE_INCONSISTENT.

You can use the C_GenerateKeyPair function to generate a key pair. If you supply one or more parts of the discrete log group in the template, the PKCS #11 library assumes that you want to supply a specific discrete log group. CKR_TEMPLATE_INCOMPLETE is returned if not all parts are supplied. If you want the module to calculate a discrete log group for you, ensure that there are no discrete log group attributes present in the template.

A CKK_KCDSA private key has two value attributes, CKA_PUBLIC_VALUE and CKA_PRIVATE_VALUE. This is in contrast to DSA keys, where the private key has only the attribute CKA_VALUE, the private value. The public key in each case contains only the public value.

The standard key-pair attributes common to all key pairs apply. Their values are the same as those for DSA pairs unless specified differently in this section.

CKM_KCDSA_PARAMETER_GEN

For information about DOMAIN Objects, read the PKCS #11 specification v2.11.

Use this mechanism to create a CKO_DOMAIN_PARAMETERS object. This is referred to as a KCDSAComm key in the nCore interface.

Use C_GenerateKey to generate a new discrete log group and initialization values. The initialization values consist of a counter (CKA_COUNTER) and a hash (CKA_SEED) that is the same length as CKA_PRIME_BITS, which must have a value of 160. The CKA_SEED must be the same size as CKA_SUBPRIME_BITS. If this not the case, the PKCS #11 library returns CKR_DOMAIN_PARAMS_INVALID.

Optionally, you can supply the initialization values. If you supply the initialization values with CKA_PRIME_BITS and CKA_SUBPRIME_BITS, you can reproduce a discrete log group generated elsewhere. This allows you to verify that the discrete log group used in key pairs is correct. If the initialization values are not present in the template, a new discrete log group and corresponding initialization values are generated. These initialization values can be used to reproduce the discrete log group that has just been generated. The newly generated discrete log group can then be used in a PKCS #11 template to generate a CKK_KCDSA key using C_Generate_Key_Pair. DOMAIN keys can also be imported using the C_CreateObject call.

CKM_HAS160

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.

SEED secret keys

CKM_SEED_KEY_GEN

This mechanism generates a 128-bit SEED key. The standard secret key attributes are required, except that no length is required since this a fixed length key type similar to DES3. Normal return values apply when generating a CKK_SEED type key.

CKM_SEED_ECB, CKM_SEED_CBC, CKM_SEED_CBC_PAD

These mechanisms are the standard mechanisms to be used when encrypting and decrypting or wrapping with a CKK_SEED key. A CKK_SEED key can be used to wrap or unwrap both secret keys and private keys. A CKK_KCDSA key cannot be wrapped by any key type.

The CKM_SEED_ECB mechanism wraps only secret keys of exact multiples of the CKK_SEED block size (16) in ECB mode. The CKM_SEED_CBC_PAD key wraps the same keys in CBC mode.

The CKM_SEED_CBC_PAD key wraps keys of variable block size. It is the only mechanism available to wrap private keys.

A CKK_SEED key can be used to encrypt and decrypt with both single and multipart methods using the standard PKCS #11 API. The plain text size for multipart cryptographic function must be a multiple of the block size.

CKM_SEED_MAC, CKM_SEED_MAC_GENERAL

These mechanisms perform both signing and verification. They can be used with both single and multipart signing or verification using the standard PKCS #11 API. Message size does not matter for either single or multipart signing and verification.