Cryptographic Token Interface Standard

PKCS#11

Mechanisms

This section describes the mechanisms that this version of Cryptoki supports for cryptographic operations. The following table summarizes the mechanisms and their uses.

Table 10-1, Mechanisms vs. Functions
Functions

Mechanism Encrypt & Decrypt Sign & Verify SR& VR ¹ Digest Generate ² Wrap & Unwrap Derive

CKM_RSA_PKCS_KEY_PAIR_GEN X

CKM_RSA_PKCS X³ X³ X³ X

CKM_RSA_9796 X³ X³

CMK_RSA_X_509 X³ X³ X³ X

CKM_DSA_KEY_PAIR_GEN X

CKM_DSA X³

CKM_DH_PKCS_KEY_PAIR_GEN X

CKM_DH_PKCS_DERIVE X

CKM_RC2_KEY_GEN X

CKM_RC2_ECB X X

CKM_RC2_CBC X

CKM_RC2_MAC X

CKM_RC4_KEY_GEN X

CKM_RC4 X

CKM_DES_KEY_GEN X

CKM_DES_ECB X X

CKM_DES_CBC X

CKM_DES_MAC X

CKM_DES2_KEY_GEN X

CKM_DES3_KEY_GEN X

CKM_DES3_ECB X X

CKM_DES3_CBC X

CKM_DES3_MAC X

CKM_MD2 X

CKM_MD5 X

CKM_SHA_1 X

¹ SR = SignRecover, VR = VerifyRecover. ² Generate includes GenerateKey and GenerateKeyPair. ³ Single-part operations only.

PKCS #1 RSA key pair generation

The PKCS #1 RSA key pair generation mechanism, denoted CKM_RSA_PKCS_KEY_PAIR_GEN, is a key generation mechanism based on the RSA public-key cryptosystem as defined in PKCS #1.

It does not have a parameter.

The mechanism generates RSA public/private key pairs with a particular modulus length in bits and public exponent, as specified in the CKA_MODULUS_BITS and CKA_EXPONENT attributes of the template for the public key.

The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_MODULUS attributes to the new public key and the CKA_CLASS, CKA_KEY_TYPE, CKA_MODULUS, CKA_PUBLIC_EXPONENT, CKA_PRIVATE_EXPONENT, CKA_PRIME_1, CKA_PRIME_2, CKA_EXPONENT_1, CKA_EXPONENT_2, and CKA_COEFFICIENT attributes to the new private key. Other attributes supported by the RSA public and private key types (specifically the flags indicating which functions the keys support) may also be specified in the templates for the keys or else are assigned default initial values.

Keys generated with this mechanism are compatible with the PKCS #1 RSA, ISO/IEC 9796 RSA, and X.509 (raw) RSA mechanisms.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RSA modulus sizes, in bits.

PKCS #1 RSA

The PKCS #1 RSA mechanism, denoted CKM_RSA_PKCS, is a multi-purpose mechanism based on the RSA public-key cryptosystem and the block formats defined in PKCS #1. It supports single-part encryption and decryption, single-part signatures and verification with and without message recovery, key wrapping, and key unwrapping. This mechanism corresponds only to the part of PKCS #1 that involves RSA; it does not compute a message digest or a DigestInfo encoding as specified for the md2withRSAEncryption and md5withRSAEncryption algorithms in PKCS #1.

It does not have a parameter.

This mechanism wraps and unwraps RC2, RC4, DES, double-length DES and triple-length DES keys. For wrapping, the "input" to the encryption operation is the value of the CKA_VALUE attribute of the key that is wrapped; similarly for unwrapping. The mechanism does not wrap the key type or any other information about the key, except the key length; the application must convey these separately. In particular, the mechanism contributes only the CKA_VALUE attribute to the recovered key during unwrapping; other attributes, including the CKA_CLASS attribute, must be specified in the template since the mechanism does preserve the key length.

Constraints on key types and the length of the data are summarized in the following table. For encryption, decryption, signatures and signature verification, the input and output data may begin at the same location in memory. In the table, k is the length in bytes of the RSA modulus.

Table 10-2, PKCS #1 RSA Key And Data Length Constraints
Function Key type Input length Output length Comments

C_Encrypt¹ RSA public key <= k -11 k block type 02

C_Decrypt¹ RSA private key k <= k -11 block type 01

C_Sign¹ RSA private key <= k -11 k block type 01

C_SignRecover RSA private key <= k -11 k block type 01

C_Verify¹ RSA public key <= k -11,k ⁽²⁾ N/A block type 02

C_VerifyRecover RSA public key k <= k -11 block type 02

C_WrapKey RSA public key <= k -11 k block type 01

C_UnwrapKey RSA private key k <= k -11 block type 01

¹ Single-part operations only. ² Data length, signature length.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RSA modulus sizes, in bits.

ISO/IEC 9796 RSA

The ISO/IEC 9796 RSA mechanism, denoted CKM_RSA_9796, is a mechanism for single-part signatures and verification with and without message recovery based on the RSA public-key cryptosystem and the block formats defined in ISO/IEC 9796 and its annex A. This mechanism is compatible with the draft ANSI X9.31 (assuming the length in bits of the X9.31 hash value is a multiple of 8).

This mechanism processes only byte strings, whereas ISO/IEC 9796 operates on bit strings. Accordingly, the following transformations are performed:

data is converted between byte and bit string formats by interpreting the most significant bit of the leading byte of the byte string as the leftmost bit of the bit string, and the least significant bit of the trailing byte of the byte string as the rightmost bit of the bit string (this assumes the length in bits of the data is a multiple of 8)
a signature is converted from a bit string to a byte string by padding the bit string on the left with 0 to 7 zero bits so that the resulting length in bits is a multiple of 8, and converting the resulting bit string as above; is it converted from a byte string to a bit string by converting the byte string as above, and removing bits from the left so that the resulting length in bits is the same as that of the RSA modulus It does not have a parameter.

Constraints on key types and the length of input and output data are summarized in the following table. The input and output data may begin at the same location in memory. In the table, k is the length in bytes of the RSA modulus.

Table 10-3, ISO/IEC 9796 RSA Key And Data Length Constraints
Function Key type Input length Output length

C_Sign¹ RSA private key <= LOWER(k /2) k

C_SignRecover¹ RSA private key <= LOWER(k /2) k

C_Verify¹ RSA public key <= LOWER(k /2), k ⁽²⁾ N/A

C_VerifyRecover¹ RSA public key k <= LOWER(k /2)

¹ Single-part operations only. ² Data length, signature length.

X.509 (raw) RSA

The X.509 (raw) RSA mechanism, denoted CKM_RSA_X_509, is a multi-purpose mechanism based on the RSA public-key cryptosystem. It supports single-part encryption and decryption, single-part signatures and verification with and without message recovery, key wrapping, and key unwrapping based on the so-called "raw" RSA, as assumed in X.509.

"Raw" RSA as defined here encrypts a byte string by converting it to an integer, most significant byte first, applying "raw" RSA exponentiation, and converting the result to a byte string, most significant byte first. The input string, considered as an integer, must be less than the modulus; the output string is also less than the modulus.

It does not have a parameter.

Constraints on key types and the length of input and output data are summarized in the following table. For encryption, decryption, signatures and signature verification, the input and output data may begin at the same location in memory. In the table, k is the length in bytes of the RSA modulus.

Table 10-4, X.509 (Raw) RSA Key And Data Length Constraints
Function Key type Input length Output length

C_Encrypt¹ RSA public key <= k k

C_Decrypt¹ RSA private key k <= k

C_Sign¹ RSA private key <= k k

C_SignRecover¹ RSA private key <= k k

C_Verify¹ RSA public key <= k,k ⁽²⁾ N/A

C_VerifyRecover¹ RSA public key k <= k

C_WrapKey RSA public key <= k k

C_UnwrapKey RSA private key k <= k

¹ Single-part operations only. ² Data length, signature length.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RSA modulus sizes, in bits.

This mechanism is intended for compatibility with applications that do not follow the PKCS #1 or ISO/IEC 9796 block formats.

DSA key pair generation

The DSA key pair generation mechanism, denoted CKM_DSA_KEY_PAIR_GEN, is a key pair generation mechanism based on the Digital Signature Algorithm defined in FIPS PUB 186.

It does not have a parameter.

The mechanism generates DSA public/private key pairs with a particular prime, subprime and base, as specified in the CKA_PRIME, CKA_SUBPRIME, and CKA_BASE attributes of the template for the public key. (Note that this version of Cryptoki does not include a mechanism for generating these DSA parameters.)

The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE and CKA_VALUE attributes to the new public key and the CKA_CLASS, CKA_KEY_TYPE, CKA_PRIME, CKA_SUBPRIME, CKA_BASE, and CKA_VALUE attributes to the new private key. Other attributes supported by the DSA public and private key types (specifically the flags indicating which functions the keys support) may also be specified in the templates for the keys or else are assigned default initial values.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of DSA prime sizes, in bits.

DSA

The DSA mechanism, denoted CKM_DSA, is a mechanism for single-part signatures and verification based on the Digital Signature Algorithm defined in FIPS PUB 186. (This mechanism corresponds only to the part of DSA that processes the 20-byte hash value; it does not compute the hash value.)

For the purposes of this mechanism, a DSA signature is a 40-byte string, corresponding to the concatenation of the DSA values r and s, each represented most significant byte first.

It does not have a parameter.

Constraints on key types and the length of data are summarized in the following table. The input and output data may begin at the same location in memory.

Table 10-5, DSA Key And Data Length Constraints
Function Key type Input length Output length

C_Sign¹ DSA private key 20 40

C_Verify¹ DSA public key 20,40² N/A

¹ Single-part operations only. ² Data length, signature length.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of DSA prime sizes, in bits.

PKCS #3 Diffie-Hellman key pair generation

The PKCS #3 Diffie-Hellman key pair generation mechanism, denoted CKM_DH_PKCS_KEY_PAIR_GEN, is a key pair generation mechanism based on Diffie-Hellman key agreement, as defined in PKCS #3. (This is analogous to what PKCS #3 calls "phase I.")

It does not have a parameter.

The mechanism generates Diffie-Hellman public/private key pairs with a particular prime and base, as specified in the CKA_PRIME and CKA_BASE attributes of the template for the public key. If the CKA_VALUE_BITS attribute of the private key is specified, the mechanism limits the length in bits of the private value, as described in PKCS #3. (Note that this version of Cryptoki does not include a mechanism for generating a prime and base.)

The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE and CKA_VALUE attributes to the new public key and the CKA_CLASS, CKA_KEY_TYPE, CKA_PRIME, CKA_BASE, and CKA_VALUE attributes to the new private key; other attributes required by the Diffie-Hellman public and private key types must be specified in the templates.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of Diffie-Hellman prime sizes, in bits.

PKCS #3 Diffie-Hellman key derivation

The PKCS #3 Diffie-Hellman key derivation mechanism, denoted CKM_DH_PKCS_DERIVE, is a mechanism for key derivation based on Diffie-Hellman key agreement, as defined in PKCS #3. (This is analogous to what PKCS #3 calls "phase II.")

It has a parameter, which is the public value of the other party in the key agreement protocol, represented most significant byte first.

The mechanism derives RC2, RC4, DES, double-length DES, triple-length DES and generic secret keys from the public value of the other party and a Diffie-Hellman private key. It computes a Diffie-Hellman secret value from the public value and private key according to PKCS #3, and truncates the result according to the CKA_CLASS and CKA_KEY_TYPE attributes of the template and, if it has one and the key type supports it, the CKA_VALUE_LEN attribute of the template. (The truncation removes bytes from the leading end of the secret value.) The mechanism contributes the result as the CKA_VALUE attribute of the new key; other attributes required by the key type must be specified in the template.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of Diffie-Hellman prime sizes, in bits.

RC2 key generation

The RC2 key generation mechanism, denoted CKM_RC2_KEY_GEN, is a key generation mechanism for RSA Data Security's proprietary block cipher RC2.

It does not have a parameter.

The mechanism generates RC2 keys with a particular length in bytes, as specified in the CKA_VALUE_LEN attribute of the template for the key.

The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE and CKA_VALUE attributes to the new key. Other attributes supported by the RC2 key type (specifically, the flags indicating which functions the key supports) may be specified in the template for the key, or else are assigned default initial values.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RC2 key sizes, in bits.

RC2-ECB

RC2-ECB, denoted CKM_RC2_ECB, is a mechanism for single- and multiple-part encryption and decryption, key wrapping, and key unwrapping based on RSA Data Security's proprietary block cipher RC2 and electronic codebook mode as defined in FIPS PUB 81.

It has a parameter, a two-byte string that specifies the effective number of bits in the RC2 search space, most significant byte first; the value must be between 1 and 1024.

This mechanism wraps and unwraps RC2, RC4, DES, double-length DES and triple-length DES keys. For wrapping, the mechanism encrypts the value of the CKA_VALUE attribute of the key that is wrapped, padded on the trailing end with up to seven null bytes so that the resulting length is a multiple of eight. The output data is the same length as the padded input data. It does not wrap the key type, key length, or any other information about the key; the application must convey these separately.

For unwrapping, the mechanism decrypts the wrapped key, and truncates the result according to the CKA_CLASS and CKA_KEY_TYPE attributes of the template and, if it has one, and the key type supports it, the CKA_VALUE_LEN attribute of the template. (Truncation is mainly an issue for RC2 and RC4 keys.) The mechanism contributes the result as the CKA_VALUE attribute of the new key; other attributes required by the key type must be specified in the template.

Constraints on key types and the length of data are summarized in the following table. (These constraints apply both to data supplied as a single part, and to each part of multiple-part data.) For encryption and decryption, the input and output data (parts) may begin at the same location in memory.

Table 10-6, RC2-ECB Key And Data Length Constraints
Function Key type Input length Output length Comments

C_Encrypt RC2 multiple of 8 same as input length no final part

C_Decrypt RC2 multiple of 8 same as input length no final part

C_WrapKey RC2 any input length rounded up to multiple of 8

C_UnwrapKey RC2 any input length rounded up to multiple of 8

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RC2 effective number of bits.

RC2-CBC

RC2-CBC, denoted CKM_RC2_CBC, is a mechanism for single- and multiple-part encryption and decryption, based on RSA Data Security's proprietary block cipher RC2 and cipher block chaining mode as defined in FIPS PUB 81.

It has a parameter, a CK_RC2_CBC_PARAMS structure, where the first field indicates the effective number of bits in the RC2 search space, and the next field is the initialization vector for cipher block chaining mode. The effective number of bits must be between 1 and 1024.

Constraints on key types and the length of data are summarized in the following table. The input and output data (parts) may begin at the same location in memory.

Table 10-7, RC2-CBC Key And Data Length Constraints
Function Key type Input length Output length Comments

C_Encrypt RC2 multiple of 8 same as input length no final part

C_Decrypt RC2 multiple of 8 same as input length no final part

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RC2 effective number of bits.

RC2-MAC

RC2-MAC, denoted CKM_RC2_MAC, is a mechanism for single- and multiple-part signatures (data authentication) and verification, based on RSA Data Security's proprietary block cipher RC2 and data authentication as defined in FIPS PUB 113.

It has a parameter, a two-byte string that specifies the effective number of bits in the RC2 search space, most significant byte first; the value must be between 1 and 1024.

Constraints on key types and the length of data are summarized in the following table. (These constraints apply both to data supplied as a single part, and to each part of multiple-part data.) For single-part signing, the data and the signature may begin at the same location in memory.

Table 10-8, RC2-MAC Key And Data Length Constraints
Function Key type Data length Signature length

C_Sign RC2 any 4

C_Verify RC2 any 4

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RC2 effective number of bits.

RC4 key generation

The RC4 key generation mechanism, denoted CKM_RC4_KEY_GEN, is a key generation mechanism for RSA Data Security's proprietary stream cipher RC4.

It does not have a parameter.

The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE and CKA_VALUE attributes to the new key. Other attributes supported by the RC4 key type (specifically, the flags indicating which functions the key supports) may be specified in the template for the key, or else are assigned default initial values.

The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE and CKA_VALUE attributes to the new key; other attributes required by the RC4 key type must be specified in the template.

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RC4 key sizes, in bits.

RC4

RC4, denoted CKM_RC4, is a mechanism for single- and multiple-part encryption and decryption based on RSA Data Security's proprietary stream cipher RC4.

It does not have a parameter.

Constraints on key types and the length of input and output data are summarized in the following table. (These constraints apply both to data supplied as a single part, and to each part of multiple-part data.) The input and output data (parts) may begin at the same location in memory.

Table 10-9, RC4 Key And Data Length Constraints
Function Key type Input length Output length Comments

C_Encrypt RC4 any same as input length no final part

C_Decrypt RC4 any same as input length no final part

For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RC4 key sizes, in bits.

DES key generation

The DES key generation mechanism, denoted CKM_DES_KEY_GEN, is a key generation mechanism for DES as defined in FIPS PUB 46-2.

It does not have a parameter.

The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE and CKA_VALUE attributes to the new key. Other attributes supported by the DES key type (specifically, the flags indicating which functions the key supports) may be specified in the template for the key, or else are assigned default initial values.