Additional attribute types
This section describes additional vendor-defined attribute types. They are categorized according to the type of object to which they are applicable.
Refer to the description of each attribute to view further restrictions to its applicability. For more information about the types of objects that Cryptoki recognizes, refer to Object classes.
General object attributes
The following vendor-defined attributes are applicable to all objects.
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 can be specified in the template when the object is created, generated, or imported.
-
It can be added to an object with the C_SetAttributeValue command only if the
CKA_MODIFIABLE
isTrue
and the attribute does not already exist; that is once an object is created and made non-modifiable then theCKA_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_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_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 (ProtectServer 3 HSM Firmware 7.01.01 and newer only)
-
C_SignInit
-
C_VerifyInit
-
C_SignRecoverInit
-
C_VerifyRecoverInit
CKA_START_DATE, CKA_END_DATE
These attributes control the period in which the object can be used.
These attributes can 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, 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_TIME_STAMP
Every object created is assigned a value for the CKA_TIME_STAMP
attribute. This value is always read-only and cannot 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".
Token object attributes
The following vendor-defined attributes are applicable to token objects.
CKA_DELETABLE
This attribute can be set on any token object (that is, where the CKA_TOKEN
attribute is TRUE
) to specify that the object is permanent and cannot be deleted. Once created, an object with the CKA_DELETABLE
attribute set to FALSE
can be deleted only by re-initialization of the token (or during a hardware tamper process).
Key object attributes
The following vendor-defined attributes are applicable to key objects.
CKA_CHECK_VALUE
Note
The value definition of CKA_CHECK_VALUE was updated with ProtectServer 3 HSM Firmware 7.01.00 to match the PKCS#11 standard. CKA_CHECK_VALUE should not be considered a vendor-defined attribute if you are using a ProtectServer 3 HSM with ProtectServer 3 HSM Firmware 7.01.00 or newer.
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 ciphertext 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_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 can 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 can 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 can 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 can 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 can also not specify TRUE
for the CKA_DERIVE
attribute.
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_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_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 cannot 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_TR31_INFO
Note
This attribute is only available if you are using ProtectToolkit 7.1.0 or newer with ProtectServer 3 HSM Firmware 7.01.00 or newer.
This is a proprietary key object attribute used to hold additional information about the key. This information can be obtained from the TR-31 key block that was used to import the key, specified by the client when creating the key object or added later.
Attribute | Data type | Meaning |
---|---|---|
CKA_TR31_INFO |
Byte array | Proprietary format type 0 TR-31 header as described below. Minimum size 16. |
Rules for this attribute are the following:
-
This attribute can only be attached to an object of class
CKO_SECRET_KEY
,CKO_PRIVATE_KEY
, andCKO_PUBLIC_KEY
. -
The attribute is validated when the object is created or modified.
-
The attribute can be empty.
-
The Algorithm field must match the Key Type of the key.
-
The ID must be '0'.
-
The Length field must be valid.
-
Key usage attributes cannot exceed the capability of the header Usage/Mode.
-
-
The attribute can be added or replaced with C_SetAttributeValue or during a C_CopyObject or CT_CopyObject command only if the object has
CKA_MODIFIABLE
set toTRUE
and the new value is valid or empty. -
The attribute will be automatically added to the new key object during C_UnwrapKey command if the
CKM_UNWRAP_TR31
mechanism is used. For more information about this mechanism, see CKM_UNWRAP_TR31. -
Keys with the
CKA_TR31_INFO
attribute can be backed up and restored using the mechanisms that encode key value and attributes. -
The attribute can be specified in the new key template during the C_UnwrapKey command (using mechanisms that do not encode attributes) only if the new value is valid.
Byte array description
This section describes fields of the 16-byte array that CKA_TR31_INFO
receives as input from the TR-31 key block.
Mandatory fields
The following fields are always present.
- Key Block Version ID | Byte 0
-
This field identifies the version of the key block which defines the content and layout of the block. ‘0’ (0x30) – key block is type 0 proprietary format used for Cryptoki key object storage purposes.
Encoding is 1AN
- Key Block Length | Bytes 1-4
-
This field contains ASCII numeric digits providing key block length. Length does not include any encoded key values; that is, it is equal to the length of the
CKR_TR31_INFO
attribute.Encoding is 4N
- Key usage | Bytes 5-6
-
This field provides information about the intended function of the key or sensitive data.
Encoding is 2N
- Algorithm | Byte 7
-
This field specifies the approved algorithm for which the protected key can be used.
Encoding is 1AN
- Mode of Use | Byte 8
-
This field defines the operation the key can perform.
Encoding is 1AN
- Key Version Number | Bytes 9-10
-
This field contains the two-digit ASCII character version number, optionally used to indicate that contents of the key block is a component, or to prevent reinjection of old keys.
Encoding is 2AN
- Exportability | Byte 11
-
This field defines whether the protected key can be transferred outside the cryptographic domain in which the key is found.
Encoding is 1AN
- Number of Optional Blocks | Bytes 12-13
-
This field defines the number of optional blocks included in the key block. The minimum value is zero and the maximum is 99, but it is also limited by the maximum number of bytes in the entire key block. For example, 5 optional blocks would be represented by ‘0’ (0x30) in byte 12 and ‘5’ (0x35) in byte 13.
Encoding is 2N
- Reserved for future Use | Bytes 14-15
-
This field is reserved for future use and is filled with ASCII zero (0x30) characters.
Encoding is 2N
Optional fields
The following fields are only present if Number of Optional Blocks | Bytes 12-13 contain a value other than ‘00’ (0x3030).
- First Optional Block ID | Bytes 16-17
-
This field is the ID field for the first optional block, if one is present as indicated by a value other than ‘00’ in bytes 12 and 13.
Encoding is 2AN
- Option Block 1 Length | Bytes 18-19
-
This field contains the length of the first optional block in bytes (if it is present, as indicated by a value other than ‘00’ in bytes 12 and 13), including the field’s ID, length, and data. Byte 18 contains the high-order byte of the length and byte 19 contains the low-order byte, both in hex-ASCII form. For example, for a 24-byte optional block (18 in hexadecimal notation), byte 18 would contain a '1' (0x31) and byte 19 would contain an '8' (0x38).
Note
Optional Block Data can be omitted, in which case the Optional Block Length will be '04'.
If the length of the optional header exceeds 255, this field is set to '00' and the actual length is encoded in the following two fields.
Encoding is 2H
- Optional Block 1 Length of Length | Bytes 20-21
-
Note
This field is only present if Optional Block 1 Length is '00'
This field contains the length of the actual block length below. Valid values are '01' – 'FF'. For example, if the optional header length was '400' (0x0190 in hexadecimal notation, which needs 2 bytes), this field would be '02'.
Encoding is 2H
- Extended Optional Block 1 Length | Bytes 22-n
-
Note
This field is only present if Optional Block 1 Length is '00'
This field is the actual length of the block, expressed as a hexadecimal number. For example, if the optional header length was '400' (0x0190 in hexadecimal notation), this field would be '0190'.
Encoding is Var H
- Optional Block 1 Data | Bytes n-m
-
This field contains the data for that optional block (if it is present, as indicated by a value other than ’00’ in bytes 12-13). It will contain only printable ASCII characters.
Encoding is PA
- Additional Optional Blocks (if present) | Bytes n-m
-
A variable number of optional blocks can follow the first optional block, as indicated by the count in bytes 12-13. Each optional block contains a 2-byte ID, 2-byte length, and variable-length data field following the same format described above for Optional Block 1.
Note
Version 0 key blocks only contain the header(s) above; there is no key material or MAC following.
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 refer to 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 can 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 MODIFIABLE=False
.
BIP32 key object attributes
The following vendor-defined attributes are applicable to CKK_BIP32 key types only.
CKA_BIP32_CHAINCODE
This read-only attribute is a 32-bit numeric value produced during BIP32 key derivation, part of the extended key.
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.
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.
CKA_BIP32_FINGERPRINT
This read-only attribute is defined by the first 32 bits of the CKA_BIP32_ID
.
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.
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.
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.
Certificate Object Attributes
The following vendor-defined attributes are applicable to certificate objects.
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_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 can 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. Refer to 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_TRUSTED
This attribute can 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 cannot be modified.
The following values are defined for CKA_TRUSTED
:
Value | Description |
---|---|
TRUE (1) |
The certificate is trusted. |
FALSE (0) |
The certificate is not trusted and must be verified. |
The value of CKA_TRUSTED
can be set to TRUE
only when the Security Officer is logged on. 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 can no longer be modified.
Note
The other attributes of the certificate will remain modifiable unless the CKA_MODIFIABLE
attribute is set to FALSE
.