Uniform Secure Service Signature Alignment

Updated 2,133 Days AgoPublic

Actions

Table of contents

• Scope
• Terms and abbreviations
• References
• Introduction
• Design content
  • SST service components
  • SST request Manager
  • SST Manifest file
  • TF-M error codes
  • PSA PS APIs non-secure and secure implementation
• Validation tests

Scope

The scope of this document is to describe the SST secure service design to align it with the uniform secure service signatures.

Terms and abbreviations

This document uses the following terms and abbreviations.

References

Introduction

Currently, a <service_name>_veneers.c file is created in the secure_fw/ns_callable directory, that specifies the signature for each veneer function, and calls the secure function from the veneers.
The respective interface/include/<service_name>_veneers.h file with the veneer declarations is created and maintained manually. In addition, the TF-M framework, aligned with that design, limits the range of valid return values a secure service can provide, reserving a range for framework error codes.

The uniform secure service signature design [ 1 ] proposes to use a uniform signature for all the secure functions of the secure service. There are multiple advantages of this method:

• TF-M Core can do a sanity check on the access rights of the veneer parameters, and there is no need for the secure services to make these checks individually. Please note that in the present implementation sanity check is only fully supported for level 1 isolation.
• The veneer declarations and implementations for the secure functions can be generated automatically from a template (using the secure function list in the secure service's manifest)

The signature for such secure services would look like this:

psa_status_t secure_function_name(struct psa_invec *in_vec, size_t in_len,
                                  struct psa_outvec *out_vec, size_t out_len);

A detailed information about the signature can be found in [ 1 ].

Design Content

SST service components

The current SST service implements a set of components, each one dedicated to implementing a specific functionality in each layer of the SST service firmware stack [ 2 ][ 3 ].

The set of functionalities are:

• Protected Storage layer: This layer exposes the PSA protected storage set of interfaces which are compliant with the PPS APIs specification.
• Object System: This component contains the object system implementation to manage all objects stored in the SST area.
• File System: It abstracts the flash filesystem operations for the secure storage service. The purpose of this abstraction is to have the ability to plug-in other filesystems or filesystem proxies (supplicant). Currently, it implements a custom filesystem based on a non-hierarchical storage model where all the files are managed by linearly indexed list of metadata.

The current SST firmware stack is:

The new design adds the SST request manager layer as the entry point to the service. This layer manages all requests which arrive to the service, and performs the proper Protected Storage calls. Detailed information about this layer can be found in the section below.

The new SST firmware layers are:

SST request Manager

The SST request manager handles all requests which arrive to the service. The interfaces of this layer are aligned with the unified secure service signatures. This layer extracts the arguments from the input and output vectors, and it calls the protected storage layer with the provided parameters. It also checks that the number of parameters and sizes are aligned with the protected storage interface to call.

The list of interfaces exposed by the SST request manager layer are:

tfm_sst_set_req()

This function handles the PSA PS set requests.

psa_status_t tfm_sst_set_req(struct psa_invec *in_vec, size_t in_len,
                             struct psa_outvec *out_vec, size_t out_len);

Parameters

Return
A status indicating the success/failure of the operation as specified in psa_status_t.

The following table shows the input parameters mapping in the in_vec vector.

The following table shows the input parameters mapping in the out_vec vector.

tfm_sst_get_req()

This function handles the PSA PS get requests.

psa_status_t tfm_sst_get_req(struct psa_invec *in_vec, size_t in_len,
                             struct psa_outvec *out_vec, size_t out_len);

Parameters

Return
A status indicating the success/failure of the operation as specified in psa_status_t.

The following table shows the input parameters mapping in the in_vec vector.

The following table shows the input parameters mapping in the out_vec vector.

tfm_sst_get_info_req()

This function handles the PSA PS get info requests.

psa_status_t tfm_sst_get_info_req(struct psa_invec *in_vec, size_t in_len,
                                  struct psa_outvec *out_vec, size_t out_len);

Parameters

Return
A status indicating the success/failure of the operation as specified in psa_status_t.

The following table shows the input parameters mapping in the in_vec vector.

The following table shows the input parameters mapping in the out_vec vector.

tfm_sst_remove_req()

This function handles the PSA PS remove requests.

psa_status_t tfm_sst_remove_req(struct psa_invec *in_vec, size_t in_len,
                                struct psa_outvec *out_vec, size_t out_len);

Parameters

Return
A status indicating the success/failure of the operation as specified in psa_status_t.

The following table shows the input parameters mapping in the in_vec vector.

The following table shows the input parameters mapping in the out_vec vector.

tfm_sst_get_support_req()

This function handles the PSA PS get support requests.

psa_status_t tfm_sst_get_support_req(struct psa_invec *in_vec, size_t in_len,
                                     struct psa_outvec *out_vec, size_t out_len);

Parameters

Return
A status indicating the success/failure of the operation as specified in psa_status_t.

The following table shows the input parameters mapping in the in_vec vector.

The following table shows the input parameters mapping in the out_vec vector.

SST Manifest file

The SST manifest file must be updated to expose the SST request manager functions rather than the Protected Storage layer. However, the “tfm_init_symbol” entry needs to be tfm_sst_init as this is the function which initializes the service.
The “source_file” list must be updated to add the new SST request manager files.

TF-M error codes

The legacy TF-M framework, used by the current SST implementation, limits the range of valid return values that a secure service can provide, reserving a range for framework error codes. For that reason, the TF-M SST codes need to be different from the PSA PS ones. The uniform secure service feature in TF-M framework does not have this requirement anymore, so the current TF-M SST error codes must be replaced by the PSA PS ones [ 4 ].

PSA PS APIs non-secure and secure implementation

The current implementation must be updated to evaluate psa_status_t return codes from TF-M framework. In case, TF-M framework returns a value different from PSA_SUCCESS, the interface should return a PSA_PS_ERROR_OPERATION_FAILED as a PSA PS error code. Otherwise, it should return the error code returned via out_vec.

Each PSA PS API implementation must map the input, output and return vales as defined in section "SST request Manager" per each request interface.

Validation Tests

To validate the new design of SST service, the new version must pass all the SST test suites defined in TF-M and
PSA Arch tests [ 5 ].

However, the psa_ps_ns_interface and psa_ps_s_interface test suites must be updated to modify the tests which check the validity of the callers memory referenced by a pointer. All the null pointer checks must be with data length equal to 0. The new TF-M framework incorporates a mechanism to check the validity of the memory area referred by the pointers plus data length [ 1 ]. If secure partition requests a service with an invalid pointer with a data length different from 0, in one or more parameters, the TF-M frameworks returns a specific error code to reject the request. In the other hand, if a non-secure application requests a service with a null pointer with a data length different from 0, in one or more parameters, the TF-M framework blocks the request and it does not return the control to the non-secure application.