This chapter gives an overview about CK_ATTRIBUTES and their usage. PKCS#11 objects consist of those attributes while some of the latter are quite important. For example the "token"-attribute decides whether an object is a token object or just a session object which only lives temporary during the active session. This chapter starts with giving detailed information of those attributes followed by an explaination how to use the attributes on different functions.

Attribute

As we already learned PKCS#11 objects consists of attributes where some of them are very important because they determine how the objects is stored, handled, … . Therefore we distinguish the following attribute classes:

• global mandatory attributes
• object specific attributes
• optional object specific attributes

The first category of attributes are necessary for all objects where the resting two depend on the purpose. Before we start with having a deeper look on attributes we will discuss how one of it is composed.

Structure of an attribue

An attribute consists of the following three parts

• The type of the attribute
  PKCS#11 specifies pre-defined constants identifying the attribute or more precisely the value, i. e. the type gives information about how the content of the value can be interpreted.

• The value of the attribute
  the value contains the intended data

• The length of the attribute
  the amount of bytes necessary to store the value

Construction of an object

Now as we now how attributes are structured we can exemplary construct a PKCS#11 object.
For example a RSA public key is described by the public exponent and its modulus. For constructing such an object in PKCS#11 we would need the gobal mandatory attributes and the key specific attributes like CKA_PUBLIC_EXPONENT and CKA_MODULUS. The public exponent attribute would may look like the following:

     TYPE -> CKA_PUBLIC_EXPONENT
     VALUE -> 010001
     LENGTH -> 3

An optional attribute would be CKA_MODULUS_BITS since it gives extra information about the size of the modulus but isn't needed because this information could be derived from the modulus itsself. PKCS#11 defines all possible constructions of objects which really would go beyond the scope of this document for listing all of them here. For this reason we just concentrate on the base types and will discuss only the ones we really need in order to support our mechanisms. So lets start with the base types before we go on with defining the global mandatory attributes contained in every object.

PKCS#11 base objects

The PKCS#11 base objects follow the hirarchy depicted in Figure 3. There are three base objects we need for our ongoing investigations:

• Data objects
• Key objects
• Certificate objects

Each kind of object has its own set of possible attributes where base class attributes are additionally inherited. For example the Data base class consists of the following attributes:

• CKA_CLASS
• CKA_TOKEN
• CKA_PRIVATE
• CKA_LABEL
• CKA_MODIFIABLE
• CKA_APPLICATION
• CKA_OBJECT_ID
• CKA_VALUE

A data object is able to store values for all of these attributes but it does not neccessariliy have to set data for each of these. The next sub chapter gives us an overview which attributes are mandatory for all objects and guarantees distinguishablity. Afterwards we learn which attributes are mandatory for our three base objects. Having learned all necessary basics we are then able to talk about object templates for different key implementations such as RSA or EC.

Figure 3: class hirarchy

Golbal mandatory attributes

An object, equal being a token-, a session-, or a data object (and so on..), always needs the global mandatory attributes being present. Not containing these attributes will result in errors – so without them no object can be written to or read from the token this also applies for session objects. The mandatory attributes are:

• CKA_CLASS

This attributes describes whether the object is a

• • Data object -> CKO_DATA
  • Certificate object -> CKO_CERTIFICATE
  • Public key object -> CKO_PUBLIC_KEY
  • Private key object -> CKO_PRIVATE_KEY
  • Secret key object -> CKO_SECRET_KEY

There are also objects like CKO_HW_FEATURE, CKO_DOMAIN_PARAMETERS, CKO_MECHANISM, CKO_OTP_KEY and CKO_VENDOR_DEFINED but these are out of scope for this documentation.

• CKA_TOKEN

This attributes decides whether the object will be stored on the token or is a session object.

• CKA_PRIVATE

This attribute decides whether a public session can read this object or the user must be logged in objects which should kept secret (like private- or secret keys) will internally overwritte this flag to private even when someone tries to create them as a public.

• CKA_MODIFIABLE

This attribute decides whether the object can be changed after it was created.

Object specific attributes

We previously learned that the CKA_CLASS attribute is responsible for determining the objects kind. Having this information leads us to being more specific in enclosing the objects implementation type. Lets have a look back to Figure 3. Each of the data-, key- and certificate object contains one more attribute giving better information about what the object really is all about:

• Key contains CKA_KEY_TYPE
• Certificate contains CKA_CERTIFICATE_TYPE
• Data contains CKA_OBJECT_ID

These three attributes have one thing in common. They all give information about the implementation type of the object and which attributes it may include. Currently we support the following types:

• CKK_RSA and CKK_EC for CKA_KEY_TYPE

In conjunction with the CKA_CLASS attribute this leads to the following implementation types:

• • RSA public key (CKA_CLASS -> CKO_PUBLIC_KEY)
  • RSA private key (CKA_CLASS -> CKO_PRIVATE_KEY)
  • EC public key (CKA_CLASS -> CKO_PUBLIC_KEY)
  • EC private key (CKA_CLASS -> CKO_PRIVATE_KEY)
• CKC_X_509 for CKA_CERTIFICATE_TYPE
• and any user specific OID for CKA_OBJECT_ID

Each of the implementation types is also defined in cryptoki. In 3.2 we list all additional attributes the ones which are inherited are no more listed supported by that implementation type and give information about the ones which are mandatory (object specific attributes) and those which are optional. Since cryptoki defines all possible implementation types we only handle the ones which are affected by our implementation.

Object templates

Regarding the implementation type each object has additionally attributes. Those attributes are defined here where the fat ones are mandatory while the others are optional. We first start with the base types before we handle the specific implementation types.

Data base type

• CKA_APPLICATION
• CKA_OBJECT_ID
• CKA_VALUE

Key base type

• CKA_KEY_TYPE
• CKA_ID
• CKA_START_DATE (not yet supported for token objects)
• CKA_END_DATE (not yet supported for token objects)
• CKA_DERIVE
• CKA_LOCAL
• CKA_KEY_GEN_MECHANISM (not yet supported for token objects)
• CKA_ALLOWED_MECHANISMS (not yet supported for token objects)

Public key base type

• CKA_SUBJECT (not yet supported for token objects)
• CKA_ENCRYPT
• CKA_VERIFY
• CKA_VERIFY_RECOVER (not yet supported for token objects)
• CKA_WRAP
• CKA_TRUSTED (not yet supported for token objects)
• CKA_WRAP_TEMPLATE (not yet supported for token objects)

Private key base type

• CKA_SUBJECT (not yet supported for token objects)
• CKA_SENSITIVE
• CKA_DECRYPT
• CKA_SIGN
• CKA_SIGN_RECOVER (not yet supported for token objects)
• CKA_UNWRAP
• CKA_EXTRACTABLE (not yet supported for token objects)
• CKA_ALWAYS_SENSITIVE (not yet supported for token objects)
• CKA_NEVER_EXTRACTABLE (not yet supported for token objects)
• CKA_WRAP_WITH_TRUSTED (not yet supported for token objects)
• CKA_UNWRAP_TEMPLATE (not yet supported for token objects)
• CKA_ALWAYS_AUTHENTICATE (not yet supported for token objects)

Secret key base type (not yet supported for token objects)

• CKA_SENSITIVE
• CKA_ENCRYPT
• CKA_DECRYPT
• CKA_SIGN
• CKA_VERIFY
• CKA_WRAP
• CKA_UNWRAP
• CKA_EXTRACTABLE
• CKA_ALWAYS_SENSITIVE
• CKA_NEVER_EXTRACTABLE
• CKA_CHECK_VALUE
• CKA_WRAP_WITH_TRUSTED
• CKA_TRUSTED
• CKA_UNWRAP_TEMPLATE

Certificate base type

• CKA_CERTIFICATE_TYPE
• CKA_TRUSTED (not yet supported for token objects)
• CKA_CERTIFICATE_CATEGORY (not yet supported for token objects)
• CKA_CHECK_VALUE (not yet supported for token objects)
• CKA_START_DATE (not yet supported for token objects)
• CKA_END_DATE (not yet supported for token objects)

RSA

Public key

• CKA_MODULUS
• CKA_MODULUS_BITS
• CKA_PUBLIC_EXPONENT
• CKA_VALUE (automatically calculated as ASN1 structure from modulus and exponent)

Private key

• CKA_MODULUS (automatically calculated from prime 1 and 2)
• CKA_MODULUS_BITS (only mandatory for key generation)
• CKA_PUBLIC_EXPONENT
• CKA_PRIVATE_EXPONENT (automatically calculated from public exponent)
• CKA_PRIME_1
• CKA_PRIME_2
• CKA_EXPONENT_1 (automatically calculated from prime 1)
• CKA_EXPONENT_2 (automatically calculated from prime 2)
• CKA_COEFFICIENT (automatically calculated from prime 1 and 2)

EC

Public key

• CKA_EC_PARAMS
• CKA_EC_POINT (as BER-encoded uncompressed key)
• CKA_VALUE (automatically calculated as ASN1 structure from ec-params and ec-point)

Private key

• CKA_VALUE
• CKA_EC_PARAMS
• CKA_EC_POINT (automatically calculated as BER-encoded uncompressed key)

X509 Certificate

• CKA_SUBJECT (not yet supported for token objects)
• CKA_ID
• CKA_ISSUER (not yet supported for token objects)
• CKA_SERIAL_NUMBER (not yet supported for token objects)
• CKA_VALUE (ASN1 encoded certificate)
• CKA_URL (not yet supported for token objects)
• CKA_HASH_OF_SUBJECT_PUBLIC_KEY (not yet supported for token objects)
• CKA_HASH_OF_ISSUER_PUBLIC_KEY (not yet supported for token objects)
• CKA_JAVA_MIDP_SECURITY_DOMAIN (not yet supported for token objects)

Function specific templates

In this section we handle object templates used for different use cases - these are:

• Create / import an object
• Generate a keypair
• Change attributes

We will learn how the attributes shall be used in order to support our cryptoki implementation since in most of the writing-cases (create, change, generate) there are always some token (for us applet-) dependant attributes which are mandatory even when the specification says they are not or attributes which can't be modified or are unsupported.

Create / import an object

RSA

Table 3 describes the mandatory attributes for importing a RSA private key (token object) and a RSA public key (session object).
Since the applet generates the public key itself (for token objects) this object should not be created. Just import the private key and use the object-search (use the private keys CKA_ID) afterwards to find the corresponding public key. An example is given in 5.

Since we only support public key operations in software a RSA private key can not be created as session object. Private key operations shall always be done in hardware – therefore import the private key as token object. RSA public keys can be created as session objects in order to encrypt according to the relevant access flags data for a receiver or to verify¹⁸ a signature. An example is given in 5.

{*}Table 3: RSA key import*h3.EC
Table 5 describes the mandatory attributes for importing a EC private key (token object) and a EC public key (session object).
Table 4 lists the OIDs of the supported elliptic curves – use the desired OID as CK_EC_PARAMS.
Since the applet generates the public key itself (for token objects) this object should not be created. Just import the private key and use the object-search (use the private keys CKA_ID) afterwards to find the corresponding public key. An example is given in 5.

Use one of the following OID values as CK_BYTE[] as value for CKA_EC_PARAMS attribute.

Table 4: supported EC OIDs






Since we only support public key operations in software an EC private key can not be created as session object. Private key operations shall always be done in hardware – therefore import the private key as token object. EC public keys can be created as session objects in order to verify¹⁸ a signature. An example is given in 5.

{*}Table 5: EC key import*h2.Generate a keypair
Table 6 shows the attributes necessary to generate a keypair. We only support this feature for token objects.

Table 6: generate a keypair

Change attributes