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_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_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. 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. 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.

Note

Dependencies: m2mb_types.h

Author

Ian Levine

Date

12/09/2017

Macro Definition Documentation

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

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 system file.

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_UNKNOWN	65535: Unknown error

M2MB_SECURE_MS_MANAGE_REQ_E

enum M2MB_SECURE_MS_MANAGE_REQ_E

Management request option.

Enumerator
M2MB_SECURE_MS_GET_STATE	Return the state of the SDA
M2MB_SECURE_MS_LOCK_TSD	Lock the TSD - No more items can be added to it
M2MB_SECURE_MS_TELIT_FACTORY_RESET	Remove the CSD and OSD - return to Telit's defaults as defined in TSD
M2MB_SECURE_MS_LOCK_CSD	Lock the CSD - No more items can be added to it
M2MB_SECURE_MS_CUSTOMER_FACTORY_RESET	Remove the OSD - return to Customer's defaults as defined in CSD

M2MB_SECURE_MS_MANAGE_STATE_E

enum M2MB_SECURE_MS_MANAGE_STATE_E

The state of the Secure Storage.

Enumerator
M2MB_SECURE_MS_TSD_ACTIVE	The CSD & OSD don't exist, TSD isn't locked
M2MB_SECURE_MS_CSD_ACTIVE	The OSD doesn't exist, TSD is locked
M2MB_SECURE_MS_OSD_ACTIVE	Both TSD & CSD are locked

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 deletes the secure data file handle.

Parameters

[in]

handle

Secure data file handle

Returns

M2MB_RESULT_FAIL M2MB_RESULT_SUCCESS

Note

The specific error can be retrieved using m2mb_secure_ms_errno().

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, 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 );
  }
}

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 this item will also be created with the M2MB_SECURE_MS_TRUSTED flag.

Parameters

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

Returns

M2MB_RESULT_FAIL - Error or data doesn't match M2MB_RESULT_SUCCESS - Data match.

Note

The specific error can be retrieved using m2mb_secure_ms_errno().

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 with M2MB_SECURE_MS_ADMIN as an option flag. A READ_ONLY file cannot be deleted.

Parameters

[in]

handle

Secure data file handle

Returns

M2MB_RESULT_FAIL M2MB_RESULT_SUCCESS

Note

The specific error can be retrieved using m2mb_secure_ms_errno().

Example

int main()
{
  M2MB_RESULT_E ret  = M2MB_RESULT_SUCCESS;
  M2MB_SECURE_MS_HANDLE pHandle;
  
  ret = m2mb_secure_ms_open( &pHandle, M2MB_SYSTEM_FILE_ID, 3, M2MB_SECURE_MS_WRITE | M2MB_SECURE_MS_ADMIN );
  if( ret == M2MB_RESULT_SUCCESS )
  {
    ret = m2mb_secure_ms_delete( pHandle );
    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

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.

Returns

M2MB_RESULT_FAIL M2MB_RESULT_SUCCESS

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 System Files:

1. TSD - Telit Secure Data that contains Telit's default values as they are set during manufacturing.
2. CSD - Customer's Secure Data that contains the Customer's default values as they are set during manufacturing.
3. OSD - Operational Secure Storage that contains data that is 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 in m2mb_secure_ms_open, the search for an item is done first in the OSD, then in the CSD and at last in the TSD.

The effect of the request parameter is on the identity of the system file (M2MB_SYSTEM_FILE_ID) as following:

M2MB_SECURE_MS_LOCK_TSD
    From now on, no data can be added to the TSD.
    This causes the following State change:
        M2MB_SYSTEM_FILE_ID --> CSD.
        M2MB_SECURE_MS_TSD_ACTIVE --> M2MB_SECURE_MS_CSD_ACTIVE.

M2MB_SECURE_MS_TELIT_FACTORY_RESET
    This will remove both the OSD and the CSD files.
    Note that the USD files are not deleted.
    This causes the following State change:
        M2MB_SYSTEM_FILE_ID --> TSD.
        M2MB_SECURE_MS_CSD_ACTIVE/M2MB_SECURE_MS_OSD_ACTIVE --> M2MB_SECURE_MS_TSD_ACTIVE.

M2MB_SECURE_MS_LOCK_CSD
    From now on, no data can be added to the CSD.
    This causes the following State change:
        M2MB_SYSTEM_FILE_ID --> OSD.
        M2MB_SECURE_MS_CSD_ACTIVE --> M2MB_SECURE_MS_OSD_ACTIVE.

M2MB_SECURE_MS_CUSTOMER_FACTORY_RESET
    This will remove the OSD file.
    Note that the USD files are not deleted.
    This causes the following State change:
        M2MB_SYSTEM_FILE_ID --> OSD.
        M2MB_SECURE_MS_OSD_ACTIVE --> M2MB_SECURE_MS_CSD_ACTIVE.

Parameters

[in]	request	M2MB_SECURE_MS_MANAGE_REQ_E
[out]	state	M2MB_SECURE_MS_MANAGE_REQ_E

Returns

M2MB_RESULT_FAIL M2MB_SECURE_MS_MANAGE_STATE_E

Note

The specific error can be retrieved using m2mb_secure_ms_errno().

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 the relevant item in the relevant file. If file_id == M2MB_SYSTEM_FILE_ID then The item_id will be searched for in the 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
[in]	item_id	The ID of the item.
[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_FAIL M2MB_RESULT_SUCCESS

Note

The specific error can be retrieved using m2mb_secure_ms_errno. When called from the AppZone (public area) the M2MB_SECURE_MS_ADMIN flag can be used only for creating new items (M2MB_SECURE_MS_CREATE). Once the item is created, it can't be accessed anymore from the AppZone. 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, 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 );
  }
}

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 is not supported - always have to read all the data.

Parameters

[in]	handle	Secure data file handle
[in]	max_len	The number of the maximum bytes to read. This should be a product of 16 and big enough to contain all the item's data.
[out]	data	Returned data.
[out]	act_len	The actual number of bytes returned.

Returns

M2MB_RESULT_FAIL M2MB_RESULT_SUCCESS

Note

The specific error can be retrieved using m2mb_secure_ms_errno().

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 ) ) )
 
  ret = m2mb_secure_ms_open( &pHandle, M2MB_SYSTEM_FILE_ID, 3, M2MB_SECURE_MS_WRITE | M2MB_SECURE_MS_ADMIN );
  if( ret == M2MB_RESULT_SUCCESS )
  {
    ret = m2mb_secure_ms_read( pHandle, 0, NULL, &act_len );
 
    max_len = M2MB_ALIGN( act_len, 16 );
 
    if( ret == M2MB_RESULT_SUCCESS )
    {
      pData = m2mb_os_malloc(max_len );
      if ( pData != NULL )
      {
        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.

Parameters

[in]

file_id

0..11 eUICC Profile ID

Returns

M2MB_RESULT_FAIL M2MB_RESULT_SUCCESS

Note

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.

Parameters

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

Returns

M2MB_RESULT_FAIL M2MB_RESULT_SUCCESS

Note

The specific error can be retrieved using m2mb_secure_ms_errno().

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, 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 );
  }
}