Cryptographic Token Interface Standard

PKCS#11


Objects

Cryptoki recognizes a number of classes of objects, as defined in the CK_OBJECT_CLASS data type. Objects consist of a set of attributes, each of which has a given value. The following figure illustrates the high-level hierarchy of the Cryptoki objects and the attributes they support:

v200_figure_5.gif
Figure 8-1, Cryptoki Object Hierarchy

Cryptoki provides functions for creating and destroying objects, and for obtaining and modifying the values of attributes. Some of the cryptographic functions (e.g., key generation) also create objects to hold their results.

Objects are always "well-formed" in Cryptoki"that is, an object always contains required attributes, and the attributes are always consistent with one another, from the time the object is created. This is in contrast with some object-based paradigms, where an object has no attributes other than perhaps a class when it is created, and is "uninitialized" for some time. In Cryptoki, objects are always initialized.

To ensure that the required attributes are defined, the functions that create objects take a "template" as an argument, where the template specifies initial attribute values. The template can also provide input to cryptographic functions that create objects (e.g., it can specify a key size). Cryptographic functions that create objects may also contribute some of the initial attribute values (see Section for details). In any case, all the attributes supported by an object class that do not have default values must be specified when an object is created, either in the template, or by the function.

Tables in this section define attributes in terms of the data type of the attribute value and the meaning of the attribute, which may include a default initial value. Some of the data types are defined explicitly by Cryptoki (e.g., CK_OBJECT_CLASS). Attributes may also take the following types:

Byte array an arbitrary string (array) of CK_BYTE s

Big integer a string of CK_BYTEs representing an unsigned integer of arbitrary size, most-significant byte first (e.g., the integer 32768 is represented as the 2-byte string 0x80 0x00)

Local stringa string of CK_CHARs (see Table 4 -3)

A token can hold several identical objects, i.e., it is permissible for two or more objects to have exactly the same values for all their attributes.

With the exception of RSA private key objects (see Section), each type of object possesses a completely well-defined set of attributes. For example, an X.509 certificate (see Section) has precisely the following attributes: CKA_CLASS, CKA_TOKEN, CKA_PRIVATE, CKA_MODIFIABLE, CKA_LABEL, CKA_CERTIFICATE_TYPE, CKA_SUBJECT, CKA_ID, CKA_ISSUER, CKA_SERIAL_NUMBER, CKA_VALUE. Some of these attributes possess default values, and need not be specified when creating an object; some of these default values may even be the empty string (""). Nonetheless, the object possesses these attributes.

Common attributes

The following table defines the attributes common to all objects:

Table 8-1, Common Object Attributes
Attribute Data Type Meaning
CKA_CLASS1 CK_OBJECT_CLASS Object class (type)
CKA_TOKEN CK_BBOOL TRUE if object is a token object; FALSE if object is a session object (default FALSE)
CKA_PRIVATE CK_BBOOL TRUE if object is a private object; FALSE if object is a public object (default FALSE)
CKA_MODIFIABLE CK_BBOOL TRUE if object can be modified (default TRUE)
CKA_LABEL Local string Description of the object (default empty)

1Must be specified when object is created

Only the CKA_LABEL attribute can be modified after the object is created. (The CKA_TOKEN, CKA_PRIVATE, and CKA_MODIFIABLE attributes can be changed in the process of copying an object.)

Cryptoki v2.0 supports the following values for CKA_CLASS (i.e., the following classes (types) of objects): CKO_DATA, CKO_CERTIFICATE, CKO_PUBLIC_KEY, CKO_PRIVATE_KEY, and CKO_SECRET_KEY.

When the CKA_PRIVATE attribute is TRUE, a user may not access the object until the user has been authenticated to the token.

The value of the CKA_MODIFIABLE attribute determines whether or not an object is read-only. It may or may not be the case that an unmodifiable object can be deleted.

The CKA_LABEL attribute is intended to assist users in browsing.

Additional attributes for each object type are described in the following sections. Note that only attributes visible to applications using Cryptoki are listed. Objects may well carry other useful information on a token which is not visible to the application via Cryptoki.

Data objects

Data objects (object class CKO_DATA) hold information defined by an application. Other than providing access to a data objects, Cryptoki does not attach any special meaning to a data object. The following table lists the attributes supported by data objects, in addition to the common attributes listed in Table 8 -1:

Table 8-2, Data Object Attributes
Attribute Data type Meaning
CKA_APPLICATION Local string Description of the application that manages the object (default empty)
CKA_VALUE Byte array Value of the object (default empty)

Both of these attributes may be modified after the object is created.

The CKA_APPLICATION attribute provides a means for applications to indicate ownership of the objects they manage. Cryptoki does not provide a means of ensuring that only a particular application has access to a data object, however.

The following is a sample template containing attributes for creating a data object:

CK_OBJECT_CLASS class = CKO_DATA;
CK_CHAR label[] = "A data object";
CK_CHAR application[] = "An application";
CK_BYTE data[] = "Sample data";
CK_BBOOL true = TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)},
{CKA_APPLICATION, application, sizeof(application)},
{CKA_VALUE, data, sizeof(data)}
};

Certificate objects

Certificate objects (object class CKO_CERTIFICATE) hold public-key certificates. Other than providing access to certificate objects, Cryptoki does not attach any special meaning to certificates. The following table defines the common certificate object attributes, in addition to the common attributes listed in Table 8 -1:

Table 8-3, Common Certificate Object Attributes
Attribute Data type Meaning
CKA_CERTIFICATE_TYPE1 CK_CERTIFICATE_TYPE Type of certificate

1Must be specified when the object is created.

The CKA_CERTIFICATE_TYPE attribute may not be modified after an object is created.

X.509 certificate objects

X.509 certificate objects (certificate type CKC_X_509) hold X.509 certificates. The following table defines the X.509 certificate object attributes, in addition to the common attributes listed in Table 8 -1 and Table 8 -3:

Table 8-4, X.509 Certificate Object Attributes
Attribute Data type Meaning
CKA_SUBJECT1 Byte array DER encoding of the certificate subject name
CKA_ID Byte array Key identifier for public/private key pair (default empty)
CKA_ISSUER Byte array DER encoding of the certificate issuer name (default empty)
CKA_SERIAL_NUMBER Byte array DER encoding of the certificate serial number (default empty)
CKA_VALUE1 Byte array BER encoding of the certificate

1Must be specified when the object is created.

Only the CKA_ID, CKA_ISSUER, and CKA_SERIAL_NUMBER attributes may be modified after the object is created.

The CKA_ID attribute is intended as a means of distinguishing multiple public-key/private-key pairs held by the same subject (whether stored in the same token or not). (Since the keys are distinguished by subject name as well as identifier, it is possible that keys for different subjects may have the same CKA_ID value without introducing any ambiguity.)

It is intended in the interests of interoperability that the subject name and key identifier for a certificate will be the same as those for the corresponding public and private keys (though it is not required that all be stored in the same token). However, Cryptoki does not enforce this association, or even the uniqueness of the key identifier for a given subject; in particular, an application may leave the key identifier empty.

The CKA_ISSUER and CKA_SERIAL_NUMBER attributes are for compatibility with PKCS #7 and Privacy Enhanced Mail (RFC1421). Note that with the version 3 extensions to X.509 certificates, the key identifier may be carried in the certificate. It is intended that the CKA_ID value be identical to the key identifier in such a certificate extension, although this will not be enforced by Cryptoki.

The following is a sample template for creating a certificate object:

CK_OBJECT_CLASS class = CKO_CERTIFICATE;
CK_CERTIFICATE_TYPE certType = CKC_X_509;
CK_CHAR label[] = "A certificate object";
CK_BYTE subject[] = {...};
CK_BYTE id[] = {123};
CK_BYTE certificate[] = {...};
CK_BBOOL true = TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_CERTIFICATE_TYPE, &certType, sizeof(certType)};
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)},
{CKA_SUBJECT, subject, sizeof(subject)},
{CKA_ID, id, sizeof(id)},
{CKA_VALUE, certificate, sizeof(certificate)}
};

Key objects

The following figure illustrates the details of key objects:

v200_figure_6.gif
Figure 8-2, Key Object Detail

Key objects hold encryption or authentication keys, which can be public keys, private keys, or secret keys. The following common footnotes apply to all the tables describing attributes of keys:

Table 8-5, Common footnotes for key attribute tables
Footnote Meaning
1 Must be specified when object is created.
2 Must not be specified when object is created.
3 Must be specified when object is generated.
4 Must not be speficied when object is generated.
5 Must be specified when object is unwrapped.
6 Must not be specified when object is unwrapped.
7 Cannot be revealed if object has its CKA_SENSITIVE attribute set to TRUE or its CKA_EXTRACTABLE attribute set to FALSE.
8 May be modified after object is created.
9 Default is up to the token. The application can specify an explicit value in the template, and Cryptoki will reject it if it cannot be supported by the library or token.

The following table defines the attributes common to public key, private key and secret key classes, in addition to the common attributes listed in Table 8 -1:

Table 8-6, Common Key Attributes
Attribute Data Type Meaning
CKA_KEY_TYPE1,3,5 CK_KEY_TYPE Type of key
CKA_ID8 Byte array Key identifier for key (default empty)
CKA_START_DATE8 CK_DATE Start date for the key (default empty)
CKA_END_DATE8 CK_DATE End date for the key (default empty)
CKA_DERIVE8 CK_BBOOL TRUE if key supports key derivation (default FALSE)
CKA_LOCAL2,4,6 CK_BBOOL TRUE if key was generated locally (i.e., on token)

The CKA_ID field is intended to distinguish among multiple keys. In the case of public and private keys, this is for multiple keys held by the same subject; the key identifier for a public key and its corresponding private key should be the same. The key identifier should also be the same as for the corresponding certificate. Cryptoki does not enforce this association, however. (See Section for further commentary.)

In the case of secret keys, the meaning of the CKA_ID attribute is up to the application.

Note that the CKA_START_DATE and CKA_END_DATE attributes are for reference only; Cryptoki does not attach any special meaning to them. In particular, it does not restrict usage of a key according to the dates; doing this is up to the application.

The CKA_DERIVE attribute has the value TRUE if and only if it is possible to derive other keys from the key.

Public key objects

Public key objects (object class CKO_PUBLIC_KEY) hold public keys. This version of Cryptoki recognizes six types of public keys: RSA, DSA, ECDSA, Diffie-Hellman, KEA, and MAYFLY. The following table defines the attributes common to all public keys, in addition to the common attributes listed in Table 8 -1 and Table 8 -6:

Table 8-7, Common Public Key Attributes
Attribute Data type Meaning
CKA_SUBJECT8 Byte array DER encoding of the key subject name (default empty)
CKA_ENCRYPT8 CK_BBOOL TRUE if key supports encryption9
CKA_VERIFY8 CK_BBOOL TRUE if key supports verification9
CKA_VERIFY_RECOVER8 CK_BBOOL TRUE if key supports verification where the data is recovered from the signature9
CKA_WRAP8 CK_BBOOL TRUE if key supports wrapping9

It is intended in the interests of interoperability that the subject name and key identifier for a public key will be the same as those for the corresponding certificate and private key. However, Cryptoki does not enforce this, and it is not required that the certificate and private key also be stored on the token.

RSA public key objects

RSA public key objects (object class CKO_PUBLIC_KEY, key type CKK_RSA) hold RSA public keys. The following table defines the RSA public key object attributes, in addition to the common attributes listed in Table 8 -1, Table 8 -6, and Table 8 -7:

Table 8-8, RSA Public Key Object Attributes
Attribute Data type Meaning
CKA_MODULUS1,4,6 Big integer Modulus n
CKA_MODULUS_BITS2,3,6 CK_ULONG Length in bits of modulus n
CKA_PUBLIC_EXPONENT1,3,6 Big integer Public exponent e

Depending on the token, there may be limits on the length of key components. See PKCS #1 for more information on RSA keys.

The following is a sample template for creating an RSA public key object:

CK_OBJECT_CLASS class = CKO_PUBLIC_KEY;
CK_KEY_TYPE keyType = CKK_RSA;
CK_CHAR label[] = "An RSA public key object";
CK_BYTE modulus[] = {...};
CK_BYTE exponent[] = {...};
CK_BBOOL true = TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)},
{CKA_WRAP, &true, sizeof(true)},
{CKA_ENCRYPT, &true, sizeof(true)},
{CKA_MODULUS, modulus, sizeof(modulus)},
{CKA_PUBLIC_EXPONENT, exponent, sizeof(exponent)}
};

DSA public key objects

DSA public key objects (object class CKO_PUBLIC_KEY, key type CKK_DSA) hold DSA public keys. The following table defines the DSA public key object attributes, in addition to the common attributes listed in Table 8 -1, Table 8 -6, and Table 8 -7:

Table 8-9, DSA Public Key Object Attributes
Attribute Data type Meaning
CKA_PRIME1,3,6 Big integer Prime p (512 to 1024 bits, in steps of 64 bits)
CKA_SUBPRIME1,3,6 Big integer Subprime q (160 bits)
CKA_BASE1,3,6 Big integer Base g
CKA_VALUE1,4,6 Big integer Public value y

The CKA_PRIME, CKA_SUBPRIME and CKA_BASE attribute values are collectively the "DSA parameters". See FIPS PUB 186 for more information on DSA keys.

The following is a sample template for creating a DSA public key object:

CK_OBJECT_CLASS class = CKO_PUBLIC_KEY;
CK_KEY_TYPE keyType = CKK_DSA;
CK_CHAR label[] = "A DSA public key object";
CK_BYTE prime[] = {...};
CK_BYTE subprime[] = {...};
CK_BYTE base[] = {...};
CK_BYTE value[] = {...};
CK_BBOOL true = TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)},
{CKA_PRIME, prime, sizeof(prime)},
{CKA_SUBPRIME, subprime, sizeof(subprime)},
{CKA_BASE, base, sizeof(base)},
{CKA_VALUE, value, sizeof(value)}
};

ECDSA public key objects

ECDSA public key objects (object class CKO_PUBLIC_KEY, key type CKK_ECDSA) hold ECDSA public keys. The following table defines the ECDSA public key object attributes, in addition to the common attributes listed in Table 8 -1, Table 8 -6, and Table 8 -7:

Table 8-10, ECDSA Public Key Object Attributes
Attribute Data type Meaning
CKA_PRIME1,3,6 Big integer Prime p (512 to 1024 bits, in steps of 64 bits)
CKA_SUBPRIME1,3,6 Big integer Subprime q (160 bits)
CKA_BASE1,3,6 Big integer Base g (512 to 1024 bits, in steps of 64 bits)
CKA_VALUE1,4,6 Big integer Public value W

The CKA_PRIME, CKA_SUBPRIME and CKA_BASE attribute values are collectively the "ECDSA parameters".

The following is a sample template for creating an ECDSA public key object:

CK_OBJECT_CLASS class = CKO_PUBLIC_KEY;
CK_KEY_TYPE keyType = CKK_ECDSA;
CK_CHAR label[] = "An ECDSA public key object";
CK_BYTE prime[] = {...};
CK_BYTE subprime[] = {...};
CK_BYTE base[] = {...};
CK_BYTE value[] = {...};
CK_BBOOL true = TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)},
{CKA_PRIME, prime, sizeof(prime)},
{CKA_SUBPRIME, subprime, sizeof(subprime)},
{CKA_BASE, base, sizeof(base)},
{CKA_VALUE, value, sizeof(value)}
};

Diffie-Hellman public key objects

Diffie-Hellman public key objects (object class CKO_PUBLIC_KEY, key type CKK_DH) hold Diffie-Hellman public keys. The following table defines the RSA public key object attributes, in addition to the common attributes listed in Table 8 -1, Table 8 -6, and Table 8 -7:

Table 8-11, Diffie-Hellman Public Key Object Attributes
Attribute Data type Meaning
CKA_PRIME1,3,6 Big integer Prime p
CKA_BASE1,3,6 Big integer Base g
CKA_VALUE1,4,6 Big integer Public value y

The CKA_PRIME and CKA_BASE attribute values are collectively the "Diffie-Hellman parameters". Depending on the token, there may be limits on the length of the key components. See PKCS #3 for more information on Diffie-Hellman keys.

The following is a sample template for creating a Diffie-Hellman public key object:

CK_OBJECT_CLASS class = CKO_PUBLIC_KEY;
CK_KEY_TYPE keyType = CKK_DH;
CK_CHAR label[] = "A Diffie-Hellman public key object";
CK_BYTE prime[] = {...};
CK_BYTE base[] = {...};
CK_BYTE value[] = {...};
CK_BBOOL true = TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)},
{CKA_PRIME, prime, sizeof(prime)},
{CKA_BASE, base, sizeof(base)},
{CKA_VALUE, value, sizeof(value)}
};

KEA public key objects

KEA public key objects (object class CKO_PUBLIC_KEY, key type CKK_KEA) hold KEA public keys. The following table defines the KEA public key object attributes, in addition to the common attributes listed in Table 8 -1, Table 8 -6, and Table 8 -7:

Table 8-12, KEA Public Key Object Attributes
Attribute Data type Meaning
CKA_PRIME1,3,6 Big integer Prime p (512 to 1024 bits, in steps of 64 bits)
CKA_SUBPRIME1,3,6 Big integer Subprime q (160 bits)
CKA_BASE1,3,6 Big integer Base g (512 to 1024 bits, in steps of 64 bits)
CKA_VALUE1,4,6 Big integer Public value y

The CKA_PRIME, CKA_SUBPRIME and CKA_BASE attribute values are collectively the "KEA parameters".

The following is a sample template for creating a KEA public key object:

CK_OBJECT_CLASS class = CKO_PUBLIC_KEY;
CK_KEY_TYPE keyType = CKK_KEA;
CK_CHAR label[] = "A KEA public key object";
CK_BYTE prime[] = {...};
CK_BYTE subprime[] = {...};
CK_BYTE base[] = {...};
CK_BYTE value[] = {...};
CK_BBOOL true = TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)},
{CKA_PRIME, prime, sizeof(prime)},
{CKA_SUBPRIME, subprime, sizeof(subprime)},
{CKA_BASE, base, sizeof(base)},
{CKA_VALUE, value, sizeof(value)}
};

MAYFLY public key objects

MAYFLY public key objects (object class CKO_PUBLIC_KEY, key type CKK_MAYFLY) hold MAYFLY public keys. The following table defines the MAYFLY public key object attributes, in addition to the common attributes listed in Table 8 -1, Table 8 -6, and Table 8 -7:

Table 8-13, MAYFLY Public Key Object Attributes
Attribute Data type Meaning
CKA_PRIME1,3,6 Big integer Prime p (512 to 1024 bits, in steps of 64 bits)
CKA_SUBPRIME1,3,6 Big integer Subprime q (160 bits)
CKA_BASE1,3,6 Big integer Base g (512 to 1024 bits, in steps of 64 bits)
CKA_VALUE1,4,6 Big integer Public value W

The CKA_PRIME, CKA_SUBPRIME and CKA_BASE attribute values are collectively the "MAYFLY parameters".

The following is a sample template for creating a MAYFLY public key object:

CK_OBJECT_CLASS class = CKO_PUBLIC_KEY;
CK_KEY_TYPE keyType = CKK_MAYFLY;
CK_CHAR label[] = "A MAYFLY public key object";
CK_BYTE prime[] = {...};
CK_BYTE subprime[] = {...};
CK_BYTE base[] = {...};
CK_BYTE value[] = {...};
CK_BBOOL true = TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)},
{CKA_PRIME, prime, sizeof(prime)},
{CKA_SUBPRIME, subprime, sizeof(subprime)},
{CKA_BASE, base, sizeof(base)},
{CKA_VALUE, value, sizeof(value)}
};

Private key objects

Private key objects (object class CKO_PRIVATE_KEY) hold private keys. This version of Cryptoki recognizes six types of private key: RSA, DSA, ECDSA, Diffie-Hellman, KEA, and MAYFLY. The following table defines the attributes common to all private keys, in addition to the common attributes listed in Table 8 -1 and Table 8 -6:

Table 8-14, Common Private Key Attributes
Attribute Data type Meaning
CKA_SUBJECT8 Byte array DER encoding of certificate subject name (default empty)
CKA_SENSITIVE8 CK_BBOOL TRUE if key is sensitive9
CKA_DECRYPT8 CK_BBOOL TRUE if key supports decryption9
CKA_SIGN8 CK_BBOOL TRUE if key supports signatures where the signature is an appendix to the data9
CKA_SIGN_RECOVER8 CK_BBOOL TRUE if key supports signatures where the data can be recovered from the signature9
CKA_UNWRAP8 CK_BBOOL TRUE if key supports unwrapping9
CKA_EXTRACTABLE8 CK_BBOOL TRUE if key is extractable9
CKA_ALWAYS_SENSITIVE2,4,6 CK_BBOOL TRUE if key has always had the CKA_SENSITIVE attribute set to TRUE
CKA_NEVER_EXTRACTABLE2,4,6 CK_BBOOL TRUE if key has never had the CKA_EXTRACTABLE attribute set to TRUE

After an object is created, the CKA_SENSITIVE attribute may only be set to TRUE. Similarly, after an object is created, the CKA_EXTRACTABLE attribute may only be set to FALSE.

If the CKA_SENSITIVE attribute is TRUE, or if the CKA_EXTRACTABLE attribute is false, then certain attributes of the private key cannot be revealed off the token. Which attributes these are is specified for each type of private key in the attribute table in the section describing that type of key.

If the CKA_EXTRACTABLE attribute is false, then the key cannot be wrapped.

It is intended in the interests of interoperability that the subject name and key identifier for a private key will be the same as those for the corresponding certificate and public key. However, this is not enforced by Cryptoki, and it is not required that the certificate and public key also be stored on the token.

RSA private key objects

RSA private key objects (object class CKO_PRIVATE_KEY, key type CKK_RSA) hold RSA private keys. The following table defines the RSA private key object attributes, in addition to the common attributes listed in Table 8 -1, Table 8 -6, and Table 8 -14:

Table 8-15, RSA Private Key Object Attributes
Attribute Data type Meaning
CKA_MODULUS1,4,6 Big integer Modulus n
CKA_PUBLIC_EXPONENT4,6 Big integer Public exponent e
CKA_PRIVATE_EXPONENT1,4,6,7 Big integer Private exponent d
CKA_PRIME_14,6,7 Big integer Prime p
CKA_PRIME_24,6,7 Big integer Prime q
CKA_EXPONENT_14,6,7 Big integer Private exponent d modulo p -1
CKA_EXPONENT_24,6,7 Big integer Private exponent d modulo q -1
CKA_COEFFICIENT4,6,7 Big integer CRT coefficient q -1 mod p

Depending on the token, there may be limits on the length of the key components. See PKCS #1 for more information on RSA keys.

Tokens vary in what they actually store for RSA private keys. Some tokens store all of the above attributes, which can assist in performing rapid RSA computations. Other tokens might store only the CKA_MODULUS and CKA_PRIVATE_EXPONENT values.

Because of this, Cryptoki is flexible in dealing with RSA private key objects. When a token generates an RSA private key, it stores whichever of the fields in Table 8 -15 it keeps track of. Later, if an application asks for the values of the key's various attributes, Cryptoki supplies values only for attributes whose values it can obtain (i.e., if Cryptoki is asked for the value of an attribute it cannot obtain, the request fails). Note that a Cryptoki implementation may or may not be able and/or willing to supply various attributes of RSA private keys which are not actually stored on the token. E.g., if a particular token stores values only for the CKA_PRIVATE_EXPONENT, CKA_PRIME_1, and CKA_PRIME_2 attributes, then Cryptoki is certainly able to report values for all the attributes above (since they can all be computed from these three values). However, a Cryptoki implementation may or may not actually do this extra computation. The only attributes from Table 8 -15 that a Cryptoki implementation is required to be able to return values for are CKA_MODULUS and CKA_PRIVATE_EXPONENT.

If an RSA private key object is created on a token, and more attributes from Table 8 -15 are supplied to the object creation call than are supported by the token, the extra attributes are likely to be thrown away. If an attempt is made to create an RSA private key object on a token with insufficient attributes for that particular token, then the object creation call fails.

Note that when generating an RSA private key, there is no CKA_MODULUS_BITS attribute specified. This is because RSA private keys are only generated as part of an RSA key pair, and the CKA_MODULUS_BITS attribute for the pair is specified in the template for the RSA public key.

The following is a sample template for creating an RSA private key object:

CK_OBJECT_CLASS class = CKO_PRIVATE_KEY;
CK_KEY_TYPE keyType = CKK_RSA;
CK_CHAR label[] = "An RSA private key object";
CK_BYTE subject[] = {...};
CK_BYTE id[] = {123};
CK_BYTE modulus[] = {...};
CK_BYTE publicExponent[] = {...};
CK_BYTE privateExponent[] = {...};
CK_BYTE prime1[] = {...};
CK_BYTE prime2[] = {...};
CK_BYTE exponent1[] = {...};
CK_BYTE exponent2[] = {...};
CK_BYTE coefficient[] = {...};
CK_BBOOL true = TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)},
{CKA_SUBJECT, subject, sizeof(subject)},
{CKA_ID, id, sizeof(id)},
{CKA_SENSITIVE, &true, sizeof(true)},
{CKA_DECRYPT, &true, sizeof(true)},
{CKA_SIGN, &true, sizeof(true)},
{CKA_MODULUS, modulus, sizeof(modulus)},
{CKA_PUBLIC_EXPONENT, publicExponent, sizeof(publicExponent)},
{CKA_PRIVATE_EXPONENT, privateExponent, sizeof(privateExponent)},
{CKA_PRIME_1, prime1, sizeof(prime1)},
{CKA_PRIME_2, prime2, sizeof(prime2)},
{CKA_EXPONENT_1, exponent1, sizeof(exponent1)},
{CKA_EXPONENT_2, exponent2, sizeof(exponent2)},
{CKA_COEFFICIENT, coefficient, sizeof(coefficient)}
};

DSA private key objects

DSA private key objects (object class CKO_PRIVATE_KEY, key type CKK_DSA) hold DSA private keys. The following table defines the DSA private key object attributes, in addition to the common attributes listed in Table 8 -1, Table 8 -6, and Table 8 -14:

Table 8-16, DSA Private Key Object Attributes
Attribute Data type Meaning
CKA_PRIME1,4,6 Big integer Prime p (512 to 1024 bits, in steps of 64 bits)
CKA_SUBPRIME1,4,6 Big integer Subprime q (160 bits)
CKA_BASE1,4,6 Big integer Base g
CKA_VALUE1,4,6,7 Big integer Private value x

The CKA_PRIME, CKA_SUBPRIME and CKA_BASE attribute values are collectively the "DSA parameters". See FIPS PUB 186 for more information on DSA keys.

Note that when generating a DSA private key, the DSA parameters are not specified in the key's template. This is because DSA private keys are only generated as part of a DSA key pair, and the DSA parameters for the pair are specified in the template for the DSA public key.

The following is a sample template for creating a DSA private key object:

CK_OBJECT_CLASS class = CKO_PRIVATE_KEY;
CK_KEY_TYPE keyType = CKK_DSA;
CK_CHAR label[] = "A DSA private key object";
CK_BYTE subject[] = {...};
CK_BYTE id[] = {123};
CK_BYTE prime[] = {...};
CK_BYTE subprime[] = {...};
CK_BYTE base[] = {...};
CK_BYTE value[] = {...};
CK_BBOOL true = TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)},
{CKA_SUBJECT, subject, sizeof(subject)},
{CKA_ID, id, sizeof(id)},
{CKA_SENSITIVE, &true, sizeof(true)},
{CKA_SIGN, &true, sizeof(true)},
{CKA_PRIME, prime, sizeof(prime)},
{CKA_SUBPRIME, subprime, sizeof(subprime)},
{CKA_BASE, base, sizeof(base)},
{CKA_VALUE, value, sizeof(value)}
};

ECDSA private key objects

ECDSA private key objects (object class CKO_PRIVATE_KEY, key type CKK_ECDSA) hold ECDSA private keys. The following table defines the ECDSA private key object attributes, in addition to the common attributes listed in Table 8 -1, Table 8 -6, and Table 8 -14:

Table 8-17, ECDSA Private Key Object Attributes
Attribute Data type Meaning
CKA_PRIME1,4,6 Big integer Prime p (512 to 1024 bits, in steps of 64 bits)
CKA_SUBPRIME1,4,6 Big integer Subprime q (160 bits)
CKA_BASE1,4,6 Big integer Base g (512 to 1024 bits, in steps of 64 bits)
CKA_VALUE1,4,6,7 Big integer Private value w

The CKA_PRIME, CKA_SUBPRIME and CKA_BASE attribute values are collectively the "ECDSA parameters".

Note that when generating an ECDSA private key, the ECDSA parameters are not specified in the key's template. This is because ECDSA private keys are only generated as part of an ECDSA key pair, and the ECDSA parameters for the pair are specified in the template for the ECDSA public key.

The following is a sample template for creating an ECDSA private key object:

CK_OBJECT_CLASS class = CKO_PRIVATE_KEY;
CK_KEY_TYPE keyType = CKK_ECDSA;
CK_CHAR label[] = "An ECDSA private key object";
CK_BYTE subject[] = {...};
CK_BYTE id[] = {123};
CK_BYTE prime[] = {...};
CK_BYTE subprime[] = {...};
CK_BYTE base[] = {...};
CK_BYTE value[] = {...};
CK_BBOOL true = TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)},
{CKA_SUBJECT, subject, sizeof(subject)},
{CKA_ID, id, sizeof(id)},
{CKA_SENSITIVE, &true, sizeof(true)},
{CKA_DERIVE, &true, sizeof(true)},
{CKA_PRIME, prime, sizeof(prime)},
{CKA_SUBPRIME, subprime, sizeof(subprime)},
{CKA_BASE, base, sizeof(base)},
{CKA_VALUE, value, sizeof(value)}
};

Diffie-Hellman private key objects

Diffie-Hellman private key objects (object class CKO_PRIVATE_KEY, key type CKK_DH) hold Diffie-Hellman private keys. The following table defines the Diffie-Hellman private key object attributes, in addition to the common attributes listed in Table 8 -1, Table 8 -6, and Table 8 -14:

Table 8-18, Diffie-Hellman Private Key Object Attributes
Attribute Data type Meaning
CKA_PRIME1,4,6 Big integer Prime p
CKA_BASE1,4,6 Big integer Base g
CKA_VALUE1,4,6,7 Big integer Private value x
CKA_VALUE_BITS2,6 CK_ULONG Length in bits of private value x

The CKA_PRIME and CKA_BASE attribute values are collectively the "Diffie-Hellman parameters". Depending on the token, there may be limits on the length of the key components. See PKCS #3 for more information on Diffie-Hellman keys.

Note that when generating an Diffie-Hellman private key, the Diffie-Hellman parameters are not specified in the key's template. This is because Diffie-Hellman private keys are only generated as part of a Diffie-Hellman key pair, and the Diffie-Hellman parameters for the pair are specified in the template for the Diffie-Hellman public key.

The following is a sample template for creating a Diffie-Hellman private key object:

CK_OBJECT_CLASS class = CKO_PRIVATE_KEY;
CK_KEY_TYPE keyType = CKK_DH;
CK_CHAR label[] = "A Diffie-Hellman private key object";
CK_BYTE subject[] = {...};
CK_BYTE id[] = {123};
CK_BYTE prime[] = {...};
CK_BYTE base[] = {...};
CK_BYTE value[] = {...};
CK_BBOOL true = TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)},
{CKA_SUBJECT, subject, sizeof(subject)},
{CKA_ID, id, sizeof(id)},
{CKA_SENSITIVE, &true, sizeof(true)},
{CKA_DERIVE, &true, sizeof(true)},
{CKA_PRIME, prime, sizeof(prime)},
{CKA_BASE, base, sizeof(base)},
{CKA_VALUE, value, sizeof(value)}
};

KEA private key objects

KEA private key objects (object class CKO_PRIVATE_KEY, key type CKK_KEA) hold KEA private keys. The following table defines the KEA private key object attributes, in addition to the common attributes listed in Table 8 -1, Table 8 -6, and Table 8 -14:

Table 8-19, KEA Private Key Object Attributes
Attribute Data type Meaning
CKA_PRIME1,4,6 Big integer Prime p (512 to 1024 bits, in steps of 64 bits)
CKA_SUBPRIME1,4,6 Big integer Subprime q (160 bits)
CKA_BASE1,4,6 Big integer Base g (512 to 1024 bits, in steps of 64 bits)
CKA_VALUE1,4,6,7 Big integer Private value x

The CKA_PRIME, CKA_SUBPRIME and CKA_BASE attribute values are collectively the "KEA parameters".

Note that when generating a KEA private key, the KEA parameters are not specified in the key's template. This is because KEA private keys are only generated as part of a KEA key pair, and the KEA parameters for the pair are specified in the template for the KEA public key.

The following is a sample template for creating a KEA private key object:

CK_OBJECT_CLASS class = CKO_PRIVATE_KEY;
CK_KEY_TYPE keyType = CKK_KEA;
CK_CHAR label[] = "A KEA private key object";
CK_BYTE subject[] = {...};
CK_BYTE id[] = {123};
CK_BYTE prime[] = {...};
CK_BYTE subprime[] = {...};
CK_BYTE base[] = {...};
CK_BYTE value[] = {...};
CK_BBOOL true = TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)},
{CKA_SUBJECT, subject, sizeof(subject)},
{CKA_ID, id, sizeof(id)},
{CKA_SENSITIVE, &true, sizeof(true)},
{CKA_DERIVE, &true, sizeof(true)},
{CKA_PRIME, prime, sizeof(prime)},
{CKA_SUBPRIME, subprime, sizeof(subprime)},
{CKA_BASE, base, sizeof(base)},
{CKA_VALUE, value, sizeof(value)}
};

MAYFLY private key objects

MAYFLY private key objects (object class CKO_PRIVATE_KEY, key type CKK_MAYFLY) hold MAYFLY private keys. The following table defines the MAYFLY private key object attributes, in addition to the common attributes listed in Table 8 -1, Table 8 -6, and Table 8 -14:

Table 8-20, MAYFLY Private Key Object Attributes
Attribute Data type Meaning
CKA_PRIME1,4,6 Big integer Prime p (512 to 1024 bits, in steps of 64 bits)
CKA_SUBPRIME1,4,6 Big integer Subprime q (160 bits)
CKA_BASE1,4,6 Big integer Base g (512 to 1024 bits, in steps of 64 bits)
CKA_VALUE1,4,6,7 Big integer Private value w

The CKA_PRIME, CKA_SUBPRIME and CKA_BASE attribute values are collectively the "MAYFLY parameters".

Note that when generating a MAYFLY private key, the MAYFLY parameters are not specified in the key's template. This is because MAYFLY private keys are only generated as part of a MAYFLY key pair, and the MAYFLY parameters for the pair are specified in the template for the MAYFLY public key.

The following is a sample template for creating a MAYFLY private key object:

CK_OBJECT_CLASS class = CKO_PRIVATE_KEY;
CK_KEY_TYPE keyType = CKK_MAYFLY;
CK_CHAR label[] = "A MAYFLY private key object";
CK_BYTE subject[] = {...};
CK_BYTE id[] = {123};
CK_BYTE prime[] = {...};
CK_BYTE subprime[] = {...};
CK_BYTE base[] = {...};
CK_BYTE value[] = {...};
CK_BBOOL true = TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)},
{CKA_SUBJECT, subject, sizeof(subject)},
{CKA_ID, id, sizeof(id)},
{CKA_SENSITIVE, &true, sizeof(true)},
{CKA_DERIVE, &true, sizeof(true)},
{CKA_PRIME, prime, sizeof(prime)},
{CKA_SUBPRIME, subprime, sizeof(subprime)},
{CKA_BASE, base, sizeof(base)},
{CKA_VALUE, value, sizeof(value)}
};

Secret key objects

Secret key objects (object class CKO_SECRET_KEY) hold secret keys. This version of Cryptoki recognizes the following types of secret key: generic, RC2, RC4, RC5, DES, DES2, DES3, CAST, CAST3, CAST5, IDEA, SKIPJACK, BATON, JUNIPER, and CDMF. The following table defines the attributes common to all secret keys, in addition to the common attributes listed in Table 8 -1 and Table 8 -6:

Table 8-21, Common Secret Key Attributes
Attribute Data type Meaning
CKA_SENSITIVE8 CK_BBOOL TRUE if object is sensitive (default FALSE)
CKA_ENCRYPT8 CK_BBOOL TRUE if key supports encryption9
CKA_DECRYPT8 CK_BBOOL TRUE if key supports decryption9
CKA_SIGN8 CK_BBOOL TRUE if key supports signatures (i.e., authentication codes) where the signature is an appendix to the data9
CKA_VERIFY8 CK_BBOOL TRUE if key supports verification (i.e., of authentication codes) where the signature is an appendix to the data9
CKA_WRAP8 CK_BBOOL TRUE if key supports wrapping9
CKA_UNWRAP8 CK_BBOOL TRUE if key supports unwrapping9
CKA_EXTRACTABLE8 CK_BBOOL TRUE if key is extractable9
CKA_ALWAYS_SENSITIVE2,4,6 CK_BBOOL TRUE if key has always had the CKA_SENSITIVE attribute set to TRUE
CKA_NEVER_EXTRACTABLE2,4,6 CK_BBOOL TRUE if key has never had the CKA_EXTRACTABLE attribute set to TRUE

After an object is created, the CKA_SENSITIVE attribute may only be set to TRUE. Similarly, after an object is created, the CKA_EXTRACTABLE attribute may only be set to FALSE.

If the CKA_SENSITIVE attribute is TRUE, or if the CKA_EXTRACTABLE attribute is false, then certain attributes of the private key cannot be revealed in plaintext outside the token. These attributes are specified for each type of private key in the attribute table in the section describing that type of key.

If the CKA_EXTRACTABLE attribute is false, then the key cannot be wrapped.

Generic secret key objects

Generic secret key objects (object class CKO_SECRET_KEY, key type CKK_GENERIC_SECRET) hold generic secret keys. These keys do not support encryption, decryption, signatures or verification; however, other keys can be derived from them. The following table defines the generic secret key object attributes, in addition to the common attributes listed in Table 8 -1, Table 8 -6, and Table 8 -21:

Table 8-22, Generic Secret Key Object Attributes
Attribute Data type Meaning
CKA_VALUE1,4,6,7 Byte array Key value (arbitrary length)
CKA_VALUE_LEN2,3,6 CK_ULONG Length in bytes of key value

The following is a sample template for creating a generic secret key object:

CK_OBJECT_CLASS class = CKO_SECRET_KEY;
CK_KEY_TYPE keyType = CKK_GENERIC_SECRET;
CK_CHAR label[] = "A generic secret key object";
CK_BYTE value[] = {...};
CK_BBOOL true = TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)},
{CKA_DERIVE, &true, sizeof(true)},
{CKA_VALUE, value, sizeof(value)}
};

RC2 secret key objects

RC2 secret key objects (object class CKO_SECRET_KEY, key type CKK_RC2) hold RC2 keys. The following table defines the RC2 secret key object attributes, in addition to the common attributes listed in Table 8 -1, Table 8 -6, and Table 8 -21:

Table 8-23, RC2 Secret Key Object Attributes
Attribute Data type Meaning
CKA_VALUE1,4,6,7 Byte array Key value (1 to 128 bytes)
CKA_VALUE_LEN2,3,6 CK_ULONG Length in bytes of key value

The following is a sample template for creating an RC2 secret key object:

CK_OBJECT_CLASS class = CKO_SECRET_KEY;
CK_KEY_TYPE keyType = CKK_RC2;
CK_CHAR label[] = "An RC2 secret key object";
CK_BYTE value[] = {...};
CK_BBOOL true = TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)},
{CKA_ENCRYPT, &true, sizeof(true)},
{CKA_VALUE, value, sizeof(value)}
};

RC4 secret key objects

RC4 secret key objects (object class CKO_SECRET_KEY, key type CKK_RC4) hold RC4 keys. The following table defines the RC4 secret key object attributes, in addition to the common attributes listed in Table 8 -1, Table 8 -6, and Table 8 -21:

Table 8-24, RC4 Secret Key Object
Attribute Data type Meaning
CKA_VALUE1,4,6,7 Byte array Key value (1 to 256 bytes)
CKA_VALUE_LEN2,3,6 CK_ULONG Length in bytes of key value

The following is a sample template for creating an RC4 secret key object:

CK_OBJECT_CLASS class = CKO_SECRET_KEY;
CK_KEY_TYPE keyType = CKK_RC4;
CK_CHAR label[] = "An RC4 secret key object";
CK_BYTE value[] = {...};
CK_BBOOL true = TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)},
{CKA_ENCRYPT, &true, sizeof(true)},
{CKA_VALUE, value, sizeof(value)}
};

RC5 secret key objects

RC5 secret key objects (object class CKO_SECRET_KEY, key type CKK_RC5) hold RC5 keys. The following table defines the RC5 secret key object attributes, in addition to the common attributes listed in Table 8 -1, Table 8 -6, and Table 8 -21:

Table 8-25, RC4 Secret Key Object
Attribute Data type Meaning
CKA_VALUE1,4,6,7 Byte array Key value (0 to 255 bytes)
CKA_VALUE_LEN2,3,6 CK_ULONG Length in bytes of key value

The following is a sample template for creating an RC5 secret key object:

CK_OBJECT_CLASS class = CKO_SECRET_KEY;
CK_KEY_TYPE keyType = CKK_RC5;
CK_CHAR label[] = "An RC5 secret key object";
CK_BYTE value[] = {...};
CK_BBOOL true = TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)},
{CKA_ENCRYPT, &true, sizeof(true)},
{CKA_VALUE, value, sizeof(value)}
};

DES secret key objects

DES secret key objects (object class CKO_SECRET_KEY, key type CKK_DES) hold single-length DES keys. The following table defines the DES secret key object attributes, in addition to the common attributes listed in Table 8 -1, Table 8 -6, and Table 8 -21:

Table 8-26, DES Secret Key Object
Attribute Data type Meaning
CKA_VALUE1,4,6,7 Byte array Key value (always 8 bytes long)

DES keys must always have their parity bits properly set, as described in FIPS PUB 46-2. Attempting to create or unwrap a DES key with incorrect parity will return an error.

The following is a sample template for creating a DES secret key object:

CK_OBJECT_CLASS class = CKO_SECRET_KEY;
CK_KEY_TYPE keyType = CKK_DES;
CK_CHAR label[] = "A DES secret key object";
CK_BYTE value[8] = {...};
CK_BBOOL true = TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)},
{CKA_ENCRYPT, &true, sizeof(true)},
{CKA_VALUE, value, sizeof(value)}
};

DES2 secret key objects

DES2 secret key objects (object class CKO_SECRET_KEY, key type CKK_DES2) hold double-length DES keys. The following table defines the DES2 secret key object attributes, in addition to the common attributes listed in Table 8 -1, Table 8 -6, and Table 8 -21:

Table 8-27, DES2 Secret Key Object Attributes
Attribute Data type Meaning
CKA_VALUE1,4,6,7 Byte array Key value (always 16 bytes long)

DES2 keys must always have their parity bits properly set, as described in FIPS PUB 46-2 (i.e., each of the DES keys comprising a DES2 key must have its parity bits properly set). Attempting to create or unwrap a DES2 key with incorrect parity will return an error.

The following is a sample template for creating a double-length DES secret key object:

CK_OBJECT_CLASS class = CKO_SECRET_KEY;
CK_KEY_TYPE keyType = CKK_DES2;
CK_CHAR label[] = "A DES2 secret key object";
CK_BYTE value[16] = {...};
CK_BBOOL true = TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)},
{CKA_ENCRYPT, &true, sizeof(true)},
{CKA_VALUE, value, sizeof(value)}
};

DES3 secret key objects

DES3 secret key objects (object class CKO_SECRET_KEY, key type CKK_DES3) hold triple-length DES keys. The following table defines the DES3 secret key object attributes, in addition to the common attributes listed in Table 8 -1, Table 8 -6, and Table 8 -21:

Table 8-28, DES3 Secret Key Object Attributes
Attribute Data type Meaning
CKA_VALUE1,4,6,7 Byte array Key value (always 24 bytes long)

DES3 keys must always have their parity bits properly set, as described in FIPS PUB 46-2 (i.e., each of the DES keys comprising a DES3 key must have its parity bits properly set). Attempting to create or unwrap a DES3 key with incorrect parity will return an error.

The following is a sample template for creating a triple-length DES secret key object:

CK_OBJECT_CLASS class = CKO_SECRET_KEY;
CK_KEY_TYPE keyType = CKK_DES3;
CK_CHAR label[] = "A DES3 secret key object";
CK_BYTE value[24] = {...};
CK_BBOOL true = TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)},
{CKA_ENCRYPT, &true, sizeof(true)},
{CKA_VALUE, value, sizeof(value)}
};

CAST secret key objects

CAST secret key objects (object class CKO_SECRET_KEY, key type CKK_CAST) hold CAST keys. The following table defines the CAST secret key object attributes, in addition to the common attributes listed in Table 8 -1, Table 8 -6, and Table 8 -21:

Table 8-29, CAST Secret Key Object Attributes
Attribute Data type Meaning
CKA_VALUE1,4,6,7 Byte array Key value (1 to 8 bytes)
CKA_VALUE_LEN2,3,6 CK_ULONG Length in bytes of key value

The following is a sample template for creating an CAST secret key object:

CK_OBJECT_CLASS class = CKO_SECRET_KEY;
CK_KEY_TYPE keyType = CKK_CAST;
CK_CHAR label[] = "A CAST secret key object";
CK_BYTE value[] = {...};
CK_BBOOL true = TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)},
{CKA_ENCRYPT, &true, sizeof(true)},
{CKA_VALUE, value, sizeof(value)}
};

CAST3 secret key objects

CAST3 secret key objects (object class CKO_SECRET_KEY, key type CKK_CAST3) hold CAST3 keys. The following table defines the CAST3 secret key object attributes, in addition to the common attributes listed in Table 8 -1, Table 8 -6, and Table 8 -21:

Table 8-30, CAST3 Secret Key Object Attributes
Attribute Data type Meaning
CKA_VALUE1,4,6,7 Byte array Key value (1 to 8 bytes)
CKA_VALUE_LEN2,3,6 CK_ULONG Length in bytes of key value

The following is a sample template for creating an CAST3 secret key object:

CK_OBJECT_CLASS class = CKO_SECRET_KEY;
CK_KEY_TYPE keyType = CKK_CAST3;
CK_CHAR label[] = "A CAST3 secret key object";
CK_BYTE value[] = {...};
CK_BBOOL true = TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)},
{CKA_ENCRYPT, &true, sizeof(true)},
{CKA_VALUE, value, sizeof(value)}
};

CAST5 secret key objects

CAST5 secret key objects (object class CKO_SECRET_KEY, key type CKK_CAST5) hold CAST5 keys. The following table defines the CAST5 secret key object attributes, in addition to the common attributes listed in Table 8 -1, Table 8 -6, and Table 8 -21:

Table 8-31, CAST5 Secret Key Object Attributes
Attribute Data type Meaning
CKA_VALUE1,4,6,7 Byte array Key value (1 to 16 bytes)
CKA_VALUE_LEN2,3,6 CK_ULONG Length in bytes of key value

The following is a sample template for creating an CAST5 secret key object:

CK_OBJECT_CLASS class = CKO_SECRET_KEY;
CK_KEY_TYPE keyType = CKK_CAST5;
CK_CHAR label[] = "A CAST5 secret key object";
CK_BYTE value[] = {...};
CK_BBOOL true = TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)},
{CKA_ENCRYPT, &true, sizeof(true)},
{CKA_VALUE, value, sizeof(value)}
};

IDEA secret key objects

IDEA secret key objects (object class CKO_SECRET_KEY, key type CKK_IDEA) hold IDEA keys. The following table defines the IDEA secret key object attributes, in addition to the common attributes listed in Table 8 -1, Table 8 -6, and Table 8 -21:

Table 8-32, IDEA Secret Key Object
Attribute Data type Meaning
CKA_VALUE1,4,6,7 Byte array Key value (always 16 bytes long)

The following is a sample template for creating an IDEA secret key object:

CK_OBJECT_CLASS class = CKO_SECRET_KEY;
CK_KEY_TYPE keyType = CKK_IDEA;
CK_CHAR label[] = "An IDEA secret key object";
CK_BYTE value[16] = {...};
CK_BBOOL true = TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)},
{CKA_ENCRYPT, &true, sizeof(true)},
{CKA_VALUE, value, sizeof(value)}
};

CDMF secret key objects

CDMF secret key objects (object class CKO_SECRET_KEY, key type CKK_CDMF) hold single-length CDMF keys. The following table defines the CDMF secret key object attributes, in addition to the common attributes listed in Table 8 -1, Table 8 -6, and Table 8 -21:

Table 8-33, CDMF Secret Key Object
Attribute Data type Meaning
CKA_VALUE1,4,6,7 Byte array Key value (always 8 bytes long)

CDMF keys must always have their parity bits properly set in exactly the same fashion described for DES keys in FIPS PUB 46-2. Attempting to create or unwrap a CDMF key with incorrect parity will return an error.

The following is a sample template for creating a CDMF secret key object:

CK_OBJECT_CLASS class = CKO_SECRET_KEY;
CK_KEY_TYPE keyType = CKK_CDMF;
CK_CHAR label[] = "A CDMF secret key object";
CK_BYTE value[8] = {...};
CK_BBOOL true = TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)},
{CKA_ENCRYPT, &true, sizeof(true)},
{CKA_VALUE, value, sizeof(value)}
};

SKIPJACK secret key objects

SKIPJACK secret key objects (object class CKO_SECRET_KEY, key type CKK_SKIPJACK) holds a single-length MEK or a TEK. The following table defines the SKIPJACK secret key object attributes, in addition to the common attributes listed in Table 8 -1, Table 8 -6, and Table 8 -21:

Table 8-34, SKIPJACK Secret Key Object
Attribute Data type Meaning
CKA_VALUE1,4,6,7 Byte array Key value (always 10 bytes long)

The following is a sample template for creating a SKIPJACK MEK secret key object:

CK_OBJECT_CLASS class = CKO_SECRET_KEY;
CK_KEY_TYPE keyType = CKK_SKIPJACK;
CK_CHAR label[] = "A SKIPJACK MEK secret key object";
CK_BYTE value[12] = {...};
CK_BBOOL true = TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)},
{CKA_ENCRYPT, &true, sizeof(true)},
{CKA_VALUE, value, sizeof(value)}
};

The following is a sample template for creating a SKIPJACK TEK secret key object:

CK_OBJECT_CLASS class = CKO_SECRET_KEY;
CK_KEY_TYPE keyType = CKK_SKIPJACK;
CK_CHAR label[] = "A SKIPJACK TEK secret key object";
CK_BYTE value[12] = {...};
CK_BBOOL true = TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)},
{CKA_ENCRYPT, &true, sizeof(true)},
{CKA_WRAP, &true, sizeof(true)},
{CKA_VALUE, value, sizeof(value)}
};

BATON secret key objects

BATON secret key objects (object class CKO_SECRET_KEY, key type CKK_BATON) hold single-length BATON keys. The following table defines the BATON secret key object attributes, in addition to the common attributes listed in Table 8 -1, Table 8 -6, and Table 8 -21:

Table 8-35, BATON Secret Key Object
Attribute Data type Meaning
CKA_VALUE1,4,6,7 Byte array Key value (always 20 bytes long)

The following is a sample template for creating a BATON MEK secret key object:

CK_OBJECT_CLASS class = CKO_SECRET_KEY;
CK_KEY_TYPE keyType = CKK_BATON;
CK_CHAR label[] = "A BATON MEK secret key object";
CK_BYTE value[12] = {...};
CK_BBOOL true = TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)},
{CKA_ENCRYPT, &true, sizeof(true)},
{CKA_VALUE, value, sizeof(value)}
};

The following is a sample template for creating a BATON TEK secret key object:

CK_OBJECT_CLASS class = CKO_SECRET_KEY;
CK_KEY_TYPE keyType = CKK_BATON;
CK_CHAR label[] = "A BATON TEK secret key object";
CK_BYTE value[12] = {...};
CK_BBOOL true = TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)},
{CKA_ENCRYPT, &true, sizeof(true)},
{CKA_WRAP, &true, sizeof(true)},
{CKA_VALUE, value, sizeof(value)}
};

JUNIPER secret key objects

JUNIPER secret key objects (object class CKO_SECRET_KEY, key type CKK_JUNIPER) hold single-length JUNIPER keys. The following table defines the JUNIPER secret key object attributes, in addition to the common attributes listed in Table 8 -1, Table 8 -6, Table 8 -21:

Table 8-36, JUNIPER Secret Key Object
Attribute Data type Meaning
CKA_VALUE1,4,6,7 Byte array Key value (always 20 bytes long)

The following is a sample template for creating a JUNIPER MEK secret key object:

CK_OBJECT_CLASS class = CKO_SECRET_KEY;
CK_KEY_TYPE keyType = CKK_JUNIPER;
CK_CHAR label[] = "A JUNIPER MEK secret key object";
CK_BYTE value[12] = {...};
CK_BBOOL true = TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)},
{CKA_ENCRYPT, &true, sizeof(true)},
{CKA_VALUE, value, sizeof(value)}
};

The following is a sample template for creating a JUNIPER TEK secret key object:

CK_OBJECT_CLASS class = CKO_SECRET_KEY;
CK_KEY_TYPE keyType = CKK_JUNIPER;
CK_CHAR label[] = "A JUNIPER TEK secret key object";
CK_BYTE value[12] = {...};
CK_BBOOL true = TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)},
{CKA_ENCRYPT, &true, sizeof(true)},
{CKA_WRAP, &true, sizeof(true)},
{CKA_VALUE, value, sizeof(value)}
};


RSA Security Inc. Public-Key Cryptography Standards - PKCS#11 - v200