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.

Not all attributes can be changed. Currently we only support changing the attributes mentionend in 3.3.3.

The values set to the mandatory attributes influence the associated object for its complete lifetime.


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.

Each object inherits the base classe's attributes thus it also includes that attributes. Inherited attributes are no more listed and can be extracted from Figure 3.


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.


RSA private key (token object)
During the import a label can be also given. If not CKA_LABEL receives the same value as CKA_ID.
The values for CKA_MODULUS, CKA_PRIVATE_EXPONENT, CKA_EXPONENT_1, CKA_EXPONENT_2 and CKA_COEFFICIENT can be also given. If not when one of the previous attributes is missing all these attributes are calculated they are calculated in software from CKA_PRIME_1, CKA_PRIME_2 and CKA_PUBLIC_EXPONENT.

Do not use CKA_MODULUS_BITS as attribute when creating / importing a RSA keypair. This attribute is reserved and is used for detecting keypair generation! The attribute will be automatically set during import.

We do not support the creation / import of a private key session object since we only allow public key operations in software.


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 verify18 a signature. An example is given in 5.


RSA public key (session object)
During the import a label can be also given. If not CKA_LABEL receives the same value as CKA_ID.
During the import CKA_MODULUS_BITS can be also given. If not it is calculated from CKA_MODULUS.

Key Type

CKA_CLASS

CKA_TOKEN

CKA_PRIVATE

CKA_MODIFIABLE

CKA_KEY_TYPE

CKA_ID

CKA_PRIME_1

CKA_PRIME_2

CKA_PUBLIC_EXPONENT

Private key (token object)

CKO_PRIVATE_KEY

CK_TRUE

CK_TRUE

CK_TRUE or CK_FALSE

CKK_RSA

All UTF8 symbols

CK_BYTE[]

CK_BYTE[]

CK_BYTE[]
(recommended is 0x010001)

Key Type

CKA_CLASS

CKA_TOKEN

CKA_PRIVATE

CKA_MODIFIABLE

CKA_KEY_TYPE

CKA_ID

CKA_MODULUS

CKA_PUBLIC_EXPONENT

-

Public key (session object)

CKO_PUBLIC_KEY

CK_FALSE

CK_FALSE

CK_TRUE or CK_FALSE

CKK_RSA

All UTF8 symbols

CK_BYTE[]

CK_BYTE[]

-

Table 3: RSA key import


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.


During the import a label can be also given. If not CKA_LABEL receives the same value as CKA_ID.
The value CKA_EC_POINT In uncompressed format => starting with 0x04 indicating this is the uncompressed format followed by concatenating the x and then the y coordinate of the point can be also given. If not it is calculated in software from CKA_VALUE.

We do not support the import of a private key session object since we only allow public key operations in software.


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

Defined elliptic curve

OID

brainpoolP160r1

0x06, 0x09, 0x2B, 0x24, 0x03, 0x03, 0x02, 0x08, 0x01, 0x01, 0x01

brainpoolP192r1

0x06, 0x09, 0x2B, 0x24, 0x03, 0x03, 0x02, 0x08, 0x01, 0x01, 0x03

brainpoolP224r1

0x06, 0x09, 0x2B, 0x24, 0x03, 0x03, 0x02, 0x08, 0x01, 0x01, 0x05

brainpoolP256r1

0x06, 0x09, 0x2B, 0x24, 0x03, 0x03, 0x02, 0x08, 0x01, 0x01, 0x07

brainpoolP320r1

0x06, 0x09, 0x2B, 0x24, 0x03, 0x03, 0x02, 0x08, 0x01, 0x01, 0x09

ansi-x962 prime192v1

0x06, 0x08, 0x2A, 0x86, 0x48, 0xCE, 0x3D, 0x03, 0x01, 0x01

ansip224r1

0x06, 0x05, 0x2B, 0x81, 0x04, 0x00, 0x21

ansi-x962 prime256v1

0x06, 0x08, 0x2A, 0x86, 0x48, 0xCE, 0x3D, 0x03, 0x01, 0x07

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 verify18 a signature. An example is given in 5.

EC public key (session object)
During the import a label can be also given. If not CKA_LABEL receives the same value as CKA_ID.

Key Type

CKA_CLASS

CKA_TOKEN

CKA_PRIVATE

CKA_MODIFIABLE

CKA_KEY_TYPE

CKA_ID

CKA_EC_PARAMS

CKA_VALUE

Private key

CKO_PRIVATE_KEY

CK_TRUE

CK_TRUE

CK_TRUE or CK_FALSE

CKK_EC

All UTF8 symbols

CK_BYTE[]

CK_BYTE[]

Key Type

CKA_CLASS

CKA_TOKEN

CKA_PRIVATE

CKA_MODIFIABLE

CKA_KEY_TYPE

CKA_ID

CKA_EC_PARAMS

CK_EC_POINT

Public key

CKO_PUBLIC_KEY

CK_FALSE

CK_ FALSE

CK_TRUE or CK_FALSE

CKK_EC

All UTF8 symbols

CK_BYTE[]

CK_BYTE[]

Table 5: EC key import


Generate a keypair

Table 6 shows the attributes necessary to generate a keypair. We only support this feature for token objects.


When calling the function C_GenerateKeyPair(…) the same template (the same pointer can be used) for pPublicKeyTemplate and pPublicKeyTemplate shall be used.

We do not support the generation of keypairs for session objects.

Keypair type

CKA_CLASS

CKA_TOKEN

CKA_PRIVATE

CKA_KEY_TYPE

CKA_MODULUS_BITS

RSA KeyPair
(CKM_RSA_PKCS_KEY_PAIR_GEN)

CKO_PRIVATE_KEY

CK_TRUE

CK_TRUE

CKK_RSA

512 – 2048

Keypair type

CKA_CLASS

CKA_TOKEN

CKA_PRIVATE

CKA_KEY_TYPE

CKA_EC_PARAMS

EC KeyPair
(CKM_ECDSA_KEY_PAIR_GEN)

CKO_PRIVATE_KEY

CK_TRUE

CK_TRUE

CKK_EC

use one OID from Table 4

Table 6: generate a keypair

Change attributes

Currently we do only support to change CKA_ID.

  • No labels