Attributes

Updated at:

The PKCS #11 library supports the following attributes for keys used with Cloud Hardware Security Module (CloudHSM). Attributes differ by key type and indicate whether a given operation is supported for a specific cryptographic function.

Attribute reference

The following table lists all supported attributes, their default values, and whether they can be changed after the key object is created.

Attribute Description Mutable after creation Default value
CKA_SIGN Boolean. CK_TRUE if the key supports signing. Yes FALSE
CKA_VERIFY Boolean. CK_TRUE if the key supports verification. Yes FALSE
CKA_ENCRYPT Boolean. CK_TRUE if the key supports encryption. Yes FALSE
CKA_DECRYPT Boolean. CK_TRUE if the key supports decryption. Yes FALSE
CKA_WRAP Boolean. CK_TRUE if the key supports wrapping. Yes FALSE
CKA_UNWRAP Boolean. CK_TRUE if the key supports unwrapping. Yes FALSE
CKA_LABEL Description of the object. Yes —
CKA_SENSITIVE TRUE if the key is sensitive. Yes TRUE
CKA_DERIVE Boolean. CK_TRUE if the key supports key derivation. Must be FALSE for all public keys. For secret and EC private keys, can be TRUE or FALSE. See CKA_DERIVE for details. Yes FALSE
CKA_TRUSTED Can be set to TRUE or FALSE by a Crypto Officer (CO) only. Marks the key as trusted for the application that created it. Yes FALSE
CKA_WRAP_WITH_TRUSTED CK_TRUE if the key can only be wrapped with a wrapping key that has CKA_TRUSTED set to CK_TRUE. Can be changed from FALSE to TRUE, but cannot be reverted once set to TRUE. Depends on initial value FALSE
CKA_DESTROYABLE Boolean. CK_TRUE if the object can be destroyed using C_DestroyObject. Not applied to session keys (deviation from the PKCS #11 specification). Yes TRUE
CKA_WRAP_TEMPLATE Applies to wrapping keys only. An attribute template that keys must match to be wrapped with this key. If a key does not match, the wrapping operation fails. CKA_WRAP must be TRUE. See CKA_WRAP_TEMPLATE for details. Yes Not defined
CKA_UNWRAP_TEMPLATE Applies to unwrapping keys only. An attribute template prefixed to each key unwrapped with this key, provided no conflict exists with the user-supplied template. CKA_UNWRAP must be TRUE. See CKA_UNWRAP_TEMPLATE for details. Yes Not defined
CKA_ID Byte array. Key identifier. No —
CKA_CHECK_VALUE Byte array. Key checksum. No —
CKA_CLASS Object class. No —
CKA_LOCAL Boolean. TRUE if the key was generated locally. No TRUE
CKA_EXTRACTABLE Boolean. TRUE if the key is extractable and can be wrapped. No TRUE
CKA_EC_PARAMS No —
CKA_EC_POINT Applicable when creating a public key only. No —
CKA_PRIVATE_EXPONENT Private exponent *d*. Applicable when creating a private key object only. No —
CKA_NEVER_EXTRACTABLE Returns the value set by the HSM. Read-only. See CKA_NEVER_EXTRACTABLE for details. No TRUE for private and secret keys
CKA_ALWAYS_SENSITIVE CK_TRUE if the key has always had CKA_SENSITIVE set to CK_TRUE. Read-only. See CKA_ALWAYS_SENSITIVE for details. No TRUE

Attribute behaviors

The following attributes have specific behaviors described below.

CKA_NEVER_EXTRACTABLE

CKA_NEVER_EXTRACTABLE tracks the full history of CKA_EXTRACTABLE for a key. It is a read-only attribute and cannot be set by any user as part of a create or generate template.

CKA_ALWAYS_SENSITIVE

CKA_ALWAYS_SENSITIVE tracks the full history of CKA_SENSITIVE for a key and cannot be set by the user as part of an import or generate template. It is a read-only attribute.

CKA_WRAP_TEMPLATE

CKA_WRAP_TEMPLATE is applicable to wrapping keys only. It specifies an attribute template that keys must match to be wrapped with that key. If a key does not match the template, the wrapping operation fails.

The default value is empty, which prevents a single wrapping key from being used to wrap all keys without restriction.

CKA_WRAP must be TRUE to use this attribute.

The following sub-attributes are supported in CKA_WRAP_TEMPLATE for C_GenerateKeyPair, C_GenerateKey, and C_CreateObject:

Sub-attribute Accepted values
CKA_CLASS Private and secret class
CKA_KEY_TYPE Based on key class
CKA_LOCAL TRUE or FALSE
CKA_TOKEN TRUE or FALSE
CKA_PRIVATE TRUE or FALSE
CKA_ENCRYPT TRUE or FALSE
CKA_DECRYPT TRUE or FALSE
CKA_DERIVE TRUE or FALSE
CKA_DESTROYABLE TRUE or FALSE
CKA_SIGN TRUE or FALSE
CKA_VERIFY TRUE or FALSE
CKA_WRAP TRUE or FALSE
CKA_UNWRAP TRUE or FALSE
CKA_SENSITIVE TRUE or FALSE
CKA_ALWAYS_SENSITIVE TRUE or FALSE
CKA_MODULUS_BITS 1024–4096
CKA_VALUE_LEN 1–800 (secret keys only)
CKA_WRAP_WITH_TRUSTED TRUE or FALSE
CKA_TRUSTED TRUE or FALSE

CKA_UNWRAP_TEMPLATE

CKA_UNWRAP_TEMPLATE is applicable to unwrapping keys only. During an unwrap operation, the attributes in this template are prefixed to the template of each unwrapped key, provided no conflict exists with the user-supplied template.

The default value is empty.

CKA_UNWRAP must be TRUE to use this attribute.

The following sub-attributes are supported in CKA_UNWRAP_TEMPLATE for C_GenerateKeyPair, C_GenerateKey, and C_CreateObject:

Supported sub-properties and accepted input values
CKA_CLASS Private and secret class only
CKA_KEY_TYPE Based on key class
CKA_TOKEN TRUE or FALSE
CKA_PRIVATE TRUE or FALSE
CKA_ENCRYPT TRUE or FALSE
CKA_DECRYPT TRUE or FALSE
CKA_DERIVE TRUE or FALSE
CKA_DESTROYABLE TRUE or FALSE
CKA_SIGN TRUE or FALSE
CKA_VERIFY TRUE or FALSE
CKA_WRAP TRUE or FALSE
CKA_UNWRAP TRUE or FALSE
CKA_SENSITIVE TRUE or FALSE
CKA_EXTRACTABLE TRUE or FALSE
CKA_MODULUS_BITS 1024–4096
CKA_VALUE_LEN 1–800 (secret keys only)
CKA_WRAP_WITH_TRUSTED TRUE or FALSE

CKA_DERIVE

CKA_DERIVE controls key derivation. Set it to CK_TRUE to allow the key to derive another key.

  • For all public keys: must be FALSE and cannot be set to TRUE.

  • For secret keys and EC private keys: can be TRUE or FALSE.