..
 # SPDX-FileCopyrightText: <text>Copyright 2025 Arm Limited and/or its
 # affiliates <open-source-office@arm.com></text>
 #
 # SPDX-License-Identifier: MIT

.. _rd-aspen_design_secure_services:

###############
Secure Services
###############

************
Introduction
************

The Reference Software Stack provides the implementation of Secure Services
through the Primary Compute. These services are aligned to the following
specifications:

* :link_subs:`rd-aspen:psa-crypto-api-doc`: The API provides a portable
  programming interface to cryptographic operations, and key storage functionality
  on a wide range of hardware.

* :link_subs:`rd-aspen:psa-secure-storage-api-doc`: The API provides key/value
  storage interfaces for use with device-protected storage. The Secure Storage API
  describes two interfaces for storage:

    * Internal Trusted Storage (ITS) API: An interface for storage provided by
      the Platform Root of Trust (PRoT).
    * Protected Storage (PS) API: An interface for external protected storage.

* :link_subs:`rd-aspen:psa-attestation-api-doc`: The Attestation service securely
  collects device state information and generates a signed report of claims for
  remote verification. The API provides a portable programming interface to
  Initial Attestation operations.

.. _rd-aspen_design_primary_compute_secure_services:

*******************************
Primary Compute Secure Services
*******************************

On Primary Compute, the Crypto Service, Secure Storage Service and Attestation
Service can be requested using :link_subs:`rd-aspen:se-proxy-doc`.

The Primary Compute also provides the implementation of
:link_subs:`rd-aspen:uefi-smm-services-doc` via the SMM Gateway Secure Partition
(SMM Gateway SP) to support UEFI System Management Mode (SMM).

These Secure Services are provided by the :link_subs:`rd-aspen:trusted-services-doc`
project, and implemented by leveraging the :link_subs:`common:trustzone-doc`
technology in the Primary Compute and the hardware-isolated secure enclave in
RSE.

The Reference Software Stack provides the implementation of Secure Services
through Primary Compute.

.. _rd-aspen_design_primary_compute_secure_services_architecture:

Architecture
============

The following diagram shows the components and data flow that implement
the Primary Compute Secure Services.

|

.. image:: ../images/primary_compute_secure_services.*
   :align: center
   :alt: Primary Compute Secure Services

|

PSA APIs Tests
==============

The PSA Protected Storage, PSA Internal Trusted Storage, PSA Initial Attestation
and PSA Crypto APIs tests can be accessed from the Primary Compute Linux
terminal by running a single command for each. The test suites take around a
minute to execute, and a table of results is displayed upon completion.

See :ref:`rd_aspen_user_guide_reproduce_psa_apis_tests_in_pc` for more
information.

libts
=====

In Linux userspace, the Secure Services are provided in the form of
:link_subs:`rd-aspen:libts-doc` API. ``libts`` is a library that is provided by
:link_subs:`rd-aspen:trusted-services-doc` for handling service discovery and
Remote Procedure Call (RPC) messaging. ``libts`` entirely decouples client
applications from details of where a service provider is deployed and how to
communicate with it.

The client application sends operation requests and receives responses by
calling the ``libts`` API. ``libts`` communicates with the
:link_subs:`rd-aspen:secure-partition-doc` (SP) running in the Secure world.
The communication between ``libts`` and the Secure world SP is carried by the
:link_subs:`common:ff-a-doc` (FF-A) call which is supported by Linux kernel and
Trusted Firmware-A.

SE-Proxy SP
===========

The Secure Enclave Proxy Secure Partition (:link_subs:`rd-aspen:se-proxy-doc`)
is a proxy partition managed by :link_subs:`rd-aspen:op-tee-doc`. It provides
access to services hosted by the RSE.

The ``SE-Proxy SP`` receives Secure Service operation requests from the Normal
world, translates the request parameters to IPC calls, and invokes the runtime
services provided by the RSE. The IPC is carried by Message Handling Unit
(MHUv3) communication between the Primary Compute and the RSE.

SMM Gateway SP
==============

The System Management Mode Gateway Secure Partition
(:link_subs:`rd-aspen:smm-gateway-sp-doc`) serves as a gateway for the variable
storage required by the implementation of UEFI Boot and Runtime Services APIs.
These UEFI variables are stored in the Protected Storage Service provided by the
RSE.

The data flow to store UEFI variables is presented in the diagram at the
beginning of the :ref:`rd-aspen_design_primary_compute_secure_services_architecture`
section. The U-Boot implementation of the UEFI subsystem uses the FF-A driver to
communicate with the :link_subs:`rd-aspen:uefi-smm-services-doc` in the
:link_subs:`rd-aspen:smm-gateway-sp-doc`. The backend of the SMM services uses
the Protected Storage proxy from the :link_subs:`rd-aspen:se-proxy-doc`. From
there on, the Protected Storage calls are forwarded to the secure enclave as
explained above.