1##########################################
2Stateless Root of Trust Services Reference
3##########################################
4
5:Author: Mingyang Sun
6:Organization: Arm Limited
7:Contact: mingyang.sun@arm.com
8
9
10************
11Introduction
12************
13
14This document describes the implementation for the FF-M v1.1 feature -
15'Stateless RoT Service', and the related references when developing RoT
16services.
17
18It is recommended to refer to the FF-M v1.0 specification [1]_ and FF-M v1.1
19extension [2]_ for background and rationale details.
20
21
22**********************
23Implementation Details
24**********************
25
26This chapter describes the implementation-defined items, including stateless
27handle value definition, tooling update, and programming API changes.
28
29Stateless Handle Value Definition
30=================================
31
32The index, stateless indicator, and service version information are encoded into
33a handle by the manifest tooling, and then generated to header file ``sid.h``.
34
35.. list-table:: Bit Fields of Stateless Handle
36    :header-rows: 1
37    :widths: 20 80
38
39    * - Bits
40      - Field Description
41    * - bit 31
42      - reserved
43    * - bit 30
44      - stateless handle indicator bit, always 1
45    * - bit 29 - bit 16
46      - reserved
47    * - bit 15 - bit 8
48      - service version requested by client - for client version check
49    * - bit 7 - bit 5
50      - reserved
51    * - bit 4 - bit 0
52      - the handle index, [0, 31]
53
54Since connection-based services and stateless services share the same PSA API
55``psa_call()``, an indicator bit is set in the handle indicate the type of the
56handle. If it is set, the handle is stateless, and definition is as described
57in the table above. Maximum connection-based handle is 0x3FFFFFFF, thus the
58indicator bit is always 0.
59
60The index is used for organizing stateless services in manifest tool and
61locating a stateless service in SPM logic. A range of index [0, 31] is the
62initial implementation. Future expansion is possible.
63
64Tooling Support
65===============
66
67TF-M provides a tool (``tools/tfm_parse_manifest_list.py``) to generate source
68header files required by partition and services. For example, the generated
69``sid.h`` contains service ID and version. The tooling is extended to generate
70stateless handle from partition manifests automatically.
71
72The ``stateless_handle`` attribute in manifest is only supported by partitions
73with firmware framework version 1.1.
74
75- If ``stateless_handle`` in manifest is set to an integer, the index is
76  ``stateless_handle - 1``.
77- If it is ``auto`` or not set, the first empty index in range [0, 31] is
78  assigned.
79- Other settings - tooling reports an error.
80
81Finally, the tooling encodes the handle according to definitions in
82`Stateless Handle Value Definition`_ section, and writes them to ``sid.h``
83header file.
84
85Changes in Programming API
86==========================
87
88This chapter describes the changes in programming API for stateless services.
89The following APIs' behavious and message data structure members are updated to
90support the stateless service.
91
92psa_connect()
93-------------
94
95According to FF-M v1.1, client calling ``psa_connect()`` with the SID of a
96stateless RoT Service is a ``PROGRAMMER_ERROR``.
97
98psa_close()
99-----------
100
101According to FF-M v1.1, client passing a stateless handle to call this API is a
102``PROGRAMMER_ERROR``.
103
104psa_call()
105----------
106
107.. code-block:: c
108
109    psa_status_t psa_call(psa_handle_t handle, int32_t type,
110                          const psa_invec *in_vec, size_t in_len,
111                          psa_outvec *out_vec, size_t out_len)
112
113API parameters and behaviour change:
114
1151. The ``handle`` parameter must be a stateless handle defined in
116   ``psa_manifest/sid.h`` when requesting a stateless service.
1172. This API validates stateless handle, decodes index and service version
118   information from it. SPM uses the index to know which stateless service is
119   requested.
1203. This API performs some operations as ``psa_connect()`` does, such as the
121   authorization check, service and client version check, and handle space
122   allocation.
123
124Service behaviour change during a "psa_call":
125
126Service does not accept connection and disconnection messages. After a
127"psa_call" request is serviced, it calls ``psa_reply()``, frees the connection
128handle to handle pool.
129
130psa_set_rhandle()
131-----------------
132
133According to FF-M v1.1, stateless service calling this API on a message is a
134``PROGRAMMER_ERROR`` and it will never return.
135
136psa_msg_t type
137--------------
138
139The ``rhandle`` member of a ``psa_msg_t`` type received by a stateless RoT
140Service is always ``NULL``.
141
142
143**************************
144Application Recommendation
145**************************
146
147There are particular services that do not need sessions. The access to the
148service is a one-shot connection. These services provide standalone operations
149that do not require any non-volatile state of resources to be maintained by the
150RoT service itself or do not expose any kind of context or session to the
151caller. Such services are recommended to be implemented as stateless, to provide
152quick access and to avoid extra overheads.
153
154In this case, ``rhandle`` access would be prohibited as it is used for saving
155state or non-volatile resources while stateless services do not need them.
156
157Update Feasibility of Existing Services
158=======================================
159
160TF-M native services are used widely. They only need standalone operations and
161do not need to keep state between sessions. For example, the service in Crypto
162partition does not do anything during ``psa_connect()`` or ``psa_close()``
163process. Same for services in other partitions, thus all of them can be
164implemented as stateless.
165
166Analysis for them:
167
168.. list-table:: TF-M Partition Services Update Possibility
169    :header-rows: 1
170    :widths: 30 30 40
171
172    * - Partition
173      - Number of Services
174      - Can be Stateless
175    * - ITS
176      - 4
177      - All
178    * - PS
179      - 5
180      - All
181    * - Crypto
182      - 1
183      - All
184    * - FWU
185      - 6
186      - All
187    * - Platform
188      - 4
189      - All
190    * - Initial Attestation
191      - 2
192      - All
193
194Other services are not analyzed here.
195
196Grouping Services
197=================
198
199Stateless service table is stored statically, and TF-M supports 32 stateless
200services currently.
201
202Similar stateless services in a partition could be grouped, and assign one
203``SID`` for the group. The ``type`` parameter in ``psa_call()`` could be
204extended to identify the service in group. In this case, it is recommended to
205use consecutive values for ``type``.
206
207It is recommended that each Secure Partition declares one stateless service
208and uses the type parameter to distinguish different stateless services.
209Therefore, more stateless services can be supported.
210
211Migrating to Stateless Services
212===============================
213
214Please refer to Chapter 4 "Stateless Root of Trust services", Appendix B.3.2
215"Using a stateless RoT Service", and Appendix D "Implementing session-less RoT
216Services" in FF-M v1.1 document for details on which kind of service can be
217stateless and how to implement a stateless service.
218
219
220*********
221Reference
222*********
223
224.. [1] `FF-M v1.0 Specification <https://developer.arm.com/documentation/den0063/latest/>`__
225
226.. [2] `FF-M v1.1 Extension <https://developer.arm.com/documentation/aes0039/latest/>`__
227
228--------------
229
230*Copyright (c) 2021-2024, Arm Limited. All rights reserved.*
231