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