1Service Locator
2===============
3
4The service locator model provides clients of trusted services with a common interface for locating service instances and
5establishing RPC sessions with service endpoints.  By using the service locator, application code is decoupled from the details
6of where services are deployed.  Use of the service locator is entirely optional for client applications.  Different deployments
7of *libts* provide implementations of the service locator API that are suitable for different environments.  The trusted
8services project uses *libts* to decouple test code from the services under test.  This enables tests to be reused for testing
9on different platforms with different distributions of services.  The same flexibility may be exploited when writing
10applications that use trusted services.
11
12Service Locator Model
13---------------------
14
15The following class diagram illustrates the service locator model:
16
17.. uml:: uml/ServiceLocatorClassDiagram.puml
18
19The model takes inspiration from microservices architectures where there is a similar need to decouple clients from service
20location.  In the model, classes have the following roles:
21
22Class service_locator
23'''''''''''''''''''''
24
25The service_locator is responsible for locating service provider instances and returning a service_context object to allow a
26client to establish RPC sessions with the located service endpoint.  A service instance is requested by a client using a service
27name.  The service name uniquely identifies a service instance, independent of where the service provider is located.  The
28service_locator is a singleton and forms the common interface for locating trusted services.
29
30Class service_context
31'''''''''''''''''''''
32
33A service_context object represents a located service and enables a service client to establish RPC sessions with the service.
34A concrete service_context will provide open and close methods that manage RPC session setup and teardown.
35
36Class rpc_caller
37''''''''''''''''
38
39An rpc_caller provides methods for making remote calls associated with a service endpoint.  An rpc_caller object represents an
40instance of an RPC session.
41
42Locating Service Instances
43--------------------------
44
45The location of service instances is likely to vary between deployments.  Many factors influence where a service instance is
46deployed and the method needed to locate it.  e.g.:
47
48    - The type of processing environment in which a service instance is deployed. e.g. service could be deployed in a secure
49      partition, as a TA or in a secure enclave.
50    - Whether a service instance is co-located with other services instances in the same processing environment or whether a
51      separate environment instance is used per service instance.
52    - For Linux user-space clients, the kernel driver model used for messaging influences how a service is located and the type
53      of messaging interface used for RPC requests.
54
55Because of the wide variability in service deployment options, the Trusted Services framework supports the following:
56
57    - *Location independent service names* - a naming convention for identifying service instances, wherever they are located.
58      By using a location independent service name, a client is decoupled from the actual location of a service instance
59      (similar to a DNS names).  A concrete service locator is responsible for resolving the location independent service name.
60    - *Service location strategies* - to accommodate the likely variability, an extensible framework for alternative service
61      location strategies is provided.
62
63Service Names
64'''''''''''''
65
66Location Independent Service Names
67``````````````````````````````````
68
69Because of the potential variability in where service instances are deployed, a naming convention that allows a service instance
70to be identified, independent of its location, is useful.  By using a location independent service name, coupling between a
71client application and any particular service deployment can be avoided.  Use of the Service Locator API and location
72independent service names allows client applications to be portable across different platforms.
73
74The service instance naming convention uses a URN type string to uniquely identify a particular instance of a class of service.
75To provide extensibility, a naming authority is included in the name.  This allows anyone with a domain name to define their own
76unique service names.  Core service names are defined under the *trustedfirmware.org* authority.  The general structure of a
77service name is as follows::
78
79    urn:sn:<authority>:<service>.<version>:<instance>
80
81    The 'urn' prefix should be dropped when service names are used in context.
82    The version field is optional.
83
84The naming convention includes a version number, separated from the <service> field by a '.' character. Beyond the '.', any
85version numbering scheme may be used.  This will potentially be useful for delegating version compatibility decisions to a
86service locator.  It is preferable for a client to specify a service name that includes a version number as this will
87potentially allow a service locator to:
88
89    - Locate a compatible service instance.  For example, a service provider may expose multiple RPC call endpoints to handle
90      different protocol versions.  A service locator may resolve the name to the compatible RPC endpoint, based on the version
91      string requested by the client.
92    - Fail gracefully if no compatible version is found.
93
94Some example service names::
95
96    sn:trustedfirmware.org:crypto.1.0.4:0
97    sn:trustedfirmware.org:secure-storage.1.3.11:1
98    sn:trustedfirmware.org:tpm.2.0:0
99
100Location Specific Service Names
101```````````````````````````````
102
103To enable a client to be able to specify location specific service names, it should also be possible to use names that express a
104location specific identifier such as a partition UUID.  While use of location specific services names creates a coupling between
105the client and details of the service deployment, their use may be important in the following cases:
106
107    - Where there is no well-known mapping between a location independent service name and a location specific identifier.
108    - Where the client needs to be specific e.g. for tests that target a specific service deployment.
109
110Location specific service names use the same structure as location independent services names but with a technology specific
111authority field.  The following is an example of a service name that identifies a service instance that is deployed in a secure
112partition::
113
114    sn:ffa:d9df52d5-16a2-4bb2-9aa4-d26d3b84e8c0:0
115
116    The instance field qualified a particular SP instance from the discovered set.
117
118Service Location Strategies
119'''''''''''''''''''''''''''
120
121The method used by the service locator to resolve a service name to a service instance will depend on the environment in which a
122client is running and where service instances are located.  Services will need to be located by any client of a trusted service.
123There are typically two classes of trusted service client:
124
125    - A user-space application.
126    - Another trusted service, running in a secure processing environment.
127
128Different methods for locating service instances in different environments are illustrated in the following examples:
129
130Locating a Service from Linux User-space
131````````````````````````````````````````
132
133Depending on the kernel driver model used, the example methods for locating service instances from Linux user-space are:
134
135    1. Service instances are represented by device nodes e.g. /dev/tpm0.  The service locator will simply map the <service>
136       portion of the services name to the base device name and the <instance> to the device node instance.
137    2. A service instance is hosted by a TEE as a TA.  The TEE will provide a discovery mechanism that will allow a TA type and
138       instance to be identified.  The service locator will need to map the service name to the TEE specific naming scheme.
139    3. A special device that provides messaging provides a method for discovery. e.g. an FF-A driver supports partition
140       discovery.
141    4. A device is used for remote messaging to a separate microcontroller.  There is a well-known protocol for endpoint
142       discovery using the messaging layer.
143
144Locating a Service from another Trusted Service
145```````````````````````````````````````````````
146
147Where a trusted service uses another trusted service, it is likely that both service instances will be running in the same
148security domain e.g. both running in secure partitions within the secure world.  Where a single service instance is deployed per
149secure partition, the client service will use the following strategy to locate the service provider:
150
151    1. The service name is mapped to the well known UUID for the class of SP that hosts the service provider.
152    2. FF-A partition discovery is used to find all SPs that match the requested UUID.
153    3. The service instance portion of the service name is used to match the partition ID when selecting the target SP from the
154       list of discovered SPs.
155
156Extending the Service Locator Model
157```````````````````````````````````
158
159To accommodate the need to support alternative location strategies, the Service Locator model can be extended to use a set of
160concrete strategy objects to implement different methods of locating a service instance.  The set of strategies used will be
161different for different client environments.  The following class diagram illustrates how the model can be extended.
162
163.. uml:: uml/ServiceLocationStrategyClassDiagram.puml
164
165--------------
166
167*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
168
169SPDX-License-Identifier: BSD-3-Clause
170