diff options
Diffstat (limited to 'docs/technical_references/tfm_non_secure_client_management.rst')
-rw-r--r-- | docs/technical_references/tfm_non_secure_client_management.rst | 388 |
1 files changed, 0 insertions, 388 deletions
diff --git a/docs/technical_references/tfm_non_secure_client_management.rst b/docs/technical_references/tfm_non_secure_client_management.rst deleted file mode 100644 index 970550aa49..0000000000 --- a/docs/technical_references/tfm_non_secure_client_management.rst +++ /dev/null @@ -1,388 +0,0 @@ -############################ -Non-secure Client Management -############################ - -:Author: Miklos Balint -:Organization: Arm Limited -:Contact: Miklos Balint <miklos.balint@arm.com> -:Status: Accepted - -*********** -Terminology -*********** - -**Secure service call**: request to a secure partition by a secure or non-secure -client thread - -**Secure function call**: any function call from NSPE to SPE - -**TrustZone (TZ) API**: the set of functions defined by CMSIS for RTOS secure -context management - -**Client ID**: the identifier defining a single entity within the system, -determining its access policies for any given secure assets - -************************* -Assumptions, restrictions -************************* - -This design considers as its baseline the current operation of TF-M: an -operating mode where at any given time only a single non-secure access is -permitted to call a secure service. - -If a non-secure RTOS/bare-metal application does not use the API calls defined -in this design, that non-secure application is still able to use secure services -using a single, default non-secure client context. That remains a supported use -case and use of this API is optional and is only needed if multiple access -policies and/or concurrent secure contexts initiated by non-secure threads are -required. - -Investigation is ongoing to address the option of enabling multiple concurrent -calls by non-secure threads without the use of the context management API below. - -****** -Issues -****** - -The topics being discussed in this document: - -- NS client/thread awareness in TF-M Core -- "Known client" list - -Improvements, alternatives, investigations - -- Concurrent secure service requests -- NS to S priority inheritance -- NS privilege to be derived from CONTROL_NS register - -************** -Design details -************** - -NS thread awareness in TF-M Core -================================ - -Description ------------ - -TrustZone context management API defines a set of secure function calls from NS -RTOS handler mode to TF-M Core to get notification of context switch. - -While CMSIS context management can be used to directly expose secure context -management to the non-secure OS, TF-M has a proprietary implementation: the -context management API is used to get notification of NS context switches and -to track various non-secure clients. - -.. _`API definition`: - -API definition --------------- - -TZ_MemoryId_t data type -^^^^^^^^^^^^^^^^^^^^^^^ - -TZ Memory ID identifies an allocated memory slot. - -TF-M usage -"""""""""" - -``TZ_MemoryId_t`` is used for an index into an array containing active NS client -IDs. The memory ID is required by CMSIS to be a positive integer, so it is -mapped to the array index by being decremented by 1. - -Signature -""""""""" - -.. code-block:: c - - typedef uint32_t TZ_MemoryId_t; - -Context management initialization: TZ_InitContextSystem_S -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Initialize secure context memory system. - -Return value -"""""""""""" - -This function returns execution status: 1 for success, 0 for error. - -TF-M usage -"""""""""" - -This function call is used to identify a non-secure RTOS that has TZ context -management capabilities, as this function is expected to be called before any -other TZ API function is used. - -Signature -"""""""""" - -.. code-block:: c - - uint32_t TZ_InitContextSystem_S (void); - -Context allocation: TZ_AllocModuleContext_S -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Allocate context memory for calling secure software modules in TrustZone. - -Parameters -"""""""""" - -``module`` [input]: identifies software modules called from non-secure mode - -Return value -"""""""""""" - -``value != 0`` TrustZone memory slot identifier -``value == 0`` no memory available or internal error - -TF-M usage -"""""""""" - -This function is used to identify a new non-secure thread that may be identified -as a client in the non-secure domain. The ``module`` parameter is unused. The -returned ``TZ_MemoryId_t`` value is the index in the ``NsClientIdList`` array -where the client ID for the newly allocated context is stored. - -Signature -""""""""" - -.. code-block:: c - - TZ_MemoryId_t TZ_AllocModuleContext_S (TZ_ModuleId_t module); - -Context freeing: TZ_FreeModuleContext_S -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Free context memory that was previously allocated with TZ_AllocModuleContext_S - -Parameters -"""""""""" - -``id`` [input]: TrustZone memory slot identifier - -Return value -"""""""""""" - -Execution status (1: success, 0: error) - -TF-M usage -"""""""""" - -This function indicates that a non-secure client is inactive, meaning that any -subsequent references to the client ID are considered erroneous. In effect, the -client ID indexed by ``(id – 1)`` is cleared and the memory slot flagged as -free. - -Signature -""""""""" - -.. code-block:: c - - uint32_t TZ_FreeModuleContext_S (TZ_MemoryId_t id); - -Context activation: TZ_LoadContext_S -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Load secure context (called on RTOS thread context switch) - -Parameters -"""""""""" - -``id`` [input]: TrustZone memory slot identifier - -Return value -"""""""""""" - -Execution status (1: success, 0: error) - -TF-M usage -"""""""""" - -The client ID indexed by ``(id – 1)`` becomes the active NS client. Any -subsequent secure service requests coming from non-secure domain will be -associated with this client ID. - -Signature -""""""""" - -.. code-block:: c - - uint32_t TZ_LoadContext_S (TZ_MemoryId_t id); - -Context deactivation: TZ_StoreContext_S -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Store secure context (called on RTOS thread context switch) - -Parameters -"""""""""" - -``id`` [input]: TrustZone memory slot identifier - -Return value -"""""""""""" - -Execution status (1: success, 0: error) - -TF-M usage -"""""""""" - -The client ID indexed by ``(id – 1)`` becomes inactive. Any subsequent secure -service requests coming from non-secure domain will be invalid until a new NS -context is loaded. - -Signature -""""""""" - -.. code-block:: c - - uint32_t TZ_StoreContext_S (TZ_MemoryId_t id); - -Security implications (to be assessed separately if needed) ------------------------------------------------------------ - -If NS RTOS / NS handler mode is compromised, NS clients’ data can be disclosed -to unauthorised non-secure actors, as it’s not in the scope of TF-M to guarantee -non-secure client isolation. Support for this API is only an enabler for a -non-secure RTOS feature. - -Vulnerabilities of the NS handler mode cannot and will not lead to disclosure of -assets owned by secure entities to non-secure actors after the introduction of -this feature as a malicious NS handler can only ever assume the identity of -another non-secure client and cannot elevate its access privileges to those of -secure clients. - -Known client list -================= - -Description ------------ - -A different – but related – API to that defined by CMSIS is proposed in this -design to register a specific client ID to the active non-secure thread. - -The purpose of this API is to provide non-secure privileged code with the -ability to associate the active non-secure context with a pre-defined identity. -This enables the application of a pre-set access policy on the secure side to be -applied to the non-secure thread. - -Use cases ---------- - -It is valid for non-secure privileged code to only support the TF-M-specific API -defined below and not the CMSIS TZ API defined previously. In this case the -single non-secure client is still able to access resources based on a -pre-defined access policy in secure services without relying on the default -non-secure identity configured in TF-M. - -If used in conjunction with the TZ API, this function can provide a means to -assign and identify multiple non-secure client IDs based on the active context, -overriding TF-M’s default non-secure client identity assignment policy. - -API definition --------------- - -NS RTOS client registration API – secure function calls from NS handler mode to -TF-M Core to associate a “known” Client ID to the active non-secure thread. - -Register specific client ID: ``tfm_register_client_id`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Assign client ID to the current TZ context. - -**Note**: This function must be called from handler mode so that TF-M can verify -that it was sent by a privileged entity. - -This function call must follow all TZ_AllocModuleContext_S function calls to -override the default NS client IDs allocated by TF-M. - -Secure and non-secure client IDs are allocated from different ranges (negative -IDs for non-secure clients, positive for secure clients). The function call is -rejected if called with a secure ID. - -Parameters -"""""""""" - -``ns_client_id`` [input]: The client ID to be assigned to the current context - -Return value -"""""""""""" - -``TFM_SUCCESS`` (0) if the client ID assigned successfully, a non-zero error -code in case of error. - -Signature -""""""""" - -.. code-block:: c - - enum tfm_status_e tfm_register_client_id (int32_t ns_client_id); - -******************** -Implementation notes -******************** - -Option to reduce required context switch notifications -====================================================== - -According to TrustZone API definition ``TZ_StoreContext_S()`` is to be called -"at thread context switch after running a thread" and ``TZ_LoadContext_S`` "at -thread context switch before running a thread". The API definition does not -define the course of action to be taken if two ``TZ_LoadContext_S()`` calls are -made without an interleaving StoreContext. - -The proposal for TF-M is to accept this as a valid scenario where the second -``TZ_LoadContext_S()`` call is taken to imply a ``TZ_StoreContext_S()`` with -the previous active Memory_Id. - -This assumption does not alter the intended use of ``TZ_StoreContext_S()``, -which remains a valid call with the behaviour as defined in the -`API definition`_ section above. - -****************************************** -Investigations, improvements, alternatives -****************************************** - -Concurrent secure service requests -================================== - -If there are concurrent services requests, TF-M needs to identify the client for -each request and should make their corresponding context available in the secure -domain. Client ID needs to be associated with the secure service request so that -a NS context switch does not break client identification. - -If a non-secure client is blocked on an asynchronous secure service completion, -the NS TFM library must provide a semaphore the NS thread can wait on, whereby -NS RTOS can schedule a different context. - -Should a secure service completion happen for an inactive NS context, a -notification mechanism needs to be created to activate the given NS context. - -The proposal is for the NS TFM library to include a NS IRQ handler for a -reserved interrupt signal. The ISR would identify the context to be activated -and release the corresponding semaphore. - -NS to S priority inheritance -============================ - -Whether or not NS thread priorities should be influencing secure service -prioritization needs to be analysed. It is raised as a topic of discussion and -is not detailed in this document further at this stage. - -NS privilege check for secure function calls -============================================ - -Non-secure privilege can be derived from CONTROL_NS instead of requiring NS to -call context management veneers in handler mode. This can be a more generic -approach, but implications are to be investigated. - -********** -References -********** - -Description of the TZ API: -https://www.keil.com/pack/doc/CMSIS/Core/html/group__context__trustzone__functions.html - -*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
\ No newline at end of file |