3.3.4. Key Object¶
Objects / Key Objects are Low level entities of key/certificates in SSS domain.
Below we can see UML Hierarchy of an object:

3.3.4.1. Create / Provision¶
To create a key, the sequence of APIs looks as under. This is generally done during provisioning stage.

To set (inject) values in a previously allocated key, the sequence of APDUs look as under.
Note
Policies
This section would be updated later to show case creation of keys with different policies attached to it.
3.3.4.2. Change value of previously created Objects¶
To create a key, the sequence of APIs looks as under:

3.3.4.3. Use previously provisioned/created Keys/Objects¶
To use a key, the API sequence is as under:

3.3.4.4. APIs¶
-
group
sss_key_object
Low level iota of key/certificates in
SSS
domain.Functions
-
sss_status_t
sss_key_object_allocate_handle
(sss_object_t *keyObject, uint32_t keyId, sss_key_part_t keyPart, sss_cipher_type_t cipherType, size_t keyByteLenMax, uint32_t options) Allocate / pre-provision memory for new key.
This API allows underlying cryptographic subsystems to perform preconditions of before creating any cryptographic key object.
- Return
Status of object allocation.
- Parameters
[inout] keyObject
: The object If required, update implementation defined values inside the keyObjectkeyId
: External Key ID. Later on this may be used by sss_key_object_get_handlekeyPart
: See sss_key_part_tcipherType
: See sss_cipher_type_tkeyByteLenMax
: Maximum storage this type of key may need. For systems that have their own internal allocation table this would helpoptions
: 0 = Persistant Key (Default) or Transient Key. See sss_key_object_mode_t
-
void
sss_key_object_free
(sss_object_t *keyObject) Destructor for the key object. The function frees key object context.
- Parameters
keyObject
: Pointer to key object context.
-
sss_status_t
sss_key_object_get_access
(sss_object_t *keyObject, uint32_t *access) Check what are access restrictions on an object
- Return
- Parameters
keyObject
: Objectaccess
: What is permitted
-
sss_status_t
sss_key_object_get_handle
(sss_object_t *keyObject, uint32_t keyId) Get handle to an existing allocated/provisioned/created Object.
See @ref sss_key_object_allocate_handle. After calling this API, Ideally keyObject should become equivlant to as set after the calling of @ref sss_key_object_allocate_handle api.
- Return
The sss status.
- Parameters
keyObject
: The key object[in] keyId
: The key identifier
-
sss_status_t
sss_key_object_get_purpose
(sss_object_t *keyObject, sss_mode_t *purpose) Check what is purpose restrictions on an object
- Return
- Parameters
keyObject
: Object to be checkedpurpose
: Know what is permitted.
-
sss_status_t
sss_key_object_get_user
(sss_object_t *keyObject, uint32_t *user) get attributes
-
sss_status_t
sss_key_object_init
(sss_object_t *keyObject, sss_key_store_t *keyStore) Constructor for a key object data structure The function initializes keyObject data structure and associates it with a key store in which the plain key and other attributes are stored.
- Return
Status of the operation
- Parameters
keyObject
:keyStore
:
- Return Value
kStatus_SSS_Success
: The operation has completed successfully.kStatus_SSS_Fail
: The operation has failed.kStatus_SSS_InvalidArgument
: One of the arguments is invalid for the function to execute.
-
sss_status_t
sss_key_object_set_access
(sss_object_t *keyObject, uint32_t access, uint32_t options) Assign access permissions to a key object.
- Parameters
keyObject
: the object where permission restrictions are appliedaccess
: Logical OR of read, write, delete, use, change attributes defined by enum _sss_access_permission.options
: Transient or persistent update. Allows for transient update of persistent attributes.
-
sss_status_t
sss_key_object_set_eccgfp_group
(sss_object_t *keyObject, sss_eccgfp_group_t *group) Set elliptic curve domain parameters over Fp for a key object.
When the key object is a reference to one of ECC Private, ECC Public or ECC Pair key types, this function shall be used to specify the exact domain parameters prior to using the key object for ECDSA or ECDH algorithms.
- Parameters
keyObject
: The destination key objectgroup
: Pointer to elliptic curve domain parameters over Fp (sextuple p,a,b,G,n,h)
-
sss_status_t
sss_key_object_set_purpose
(sss_object_t *keyObject, sss_mode_t purpose, uint32_t options) Assign purpose to a key object.
- Parameters
keyObject
: the object where permission restrictions are appliedpurpose
: Usage of the key.options
: Transient or persistent update. Allows for transient update of persistent attributes.
-
sss_status_t
sss_key_object_set_user
(sss_object_t *keyObject, uint32_t user, uint32_t options) Assign user to a key object.
- Parameters
keyObject
: the object where permission restrictions are applieduser
: Assign User id for a key object. The user is kept in the key store along with the key data and other properties.options
: Transient or persistent update. Allows for transient update of persistent attributes.
-
struct
sss_object_t
- #include <fsl_sss_api.h>
An object (secure / non-secure) within a Key Store.
Public Members
-
uint32_t
cipherType
cipherType type from sss_cipher_type_t
-
uint8_t
data
[(0 + (1 * sizeof(void *)) + (2 * sizeof(int)) + (4 * sizeof(void *)) + 32)]
-
struct sss_object_t::[anonymous]
extension
Reserved memory for implementation specific extension
-
uint32_t
keyId
Application specific key identifier. The keyId is kept in the key store along with the key data and other properties.
-
sss_key_store_t *
keyStore
key store holding the data and other properties
-
uint32_t
objectType
The type/part of object is referneced from sss_key_part_t
-
uint32_t
-
sss_status_t