Additional Attribute Types

This section describes additional vendor-defined attribute types.

CKA_KEY_SIZE

The key size for key type CKK_EC can be any arbitrary bit length. That is, not within the byte boundary (for example: the key size for a P-521 curve).

The CKA_KEY_SIZE attribute has the following additional properties:

>Size is in bits

>Read-only attribute

>Assigned at object creation time

>Applicable to both private and public keys

NOTE   This attribute is applicable only to CKK_EC.

CKA_TIME_STAMP

Every object created is assigned a value for the CKA_TIME_STAMP attribute. This value is always read-only and may not be included in a template for a new object.  However, when an object is duplicated using the C_CopyObject function or the object is a key derived using the C_DeriveKey, the new object will inherit the same creation time as the original object.

The value of this attribute is a text string encoding of the time. The encoding format is "YYYYMMDDHHMMSS00".

CKA_TRUSTED

This attribute may be included in a template for the creation of a Certificate object.  It indicates whether or not the certificate is trusted by the application. Once set, the value of this attribute may not be modified.

The following values are defined for this attribute:

CKA_TRUSTED	Description
TRUE (1)	The certificate is trusted.
FALSE (0)	The certificate is not trusted and must be verified.

The value of CKA_TRUSTED may be set to TRUE only when the Security Officer is logged in.  That is, the state of the session must be CKS_RW_SO_FUNCTIONS. Once a Certificate object has the CKA_TRUSTED attribute equal to TRUE, the Certificate is considered a trusted root certificate. The certificate validation code will stop once it reaches a trusted root certificate.

The certificate validation algorithm will locate the certificate’s issuer by searching for a Certificate object with the CKA_SUBJECT attribute equal to the issuer’s distinguished name. If located, it will then verify the signature on the certificate.  If the signature is invalid it will return false, otherwise it will check the CKA_TRUSTED attribute on the issuer’s certificate.  If not equal to TRUE it will search for the issuer of that certificate.  The algorithm will continue until a trusted certificate is found, the signature verification fails or the certificate chain is broken. The chain is broken when a certificate for the issuer cannot be found.

Once a certificate is marked as trusted, the object’s CKA_VALUE attribute may no longer be modified. 

NOTE   The other attributes of the certificate will remain modifiable unless the CKA_MODIFIABLE attribute is set to FALSE.

CKA_USAGE_COUNT

The value of this attribute maintains a count of the number of times a key object is used for a cryptographic operation.  It is possible to set the value of this attribute for a key. Afterwards it is automatically incremented each time the key is used in a Cryptoki initialization routine (that is, C_SignInit).

Also see description for CKA_USAGE_LIMIT.

When generating Certificate objects with the CKM_ENCODE_X_509 mechanism, the CKA_SERIAL_NUMBER attribute for the new certificate object is taken from the certificate signing key’s CKA_USAGE_COUNT attribute. The usage count from the private key is used only if the serial number is not already included in the template for the new certificate.

CKA_USAGE_LIMIT

This attribute represents the highest possible CKA_USAGE_COUNT value allowed on this object - the maximum number of times the object can be used.

This attribute may be specified when the object is created, or added to an object when CKA_MODIFIABLE is true. Once the attribute is added, it cannot be changed by the C_SetAttributeValue function.

Only the CKM_SET_ATTRIBUTES ticket mechanism can change this attribute. The Ticket can modify the attribute even if MODIFABLE=False.

CKA_START_DATE, CKA_END_DATE

These attributes control the period in which the object can be used.

These attributes may be specified when the object is created or added to an object when CKA_MODIFIABLE is true. Once the attribute is added it cannot be changed by the C_SetAttributeValue function.

Only the CKM_SET_ATTRIBUTES ticket mechanism can change these attributes. The Ticket can modify the attributes even if MODIFABLE=False.

Attribute validation is performed if these attributes are supplied during a C_CreateObject or C_UnWrapkey or C_DeriveKey operation. One or both of these attributes may be missing, or present but with an empty value. In this case the attribute is interpreted as "No restriction applies". For example if START_DATE is specified, but END_DATE is not, then the object will be usable from the start date onwards.

If the attribute is specified, it must have a valid data structure (year is between 1900 and 9999, month from 01 to 12 and day from 01 to 31).

CKA_ADMIN_CERT

The CKA_ADMIN_CERT is a new Vendor-defined Attribute.

This attribute is used to hold the certificate of an entity that can perform certain management operations on the object.

The value of the attribute is the DER encoding of an X509 v3 Public Key Certificate.

Rules for validation of the Certificate are:

>If it is self signed, it is implicitly trusted

>If it is signed by another entity, that entity's PKC must be present on the Token and be part of a chain terminating in a Cert marked CKA_TRUSTED=True

>It may be specified in the template when the Object is created, generated or imported.

>It may be added to an object with the C_SetAttributeValue command only if the CKA_MODIFIABLE is True and the attribute does not already exist i.e. once an object is created and made non-modifiable then the CKA_ADMIN_CERT cannot be added later.

The CKA_ADMIN_CERT is used with the CKM_SET_ATTRIBUTES Ticket Mechanism.

So if an object is not Modifiable and has no CKA_ADMIN_CERT then the CKM_SET_ATTRIBUTES Ticket Mechanism can never be applied to that object. Its attributes are forever locked.

CKA_ISSUER_STR, CKA_SUBJECT_STR, CKA_SERIAL_NUMBER_INT

These attributes mirror the standard attributes (without the _STR or _INT suffix) but present that attribute as a printable value rather than as a DER encoding.

For the distinguished name attributes the string is encoded in the form: C=Country code, O=Organization, CN=Common Name, OU=Organizational Unit, L=Locality name, ST=State name.

These attributes may be supplied by an application in place of the DER-encoded form and the other form of the attribute shall be derived from the one supplied in the template.

NOTE   CKA_SERIAL_NUMBER_INT is a CK_ULONG value and is an intrinsic integer type.

CKA_PKI_ATTRIBUTE_BER_ENCODED

This attribute may be used to supply X.509 certificate extensions or PKCS#10 attribute values when creating these objects using the CKM_ENCODE_X509 or CKM_ENCODE_PKCS10 mechanisms, respectively. Please refer to the sections CKM_DECODE_X_509 and CKM_ENCODE_PKCS_10 for full descriptions of these mechanisms.

The value of the CKA_PKI_ATTRIBUTE_BER_ENCODED is the BER-encoded attribute.

CKA_EXPORT, CKA_EXPORTABLE

These attributes are similar to the standard CKA_WRAP and CKA_EXTRACTABLE attributes, as they determine if a given key can wrap other keys and be extracted from the token in an encrypted form.  The important difference between these attributes and their standard counterparts is that there are special controls on who can set the CKA_EXPORT flag. This flag may be set to TRUE by the token’s Security Officer, or by the User if certain conditions are met. Thus the normal user can specify that a key may be exported in an encrypted form (by specifying that the CKA_EXPORTABLE attribute is TRUE) but only by keys as determined by the SO (for example, a key that has the CKA_EXPORT attribute set to TRUE).

The user may also specify the CKA_EXPORT attribute for keys that are generated internally and cannot be extracted other than by another key marked with CKA_EXPORT. This class of key may be used for transport keys where a master key encryption key (KEK) exists.  In this case, the Security Officer would create the KEK, and the user could then create transport keys that could be exported only under the master KEK.

All other key usage attributes that might allow such a key, or any key exported by it, to be known outside the adapter must be set to FALSE. Specifically the template must specify FALSE for CKA_EXTRACTABLE, CKA_DECRYPT, CKA_SIGN and CKA_MODIFIABLE, and TRUE for CKA_SENSITIVE. The template may also not specify TRUE for the CKA_DERIVE attribute.

CKA_DELETABLE

This attribute may be set on any token object (that is, where the CKA_TOKEN attribute is TRUE) to specify that the object is permanent and may not be deleted.  Once created, an object with the CKA_DELETABLE attribute set to FALSE may be deleted only by re-initialization of the token (or during a hardware tamper process).

CKA_SIGN_LOCAL_CERT

This attribute must be set to TRUE on any private key that is used with the Proof of Origin mechanism (CKM_ENCODE_X_509_LOCAL_CERT). Signing keys that do not have this attribute may not be used with this mechanism. Refer to CKM_WRAPKEY_DES3_ECB and CKM_WRAPKEY_DES3_CBC for more information.

Keys with this attribute should have the CKA_SIGN and CKA_ENCRYPT attributes set to FALSE to ensure that the key cannot be used to sign arbitrary data.  Special precautions should be taken to ensure that the key cannot leave the adapter - generally, CKA_EXTRACTABLE and CKA_EXPORTABLE should be FALSE and CKA_SENSITIVE should be TRUE.

CKA_CHECK_VALUE

This attribute is a key check value that is calculated as follows:

>Take a buffer of the cipher block size of binary zeros (0x00).

>Encrypt this block in ECB mode.

>Take the first three bytes of cipher text as the check value.

This attribute is calculated on all keys of class CKO_SECRET, that is, all symmetric key types when they are created or generated. The attribute is generated by default if it is not supplied in the key template. If it is supplied in the template, the template value is used even if its value would conflict with the one calculated as shown above. This is applicable when a customer wants to use an alternative method to validate a key.

NOTE   The CKA_ENCRYPT attribute is not required to be set to TRUE on the key object for the CKA_CHECK_VALUE attribute to be generated. This attribute cannot be changed once it has been set.

CKA_IMPORT

This attribute is similar to the standard CKA_UNWRAP attribute, which determines if a given key can be used to unwrap encrypted key material.  The important difference between this attribute and CKA_UNWRAP is that if CKA_IMPORT is set to TRUE and CKA_UNWRAP attribute is set to FALSE, the only available unwrap mechanism is CKM_WRAPKEY_DES3_CBC. The error code CKR_MECHANISM_INVALID is returned for all other mechanisms. CKA_IMPORT is set to FALSE by default.

CKA_CERTIFICATE_START_TIME; CKA_CERTIFICATE_END_TIME

These attributes are used to specify a user-defined validity period for X.509 certificates. Without these, the certificate validity period is 1 year from the date and time of creation. The format is YYYYMMDDhhmmss00, which is identical to that defined for utcTime in CK_TOKEN_INFO.

CKA_MECHANISM_LIST

These attributes hold an array of CK_MECHANISM_TYPE values.

The CKA_MECHANISM_LIST attribute restricts the operations that can be performed with any object containing it.

The following functions will check the object for the attribute, and if it is found, the CK_MECHANISM_TYPE being requested must be present in the attribute, or a CKR_MECHANISM_INVALID error is returned:

>C_Wrapkey

>C_Unwrapkey

>C_EncryptInit

>C_DecryptInit

>C_DigestKey

>C_SignInit

>C_VerifyInit

>C_SignRecoverInit

>C_VerifyRecoverInit

CKA_ENUM_ATTRIBUTE

This attribute is used to enumerate all the attributes of an object.

The attribute can only be passed in as part of a pTemplate parameter to the C_GetAttributeValue. It is never stored on an object.

Each ProtectToolkit-C session can hold an index value that is just used to support attribute enumeration.

Each call to C_GetAttributeValue using CKA_ENUM_ATTRIBUTE will return the next object attribute.

The error CKR_ATTRIBUTE_TYPE_INVALID is returned to indicate that the object has no more attributes.

A call to C_GetAttributeValue with the ulCount parameter set to zero will reset the index to zero.

CKA_BIP32_CHAINCODE

This read-only attribute is a 32-bit numeric value produced during BIP32 key derivation, part of the extended key. Applicable to the CKK_BIP32 key type only.

CKA_BIP32_VERSION_BYTES

This attribute is a 32-bit numeric value used by client applications to determine the network the key should be used in. By default, it is set to the main-net values. Applicable to the CKK_BIP32 key type only.

CKA_BIP32_CHILD_INDEX

This read-only attribute is a 32-bit numeric value that defines the child number. Values over 0x80000000 are considered hardened keys. The Master key node value is always 0. Applicable to the CKK_BIP32 key type only.

CKA_BIP32_CHILD_DEPTH

This read-only attribute is an 8 bit numeric value that defines the depth of the child. The Master key node depth is always 0.Applicable to the CKK_BIP32 key type only.

CKA_BIP32_ID

This read-only attribute provides a unique identifier for the BIP32 key pair. This value is generated by calculating the HASH160 of the public key. Applicable to the CKK_BIP32 key type only.

CKA_BIP32_FINGERPRINT

This read-only attribute is defined by the first 32 bits of the CKA_BIP32_ID. Applicable to the CKK_BIP32 key type only.

CKA_BIP32_PARENT_FINGERPRINT

This read-only attribute is defined by the first 32 bits of the parent node's CKA_BIP32_ID. For master keys, the value is always 0. Applicable to the CKK_BIP32 key type only.