m2mb_secure_ms.h File Reference

Secure Microservice Support. More...

Go to the source code of this file.

Macros
#define	M2MB_SYSTEM_FILE_ID   (-1)
#define	M2MB_RAM_FILE_ID   (0)
#define	M2MB_SECURE_MS_READ   0x0000
#define	M2MB_SECURE_MS_WRITE   0x0001
#define	M2MB_SECURE_MS_CREATE   0x0002
#define	M2MB_SECURE_MS_ADMIN   0x0004
#define	M2MB_SECURE_MS_READ_ONLY   0x0008
#define	M2MB_SECURE_MS_TRUSTED   0x0010
#define	M2MB_SECURE_MS_ALLOW_COMPARE   0x0020
#define	M2MB_SECURE_MS_NO_ENCRYPTION   0x0080

Typedefs
typedef struct M2MB_SECURE_MS_HANDLE_S *	M2MB_SECURE_MS_HANDLE
	Opaque Handle used for the Secure Microservice calls.

Enumerations
enum	M2MB_SECURE_MS_ERRNO_E {   M2MB_SECURE_MS_ERRNO_NOERROR, M2MB_SECURE_MS_ERRNO_IN_USE, M2MB_SECURE_MS_ERRNO_NO_ACCESS_RIGHTS, M2MB_SECURE_MS_ERRNO_ID_ALREADY_EXIST,   M2MB_SECURE_MS_ERRNO_ID_DOESNT_EXIST, M2MB_SECURE_MS_ERRNO_ILLEGAL_PARAM, M2MB_SECURE_MS_ERRNO_OUT_OF_SPACE, M2MB_SECURE_MS_ERRNO_INVALID_HANDLE,   M2MB_SECURE_MS_ERRNO_FAIL_TO_CREATE_HANDLE, M2MB_SECURE_MS_ERRNO_INVALID_DATA, M2MB_SECURE_MS_ERRNO_CRYPTO_ERR, M2MB_SECURE_MS_ERRNO_FILE_SYSTEM_ERR,   M2MB_SECURE_MS_ERRNO_DATA_ISNT_DEFINED_AS_KEY, M2MB_SECURE_MS_ERRNO_FATAL, M2MB_SECURE_MS_ERRNO_DELETE_ERR, M2MB_SECURE_MS_ERRNO_INCOMPATIBLE_REQ,   M2MB_SECURE_MS_ERRNO_UNKNOWN = 65535 }
	Enumeration representing all supported: value different got. has line code meaning: provide number to analyze. More...
enum	M2MB_SECURE_MS_MANAGE_REQ_E {   M2MB_SECURE_MS_GET_STATE, M2MB_SECURE_MS_LOCK_TSD, M2MB_SECURE_MS_TELIT_FACTORY_RESET, M2MB_SECURE_MS_LOCK_CSD,   M2MB_SECURE_MS_CUSTOMER_FACTORY_RESET }
	Management request option. Secure Microservice System File has 3 levels (see M2MB_SECURE_MS_MANAGE_STATE_E): TSD(level 0)-CSD(level 1)-OSD(level 2) More...
enum	M2MB_SECURE_MS_MANAGE_STATE_E { M2MB_SECURE_MS_TSD_ACTIVE, M2MB_SECURE_MS_CSD_ACTIVE, M2MB_SECURE_MS_OSD_ACTIVE }
	The state of the Secure Storage. It represent the Secure Microservice System File levels (TSD-CSD-OSD) More...

Functions
M2MB_RESULT_E	m2mb_secure_ms_manage (M2MB_SECURE_MS_MANAGE_REQ_E request, M2MB_SECURE_MS_MANAGE_STATE_E *state)
	A management function that handles Telit's and the Customer's default values. More...
M2MB_RESULT_E	m2mb_secure_ms_remove_file (INT32 file_id)
	Deletes the relevant secure data file. More...
M2MB_RESULT_E	m2mb_secure_ms_open (M2MB_SECURE_MS_HANDLE *handle, INT32 file_id, UINT16 item_id, UINT16 flags)
	Open the relevant secure data file. More...
M2MB_RESULT_E	m2mb_secure_ms_read (M2MB_SECURE_MS_HANDLE handle, UINT32 max_len, UINT8 *data, UINT32 *act_len)
	Read a Secured Data item. More...
M2MB_RESULT_E	m2mb_secure_ms_write (M2MB_SECURE_MS_HANDLE handle, UINT8 *data, UINT32 len)
	Writes a Secured Data item. More...
M2MB_RESULT_E	m2mb_secure_ms_compare (M2MB_SECURE_MS_HANDLE handle, UINT8 *data, UINT32 len)
	Compare the input Item to the Secured copy. More...
M2MB_RESULT_E	m2mb_secure_ms_delete (M2MB_SECURE_MS_HANDLE handle)
	Delete an Item from the Secured file. More...
M2MB_RESULT_E	m2mb_secure_ms_close (M2MB_SECURE_MS_HANDLE handle)
	Close the opened secure data file. More...
M2MB_SECURE_MS_ERRNO_E	m2mb_secure_ms_errno (M2MB_SECURE_MS_HANDLE handle)
	Return the last error obtained calling Secure MS functions. More...
M2MB_RESULT_E	m2mb_secure_ms_init (void)
	Module initialization. More...

Detailed Description

Secure Microservice Support.

m2m/m2m_common/m2mb_inc/m2mb_secure_ms.h

APIs for all the secure data. See also "m2mb_secure_ms_extend" module that is correlated for a complete set of APIs usage, along with "m2mb_crypto" module

Note

Dependencies: m2mb_types.h

Author

Ian Levine, Alessandro Papagno

Date

12/09/2017

Macro Definition Documentation

M2MB_RAM_FILE_ID

#define M2MB_RAM_FILE_ID   (0)

file_id to be used when accessing the volatile system file (ram): item created will not be present at next reboot

M2MB_SECURE_MS_ADMIN

#define M2MB_SECURE_MS_ADMIN   0x0004

When with the CREATE flag then the new item can be access only with the ADMIN flag: ADMIN property is reserved for not volatile file system part, on the user space ADMIN can be used only for not volatile file system using M2MB_RAM_FILE_ID

M2MB_SECURE_MS_ALLOW_COMPARE

#define M2MB_SECURE_MS_ALLOW_COMPARE   0x0020

The new item can be used by the m2mb_secure_ms_compare function (has to come with the CREATE flag)

M2MB_SECURE_MS_CREATE

#define M2MB_SECURE_MS_CREATE   0x0002

For writing a new item

M2MB_SECURE_MS_NO_ENCRYPTION

#define M2MB_SECURE_MS_NO_ENCRYPTION   0x0080

The new item doesn't need to be encrypted (has to come with the CREATE flag)

M2MB_SECURE_MS_READ

#define M2MB_SECURE_MS_READ   0x0000

In all modes items can be read

M2MB_SECURE_MS_READ_ONLY

#define M2MB_SECURE_MS_READ_ONLY   0x0008

The new item is READ ONLY (has to come with the CREATE flag). A READ_ONLY item can't be deleted

M2MB_SECURE_MS_TRUSTED

#define M2MB_SECURE_MS_TRUSTED   0x0010

The new item is a trusted item (e.g. PrK, PsK) This data cannot be read using m2mb_secure_read Has to come with the CREATE flag

M2MB_SECURE_MS_WRITE

#define M2MB_SECURE_MS_WRITE   0x0001

For writing on existing item

M2MB_SYSTEM_FILE_ID

#define M2MB_SYSTEM_FILE_ID   (-1)

file_id to be used when accessing the non volatile system file (flash)

Enumeration Type Documentation

M2MB_SECURE_MS_ERRNO_E

enum M2MB_SECURE_MS_ERRNO_E

Enumeration representing all supported: value different got. has line code meaning: provide number to analyze.

Enumerator
M2MB_SECURE_MS_ERRNO_NOERROR	0: No Error
M2MB_SECURE_MS_ERRNO_IN_USE	1: Tried to write an item that is in use or to read an item that is in use for write operation
M2MB_SECURE_MS_ERRNO_NO_ACCESS_RIGHTS	2: Tried to access without Admin rights
M2MB_SECURE_MS_ERRNO_ID_ALREADY_EXIST	3: Tried to CREATE an item that already exist
M2MB_SECURE_MS_ERRNO_ID_DOESNT_EXIST	4: Tried to access an item that doesn't exist
M2MB_SECURE_MS_ERRNO_ILLEGAL_PARAM	5: Parameter has an illegal value
M2MB_SECURE_MS_ERRNO_OUT_OF_SPACE	6: The Secure Data Area is full
M2MB_SECURE_MS_ERRNO_INVALID_HANDLE	7: An invalid handle
M2MB_SECURE_MS_ERRNO_FAIL_TO_CREATE_HANDLE	8: Failed to create a handle
M2MB_SECURE_MS_ERRNO_INVALID_DATA	9: The data is invalid
M2MB_SECURE_MS_ERRNO_CRYPTO_ERR	10: Error from m2mb_crypto_*
M2MB_SECURE_MS_ERRNO_FILE_SYSTEM_ERR	11: Error from m2mb_fs_*, use m2mb_fs_get_errno_value to retrieve the value
M2MB_SECURE_MS_ERRNO_DATA_ISNT_DEFINED_AS_KEY	12: Tried to use the item as a key but it wasn't created that way
M2MB_SECURE_MS_ERRNO_FATAL	13: Fatal error - The Secure Storage isn't valid, may have been modified
M2MB_SECURE_MS_ERRNO_DELETE_ERR	14: Item cannot be deleted, since relòative to locked item
M2MB_SECURE_MS_ERRNO_INCOMPATIBLE_REQ	15: request is incompatible\inconsistent in current Microservice System File level
M2MB_SECURE_MS_ERRNO_UNKNOWN	65535: Unknown error

M2MB_SECURE_MS_MANAGE_REQ_E

enum M2MB_SECURE_MS_MANAGE_REQ_E

Management request option. Secure Microservice System File has 3 levels (see M2MB_SECURE_MS_MANAGE_STATE_E): TSD(level 0)-CSD(level 1)-OSD(level 2)

TSD - Telit Secure Data Data items written on Telit production site CSD - Custom Secure Data Data items written on Customer production site OSD - Operational Secure Data Data items written after previous phases

System starts from TSD at first boot; When a level is locked (TSD or CSD) system moves to the next level (e.g from TSD to CSD) Levels are like OTP, One Time Programmable, when locked, items in it cannot longer be removed

• TSD When LOCKED, items in it cannot longer be removed\written, but in case updated in CSD (constraint for update: updated item must have same lenght)
• CSD When LOCKED, items in it cannot longer be removed\written, but in case updated in OSD (constraint for update: updated item must have same lenght)
• OSD Level cannot be locked, it is the last level

To update a system item locked in a previous level (e.g TSD), just rewrite it (same lenght!) A copy of it, is create and written on next level (e.g CSD)

When a system item has to be opened, Secure Microservice searchs first on the current level, and in case moves on the previous one (e.g current CSD, search on CSD, if not found look on TSD)

Below an example of current internal status when current level is OSD

TSD CSD OSD 3 ---— updated --> 3 8 4 9 10 15 -----—|updated 11 |------—> 15

Item 10: is used from OSD (can be used) Item 9: is used from CSD (not found in OSD, search in CSD, can be used) Item 3: is used from CSD (not found in OSD, search in CSD, can be used) It is an update of item 3 in TSD, is used as update Item 4: is used from TSD (not found in OSD, not found in CSD, search in TSD, can be used) Item 12: not FOUND, cannot be used. Need to create new one in OSD

Enumerator
M2MB_SECURE_MS_GET_STATE	Return the current Secure Microservice System File's level (TSD-CSD-OSD)
M2MB_SECURE_MS_LOCK_TSD	Lock the TSD - No more items can be added to or removed from it. Current level moves to CSD (M2MB_SECURE_MS_CSD_ACTIVE)
M2MB_SECURE_MS_TELIT_FACTORY_RESET	Allowed only on CSD level: removing the CSD items, Telit's defaults is fully recovered as in TSD Current level remains CSD
M2MB_SECURE_MS_LOCK_CSD	Lock the CSD - No more items can be added to or removed from it. Current level moves to OSD (M2MB_SECURE_MS_OSD_ACTIVE)
M2MB_SECURE_MS_CUSTOMER_FACTORY_RESET	Allowed only on OSD level: removing the OSD items, Customer's defaults is fully recovered as in CSD Current level remains OSD

M2MB_SECURE_MS_MANAGE_STATE_E

enum M2MB_SECURE_MS_MANAGE_STATE_E

The state of the Secure Storage. It represent the Secure Microservice System File levels (TSD-CSD-OSD)

Enumerator
M2MB_SECURE_MS_TSD_ACTIVE	CSD & OSD levels don't exist: current level is TSD
M2MB_SECURE_MS_CSD_ACTIVE	OSD doesn't exist, TSD level is locked
M2MB_SECURE_MS_OSD_ACTIVE	Both TSD & CSD are locked, OSD is the current level

Function Documentation

m2mb_secure_ms_close()

M2MB_RESULT_E m2mb_secure_ms_close

(

M2MB_SECURE_MS_HANDLE

handle

)

Close the opened secure data file.

This function while closing the file deletes the secure data file handle. Content of file are saved in FS or removed in case m2mb_secure_ms_delete was used before.

Parameters

[in]

handle

Secure data file handle

Returns

M2MB_RESULT_SUCCESS in case of success

M2MB_RESULT_FAIL in case of fail

Note

The specific error can be retrieved using m2mb_secure_ms_errno( h ).

Example

int main()
{
    M2MB_SECURE_MS_HANDLE pHandle;
    M2MB_RESULT_E ret  = M2MB_RESULT_SUCCESS;
    UINT8 tempBuff[1];
    UINT32 len;
 
    tempBuff[0] = 0xFF;
    // in case use M2MB_RAM_FILE_ID instead of M2MB_SYSTEM_FILE_ID
    ret = m2mb_secure_ms_open( &pHandle, M2MB_SYSTEM_FILE_ID, 3, M2MB_SECURE_MS_CREATE | M2MB_SECURE_MS_TRUSTED | M2MB_SECURE_MS_ADMIN );
 
    if( ret == M2MB_RESULT_SUCCESS )
    {
      //write data
      ret = m2mb_secure_ms_write( pHandle, tempBuff, len );
    }
    // apply the new data saving on FS
    ret = m2mb_secure_ms_close( pHandle );
  }
}

m2mb_secure_ms_compare()

M2MB_RESULT_E m2mb_secure_ms_compare	(	M2MB_SECURE_MS_HANDLE	handle,
		UINT8 *	data,
		UINT32	len
	)

Compare the input Item to the Secured copy.

This function checks if the input data is equal to the Secure Data. Only items that were created using the M2MB_SECURE_MS_ALLOW_COMPARE flag can be compared. Typically item created with M2MB_SECURE_MS_TRUSTED flag are not created with M2MB_SECURE_MS_ALLOW_COMPARE flag, to avoid attempts to reveal trusted item data

Parameters

[in]	handle	Secure data file handle
[in]	data	Data (item) to compare.
[out]	len	The number of bytes in data.

Returns

M2MB_RESULT_SUCCESS - Data match.

M2MB_RESULT_FAIL - Error or data doesn't match

Note

The specific error can be retrieved using m2mb_secure_ms_errno( h ).

Example

<C code example>

m2mb_secure_ms_delete()

M2MB_RESULT_E m2mb_secure_ms_delete

(

M2MB_SECURE_MS_HANDLE

handle

)

Delete an Item from the Secured file.

This function deletes a specific item from the Secure Data. The item should have been open as M2MB_SECURE_MS_WRITE and in case with M2MB_SECURE_MS_ADMIN as an option flag. Item with M2MB_SECURE_MS_ADMIN attributes cannot be deleted if not opened as ADMIN. A READ_ONLY file cannot be deleted. The content of the item is deleted, but still present in File System until m2mb_secure_ms_close() is invoked which perform permanent removal from FS.

Parameters

[in]

handle

Secure data file handle

Returns

M2MB_RESULT_SUCCESS in case of success

M2MB_RESULT_FAIL in case of fail

Note

The specific error can be retrieved using m2mb_secure_ms_errno( h ).

Example

int main()
{
  M2MB_RESULT_E ret  = M2MB_RESULT_SUCCESS;
  M2MB_SECURE_MS_HANDLE pHandle;
 
  // need to be opened with M2MB_SECURE_MS_WRITE to delete
  ret = m2mb_secure_ms_open( &pHandle, M2MB_SYSTEM_FILE_ID, 3, M2MB_SECURE_MS_WRITE );
  if( ret == M2MB_RESULT_SUCCESS )
  {
    // delete just delete the current data on ram
    ret = m2mb_secure_ms_delete( pHandle );
    // now removal of item is applied on the file system
    ret = m2mb_secure_ms_close( pHandle );
  }
}

m2mb_secure_ms_errno()

M2MB_SECURE_MS_ERRNO_E m2mb_secure_ms_errno

(

M2MB_SECURE_MS_HANDLE

handle

)

Return the last error obtained calling Secure MS functions.

This function return last specific error number.

Parameters

[in]

handle

Secure data file handle. If NULL it returns the last system general error, not specific to the handle. E.g error get during file opening, where handle is not get.

Returns

The error code of the last operation.

Note

Example

<C code example>

m2mb_secure_ms_init()

M2MB_RESULT_E m2mb_secure_ms_init

(

void

)

Module initialization.

This function initializes the module. Must be called before any other secure_ms APIs

Returns

M2MB_RESULT_SUCCESS in case of success

M2MB_RESULT_FAIL in case of fail

Note

Example

<C code example>

m2mb_secure_ms_manage()

M2MB_RESULT_E m2mb_secure_ms_manage	(	M2MB_SECURE_MS_MANAGE_REQ_E	request,
		M2MB_SECURE_MS_MANAGE_STATE_E *	state
	)

A management function that handles Telit's and the Customer's default values.

There are 3 Microservice System File's level:

1. TSD - Telit Secure Data that contains Telit's default items as they are set during manufacturing.
2. CSD - Customer's Secure Data that contains the Customer's default items (plus TSD ones) as they are set during manufacturing.
3. OSD - Operational Secure Storage that contains items (plus TSD and CSD ones) that are added during the module life cycle. TSD items, that are not READ_ONLY, may be overridden by the CSD and OSD. CSD items, that are not READ_ONLY, may be overridden by the OSD. As explained above (Management request option: M2MB_SECURE_MS_MANAGE_REQ_E) and in in m2mb_secure_ms_open, search for a system item in M2MB_SYSTEM_FILE_ID is performed by looking first on the highest level, therefore first in to OSD(if the level exist), then in the CSD(if the level exist) and then in the TSD.

The effects of the request depends on the current Microservice System File level (TSD-CSD-OSD):

M2MB_SECURE_MS_LOCK_TSD
    Allowed only if TSD is the current level.
    From now on, no data can be added to nor deleted from the TSD.
    This causes the following Microservice System File level change:
        TSD -> CSD
        Current level:  TSD (M2MB_SECURE_MS_TSD_ACTIVE)
        New level    :  CSD (M2MB_SECURE_MS_CSD_ACTIVE)

M2MB_SECURE_MS_TELIT_FACTORY_RESET
    Allowed only if CSD is the current level.
    All CSD added items are removed. Full Telit's Default items are recovered.
    Microservice System File level remains unchanged:
        TSD <=> TSD
        Current level:  CSD (M2MB_SECURE_MS_CSD_ACTIVE)
        New level    :  unchanged

M2MB_SECURE_MS_LOCK_CSD
    Allowed only if CSD is the current level.
    From now on, no data can be added to nor deleted from the CSD.
    This causes the following Microservice System File level change:
        CSD -> OSD
        Current level:  CSD (M2MB_SECURE_MS_CSD_ACTIVE)
        New level    :  OSD (M2MB_SECURE_MS_OSD_ACTIVE)

M2MB_SECURE_MS_CUSTOMER_FACTORY_RESET
    Allowed only if OSD is the current level.
    All OSD added items are removed. Full Customer's Default items are recovered.
    Microservice System File level remains unchanged:
        OSD <=> OSD
        Current level:  OSD (M2MB_SECURE_MS_OSD_ACTIVE)
        New level    :  unchanged

Parameters

[in]	request	M2MB_SECURE_MS_MANAGE_REQ_E
[out]	state	address of M2MB_SECURE_MS_MANAGE_STATE_E

Returns

M2MB_RESULT_SUCCESS in case of success

M2MB_RESULT_FAIL in case of fail

Note

In case, specific error can be retrieved using m2mb_secure_ms_errno( NULL ).

Example

{
  M2MB_SECURE_MS_MANAGE_STATE_E   ActiveSystemFile = M2MB_SECURE_MS_TSD_ACTIVE;
  M2MB_RESULT_E ret  = M2MB_RESULT_SUCCESS;
 
  ret = m2mb_secure_ms_manage( M2MB_SECURE_MS_GET_STATE, &ActiveSystemFile );
}

m2mb_secure_ms_open()

M2MB_RESULT_E m2mb_secure_ms_open	(	M2MB_SECURE_MS_HANDLE *	handle,
		INT32	file_id,
		UINT16	item_id,
		UINT16	flags
	)

Open the relevant secure data file.

This function creates a Handle and associates it with item in the relative file (file_id). On user space only file_id == M2MB_SYSTEM_FILE_ID is allowed. file_id 0..11 are reserved for eUICC profile. See "Management request option: M2MB_SECURE_MS_MANAGE_REQ_E" Searching of a system item in M2MB_SYSTEM_FILE_ID is performed by looking first on the highest level, therefore first in to OSD(if the level exist), then in the CSD(if the level exist) and then in the TSD. Therefore item_id (of M2MB_SYSTEM_FILE_ID) is searched in the secure Microservice System Files in the following order: OSD, CSD, TSD.

Parameters

[out]	handle	Pointer to a Handle
[in]	file_id	M2MB_SYSTEM_FILE_ID System Data 0..11 eUICC Profile ID (reserved, not available on user space)
[in]	item_id	The ID of the item. See note
[in]	flags	A combination of the following: M2MB_SECURE_MS_READ M2MB_SECURE_MS_WRITE M2MB_SECURE_MS_ADMIN M2MB_SECURE_MS_CREATE The following flags are used only with M2MB_SECURE_MS_CREATE M2MB_SECURE_MS_READ_ONLY M2MB_SECURE_MS_TRUSTED M2MB_SECURE_MS_NO_ENCRYPTION

Returns

M2MB_RESULT_SUCCESS in case of success

M2MB_RESULT_FAIL in case of fail

Note

The specific error can be retrieved using m2mb_secure_ms_errno( NULL ) When called from the AppZone (public area) the M2MB_SECURE_MS_ADMIN flag can be used only for creating\accessing items in M2MB_RAM_FILE_ID, that are the volatile part of the Microservice System File. Some item_id on M2MB_SYSTEM_FILE_ID are reserved for special purposes and their usage can compromise the proper working. Please ask to vendor or Telit for safe item_id to be used. E.g 3,4 are reserved now

Example

int main()
{
    M2MB_SECURE_MS_HANDLE pHandle;
    M2MB_RESULT_E ret  = M2MB_RESULT_SUCCESS;
    UINT8 tempBuff[1];
    UINT32 len;
 
    tempBuff[0] = 0xFF;
    ret = m2mb_secure_ms_open( &pHandle, M2MB_SYSTEM_FILE_ID, 5, M2MB_SECURE_MS_CREATE | M2MB_SECURE_MS_TRUSTED );
 
    if( ret == M2MB_RESULT_SUCCESS )
    {
      ret = m2mb_secure_ms_write( pHandle, tempBuff, len );
    }
 
    ret = m2mb_secure_ms_close( pHandle );
  }
}

m2mb_secure_ms_read()

M2MB_RESULT_E m2mb_secure_ms_read	(	M2MB_SECURE_MS_HANDLE	handle,
		UINT32	max_len,
		UINT8 *	data,
		UINT32 *	act_len
	)

Read a Secured Data item.

This function enables reading an item from the Secure Data. Partial read of saved bytes is not supported. Complete reading of the saved bytes has always to be performed, even of actual data is lesser than the saving btyes (overhead, alignment...)

Parameters

[in]	handle	Secure data file handle
[in]	max_len	The number of the maximum bytes to read that must be a product of 16 big enough to contain all the saved bytes of the item. Actual significant data can be shorter (overhead, alignment...)
[out]	data	Returned data. If specificied pointer is NULL, it represents a request to known the actual data item size
[out]	act_len	The actual data item size Before performing the read, the total number of bytes can be read issuing data=NULL and max_len=0, and then a compliant size buffer provided (multiple of 16). So new read with data pointer can be provided, to get the data

Returns

M2MB_RESULT_SUCCESS in case of success

M2MB_RESULT_FAIL in case of fail

Note

The specific error can be retrieved using m2mb_secure_ms_errno( h ). Providing max_len=0 and data=NULL, actual data byte size is provided. It is an important inofrmation to allocate a buffer of the right size(multiple of 16 bytes) to host the reading data

Example

int main()
{
  M2MB_RESULT_E ret  = M2MB_RESULT_SUCCESS;
  M2MB_SECURE_MS_HANDLE pHandle;
  UINT8 *pData = NULL;
  UINT32 act_len, max_len;
  UINT16 i;
  #define M2MB_ALIGN( x , size )   ( ( ( UINT32 )(x) + size - 1 ) & ( ~( ( UINT32 )size - 1 ) ) )
 
  // in case use M2MB_RAM_FILE_ID instead of M2MB_SYSTEM_FILE_ID
  ret = m2mb_secure_ms_open( &pHandle, M2MB_SYSTEM_FILE_ID, 3, M2MB_SECURE_MS_WRITE | M2MB_SECURE_MS_ADMIN );
  if( ret == M2MB_RESULT_SUCCESS )
  {
    // get the complete byte size of item
    ret = m2mb_secure_ms_read( pHandle, 0, NULL, &act_len );
    // max_len must be a product of 16. select the immediate superior value
    max_len = M2MB_ALIGN( act_len, 16 );
 
    if( ret == M2MB_RESULT_SUCCESS )
    {
      // prepare a buffer with correct size, multiple of 16 which hosts inside actual data
      pData = m2mb_os_malloc(max_len );
      if ( pData != NULL )
      {
        //  max_len >= act_len got before
        ret = m2mb_secure_ms_read( pHandle, max_len, pData, &act_len );
      }
 
      ret = m2mb_secure_ms_close( pHandle );
      if ( pData != NULL )
        m2mb_os_free( pData );
    }
  }
}

m2mb_secure_ms_remove_file()

M2MB_RESULT_E m2mb_secure_ms_remove_file

(

INT32

file_id

)

Deletes the relevant secure data file.

This function deletes a secure data file. Data file (file_id 0..11) are reserved for eUICC Profile and not accessible from user space. Only M2MB_SYSTEM_FILE_ID can be used to remove any items within current Secure Microservice Sytem File level (basically equivalent to M2MB_SECURE_MS_TELIT_FACTORY_RESET or M2MB_SECURE_MS_CUSTOMER_FACTORY_RESET for m2mb_secure_ms_manage API, but automatically performed dependent on the level)

Parameters

[in]

file_id

M2MB_SYSTEM_FILE_ID (perform deletion based on level) or reserved 0..11 (reserved eUICC Profile ID)

Returns

M2MB_RESULT_SUCCESS in case of success

M2MB_RESULT_FAIL in case of fail

M2MB_RESULT_INVALID_ARG in case of not valid input (e.g file_id not M2MB_SYSTEM_FILE_ID in user space)

Note

Only M2MB_SYSTEM_FILE_ID can be used on user space. (file_id from 0..11 are reserved) The specific error can be retrieved using m2mb_secure_ms_errno().

Example

<C code example>

m2mb_secure_ms_write()

M2MB_RESULT_E m2mb_secure_ms_write	(	M2MB_SECURE_MS_HANDLE	handle,
		UINT8 *	data,
		UINT32	len
	)

Writes a Secured Data item.

This function enables writing an item to the Secure Data. If item is saved and then reopened, in order to allow data update, new data must have the same size of the previous saved data, otherwise an error is provided. So only the same size data can be updated. In case, to completely change an item also in size, open it in write mode, delete it and close it making use of m2mb_secure_ms APIs. Then open it again in create mode and write whatever needed.

Parameters

[in]	handle	Secure data file handle
[in]	data	Data (item) to set.
[out]	len	The number of bytes in data. Internally data will be saved as a multiple of 16 but keeping the actual data as specified by len

Returns

M2MB_RESULT_SUCCESS in case of success

M2MB_RESULT_FAIL in case of fail

Note

The specific error can be retrieved using m2mb_secure_ms_errno( h ). Internally data will be saved as a multiple of 16 but keeping the actual data as specified by len

Example

int main()
{
    M2MB_SECURE_MS_HANDLE pHandle;
    M2MB_RESULT_E ret  = M2MB_RESULT_SUCCESS;
    UINT8 tempBuff[1];
    UINT32 len;
 
    tempBuff[0] = 0xFF;
    ret = m2mb_secure_ms_open( &pHandle, M2MB_RAM_FILE_ID, 3, M2MB_SECURE_MS_CREATE | M2MB_SECURE_MS_TRUSTED | M2MB_SECURE_MS_ADMIN );
 
    if( ret == M2MB_RESULT_SUCCESS )
    {
      ret = m2mb_secure_ms_write( pHandle, tempBuff, len );
    }
 
    ret = m2mb_secure_ms_close( pHandle );
  }
}