Skip to content

Latest commit

 

History

History
79 lines (60 loc) · 4.45 KB

UsageModel.md

File metadata and controls

79 lines (60 loc) · 4.45 KB
Raw

Security API Usage Model

Security API Usage Model

This diagram shows the planned usage model for SecAPI 3. SecAPI 3 uses a slot for every REE application.

A Rich Execution Environment (REE) application is any application that executes outside the bounds of a Trusted Execution Environment (TEE).

A Trusted Application (TA) is any application that executes in a trusted execution environment.

SecAPI 3 is composed of two components: a SecAPI 3 REE library and a SecAPI 3 TA. The REE SecAPI 3 library provides an API for REE applications to call which delegates functionality to the SecAPI 3 TA. The SecAPI 3 TA provides an environment in which instruction execution and memory usage is not visible outside the trusted application.

The following sections describes the different use cases shown in this model and assumes the proposed threaded usage model.

Requirements

  • Any calls to the SecAPI 3 TA using different sessions shall be able to execute simultaneously within the SecAPI 3 TA.
  • Any calls to the SecAPI 3 TA using the same session may execute sequentially and may block other calls to the SecAPI 3 TA within the same session.

REE Application Use Case

A REE application will be compiled with the REE SecAPI 3 library. The REE application can be single threaded or multi-threaded. The REE SecAPI 3 library is assigned a UUID identifying it as the REE SecAPI 3 library. On the first usage of SecAPI 3 by an application, the REE SecAPI 3 library invokes open session on the SecAPI 3 TA which looks up the UUID of the REE SecAPI 3 library. This open session invocation invokes the ta_sa_init function providing the UUID of the REE SecAPI library. This assigns a slot number to the session. The TA may choose to store this slot number as part of the session context so that it does not have to be submitted on future function invocations. All future function invocations made by the REE SecAPI 3 library to the SecAPI 3 TA session will use this UUID and slot number. All keys, ciphers, macs, and SVP memory regions created in this session are only accessible by function invocations using this session. When the REE SecAPI 3 library closes the session, this likewise invokes ta_sa_close which releases the slot and any keys, ciphers, macs, or SVP memory regions associated with it.

This SecAPI 3 session can only be used by the application that created it.

Examples of REE Applications include:

  • The SoC Provisioning application.
  • Any application using the SecClient library.
  • Potentially any application using TLS where the TLS library uses SecAPI 3 as its underlying cryptographic engine.

Secure Application Use Case

A Secure REE application will interact with a Secure Application TA to perform secure functions. The Secure Application TA interacts with the SecAPI 3 TA to perform cryptographic functions on its behalf. A Secure Application TA is assigned a UUID at compile time to identify the type of the TA. Keys can be assigned rights so that they can only be utilized by Secure Application TA instances with that UUID.

On the first usage of SecAPI 3 by a Secure Application TA instance, the Secure Application TA instance invokes open session on the SecAPI 3 TA which looks up the UUID of the Secure Application TA. This open session invocation invokes the ta_sa_init function providing the UUID of the Secure Application TA. This assigns a slot number to the session. The TA may choose to store this slot number as part of the session context so that it does not have to be submitted on future function invocations. All future function invocations made by the Secure Application TA instance to the SecAPI 3 TA session will use this UUID and slot number. All keys, ciphers, macs, and SVP memory regions created in this session are only accessible by function invocations using this session. When the Secure Application TA instance closes the session, this likewise invokes ta_sa_close which releases the slot and any keys, ciphers, macs, or SVP memory regions associated with it.

This SecAPI 3 session can only be used by the Secure Application TA instance that created it.

Any calls to the SecAPI 3 TA using different sessions shall be able to execute simultaneously within the SecAPI 3 TA. Any calls to the SecAPI 3 TA using the same session may execute sequentially and may block other calls to the SecAPI 3 TA using the same session.

Examples of Secure Application TAs include:

  • FairPlay DRM TA.
  • Any other future TA that needs access to SecAPI 3.