docs/developer/service-locator.rst - TS/trusted-services - TrustedFirmware Git Browser

 Service Locator
 ===============

 The service locator model provides clients of trusted services with a common interface for locating service instances and
 establishing RPC sessions with service endpoints.  By using the service locator, application code is decoupled from the details
 of where services are deployed.  Use of the service locator is entirely optional for client applications.  Different deployments
 of *libts* provide implementations of the service locator API that are suitable for different environments.  The trusted
 services project uses *libts* to decouple test code from the services under test.  This enables tests to be reused for testing
 on different platforms with different distributions of services.  The same flexibility may be exploited when writing
 applications that use trusted services.

 Service Locator Model
 ---------------------

 The following class diagram illustrates the service locator model:

 .. uml:: uml/ServiceLocatorClassDiagram.puml

 The model takes inspiration from microservices architectures where there is a similar need to decouple clients from service
 location.  In the model, classes have the following roles:

 Class service_locator
 '''''''''''''''''''''

 The service_locator is responsible for locating service provider instances and returning a service_context object to allow a
 client to establish RPC sessions with the located service endpoint.  A service instance is requested by a client using a service
 name.  The service name uniquely identifies a service instance, independent of where the service provider is located.  The
 service_locator is a singleton and forms the common interface for locating trusted services.

 Class service_context
 '''''''''''''''''''''

 A service_context object represents a located service and enables a service client to establish RPC sessions with the service.
 A concrete service_context will provide open and close methods that manage RPC session setup and teardown.

 Class rpc_caller
 ''''''''''''''''

 An rpc_caller provides methods for making remote calls associated with a service endpoint.  An rpc_caller object represents an
 instance of an RPC session.

 Locating Service Instances
 --------------------------

 The location of service instances is likely to vary between deployments.  Many factors influence where a service instance is
 deployed and the method needed to locate it.  e.g.:

     - The type of processing environment in which a service instance is deployed. e.g. service could be deployed in a secure
       partition, as a TA or in a secure enclave.
     - Whether a service instance is co-located with other services instances in the same processing environment or whether a
       separate environment instance is used per service instance.
     - For Linux user-space clients, the kernel driver model used for messaging influences how a service is located and the type
       of messaging interface used for RPC requests.

 Because of the wide variability in service deployment options, the Trusted Services framework supports the following:

     - *Location independent service names* - a naming convention for identifying service instances, wherever they are located.
       By using a location independent service name, a client is decoupled from the actual location of a service instance
       (similar to a DNS names).  A concrete service locator is responsible for resolving the location independent service name.
     - *Service location strategies* - to accommodate the likely variability, an extensible framework for alternative service
       location strategies is provided.

 Service Names
 '''''''''''''

 Location Independent Service Names
 ``````````````````````````````````

 Because of the potential variability in where service instances are deployed, a naming convention that allows a service instance
 to be identified, independent of its location, is useful.  By using a location independent service name, coupling between a
 client application and any particular service deployment can be avoided.  Use of the Service Locator API and location
 independent service names allows client applications to be portable across different platforms.

 The service instance naming convention uses a URN type string to uniquely identify a particular instance of a class of service.
 To provide extensibility, a naming authority is included in the name.  This allows anyone with a domain name to define their own
 unique service names.  Core service names are defined under the *trustedfirmware.org* authority.  The general structure of a
 service name is as follows::

     urn:sn:<authority>:<service>.<version>:<instance>

     The 'urn' prefix should be dropped when service names are used in context.
     The version field is optional.

 The naming convention includes a version number, separated from the <service> field by a '.' character. Beyond the '.', any
 version numbering scheme may be used.  This will potentially be useful for delegating version compatibility decisions to a
 service locator.  It is preferable for a client to specify a service name that includes a version number as this will
 potentially allow a service locator to:

     - Locate a compatible service instance.  For example, a service provider may expose multiple RPC call endpoints to handle
       different protocol versions.  A service locator may resolve the name to the compatible RPC endpoint, based on the version
       string requested by the client.
     - Fail gracefully if no compatible version is found.

 Some example service names::

     sn:trustedfirmware.org:crypto.1.0.4:0
     sn:trustedfirmware.org:secure-storage.1.3.11:1
     sn:trustedfirmware.org:tpm.2.0:0

 Location Specific Service Names
 ```````````````````````````````

 To enable a client to be able to specify location specific service names, it should also be possible to use names that express a
 location specific identifier such as a partition UUID.  While use of location specific services names creates a coupling between
 the client and details of the service deployment, their use may be important in the following cases:

     - Where there is no well-known mapping between a location independent service name and a location specific identifier.
     - Where the client needs to be specific e.g. for tests that target a specific service deployment.

 Location specific service names use the same structure as location independent services names but with a technology specific
 authority field.  The following is an example of a service name that identifies a service instance that is deployed in a secure
 partition::

     sn:ffa:d9df52d5-16a2-4bb2-9aa4-d26d3b84e8c0:0

     The instance field qualified a particular SP instance from the discovered set.

 Service Location Strategies
 '''''''''''''''''''''''''''

 The method used by the service locator to resolve a service name to a service instance will depend on the environment in which a
 client is running and where service instances are located.  Services will need to be located by any client of a trusted service.
 There are typically two classes of trusted service client:

     - A user-space application.
     - Another trusted service, running in a secure processing environment.

 Different methods for locating service instances in different environments are illustrated in the following examples:

 Locating a Service from Linux User-space
 ````````````````````````````````````````

 Depending on the kernel driver model used, the example methods for locating service instances from Linux user-space are:

     1. Service instances are represented by device nodes e.g. /dev/tpm0.  The service locator will simply map the <service>
        portion of the services name to the base device name and the <instance> to the device node instance.
     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
        instance to be identified.  The service locator will need to map the service name to the TEE specific naming scheme.
     3. A special device that provides messaging provides a method for discovery. e.g. an FF-A driver supports partition
        discovery.
     4. A device is used for remote messaging to a separate microcontroller.  There is a well-known protocol for endpoint
        discovery using the messaging layer.

 Locating a Service from another Trusted Service
 ```````````````````````````````````````````````

 Where a trusted service uses another trusted service, it is likely that both service instances will be running in the same
 security domain e.g. both running in secure partitions within the secure world.  Where a single service instance is deployed per
 secure partition, the client service will use the following strategy to locate the service provider:

     1. The service name is mapped to the well known UUID for the class of SP that hosts the service provider.
     2. FF-A partition discovery is used to find all SPs that match the requested UUID.
     3. The service instance portion of the service name is used to match the partition ID when selecting the target SP from the
        list of discovered SPs.

 Extending the Service Locator Model
 ```````````````````````````````````

 To accommodate the need to support alternative location strategies, the Service Locator model can be extended to use a set of
 concrete strategy objects to implement different methods of locating a service instance.  The set of strategies used will be
 different for different client environments.  The following class diagram illustrates how the model can be extended.

 .. uml:: uml/ServiceLocationStrategyClassDiagram.puml

 --------------

 *Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*

 SPDX-License-Identifier: BSD-3-Clause
	Service Locator
	===============

	The service locator model provides clients of trusted services with a common interface for locating service instances and
	establishing RPC sessions with service endpoints. By using the service locator, application code is decoupled from the details
	of where services are deployed. Use of the service locator is entirely optional for client applications. Different deployments
	of libts provide implementations of the service locator API that are suitable for different environments. The trusted
	services project uses libts to decouple test code from the services under test. This enables tests to be reused for testing
	on different platforms with different distributions of services. The same flexibility may be exploited when writing
	applications that use trusted services.

	Service Locator Model
	---------------------

	The following class diagram illustrates the service locator model:

	.. uml:: uml/ServiceLocatorClassDiagram.puml

	The model takes inspiration from microservices architectures where there is a similar need to decouple clients from service
	location. In the model, classes have the following roles:

	Class service_locator
	'''''''''''''''''''''

	The service_locator is responsible for locating service provider instances and returning a service_context object to allow a
	client to establish RPC sessions with the located service endpoint. A service instance is requested by a client using a service
	name. The service name uniquely identifies a service instance, independent of where the service provider is located. The
	service_locator is a singleton and forms the common interface for locating trusted services.

	Class service_context
	'''''''''''''''''''''

	A service_context object represents a located service and enables a service client to establish RPC sessions with the service.
	A concrete service_context will provide open and close methods that manage RPC session setup and teardown.

	Class rpc_caller
	''''''''''''''''

	An rpc_caller provides methods for making remote calls associated with a service endpoint. An rpc_caller object represents an
	instance of an RPC session.

	Locating Service Instances
	--------------------------

	The location of service instances is likely to vary between deployments. Many factors influence where a service instance is
	deployed and the method needed to locate it. e.g.:

	- The type of processing environment in which a service instance is deployed. e.g. service could be deployed in a secure
	partition, as a TA or in a secure enclave.
	- Whether a service instance is co-located with other services instances in the same processing environment or whether a
	separate environment instance is used per service instance.
	- For Linux user-space clients, the kernel driver model used for messaging influences how a service is located and the type
	of messaging interface used for RPC requests.

	Because of the wide variability in service deployment options, the Trusted Services framework supports the following:

	- Location independent service names - a naming convention for identifying service instances, wherever they are located.
	By using a location independent service name, a client is decoupled from the actual location of a service instance
	(similar to a DNS names). A concrete service locator is responsible for resolving the location independent service name.
	- Service location strategies - to accommodate the likely variability, an extensible framework for alternative service
	location strategies is provided.

	Service Names
	'''''''''''''

	Location Independent Service Names
	``````````````````````````````````

	Because of the potential variability in where service instances are deployed, a naming convention that allows a service instance
	to be identified, independent of its location, is useful. By using a location independent service name, coupling between a
	client application and any particular service deployment can be avoided. Use of the Service Locator API and location
	independent service names allows client applications to be portable across different platforms.

	The service instance naming convention uses a URN type string to uniquely identify a particular instance of a class of service.
	To provide extensibility, a naming authority is included in the name. This allows anyone with a domain name to define their own
	unique service names. Core service names are defined under the trustedfirmware.org authority. The general structure of a
	service name is as follows::

	urn:sn:<authority>:<service>.<version>:<instance>

	The 'urn' prefix should be dropped when service names are used in context.
	The version field is optional.

	The naming convention includes a version number, separated from the <service> field by a '.' character. Beyond the '.', any
	version numbering scheme may be used. This will potentially be useful for delegating version compatibility decisions to a
	service locator. It is preferable for a client to specify a service name that includes a version number as this will
	potentially allow a service locator to:

	- Locate a compatible service instance. For example, a service provider may expose multiple RPC call endpoints to handle
	different protocol versions. A service locator may resolve the name to the compatible RPC endpoint, based on the version
	string requested by the client.
	- Fail gracefully if no compatible version is found.

	Some example service names::

	sn:trustedfirmware.org:crypto.1.0.4:0
	sn:trustedfirmware.org:secure-storage.1.3.11:1
	sn:trustedfirmware.org:tpm.2.0:0

	Location Specific Service Names
	```````````````````````````````

	To enable a client to be able to specify location specific service names, it should also be possible to use names that express a
	location specific identifier such as a partition UUID. While use of location specific services names creates a coupling between
	the client and details of the service deployment, their use may be important in the following cases:

	- Where there is no well-known mapping between a location independent service name and a location specific identifier.
	- Where the client needs to be specific e.g. for tests that target a specific service deployment.

	Location specific service names use the same structure as location independent services names but with a technology specific
	authority field. The following is an example of a service name that identifies a service instance that is deployed in a secure
	partition::

	sn:ffa:d9df52d5-16a2-4bb2-9aa4-d26d3b84e8c0:0

	The instance field qualified a particular SP instance from the discovered set.

	Service Location Strategies
	'''''''''''''''''''''''''''

	The method used by the service locator to resolve a service name to a service instance will depend on the environment in which a
	client is running and where service instances are located. Services will need to be located by any client of a trusted service.
	There are typically two classes of trusted service client:

	- A user-space application.
	- Another trusted service, running in a secure processing environment.

	Different methods for locating service instances in different environments are illustrated in the following examples:

	Locating a Service from Linux User-space
	````````````````````````````````````````

	Depending on the kernel driver model used, the example methods for locating service instances from Linux user-space are:

	1. Service instances are represented by device nodes e.g. /dev/tpm0. The service locator will simply map the <service>
	portion of the services name to the base device name and the <instance> to the device node instance.
	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
	instance to be identified. The service locator will need to map the service name to the TEE specific naming scheme.
	3. A special device that provides messaging provides a method for discovery. e.g. an FF-A driver supports partition
	discovery.
	4. A device is used for remote messaging to a separate microcontroller. There is a well-known protocol for endpoint
	discovery using the messaging layer.

	Locating a Service from another Trusted Service
	```````````````````````````````````````````````

	Where a trusted service uses another trusted service, it is likely that both service instances will be running in the same
	security domain e.g. both running in secure partitions within the secure world. Where a single service instance is deployed per
	secure partition, the client service will use the following strategy to locate the service provider:

	1. The service name is mapped to the well known UUID for the class of SP that hosts the service provider.
	2. FF-A partition discovery is used to find all SPs that match the requested UUID.
	3. The service instance portion of the service name is used to match the partition ID when selecting the target SP from the
	list of discovered SPs.

	Extending the Service Locator Model
	```````````````````````````````````

	To accommodate the need to support alternative location strategies, the Service Locator model can be extended to use a set of
	concrete strategy objects to implement different methods of locating a service instance. The set of strategies used will be
	different for different client environments. The following class diagram illustrates how the model can be extended.

	.. uml:: uml/ServiceLocationStrategyClassDiagram.puml

	--------------

	Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.

	SPDX-License-Identifier: BSD-3-Clause