1Libraries
2=========
3Some deployments build common functionality into libraries that may be used by
4other deployments or external applications. The following library deployments
5are currently supported:
6
7The libraries will have a build type-specific suffix added to the base name of
8their binaries, allowing multiple binaries to be installed in the same tree.
9(See :ref:`Selecting the build type`) This differentiation applies to the
10``Debug`` and ``DebugCoverage`` build types. The system integrator must choose
11which single ``Release<XXX>`` build type is to be supported in the system.
12Package managers and mutually exclusive release packages can be used to add
13further flexibility.
14
15.. _libs-libts:
16
17libts
18-----
19
20Userspace applications that depend on trusted services may use *libts* for handling
21service discovery and RPC messaging. A major benefit to application developers is
22that *libts* entirely decouples client applications from details of where a service
23provider is deployed and how to communicate with it. All TS test executables and
24tools that interact with service providers use *libts*.
25
26To facilitate test and development within a native PC environment, the *libts*
27deployment for the *linux-pc* environment integrates a set of service providers
28into the library itself. From a client application's perspective, this looks
29exactly the same as when running on a target platform with service providers
30deployed in secure processing environments. For more information, see:
31:ref:`Service Locator`.
32
33.. list-table::
34  :widths: 1 2
35  :header-rows: 0
36
37  * - Supported Environments
38    - * | *linux-pc* - service providers integrated into library
39      * | *arm-linux* - communicates with service providers in secure processing environment
40  * - Used by
41    - * Userspace applications.
42
43
44.. _libs-libpsats:
45
46libpsats
47--------
48
49Trusted Services implements the `PSA Certified APIs`_. Libpsats encapsulates the service client implementations
50which implement this API. Linux uuser-space applications can use libpsats to easily access the PSA services
51implemented by the project. Libpsats depends on libts for RPC and service discovery services.
52
53.. list-table::
54  :widths: 1 2
55  :header-rows: 0
56
57  * - Supported Environments
58    - * | *linux-pc*
59      * | *arm-linux*
60  * - Used by
61    - * Userspace applications
62  * - Depends on
63    - * `libts`_ library
64
65Build and integration examples
66..............................
67
68Build as shared library::
69
70  cmake -S ./trusted-services/deployments/libpsats/linux-pc/ -B ./build
71  make -C build && make -C build install
72
73.. warning::
74    Building as static library is not yet supported.
75
76To integrate the library libts shall also be integrated. To achieve this add the listed
77lines to the application's cmake files::
78
79  find_package(libpsats "1.0.0" REQUIRED PATHS "<install path>")
80  find_package(libts "2.0.0" REQUIRED PATHS "<install path>")
81  target_link_libraries(ts-demo PRIVATE libpsats::psats)
82
83Initialization
84..............
85
86Before calling any function from libpsats the proper part of the library has to be initialized.
87Before exiting the application (or when PSA services are no longer needed) the initialized
88parts must be deinitialized. To access the library **libpsats.h** must be included::
89
90   psa_status_t libpsats_init_crypto_context(const char *service_name);
91   void libpsats_deinit_crypto_context(void);
92
93   psa_status_t libpsats_init_attestation_context(const char *service_name);
94   void libpsats_deinit_attestation_context(void);
95
96   psa_status_t libpsats_init_its_context(const char *service_name);
97   void libpsats_deinit_its_context(void);
98
99   psa_status_t libpsats_init_ps_context(const char *service_name);
100   void libpsats_deinit_ps_context(void);
101
102The example below initializes and then deinitializes crypto::
103
104    psa_status_t psa_status = libpsats_init_crypto_context("sn:trustedfirmware.org:crypto:0");
105    if (psa_status) {
106        printf("libpsats_init_crypto_context failed: %d\n", psa_status);
107        return PSA_ERROR_GENERIC_ERROR;
108    }
109
110    libpsats_deinit_crypto_context();
111
112Known issues and Limitations
113............................
114
115| The library is single client.
116| The library is not thread safe.
117| Only linux user-space is supported currently.
118
119.. _libs-libsp:
120
121libsp
122-----
123
124*libsp* provides a functional interface for using FF-A messaging and memory
125management facilities. *libsp* is used in SP deployments. For more information, see:
126:ref:`libsp`.
127
128.. list-table::
129  :widths: 1 2
130  :header-rows: 0
131
132  * - Supported Environments
133    - * | *opteesp*
134  * - Used by
135    - * Secure partitions
136
137Known issues and Limitations
138............................
139
140| The library is single client.
141| The library is not thread safe.
142| Only linux user-space is supported currently.
143
144--------------
145
146.. _`PSA Certified APIs`: https://arm-software.github.io/psa-api/
147
148*Copyright (c) 2022-2023, Arm Limited and Contributors. All rights reserved.*
149
150SPDX-License-Identifier: BSD-3-Clause
151