3.3.2. Session

../../_images/session.png

See sss_session_open(), sss_session_close()

3.3.2.1. Opening a Session

Sessions are tightly coupled with underlying system. For opening a session, sss_session_open(), subsystem is passed from sss_type_t, while the parameter connectionData plays a pivotal role where there are subsystem specific parameters to be handled.

Note

sss_session_open() must not be called concurrently from multiple threads. The application must ensure this.

3.3.2.1.1. SE05x Session

For example, a dedicated SE_Connect_Ctx_t is passed while opening a session to the SE05x Secure Element.

/* Opening a password/user id based session */
sss_session_t session       = {0};
SE_Connect_Ctx_t connectCtx = {0};
sss_object_t ex_id          = {0}; /* Object to store the id value */
sss_status_t status;

/* we need a host session and key store to access
 * values from host */
sss_session_t host_session    = {0};
sss_key_store_t host_keystore = {0};

/* Value which we are going to use eventually.
 * We will not use it directly, but indirectly.
 * We will store this in in ex_id
 */
const uint8_t value_user_id[] = EX_SSS_AUTH_SE05X_UserID_VALUE;

/* Open host session and key store */
status = sss_session_open(&host_session, kType_SSS_Software, 0, kSSS_ConnectionType_Plain, NULL);
TEST_ASSERT_EQUAL_HEX(kStatus_SSS_Success, status);
status = sss_key_store_context_init(&host_keystore, &host_session);
TEST_ASSERT_EQUAL_HEX(kStatus_SSS_Success, status);

/* Set the auth object in Connect context */
connectCtx.auth.ctx.idobj.pObj = &ex_id;
status                         = sss_key_object_init(connectCtx.auth.ctx.idobj.pObj, &host_keystore);
TEST_ASSERT_EQUAL_HEX(kStatus_SSS_Success, status);

/* On the host, allocate object and set value */
status = sss_key_object_allocate_handle(connectCtx.auth.ctx.idobj.pObj,
    __LINE__,
    kSSS_KeyPart_Default,
    kSSS_CipherType_UserID,
    sizeof(value_user_id),
    kKeyObject_Mode_Transient);
TEST_ASSERT_EQUAL_HEX(kStatus_SSS_Success, status);
status = sss_key_store_set_key(&host_keystore,
    connectCtx.auth.ctx.idobj.pObj,
    value_user_id,
    sizeof(value_user_id),
    8 * sizeof(value_user_id),
    NULL,
    0);
TEST_ASSERT_EQUAL_HEX(kStatus_SSS_Success, status);

/* Now we connect to the SE.   In this example, we
 * are connecting to over JRCP V2 interface */
connectCtx.portName      = gszA71SocketPortDefault;
connectCtx.connType      = kType_SE_Conn_Type_JRCP_V2;
connectCtx.auth.authType = kSSS_AuthType_ID;

const uint32_t authObjectIdForPasswordSession = EX_SSS_AUTH_SE05X_UserID_AUTH_ID;

/* Open the session to the secure element */
status = sss_session_open(
    &session, kType_SSS_SecureElement, authObjectIdForPasswordSession, kSSS_ConnectionType_Password, &connectCtx);
TEST_ASSERT_EQUAL_HEX(kStatus_SSS_Success, status);
/* .... operations with the SE .... */
/* Close the connection to secure element */
sss_session_close(&session);

3.3.2.2. APIS

group sss_session

Manage session.

Enums

enum sss_session_prop_au8_t

Properties of session that are S32

From 0 to kSSS_SessionProp_Optional_Prop_Start, around 2^24 = 16777215 Properties are possible.

From 0 to kSSS_SessionProp_Optional_Prop_Start, around 2^24 = 16777215 Properties are possible.

Values:

kSSS_SessionProp_au8_NA = 0

Invalid

kSSS_SessionProp_szName

Name of the product, string

kSSS_SessionProp_UID

Unique Identifier

kSSS_SessionProp_au8_Optional_Start = 0x00FFFFFFu

Optional Properties Start

kSSS_SessionProp_au8_Proprietary_Start = 0x01FFFFFFu

Proprietary Properties Start

enum sss_session_prop_u32_t

Properties of session that are U32

From 0 to kSSS_SessionProp_Optional_Prop_Start, around 2^24 = 16777215 Properties are possible.

From 0 to kSSS_SessionProp_Optional_Prop_Start, around 2^24 = 16777215 Properties are possible.

Values:

kSSS_SessionProp_u32_NA = 0

Invalid

kSSS_SessionProp_VerMaj

Major version

kSSS_SessionProp_VerMin

Minor Version

kSSS_SessionProp_VerDev

Development Version

kSSS_SessionProp_UIDLen
kSSS_SessionProp_u32_Optional_Start = 0x00FFFFFFu

Optional Properties Start

kSSS_KeyStoreProp_FreeMem_Persistant

How much persistent memory is free

kSSS_KeyStoreProp_FreeMem_Transient

How much transient memory is free

kSSS_SessionProp_u32_Proprietary_Start = 0x01FFFFFFu

Proprietary Properties Start

Functions

void sss_session_close(sss_session_t *session)

Close session between application and security subsystem.

This function closes a session which has been opened with a security subsystem. All commands within the session must have completed before this function can be called. The implementation must do nothing if the input session parameter is NULL.

Parameters
  • session: Session context.

sss_status_t sss_session_create(sss_session_t *session, sss_type_t subsystem, uint32_t application_id, sss_connection_type_t connection_type, void *connectionData)

Same as sss_session_open but to support sub systems that explictily need a create before opening.

For the sake of portabilty across various sub systems, the applicaiton has to call sss_session_create before calling sss_session_open.

Parameters

void sss_session_delete(sss_session_t *session)

Counterpart to sss_session_create

Similar to contraint on sss_session_create, application may call sss_session_delete to explicitly release all underlying/used session specific resoures of that implementation.

sss_status_t sss_session_open(sss_session_t *session, sss_type_t subsystem, uint32_t application_id, sss_connection_type_t connection_type, void *connectionData)

Open session between application and a security subsystem.

           Open virtual session between application (user context) and a
           security subsystem and function thereof. Pointer to session
           shall be supplied to all SSS APIs as argument. Low level SSS
           functions can provide implementation specific behaviour based
           on the session argument.
           Note: sss_session_open() must not be called concurrently from
           multiple threads. The application must ensure this.

Return

status

Parameters
  • [inout] session: Session context.

  • [in] subsystem: Indicates which security subsystem is selected to be used.

  • [in] application_id: ObjectId/AuthenticationID Connecting to:

    • application_id == 0 => Super use / Plaform user

    • Anything else => Authenticated user

  • [in] connection_type: How are we connecting to the system.

  • [inout] connectionData: subsystem specific connection parameters.

sss_status_t sss_session_prop_get_au8(sss_session_t *session, uint32_t property, uint8_t *pValue, size_t *pValueLen)

Get an underlying property of the crypto sub system.

This API is used to get values that are numeric in nature.

Property can be either fixed value that is calculated at compile time and returned directly, or it may involve some access to the underlying system.

Return

Parameters
  • [in] session: Session context

  • [in] property: Value that is part of sss_session_prop_au8_t

  • [out] pValue: Output buffer array

  • [inout] pValueLen: Count of values thare are/must br read

sss_status_t sss_session_prop_get_u32(sss_session_t *session, uint32_t property, uint32_t *pValue)

Get an underlying property of the crypto sub system.

This API is used to get values that are numeric in nature.

Property can be either fixed value that is calculated at compile time and returned directly, or it may involve some access to the underlying system.

For applicable properties see sss_session_prop_u32_t

Return

Parameters

struct sss_session_t
#include <fsl_sss_api.h>

Root session.

This is a singleton for each connection (physical/logical) to individual cryptographic system.

Public Members

uint8_t data[(0 + (1 * sizeof(void *)) + (1 * sizeof(void *)) + (8 * sizeof(void *)) + 32)]
struct sss_session_t::[anonymous] extension

Reserved memory for implementation specific extension

sss_type_t subsystem

Indicates which security subsystem is selected.

This is set when sss_session_open is successful