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.

v100_figure_5.gif
Figure 8-1, Cryptoki Object Hierarchy

The following figure illustrates the details of the key objects.

v100_figure_6.gif
Figure 8-2, Key Object Detail

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 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 integer of arbitrary size, most significant byte first, without a sign bit (e.g., the integer 32768 is represented as the byte string 0x80 0x00)

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

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 (vs. session object) (default FALSE)    


CKA_PRIVATE CK_BBOOL TRUE if object is a private object (vs. public object) (default FALSE)    


CKA_LABEL Local string Description of the object (default empty)  

 



1Must be specified when object is created


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


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


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 are listed. Objects may well carry other information, useful to a token, which is not visible to the application.


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 distinguish among 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 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, 1},
{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 a 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.


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). But 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 proposed 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.


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, 1},
{CKA_LABEL, label, sizeof(label)},
{CKA_SUBJECT, subject, sizeof(subject)},
{CKA_ID, id, sizeof(id)},
{CKA_VALUE, certificate, sizeof(certificate)},
};




Key objects


Key objects hold encryption keys, which can be public keys, private keys, or secret keys. 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-5, Common Key Attributes   
Attribute Data Type Meaning   


CKA_KEY_TYPE1 CK_KEY_TYPE Type of key   


CKA_ID Byte array Key identifier for key (default empty)   


CKA_START_DATE CK_DATE Start date for the key (default empty)   


CKA_END_DATE CK_DATE End date for the key (default empty)   


CKA_DERIVE CK_BBOOL TRUE if key supports key derivation (default FALSE)  

 



1Must be specified when the object is created.


All of these attributes except CKA_KEY_TYPE may be modified after the object is created.


Note that the start and end dates 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; this is up to the application.


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 8.3 for further commentary.)


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


Public key objects


Public key objects (object class CKO_PUBLIC_KEY) hold public keys. This version of Cryptoki recognizes three types of public keys: RSA, DSA, and Diffie-Hellman. 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 -5.


 







 Table 8-6, Common Public Key Attributes   
Attribute Data type Meaning   


CKA_SUBJECT Byte array DER encoding of the key subject name   


CKA_ENCRYPT CK_BBOOL TRUE if key supports encryption1   


CKA_VERIFY CK_BBOOL TRUE if key supports verification1   


CKA_VERIFY_RECOVER CK_BBOOL TRUE if key supports verification where the data is recovered from the signature1   


CKA_WRAP CK_BBOOL TRUE if key supports wrapping1  

 



1 Default is up to the token, based on what mechanisms it supports; the application can specify an explicit value in the template, and Cryptoki may reject it if no compatible mechanism is supported.


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


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, 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 -5 and  Table 8 -6.


 







 Table 8-7, RSA Public Key Object Attributes   
Attribute Data type Meaning   


CKA_MODULUS1 Big integer Modulus n    


CKA_MODULUS_BITS2 CK_USHORT Length in bits of modulus n    


CKA_PUBLIC_EXPONENT1 Big integer Public exponent e   

 



1Must be specified when the object is created. 2Specify this attribute only in a template for generating a key of this type.


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


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, 1},
{CKA_LABEL, label, sizeof(label)},
{CKA_WRAP, &true, 1},
{CKA_ENCRYPT, &true, 1},
{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 -5 and  Table 8 -6.


 







 Table 8-8, DSA Public Key Object Attributes   
Attribute Data type Meaning   


CKA_PRIME1 Big integer Prime p (512 to 1024 bits, in steps of 64 bits)   


CKA_SUBPRIME1 Big integer Subprime q (160 bits)   


CKA_BASE1 Big integer Base g    


CKA_VALUE1 Big integer Public value y   

 



1Must be specified when the object is created.


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


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 an 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_BBOOL true = TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, 1},
{CKA_LABEL, label, sizeof(label)},
{CKA_PRIME, prime, sizeof(prime)},
{CKA_SUBPRIME, subprime, sizeof(subprime)},
{CKA_BASE, base, sizeof(base)},
};




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 -5 and Table 8 -6.


 







 Table 8-9, Diffie-Hellman Public Key Object Attributes   
Attribute Data type Meaning   


CKA_PRIME1 Big integer Prime p    


CKA_BASE1 Big integer Base g    


CKA_VALUE1 Big integer Public value y   

 



1Must be specified when object is created.


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


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 subprime[] = {...};
CK_BYTE base[] = {...};
CK_BBOOL true = TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, 1},
{CKA_LABEL, label, sizeof(label)},
{CKA_PRIME, prime, sizeof(prime)},
{CKA_SUBPRIME, subprime, sizeof(subprime)},
{CKA_BASE, base, sizeof(base)},
};




Private key objects


Private key objects (object class CKO_PUBLIC_KEY) hold private keys. This version of Cryptoki recognizes three types of private key: RSA, DSA, and Diffie-Hellman. 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 -5.


 







 Table 8-10, Common Private Key Attributes   
Attribute Data type Meaning   


CKA_SUBJECT Byte array DER encoding of certificate subject name (default empty)   


CKA_SENSITIVE CK_BBOOL TRUE if object is sensitive1   


CKA_DECRYPT CK_BBOOL TRUE if key supports decryption1   


CKA_SIGN CK_BBOOL TRUE if key supports signatures where the signature is an appendix to the data1   


CKA_SIGN_RECOVER CK_BBOOL TRUE if key supports signatures where the data can be recovered from the signature1   


CKA_UNWRAP CK_BBOOL TRUE if key supports unwrapping1  

 



1 Default is up to the token, based on what mechanisms it supports; the application can specify an explicit value in the template, and Cryptoki may reject it if no compatible mechanism is supported.


All of these attributes may be modified after the object is created. However, the CKA_SENSITIVE attribute may only be set to TRUE.


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, it is not required that the certificate and public key also be stored on the token.)


If the CKA_SENSITIVE attribute is TRUE, then certain attributes of the private key cannot be revealed outside the token. Also, the private key cannot be wrapped if the CKA_SENSITIVE attribute is TRUE, since it could potentially be recovered outside the token if the unwrapping key is known outside. The attribute table for the each type of private key specifies which attributes are not revealed.


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 -5 and  Table 8 -10.


 







 Table 8-11, RSA Private Key Object Attributes   
Attribute Data type Meaning   


CKA_MODULUS1 Big integer Modulus n    


CKA_PUBLIC_EXPONENT1 Big integer Public exponent e    


CKA_PRIVATE_EXPONENT1,2 Big integer Private exponent d    


CKA_PRIME_11,2 Big integer Prime p    


CKA_PRIME_21,2 Big integer Prime q    


CKA_EXPONENT_11,2 Big integer Private exponent d modulo p -1   


CKA_EXPONENT_21,2 Big integer Private exponent d modulo q -1   


CKA_COEFFICIENT1,2 Big integer CRT coefficient q -1 mod p   

 



1Must be specified when object is created. 2Cannot be revealed when CKA_SENSITIVE attribute is TRUE.


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


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


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, 1},
{CKA_LABEL, label, sizeof(label)},
{CKA_SUBJECT, subject, sizeof(subject)},
{CKA_ID, id, sizeof(id)},
{CKA_SENSITIVE, &true, 1},
{CKA_DECRYPT, &true, 1},
{CKA_SIGN, &true, 1},
{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 -5 and  Table 8 -10.


 







 Table 8-12, DSA Private Key Object Attributes   
Attribute Data type Meaning   


CKA_PRIME1 Big integer Prime p (512 to 1024 bits, in steps of 64 bits)   


CKA_SUBPRIME1 Big integer Subprime q (160 bits)   


CKA_BASE1 Big integer Base g    


CKA_VALUE1,2 Big integer Private value x   

 



1Must be specified when object is created. 2Cannot be revealed when CKA_SENSITIVE attribute is TRUE.


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


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 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, 1},
{CKA_LABEL, label, sizeof(label)},
{CKA_SUBJECT, subject, sizeof(subject)},
{CKA_ID, id, sizeof(id)},
{CKA_SENSITIVE, &true, 1},
{CKA_SIGN, &true, 1},
{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 -5 and Table 8 -10.


 







 Table 8-13, Diffie-Hellman Private Key Object Attributes   
Attribute Data type Meaning   


CKA_PRIME1 Big integer Prime p    


CKA_BASE1 Big integer Base g    


CKA_VALUE1,2 Big integer Private value x    


CKA_VALUE_BITS3 CK_USHORT Length in bits of private value x   

 



1Must be specified when object is created. 2Cannot be revealed when CKA_SENSITIVE attribute is TRUE. 3Specify this attribute only in a template for generating a key of this type.


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


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 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, 1},
{CKA_LABEL, label, sizeof(label)},
{CKA_SUBJECT, subject, sizeof(subject)},
{CKA_ID, id, sizeof(id)},
{CKA_SENSITIVE, &true, 1},
{CKA_DERIVE, &true, 1},
{CKA_PRIME, prime, sizeof(prime)},
{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 six types of secret key: generic, RC2, RC4, DES, DES2, and DES3. 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 -5.


 







 Table 8-14, Common Secret Key Attributes   
Attribute Data type Meaning   


CKA_SENSITIVE CK_BBOOL TRUE if object is sensitive (default FALSE)   


CKA_ENCRYPT CK_BBOOL TRUE if key supports encryption1   


CKA_DECRYPT CK_BBOOL TRUE if key supports decryption1   


CKA_SIGN CK_BBOOL TRUE if key supports signatures (i.e., authentication codes) where the signature is an appendix to the data1   


CKA_VERIFY CK_BBOOL TRUE if key supports verification (i.e., of authentication codes) where the signature is an appendix to the data1   


CKA_WRAP CK_BBOOL TRUE if key supports wrapping1   


CKA_UNWRAP CK_BBOOL TRUE if key supports unwrapping1  

 



1 Default is up to the token, based on what mechanisms it supports; the application can specify an explicit value in the template, and Cryptoki may reject it if no compatible mechanism is supported.


All of these attributes may be modified after the object is created. However, the CKA_SENSITIVE attribute may only be set to TRUE.


If the CKA_SENSITIVE attribute is TRUE, then certain attributes of the secret key cannot be revealed outside the token. Also, the secret key cannot be wrapped if the CKA_SENSITIVE attribute is TRUE, since it could potentially be recovered outside the token if the unwrapping key is known outside. The attribute table for the each type of secret key specifies which attributes are not revealed.


Generic secret key objects


Generic secret key objects (object class CKO_SECRET_KEY,  key type CKK_GENERIC_SECRET) hold generic secret keys. This 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 -5 and  Table 8 -14.


 







 Table 8-15, Generic Secret Key Object Attributes   
Attribute Data type Meaning   


CKA_VALUE1,2 Byte array Key value (arbitrary length)   


CKA_VALUE_LEN3 CK_USHORT Length in bytes of key value  

 



1Must be specified when object is created. 2Cannot be revealed when CKA_SENSITIVE attribute is TRUE. 3Specify this attribute only in a template for unwrapping or deriving a key of this type.


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


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, 1},
{CKA_LABEL, label, sizeof(label)},
{CKA_DERIVE, &true, 1},
{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 -5 and  Table 8 -14.


 







 Table 8-16, RC2 Secret Key Object Attributes   
Attribute Data type Meaning   


CKA_VALUE1,2 Byte array Key value (1 to 128 bytes)   


CKA_VALUE_LEN3 CK_USHORT Length in bytes of key value  

 



1Must be specified when object is created. 2Cannot be revealed when CKA_SENSITIVE attribute is TRUE. 3Specify this attribute only in a template for generating, unwrapping or deriving a key of this type.


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


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, 1},
{CKA_LABEL, label, sizeof(label)},
{CKA_ENCRYPT, &true, 1},
{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 -5 and  Table 8 -14.


 







 Table 8-17, RC4 Secret Key Object   
Attribute Data type Meaning   


CKA_VALUE1,2 Byte array Key value (1 to 256 bytes)   


CKA_VALUE_LEN3 CK_USHORT Length in bytes of key value  

 



1Must be specified when object is created. 2Cannot be revealed when CKA_SENSITIVE attribute is TRUE. 3Specify this attribute only in a template for generating, unwrapping or deriving a key of this type.


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


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, 1},
{CKA_LABEL, label, sizeof(label)},
{CKA_ENCRYPT, &true, 1},
{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 -5 and  Table 8 -14.


 







 Table 8-18, DES Secret Key Object   
Attribute Data type Meaning   


CKA_VALUE1,2 Byte array Key value (always 8 bytes long)  

 



1Must be specified when object is created. 2Cannot be revealed when CKA_SENSITIVE attribute is TRUE.


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


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, 1},
{CKA_LABEL, label, sizeof(label)},
{CKA_ENCRYPT, &true, 1},
{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 -5 and  Table 8 -14.


 







 Table 8-19, DES2 Secret Key Object Attributes   
Attribute Data type Meaning   


CKA_VALUE1,2 Byte array Key value (always 16 bytes long)  

 



1Must be specified when object is created. 2Cannot be revealed when CKA_SENSITIVE attribute is TRUE.


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


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, 1},
{CKA_LABEL, label, sizeof(label)},
{CKA_ENCRYPT, &true, 1},
{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 -5 and  Table 8 -14.


 







 Table 8-20, DES3 Secret Key Object Attributes   
Attribute Data type Meaning   


CKA_VALUE1,2 Byte array Key value (always 24 bytes long)  

 



1Must be specified when object is created. 2Cannot be revealed when CKA_SENSITIVE attribute is TRUE.


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


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, 1},
{CKA_LABEL, label, sizeof(label)},
{CKA_ENCRYPT, &true, 1},
{CKA_VALUE, value, sizeof(value)}
};




 
 



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