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:

../../_images/container-session-ks-ko.png

3.3.4.1. Create / Provision

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

../../_images/key_object-create-key.png

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:

../../_images/key_object-set-key.png

3.3.4.3. Use previously provisioned/created Keys/Objects

To use a key, the API sequence is as under:

../../_images/key_object-use-key.png

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 keyObject

  • keyId: External Key ID. Later on this may be used by sss_key_object_get_handle

  • keyPart: See sss_key_part_t

  • cipherType: See sss_cipher_type_t

  • keyByteLenMax: Maximum storage this type of key may need. For systems that have their own internal allocation table this would help

  • options: 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: Object

  • access: 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 checked

  • purpose: 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

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 applied

  • access: 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 object

  • group: 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 applied

  • purpose: 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 applied

  • user: 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