3.3.2. Session¶

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
[inout] session
: Pointer to session context[in] subsystem
: See sss_session_open[in] application_id
: See sss_session_open[in] connection_type
: See sss_session_open[in] connectionData
: See sss_session_open
-
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 userAnything 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
[in] session
: Session context[in] property
: Value that is part of sss_session_prop_u32_t[out] pValue
:
-
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
-
uint8_t
-
enum