zephyr
/
trusted-firmware-m
mirror of https://github.com/zephyrproject-rtos/trusted-firmware-m.git
1
0
Fork 0
Code Issues Releases Wiki Activity

Doc: convert markdown files to rst 

The official documentation format for TF-M is becoming Restructured
Text. This change converts the existing .md files to the new format.

Due to support for documentation of external code (/lib) md support is
kept.

Change-Id: I3c1aef5d22442e0c7c362a40a8d344a266dc0940
Signed-off-by: Gyorgy Szing <Gyorgy.Szing@arm.com>
This commit is contained in:
Gyorgy Szing 2019-04-17 21:08:48 +02:00
parent 74dae3cf92
commit db9783ceb8
46 changed files with 3516 additions and 2903 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
cmake/Common/BuildSphinxDoc.cmake
View File

@ -33,10 +33,11 @@ Include(CMakeParseArguments)
# SphinxFindTools()
#
function(SphinxFindTools)
#Find Sphinx
find_package(Sphinx)
#Find additional needed python dependencies.
find_package(PythonModules COMPONENTS m2r sphinx-rtd-theme)
#Find additional needed Sphinx dependencies.
find_package(PythonModules COMPONENTS m2r sphinx-rtd-theme sphinxcontrib.plantuml)
#Find plantUML
find_package(PlantUML)
@ -48,10 +49,11 @@ function(SphinxFindTools)
endif()
if (SPHINX_FOUND AND PLANTUML_FOUND AND PY_M2R_FOUND
AND PY_SPHINX-RTD-THEME_FOUND)
AND PY_SPHINX-RTD-THEME_FOUND AND PY_SPHINXCONTRIB.PLANTUML)
#Export executable locations to global scope.
set(SPHINX_EXECUTABLE "${SPHINX_EXECUTABLE}" PARENT_SCOPE)
set(PLANTUML_JAR_PATH "${PLANTUML_JAR_PATH}" PARENT_SCOPE)
set(Java_JAVA_EXECUTABLE "${Java_JAVA_EXECUTABLE}" PARENT_SCOPE)
set(SPHINX_NODOC False PARENT_SCOPE)
else()
message(WARNING "Some tools are missing for Sphinx document generation. Document generation target is not created.")
@ -73,8 +75,8 @@ if (NOT SPHINX_NODOC)
set(SPHINX_TMP_DOC_DIR "${CMAKE_CURRENT_BINARY_DIR}/doc_sphinx_in")
set(SPHINXCFG_TEMPLATE_FILE "${TFM_ROOT_DIR}/docs/Conf.py.in")
set(SPHINXCFG_CONFIGURED_FILE "${SPHINXCFG_OUTPUT_PATH}/Conf.py")
set(SPHINXCFG_TEMPLATE_FILE "${TFM_ROOT_DIR}/docs/conf.py.in")
set(SPHINXCFG_CONFIGURED_FILE "${SPHINXCFG_OUTPUT_PATH}/conf.py")
#Version ID of TF-M.
@ -91,10 +93,14 @@ if (NOT SPHINX_NODOC)
VERBATIM
)
add_custom_target(create_sphinx_input
SOURCES "${SPHINX_TMP_DOC_DIR}"
)
add_custom_command(OUTPUT "${SPHINXCFG_OUTPUT_PATH}/html"
COMMAND "${SPHINX_EXECUTABLE}" -c "${SPHINXCFG_OUTPUT_PATH}" -b html "${SPHINX_TMP_DOC_DIR}" "${SPHINXCFG_OUTPUT_PATH}/html"
WORKING_DIRECTORY "${TFM_ROOT_DIR}"
DEPENDS "${SPHINX_TMP_DOC_DIR}"
DEPENDS create_sphinx_input
COMMENT "Running Sphinx to generate user guide (HTML)."
VERBATIM
)
@ -120,7 +126,7 @@ if (NOT SPHINX_NODOC)
add_custom_command(OUTPUT "${SPHINXCFG_OUTPUT_PATH}/latex"
COMMAND "${SPHINX_EXECUTABLE}" -c "${SPHINXCFG_OUTPUT_PATH}" -b latex "${SPHINX_TMP_DOC_DIR}" "${SPHINXCFG_OUTPUT_PATH}/latex"
WORKING_DIRECTORY "${TFM_ROOT_DIR}"
DEPENDS "${SPHINX_TMP_DOC_DIR}"
DEPENDS create_sphinx_input
COMMENT "Running Sphinx to generate user guide (LaTeX)."
VERBATIM
)

5
cmake/SphinxCopyDoc.cmake
View File

@ -25,7 +25,7 @@
# |
#
#Usage:
# cmake -DDST_RIR=<path to destination> -DTFM_ROOT_DIR=<path to tf-m root> \
# cmake -DDST_DIR=<path to destination> -DTFM_ROOT_DIR=<path to tf-m root> \
# -P SphinxCopyDoc.cmake
#Check input parameters
@ -42,7 +42,8 @@ file(GLOB_RECURSE _COPY_FILES
LIST_DIRECTORIES false
RELATIVE "${TFM_ROOT_DIR}"
"${TFM_ROOT_DIR}/*.md"
"${TFM_ROOT_DIR}/*.rst")
"${TFM_ROOT_DIR}/*.rst"
"${TFM_ROOT_DIR}/dco.txt")
#Subtract exluded files from copy files
list(REMOVE_ITEM _COPY_FILES "docs/index.rst")

36
contributing.md
View File

@ -1,36 +0,0 @@
# Contributing to Trusted Firmware M
Contributions to TF-M project need to follow the process below.
`Note` Please contact [Maintainers](./maintainers.md) for any questions.
- Create an issue in [http://issues.trustedfirmware.org](http://issues.trustedfirmware.org)
to keep others informed about your ongoing work.
- If it is a major change then please discuss the design with maintainers.
- Clone the TF-M code on your own machine from
[http://git.trustedfirmware.org/trusted-firmware-m.git](http://git.trustedfirmware.org/trusted-firmware-m.git)
- Follow the [Coding Guidelines](docs/coding_guide.md) for the TF-M project.
- Make your changes in logical chunks to help reviewers.
- Update relevant documentation.
- Test your changes and add details to the commit description.
- Add the issue number and details to commit description as well.
- The code is accepted under [DCO](./dco.txt), Developer Certificate
of Origin, so you must add following fields to your commit description.
```
Author: Full Name <email address>
Signed-off-by: Full Name <email address>
Note: Sign off authority needs to adhere to the [DCO](./dco.txt) rules.
```
- You may add other fields in the commit message.
- Submit your patch for review at
[http://review.trustedfirmware.org](http://review.trustedfirmware.org)
- Maintainers will be notified and they will start review process.
- You may be asked to provide further details or make additional changes.
- You can discuss further with maintainer(s) offline if necessary.
- Once the change is approved by maintainers, the patch can be submitted
either by maintainer or patch owner.
--------------
*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*

42
contributing.rst Normal file
View File

@ -0,0 +1,42 @@
Contributing to Trusted Firmware M
==================================
Contributions to TF-M project need to follow the process below.
``Note`` Please contact :doc:`maintainers` for any questions.
- Create an issue in http://issues.trustedfirmware.org
to keep others informed about your ongoing work.
- If it is a major change then please discuss the design with
maintainers.
- Clone the TF-M code on your own machine from
http://git.trustedfirmware.org/trusted-firmware-m.git
- Follow the :doc:`Coding Guide </docs/coding_guide>` for the TF-M
project.
- Make your changes in logical chunks to help reviewers.
- Update relevant documentation.
- Test your changes and add details to the commit description.
- Add the issue number and details to commit description as well.
- The code is accepted under :doc:`DCO </docs/dco>`, Developer
Certificate of Origin, so you must add following fields to your commit
description.::
Author: Full Name <email address>
Signed-off-by: Full Name <email address>
Note: Sign off authority needs to adhere to the [DCO](./dco.txt) rules.
- You may add other fields in the commit message.
- Submit your patch for review at
http://review.trustedfirmware.org
- Maintainers will be notified and they will start review process.
- You may be asked to provide further details or make additional
changes.
- You can discuss further with maintainer(s) offline if necessary.
- | Once the change is approved by maintainers, the patch can be
submitted
| either by maintainer or patch owner.
--------------
*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*

10
docs/_static/css/custom.css vendored Normal file
View File

@ -0,0 +1,10 @@
/*
* Copyright (c) 2019, Arm Limited. All rights reserved.
*
* SPDX-License-Identifier: BSD-3-Clause
*
*/
.wy-nav-content {
max-width: 85% !important;
}

66
docs/coding_guide.md
View File

@ -1,66 +0,0 @@
# Yet another coding standard :)
`Every rule has an exception so if you disagree or dislike then reach out!`
The coding style of TF-M project is based on
[Linux coding style](https://www.kernel.org/doc/html/v4.10/process/coding-style.html)
but there are updates for domain specific conventions as listed below.
TF-M also reuses code from other SW projects, e.g.`CMSIS_5`, which
means some areas of code may have different styles. We use common sense approach
and new code may inherit coding style from external projects but it needs to
remain within clear scope.
The guidance below is provided as a help. It isn't meant to be a definitive list.
As implied in the [contributing guide](../contributing.md), maintainers have
the right to decide on what's acceptable in case of any divergence.
`Text files do not fall within these rules as they may require different formatting.`
## Consistent style
The code needs to be consistent with itself, so if existing code in the file
violates listed coding style rules then it is better to follow existing style
in the file and not break consistency by following the rules listed here.
You may need to add a comment in the commit description to clarify this.
## List of rules
* Use 4 spaces indentation. No tabs.
* Use `lower_case_with_underscore` for filenames, variable and function names.
* Use standard types e.g. `uint32_t`, `uint16_t`, `uint8_t`, `int32_t` etc.
* Use `uintptr_t` type when representing addresses as numbers.
* Use static for all private functions and variables.
* Use void argument if your function doesn't contain any argument.
* Use C90 `/* */` for comments rather than C99 `//`
* No trailing spaces in code.
* Max 80 characters length. Text files are exception as stated above.
* Open curly brace ' { ' at the same if/else/while/for/switch statement line.
* Use curly braces ' { } ' for one line statement bodies also.
* Put open curly brace in the line below the function header.
* Order function parameters so that input params are before output params.
* Declare local variables at the beginning of the function.
* Define macros in all caps i.e. `CAPITAL_WITH_UNDERSCORE`.
* Use typedefs ONLY for function prototype declarations.
* Type definitions in `lower_case_with_underscore` ended by `_t`.
* Do not use typedef for other constructs as it obfuscates code.
* Do not use bitfields.
* Use static for all global variables to reduce the variable scope.
* Use enumeration for error codes to keep the code readable.
* Use descriptive variable and functions names.
* Put the correct license header at the beginning of the file.
* Keep the files (.h/.c) self-contained, i.e. put include dependencies in the file.
* Put appropriate header define guard in .h files: `__HEADER_NAME__`.
Any divergence from this rules should be clearly documented.
* In a .c file, #include it's own header file first.
* Document all the public functions in the header file only.
* Document all the private functions in the source file only.
* Add "extern C " definition for C++ support in the header files.
* In the switch statement, aligned cases with the switch keyword.
* For enums, use upper case letters with digits and underscore only.
* Do not code while eating.
--------------
*Copyright (c) 2018, Arm Limited. All rights reserved.*

78
docs/coding_guide.rst Normal file
View File

@ -0,0 +1,78 @@
##############################
Yet another coding standard :)
##############################
.. Warning::
Every rule has an exception so if you disagree or dislike then reach out!
The coding style of TF-M project is based on
`Linux coding style <https://www.kernel.org/doc/html/v4.10/process/coding-style.html>`__
but there are updates for domain specific conventions as listed below.
TF-M also reuses code from other SW projects, e.g. ``CMSIS_5``, which
means some areas of code may have different styles. We use common sense approach
and new code may inherit coding style from external projects but it needs to
remain within clear scope.
The guidance below is provided as a help. It isn't meant to be a definitive
list.
As implied in the :doc:`contributing guide </contributing>` maintainers
have the right to decide on what's acceptable in case of any divergence.
.. Warning::
Text files do not fall within these rules as they may require different formatting.``
****************
Consistent style
****************
The code needs to be consistent with itself, so if existing code in the file
violates listed coding style rules then it is better to follow existing style
in the file and not break consistency by following the rules listed here.
You may need to add a comment in the commit description to clarify this.
List of rules
=============
- Use 4 spaces indentation. No tabs.
- Use ``lower_case_with_underscore`` for filenames, variable and function names.
- Use standard types e.g. ``uint32_t``, ``uint16_t``, ``uint8_t``, ``int32_t``
etc.
- Use ``uintptr_t`` type when representing addresses as numbers.
- Use static for all private functions and variables.
- Use void argument if your function doesn't contain any argument.
- Use C90 ``/* */`` for comments rather than C99 ``//``
- No trailing spaces in code.
- Max 80 characters length. Text files are exception as stated above.
- Open curly brace ``{`` at the same if/else/while/for/switch statement line.
- Use curly braces ``{ }`` for one line statement bodies also.
- Put open curly brace in the line below the function header.
- Order function parameters so that input params are before output params.
- Declare local variables at the beginning of the function.
- Define macros in all caps i.e. ``CAPITAL_WITH_UNDERSCORE``.
- Use typedefs **ONLY** for function prototype declarations.
- Type definitions in ``lower_case_with_underscore`` ended by ``_t``.
- Do not use typedef for other constructs as it obfuscates code.
- Do not use bitfields.
- Use static for all global variables to reduce the variable scope.
- Use enumeration for error codes to keep the code readable.
- Use descriptive variable and functions names.
- Put the correct license header at the beginning of the file.
- Keep the files (.h/.c) self-contained, i.e. put include dependencies in the
file.
- Put appropriate header define guard in .h files: ``__HEADER_NAME__``.
Any divergence from this rules should be clearly documented.
- In a .c file, #include it's own header file first.
- Document all the public functions in the header file only.
- Document all the private functions in the source file only.
- Add "extern C " definition for C++ support in the header files.
- In the switch statement, aligned cases with the switch keyword.
- For enums, use upper case letters with digits and underscore only.
- Do not code while eating.
--------------
*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*

22
docs/conf.py.in
View File

@ -40,16 +40,26 @@ release = '@SPHINXCFG_TFM_VERSION_FULL@'
# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
# needs_sphinx = '1.4'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.imgmath',
'm2r',
'm2r', #Support markdown files. Needed for external code.
'sphinx.ext.autosectionlabel', #Make sphinx generate a label for each section
'sphinxcontrib.plantuml' #Add support for PlantUML drawings
]
#Location of PlantUML
plantuml = '@Java_JAVA_EXECUTABLE@ -jar @PLANTUML_JAR_PATH@'
#Make auso section labals generated be prefixed with file name.
autosectionlabel_prefix_document=True
#Add auso section label for level 1 headers only.
autosectionlabel_maxdepth=1
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@ -89,11 +99,11 @@ html_theme = 'sphinx_rtd_theme'
# documentation.
#
# html_theme_options = {}
#
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
html_static_path = ['@TFM_ROOT_DIR@/docs/_static']
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
@ -108,6 +118,10 @@ html_static_path = ['_static']
#Disable adding conf.py copyright notice to HTML output
html_show_copyright = False
#Add custom css for HTML. Used to allow full page width rendering
def setup(app):
app.add_stylesheet('css/custom.css')
# -- Options for HTMLHelp output ---------------------------------------------
# Output file base name for HTML help builder.

12
docs/dco.rst Normal file
View File

@ -0,0 +1,12 @@
###############################
Developer Certificate of Origin
###############################
.. include:: /dco.txt
:literal:
-----------
*Copyright (c) 2019, Arm Limited. All rights reserved.*

53
docs/index.rst
View File

@ -13,69 +13,70 @@ Welcome to TF-M's documentation!
:maxdepth: 2
:glob:
:hidden:
contributing.md
glossary.md
maintainers.md
docs/user_guides/tfm_sw_requirement.md
docs/user_guides/tfm_build_instruction.md
docs/coding_guide.md
docs/user_guides/tfm_user_guide.md
docs/user_guides/os_migration_guide_armv8m.md
docs/user_guides/tfm_integration_guide.md
docs/user_guides/tfm_ns_client_identification.md
docs/user_guides/tfm_secure_boot.md
contributing
docs/dco
glossary
maintainers
docs/user_guides/tfm_sw_requirement
docs/user_guides/tfm_build_instruction
docs/coding_guide
docs/user_guides/tfm_user_guide
docs/user_guides/os_migration_guide_armv8m
docs/user_guides/tfm_integration_guide
docs/user_guides/tfm_ns_client_identification
docs/user_guides/tfm_secure_boot
.. toctree::
:maxdepth: 2
:caption: Secure services
:glob:
:hidden:
docs/user_guides/services/*
.. toctree::
:maxdepth: 2
:caption: Components
:glob:
:hidden:
lib/**
.. toctree::
:maxdepth: 2
:caption: Target platforms
:glob:
:hidden:
platform/**
.. toctree::
:caption: Design documents
:maxdepth: 2
:glob:
:hidden:
docs/design_documents/*
.. toctree::
:caption: Draft design documents
:maxdepth: 2
:glob:
:hidden:
docs/design_documents/drafts/*
.. toctree::
:caption: Rejected design documents
:maxdepth: 2
:glob:
:hidden:
docs/design_documents/rejected/*
.. mdinclude:: readme.md
.. include:: readme.rst
-----------
:Copyright: Copyright (c) 2019, Arm Limited. All rights reserved.
*Copyright (c) 2019, Arm Limited. All rights reserved.*

34
docs/user_guides/os_migration_guide_armv8m.md
View File

@ -1,34 +0,0 @@
# Generic OS migration from Armv7-M to Armv8-M architecture
The purpose of this document is to list a set of requirements needed for
migrating a generic OS kernel running on Armv7-M to the Armv8-M architecture.
## List of requirements
* If the same OS codebase is used for both Secure and Non Secure builds, it is
suggested to put specific code targeted to the Non Secure build under a compile
time switch, e.g. `#if (DOMAIN_NS == 1U)`. The OS build system in this case
needs to be amended accordingly to support this new switch.
* If the OS implements stack limit checking, the `PSPLIM` register needs to be
initialized and properly handled during thread context switch operations.
* If the OS manipulates directly the Link Register, the default Link Register
value used in Handler mode transitions needs to be differentiated between Secure
and Non Secure builds, i.e. `0xFD` and `0xBC`, respectively.
* If the OS supports the Thread Context Management for Armv8-M TrustZone APIs,
as described
[here](https://www.keil.com/pack/doc/CMSIS/Core/html/group__context__trustzone__functions.html)
, and would like to use the non-secure client identification feature of TF-M,
then it also have to use the `enum tfm_status_e tfm_register_client_id (int32_t
ns_client_id)` API function provided by TF-M, as described in
[NS client identification documentation](tfm_ns_client_identification.md).
* if the OS doesn't support the API mentioned above, it should set
`TFM_NS_CLIENT_IDENTIFICATION` to `OFF` in the cmake system.
* **_Note: This is NOT REQUIRED when the Non Secure OS build is meant to be
integrated with TF-M running in Secure world._** If generic function calls into
Secure world have to be supported in Non Secure builds, integrate an API for
secure stack memory management (e.g. the TrustZone API for secure stack memory
management described in `tz_context.h`).
--------------
*Copyright (c) 2018, Arm Limited. All rights reserved.*

42
docs/user_guides/os_migration_guide_armv8m.rst Normal file
View File

@ -0,0 +1,42 @@
#########################################################
Generic OS migration from Armv7-M to Armv8-M architecture
#########################################################
The purpose of this document is to list a set of requirements needed for
migrating a generic OS kernel running on Armv7-M to the Armv8-M architecture.
********************
List of requirements
********************
- If the same OS codebase is used for both Secure and Non Secure builds, it is
suggested to put specific code targeted to the Non Secure build under a
compile time switch, e.g. ``#if (DOMAIN_NS == 1U)``. The OS build system in
this case needs to be amended accordingly to support this new switch.
- If the OS implements stack limit checking, the ``PSPLIM`` register
needs to be initialized and properly handled during thread context switch
operations.
- If the OS manipulates directly the Link Register, the default Link Register
value used in Handler mode transitions needs to be differentiated between
Secure and Non Secure builds, i.e. ``0xFD`` and ``0xBC``, respectively.
- If the OS supports the Thread Context Management for Armv8-M TrustZone APIs,
as described
`here <https://www.keil.com/pack/doc/CMSIS/Core/html/group__context__trustzone__functions.html>`__
, and would like to use the non-secure client identification feature of TF-M,
then it also have to use the
``enum tfm_status_e tfm_register_client_id (int32_t ns_client_id)``
API function provided by TF-M, as described in
:doc:`NS client identification documentation <tfm_ns_client_identification>`.
- if the OS doesn't support the API mentioned above, it should set
``TFM_NS_CLIENT_IDENTIFICATION`` to ``OFF`` in the cmake system.
- .. Note::
This is NOT REQUIRED when the Non Secure OS build is meant
to be integrated with TF-M running in Secure world.
If generic function calls into Secure world have to be supported in Non Secure
builds, integrate an API for secure stack memory management (e.g. the
TrustZone API for secure stack memory management described in
``tz_context.h``).
--------------
*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*

396
docs/user_guides/services/tfm_attestation_integration_guide.md
View File

@ -1,396 +0,0 @@
# TF-M Initial Attestation Service Integration Guide
## Introduction
TF-M Initial Attestation Service allows the application to prove the device
identity during an authentication process to a verification entity. The initial
attestation service can create a token on request, which contains a fix set of
device specific data. Device must contain an attestation key pair, which is
unique per device. The token is signed with the private part of attestation key
pair. The public part of the key pair is known by the verification entity. The
public key is used to verify the token authenticity. The data items in the token
used to verify the device integrity and assess its trustworthiness. Attestation
key provisioning is out of scope for the attestation service and is expected to
take part during manufacturing of the device.
## Current service limitations
- **Signing of token** - In the current implementation the token is not properly
signed. Signature is generated according to the
[COSE](https://datatracker.ietf.org/doc/rfc8152/) format. But its actual value
is not a correct ECDSA P256 signature, due to the lack of support of the ECDSA
algorithm in the current implementation of the TF-M Crypto service. A fake
signature is created, which is the concatenation of the token's hash value
twice.
## Claims in the initial attestation token
The initial attestation token is formed of claims. A claim is a data item,
which is represented in a key - value structure. The following fixed set of
claims are included in the token:
- **Challenge**: Input object from caller. Can be a single nonce from server or
hash of nonce and attested data. It is intended to provide freshness to reports
and the caller has responsibility to arrange this. Allowed length: 32, 48,
64 bytes. The claim is modeled to be eventually represented by the EAT standard
claim nonce. Until such a time as that standard exists, the claim will be
represented by a custom claim. Value is encoded as byte string.
- **Instance ID**: It represents the unique identifier of the instance. In the
PSA definition it is a hash of the public attestation key of the instance. The
claim is modeled to be eventually represented by the EAT standard claim UEID of
type GUID. Until such a time as that standard exists, the claim will be
represented by a custom claim Value is encoded as byte string.
- **Verification service indicator**: Optional, recommended claim. It is used by
a Relying Party to locate a validation service for the token. The value is a
text string that can be used to locate the service or a URL specifying the
address of the service. The claim is modeled to be eventually represented by
the EAT standard claim origination. Until such a time as that standard exists,
the claim will be represented by a custom claim. Value is encoded as text
string.
- **Profile definition**: Optional, recommended claim. It contains the name of a
document that describes the 'profile' of the token, being a full description of
the claims, their usage, verification and token signing. The document name may
include versioning. Custom claim with a value encoded as text string.
- **Implementation ID**: It represents the original implementation signer of the
attestation key and identifies the contract between the report and verification.
A verification service will use this claim to locate the details of the
verification process. Custom claim with a value encoded as byte string.
- **Security lifecycle**: It represents the current lifecycle state of the
instance. Custom claim with a value encoded as an integer.
- **Client ID**: The partition ID of that secure partition or non-secure thread
who called the initial attestation API. Custom claim with a value encoded as a
`signed` integer. Negative number represents non-secure caller, positive numbers
represents secure callers, zero is invalid.
- **HW version**: Optional claim. Globally unique number in EAN-13 format
identifying the GDSII that went to fabrication, HW and ROM. It can be used to
reference the security level of the PSA-ROT via a certification website. Custom
claim with a value is encoded as text string.
- **Boot seed**: It represents a random value created at system boot time that
will allow differentiation of reports from different system sessions. The size
is 32 bytes. Custom claim with a value is encoded as byte string.
- **Software components**: Optional, recommended claim. It represents the
software state of the system. The value of the claim is an array of CBOR map
entries, with one entry per software component within the device. Each map
contains multiple claims that describe evidence about the details of the
software component.
- **Measurement type**: Optional claim. It represents the role of the software
component. Value is encoded as short(!) text string.
- **Measurement value**: It represents a hash of the invariant software
component in memory at start-up time. The value must be a cryptographic hash
of 256 bits or stronger. Value is encoded as byte string.
- **Security epoch**: Optional claim. It represents the security control point
of the software component. Value is encoded as unsigned integer.
- **Version**: Optional claim. It represents the issued software version. Value
is encoded as text string.
- **Signer ID**: It represents the hash of a signing authority public key.
Value is encoded as byte string.
- **Measurement description**: Optional claim. It represents the way in which
the measurement value of the software component is computed. Value is encoded
as text string containing an abbreviated description (name) of the measurement
method.
- **No software measurements**: In the event that the implementation does not
contain any software measurements then the software components claim above can
be omitted but instead it is mandatory to include this claim to indicate this is
a deliberate state. Custom claim a value is encoded as an unsigned integer set
to 1.
## Initial attestation token (IAT) data encoding
The initial attestation token is planned to be aligned with future version of
[Entity Attestation Token](https://tools.ietf.org/html/draft-mandyam-eat-01)
format. The token is encoded according to the
[CBOR](https://tools.ietf.org/html/rfc7049) format and signed according to
[COSE](https://tools.ietf.org/html/rfc8152) standard.
## Code structure
The PSA interface for the Initial Attestation Service is located in
`interface/include`.
The only header to be included by applications that want to use functions from
the PSA API is `psa_initial_attestation.h`.
The TF-M Initial Attestation Service source files are located in
`secure_fw/services/initial_attestation`.
The CBOR library is located in `lib/ext/qcbor` folder.
### Service source files
- CBOR library:
- `lib/ext/qcbor`: This library is used to create a proper CBOR token. It can
be used on 32-bit and 64-bit machines. It was designed to suite constrained
devices with low memory usage and without dynamic memory allocation. It is a
fork of this external
[QCBOR library](https://github.com/laurencelundblade/QCBOR).
- `lib/ext/qcbor/inc/qcbor.h`: Public API documentation of CBOR library.
- COSE library:
- `lib/t_cose`: This library is used to sign a CBOR token and create the COSE
header and signature around the initial attestation token. Only a subset of the
[COSE](https://tools.ietf.org/html/rfc8152) standard is implemented. Only the
cose_sign1 signature schema is supported.
- `lib/t_cose/src/t_cose_crypto.h`: Expose an API to bind `t_cose` library with
available crypto library in the device.
- `lib/t_cose/src/t_cose_psa_crypto.c`: Implements the exposed API and ports
`t_cose` to psa_crypto library.
- Initial Attestation Service:
- `attestation_core.c` : Implements core functionalities such as implementation
of APIs, retrieval of claims and token creation.
- `attest_token.c`: Implements the token creation function such as start and
finish token creation and adding claims to the token.
- `attestation_crypto_stub.c`: Temporary file, it implements the missing
psa_crypto APIs.
- `attestation_key.c`: Get the attestation key from platform layer and register
it to psa_crypto service for further usage.
- `tfm_attestation.c`: Implements the SPM abstraction layer, and bind the
attestation service to the SPM implementation in TF-M project.
- `tfm_attestation_secure_api.c`: Implements the secure API layer to allow
other services in the secure domain to request functionalities from the
attestation service using the PSA API interface.
### Service interface definitions
- **Boot loader interface**: The attestation service might include data in the
token about the distinct software components in the device. This data is
provided by the boot loader and must be encoded in the TLV format, definition
is described below in the boot loader interface paragraph. Possible claims in
the boot status are describe above in the software components paragraph.
- **Hardware abstraction layer**:
- Headers are located in `platform/include` folder.
- `tfm_attest_hal.h`: Expose an API to get the following claims: security
lifecycle, verification service indicator, profile definition.
- `tfm_plat_boot_seed.h`: Expose an API to get the boot seed claim.
- `tfm_plat_device_id.h`: Expose an API to get the following claims:
implementation ID, hardware version, instance ID.
- **SPM interface**:
- `attestation.h`: Expose an API to bind attestation service to an SPM
implementation.
- **PSA interface**:
- `psa_initial_attestation.h`: Public API definition of initial attestation
service.
- **Crypto interface**:
- `t_cose_crypto.h`: Expose an API to bind the `t_cose` implementation to any
cryptographic library.
- `tfm_plat_crypto_keys.h`: Expose an API to get the attestation key from
platform layer.
### PSA interface
The TF-M Initial Attestation Service exposes the following PSA interface:
``` c
enum psa_attest_err_t
psa_initial_attest_get_token(const uint8_t *challenge_obj,
uint32_t challenge_size,
uint8_t *token,
uint32_t *token_size);
enum psa_attest_err_t
psa_initial_attest_get_token_size(uint32_t challenge_size,
uint32_t *token_size);
```
The caller must allocate a large enough buffer, where the token is going to be
created by Initial Attestation Service. The size of the created token is highly
dependent on the number of software components in the system and the provided
attributes of these.
The `psa_initial_attest_get_token_size()` function can be called to get the
exact size of the created token.
System integrators might need to port these interfaces to a custom secure
partition manager implementation (SPM). Implementation in TF-M project can be
found here:
- `interface/src/tfm_initial_attestation_api.c`: non-secure interface
implementation
- `secure_fw/services/initial_attestation/tfm_attestation_secure_api.c`: secure
interface implementation
### Secure Partition Manager (SPM) interface
The Initial Attestation Service defines the following interface towards the
secure partition manager (SPM). System integrators **must** port this
interface according to their SPM implementation.
```c
enum psa_attest_err_t
attest_get_boot_data(uint8_t major_type, void *ptr, uint32_t len);
enum psa_attest_err_t
attest_get_caller_client_id(int32_t *caller_id);
enum psa_attest_err_t
attest_check_memory_access(void *addr,
uint32_t size,
enum attest_memory_access access);
```
- `attest_get_boot_data()`: Service can retrieve the relevant data from shared
memory area between boot loader and runtime software. It might be the case that
only SPM has direct access to the shared memory area, therefore this function
can be used to copy the service related data from shared memory to a local
memory buffer. In TF-M implementation this function must be called during
service initialization phase, because the shared memory region is deliberately
overlapping with secure main stack to spare some memory and reuse this area
during execution. If boot loader is not available in the system to provide
attributes of software components then this function must be implemented in a
way that just initialize service's memory buffer to:
```c
struct shared_data_tlv_header *tlv_header =
(struct shared_data_tlv_header *)ptr;
tlv_header->tlv_magic = 2016;
tlv_header->tlv_tot_len = sizeof(struct shared_data_tlv_header *tlv_header);
```
- `attest_get_caller_client_id()`: Retrieves the ID of the caller thread.
- `attest_check_memory_access()`: Validates the availability and access rights
of memory regions received as input data: challenge object, token buffer, etc.
- `tfm_client.h`: Service relies on the following external definitions, which
must be present or included in this header file:
```c
typedef struct psa_invec {
const void *base;
size_t len;
} psa_invec;
typedef struct psa_outvec {
void *base;
size_t len;
} psa_outvec;
```
### Hardware abstraction layer:
The following API definitions are intended to retrieve the platform specific
claims. System integrators **must** implement these interface according to their
SoC and software design. Detailed definition of the claims are above in the
claims in the initial attestation token paragraph.
- `tfm_attest_hal_get_security_lifecycle()`: Get the security lifecycle of the
device.
- `tfm_attest_hal_get_verification_service()`: Get the verification service
indicator for initial attestation.
- `tfm_attest_hal_get_profile_definition()`: Get the name of the profile
definition document for initial attestation.
- `tfm_plat_get_boot_seed()`: Get the boot seed, which is a constant random
number during a boot cycle.
- `tfm_plat_get_instance_id()`: Get the UEID of the device.
- `tfm_plat_get_implementation_id`: Get the implementation ID of the device.
- `tfm_plat_get_hw_version`: Get the hardware version of the device.
### Boot loader interface
It is **recommended** to have a secure boot loader in the boot chain, which is
capable of measuring the runtime firmware components (calculates the hash value
of firmware images) and provide other attributes of these (version, type, etc).
The shared data between boot loader and runtime software is TLV encoded. The
definition of TLV structure is described in `bl2/include/tfm_boot_status.h`.
The shared data is stored in a well known location in secure internal memory
and this is a contract between boot loader and runtime SW.
The structure of shared data must be the following:
- At the beginning there must be a header: `struct shared_data_tlv_header`
This contains a magic number and a size field which covers the entire
size of the shared data area including this header.
```c
struct shared_data_tlv_header {
uint16_t tlv_magic;
uint16_t tlv_tot_len;
};
```
- After the header there come the entries which are composed from an entry
header structure: `struct shared_data_tlv_entry` and the data. In the entry
header is a type field `tlv_type` which identify the consumer of the entry
in the runtime software and specify the subtype of that data item. There is
a size field `tlv_len` which covers the size of the entry header and the
data. After this structure comes the actual data.
```c
struct shared_data_tlv_entry {
uint16_t tlv_type;
uint16_t tlv_len;
};
```
- Arbitrary number and size of data entry can be in the shared memory area.
The table below gives of overview about the `tlv_type` field in the entry
header. The `tlv_type` always composed from a major and minor number. Major
number identifies the addressee in runtime software, which the data entry is
sent to. Minor number used to encode more info about the data entry. The actual
definition of minor number could change per major number. In case of boot
status data, which is going to be processed by initial attestation service
the minor number is split further to two part: `sw_module` and `claim`. The
`sw_module` identifies the SW component in the system which the data item
belongs to and the `claim` part identifies the exact type of the data.
`tlv_type` description:
```
|------------------------------------------------ |
| tlv_type (16 bits) |
|-------------------------------------------------|
| tlv_major(4 bits) | tlv_minor(12 bits) |
|-------------------------------------------------|
| MAJOR_IAS | sw_module(6 bits) | claim(6 bits) |
|-------------------------------------------------|
| MAJOR_CORE | TBD |
|-------------------------------------------------|
```
Overall structure of shared data:
```
---------------------------------------------------------------
| Magic number(uint16_t) | Shared data total length(uint16_t) |
---------------------------------------------------------------
| Major_type(4 bits) | Minor_type(12 bits) | Length(uint16_t) |
---------------------------------------------------------------
| Raw data |
---------------------------------------------------------------
| . |
| . |
| . |
---------------------------------------------------------------
| Major_type(4 bits) | Minor_type(12 bits) | Length(uint16_t) |
---------------------------------------------------------------
| Raw data |
---------------------------------------------------------------
```
### Crypto interface
Device **must** contain an asymmetric key pair. The private part of it is used
to sign the initial attestation token. Current implementation supports only the
ECDSA P256 signature over SHA256. The public part of the key pair is used to
create the key identifier (kid) in the unprotected part of the COSE header. The
kid is used by verification entity to look up the corresponding public key to
verify the signature in the token. The `t_cose` part of the initial attestation
service implements the signature generation and kid creation. But the actual
calculation of token's hash and signature is done by the Crypto service in the
device. System integrators might need to re-implement the following functions
if they want to use initial attestation service with a different cryptographic
library than Crypto service:
- `t_cose_crypto_pub_key_sign()`: Calculates the signature over a hash value.
- `t_cose_crypto_get_ec_pub_key()`: Get the public key to create the key
identifier.
- `t_cose_crypto_hash_start()`: Start a multipart hash operation.
- `t_cose_crypto_hash_update()`: Add a message fragment to a multipart hash
operation.
- `t_cose_crypto_hash_finish()`:Finish the calculation of the hash of a message.
Interface needed by verification code:
- `t_cose_crypto_pub_key_verify()`: Verify the signature over a hash value.
#### Key handling
The provisioning of the initial attestation key is out of scope of the service
and this document. It is assumed that device maker provisions the unique
asymmetric key pair during the manufacturing process. The following API is
defined to retrieve the attestation key pair from platform layer. Software
integrators **must** port this interface according to their SoC design and make
sure that key pair is available by Crypto service:
- `tfm_plat_get_initial_attest_key()`: Retrieve the initial attestation key pair
from platform layer.
In TF-M project the attestation key is retrieved by initial attestation service.
The key is registered and unregistered to the Crypto service by attestation
service with `psa_import_key()` and `psa_destroy_key()` API calls for further
usage. See in `attestation_key.c`. In other implementation if the attestation
key is directly retrieved by the Crypto service then this key handling is not
necessary.
--------------
*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*

440
docs/user_guides/services/tfm_attestation_integration_guide.rst Normal file
View File

@ -0,0 +1,440 @@
##################################################
TF-M Initial Attestation Service Integration Guide
##################################################
************
Introduction
************
TF-M Initial Attestation Service allows the application to prove the device
identity during an authentication process to a verification entity. The initial
attestation service can create a token on request, which contains a fix set of
device specific data. Device must contain an attestation key pair, which is
unique per device. The token is signed with the private part of attestation key
pair. The public part of the key pair is known by the verification entity. The
public key is used to verify the token authenticity. The data items in the token
used to verify the device integrity and assess its trustworthiness. Attestation
key provisioning is out of scope for the attestation service and is expected to
take part during manufacturing of the device.
***************************
Current service limitations
***************************
**Signing of token**: In the current implementation the token is not properly
signed. Signature is generated according to the
`COSE <https://datatracker.ietf.org/doc/rfc8152/>`__ format. But its actual
value is not a correct ECDSA P256 signature, due to the lack of support of the
ECDSA algorithm in the current implementation of the TF-M Crypto service. A fake
signature is created, which is the concatenation of the token's hash value
twice.
***************************************
Claims in the initial attestation token
***************************************
The initial attestation token is formed of claims. A claim is a data item,
which is represented in a key - value structure. The following fixed set of
claims are included in the token:
- **Challenge**: Input object from caller. Can be a single nonce from
server or hash of nonce and attested data. It is intended to provide
freshness to report and the caller has responsibility to arrange
this. Allowed length: 32, 48, 64 bytes. The claim is modeled to be
eventually represented by the EAT standard claim nonce. Until such a
time as that standard exists, the claim will be represented by a custom
claim. Value is encoded as byte string.
- **Instance ID**: It represents the unique identifier of the instance. In
the PSA definition it is a hash of the public attestation key of the
instance. The claim is modeled to be eventually represented by the EAT
standard claim UEID of type GUID. Until such a time as that standard
exists, the claim will be represented by a custom claim Value is encoded
as byte string.
- **Verification service indicator**: Optional, recommended claim. It
is used by a Relying Party to locate a validation service for the
token. The value is a text string that can be used to locate the service
or a URL specifying the address of the service. The claim is modelled to
be eventually represented by the EAT standard claim origination. Until
such a time as that standard exists, the claim will be represented by
a custom claim. Value is encoded as text string.
- **Profile definition**: Optional, recommended claim. It contains the
name of a document that describes the 'profile' of the token, being
a full description of the claims, their usage, verification and token
signing. The document name may include versioning. Custom claim with a
value encoded as text string.
- **Implementation ID**: It represents the original implementation
signer of the attestation key and identifies the contract between the
report and verification. A verification service will use this claim
to locate the details of the verification process. Custom claim with a
value encoded as byte string.
- **Security lifecycle**: It represents the current lifecycle state of
the instance. Custom claim with a value encoded as an integer.
- **Client ID**: The partition ID of that secure partition or non-secure
thread who called the initial attestation API. Custom claim with a value
encoded as a `signed` integer. Negative number represents non-secure
caller, positive numbers represents secure callers, zero is invalid.
- **HW version**: Optional claim. Globally unique number in EAN-13 format
identifying the GDSII that went to fabrication, HW and ROM. It can be
used to reference the security level of the PSA-ROT via a certification
website. Custom claim with a value is encoded as text string.
- **Boot seed**: It represents a random value created at system boot
time that will allow differentiation of reports from different system
sessions. The size is 32 bytes. Custom claim with a value is encoded as
byte string.
- **Software components**: Optional, recommended claim. It represents
the software state of the system. The value of the claim is an array
of CBOR map entries, with one entry per software component within the
device. Each map contains multiple claims that describe evidence about
the details of the software component.
- **Measurement type**: Optional claim. It represents the role of the
software component. Value is encoded as short(!) text string.
- **Measurement value**: It represents a hash of the invariant software
component in memory at start-up time. The value must be a cryptographic
hash of 256 bits or stronger. Value is encoded as byte string.
- **Security epoch**: Optional claim. It represents the security control
point of the software component. Value is encoded as unsigned integer.
- **Version**: Optional claim. It represents the issued software
version. Value is encoded as text string.
- **Signer ID**: It represents the hash of a signing authority public key.
Value is encoded as byte string.
- **Measurement description**: Optional claim. It represents the way in
which the measurement value of the software component is computed. Value
is encoded as text string containing an abbreviated description (name)
of the measurement method.
- **No software measurements**: In the event that the implementation
does not contain any software measurements then the software components
claim above can be omitted but instead it is mandatory to include this
claim to indicate this is a deliberate state. Custom claim a value is
encoded as an unsigned integer set to 1.
*********************************************
Initial attestation token (IAT) data encoding
*********************************************
The initial attestation token is planned to be aligned with future version of
`Entity Attestation Token <https://tools.ietf.org/html/draft-mandyam-eat-01>`__
format. The token is encoded according to the
`CBOR <https://tools.ietf.org/html/rfc7049>`__ format and signed according to
`COSE <https://tools.ietf.org/html/rfc8152>`__ standard.
**************
Code structure
**************
The PSA interface for the Initial Attestation Service is located in
``interface/include``. The only header to be included by applications that want
to use functions from the PSA API is ``psa_initial_attestation.h``.
The TF-M Initial Attestation Service source files are located in
``secure_fw/services/initial_attestation``.
The CBOR library is located in ``lib/ext/qcbor`` folder.
Service source files
====================
- CBOR library
- ``lib/ext/qcbor`` This library is used to create a proper CBOR token.
It can be used on 32-bit and 64-bit machines. It was designed to suite
constrained devices with low memory usage and without dynamic memory
allocation.
It is a fork of this external `QCBOR library <https://github.com/laurencelundblade/QCBOR>`__.
- ``lib/ext/qcbor/inc/qcbor.h``: Public API documentation of CBOR
library.
- COSE library:
- ``lib/t_cose``: This library is used to sign a CBOR token and create
the COSE header and signature around the initial attestation token. Only
a subset of the `COSE <https://tools.ietf.org/html/rfc8152>`__ standard
is implemented. Only the cose_sign1 signature schema is supported.
- ``lib/t_cose/src/t_cose_crypto.h``: Expose an API to bind ``t_cose``
library with available crypto library in the device.
- ``lib/t_cose/src/t_cose_psa_crypto.c``: Implements the exposed API
and ports ``t_cose`` to psa_crypto library.
- Initial Attestation Service:
- ``attestation_core.c`` : Implements core functionalities such as
implementation of APIs, retrieval of claims and token creation.
- ``attest_token.c``: Implements the token creation function such as
start and finish token creation and adding claims to the token.
- ``attestation_crypto_stub.c``: Temporary file, it implements the
missing psa_crypto APIs.
- ``attestation_key.c``: Get the attestation key from platform layer
and register it to psa_crypto service for further usage.
- ``tfm_attestation.c``: Implements the SPM abstraction layer, and bind
the attestation service to the SPM implementation in TF-M project.
- ``tfm_attestation_secure_api.c``: Implements the secure API layer to
allow other services in the secure domain to request functionalities
from the attestation service using the PSA API interface.
Service interface definitions
=============================
- **Boot loader interface**: The attestation service might include data
in the token about the distinct software components in the device. This data
is provided by the boot loader and must be encoded in the TLV format,
definition is described below in the boot loader interface paragraph. Possible
claims in the boot status are describe above in the software components
paragraph.
- **Hardware abstraction layer**:
- Headers are located in ``platform/include`` folder.
- ``tfm_attest_hal.h``: Expose an API to get the following claims:
security lifecycle, verification service indicator, profile definition.
- ``tfm_plat_boot_seed.h``: Expose an API to get the boot seed claim.
- ``tfm_plat_device_id.h``: Expose an API to get the following claims:
implementation ID, hardware version, instance ID.
- **SPM interface**:
- ``attestation.h``: Expose an API to bind attestation service to an SPM
implementation.
- **PSA interface**:
- ``psa_initial_attestation.h``: Public API definition of initial
attestation service.
- **Crypto interface**:
- ``t_cose_crypto.h``: Expose an API to bind the ``t_cose`` implementation
to any cryptographic library.
- ``tfm_plat_crypto_keys.h``: Expose an API to get the attestation key from
platform layer.
PSA interface
=============
The TF-M Initial Attestation Service exposes the following PSA
interface:
.. code-block:: c
enum psa_attest_err_t
psa_initial_attest_get_token(const uint8_t *challenge_obj,
uint32_t challenge_size,
uint8_t *token,
uint32_t *token_size);
enum psa_attest_err_t
psa_initial_attest_get_token_size(uint32_t challenge_size,
uint32_t *token_size);
The caller must allocate a large enough buffer, where the token is going to be
created by Initial Attestation Service. The size of the created token is highly
dependent on the number of software components in the system and the provided
attributes of these. The ``psa_initial_attest_get_token_size()`` function can be
called to get the exact size of the created token.
System integrators might need to port these interfaces to a custom secure
partition manager implementation (SPM). Implementation in TF-M project can be
found here:
- ``interface/src/tfm_initial_attestation_api.c``: non-secure interface
implementation
- ``secure_fw/services/initial_attestation/tfm_attestation_secure_api.c``:
secure interface implementation
Secure Partition Manager (SPM) interface
========================================
The Initial Attestation Service defines the following interface towards the
secure partition manager (SPM). System integrators **must** port this interface
according to their SPM implementation.
.. code:: c
enum psa_attest_err_t
attest_get_boot_data(uint8_t major_type, void *ptr, uint32_t len);
enum psa_attest_err_t
attest_get_caller_client_id(int32_t *caller_id);
enum psa_attest_err_t
attest_check_memory_access(void *addr,
uint32_t size,
enum attest_memory_access access);
- ``attest_get_boot_data()``: Service can retrieve the relevant data from shared
memory area between boot loader and runtime software. It might be the case
that only SPM has direct access to the shared memory area, therefore this
function can be used to copy the service related data from shared memory to
a local memory buffer. In TF-M implementation this function must be called
during service initialization phase, because the shared memory region is
deliberately overlapping with secure main stack to spare some memory and reuse
this area during execution. If boot loader is not available in the system to
provide attributes of software components then this function must be
implemented in a way that just initialize service's memory buffer to:
.. code-block:: c
struct shared_data_tlv_header *tlv_header = (struct shared_data_tlv_header *)ptr;
tlv_header->tlv_magic = 2016;
tlv_header->tlv_tot_len = sizeof(struct shared_data_tlv_header *tlv_header);
- ``attest_get_caller_client_id()``: Retrieves the ID of the caller thread.
- ``attest_check_memory_access()``: Validates the availability and access rights
of memory regions received as input data: challenge object, token buffer, etc.
- ``tfm_client.h``: Service relies on the following external definitions, which
must be present or included in this header file:
.. code-block:: c
typedef struct psa_invec {
const void *base;
size_t len;
} psa_invec;
typedef struct psa_outvec {
void *base;
size_t len;
} psa_outvec;
Hardware abstraction layer
==========================
The following API definitions are intended to retrieve the platform specific
claims. System integrators **must** implement these interface according to their
SoC and software design. Detailed definition of the claims are above
in the claims in the initial attestation token paragraph.
- ``tfm_attest_hal_get_security_lifecycle()``: Get the security lifecycle of the
device.
- ``tfm_attest_hal_get_verification_service()``: Get the verification
service indicator for initial attestation.
- ``tfm_attest_hal_get_profile_definition()``: Get the name of the profile
definition document for initial attestation.
- ``tfm_plat_get_boot_seed()``: Get the boot seed, which is a constant random
number during a boot cycle.
- ``tfm_plat_get_instance_id()``: Get the UEID of the device.
- ``tfm_plat_get_implementation_id``: Get the implementation ID of the
device.
- ``tfm_plat_get_hw_version``: Get the hardware version of the device.
Boot loader interface
=====================
It is **recommended** to have a secure boot loader in the boot chain, which is
capable of measuring the runtime firmware components (calculates the hash value
of firmware images) and provide other attributes of these (version, type, etc).
The shared data between boot loader and runtime software is TLV encoded. The
definition of TLV structure is described in ``bl2/include/tfm_boot_status.h``.
The shared data is stored in a well known location in secure internal memory
and this is a contract between boot loader and runtime SW.
The structure of shared data must be the following:
- At the beginning there must be a header: ``struct shared_data_tlv_header``
This contains a magic number and a size field which covers the entire size
of the shared data area including this header.
.. code-block:: c
struct shared_data_tlv_header {
uint16_t tlv_magic;
uint16_t tlv_tot_len;
};
- After the header there come the entries which are composed from an
entry header structure: ``struct shared_data_tlv_entry`` and the data. In
the entry header is a type field ``tlv_type`` which identify the consumer of
the entry in the runtime software and specify the subtype of that data item.
There is a size field ``tlv_len`` which covers the size of the entry header
and the data. After this structure comes the actual data.
.. code-block:: c
struct shared_data_tlv_entry {
uint16_t tlv_type;
uint16_t tlv_len;
};
- Arbitrary number and size of data entry can be in the shared memory
area.
The figure below gives of overview about the ``tlv_type`` field in the entry
header. The ``tlv_type`` always composed from a major and minorbnumber. Major
number identifies the addressee in runtime software, which the databentry is
sent to. Minor number used to encode more info about the data entry. The actual
definition of minor number could change per major number. In case of boot
status data, which is going to be processed by initial attestation service
the minor number is split further to two part: ``sw_module`` and ``claim``. The
``sw_module`` identifies the SW component in the system which the data item
belongs to and the ``claim`` part identifies the exact type of the data.
``tlv_type`` description::
|------------------------------------------------ |
| tlv_type (16 bits) |
|-------------------------------------------------|
| tlv_major(4 bits) | tlv_minor(12 bits) |
|-------------------------------------------------|
| MAJOR_IAS | sw_module(6 bits) | claim(6 bits) |
|-------------------------------------------------|
| MAJOR_CORE | TBD |
|-------------------------------------------------|
Overall structure of shared data::
---------------------------------------------------------------
| Magic number(uint16_t) | Shared data total length(uint16_t) |
---------------------------------------------------------------
| Major_type(4 bits) | Minor_type(12 bits) | Length(uint16_t) |
---------------------------------------------------------------
| Raw data |
---------------------------------------------------------------
| . |
| . |
| . |
---------------------------------------------------------------
| Major_type(4 bits) | Minor_type(12 bits) | Length(uint16_t) |
---------------------------------------------------------------
| Raw data |
---------------------------------------------------------------
Crypto interface
================
Device **must** contain an asymmetric key pair. The private part of it is used
to sign the initial attestation token. Current implementation supports only the
ECDSA P256 signature over SHA256. The public part of the key pair is used to
create the key identifier (kid) in the unprotected part of the COSE header. The
kid is used by verification entity to look up the corresponding public key to
verify the signature in the token. The `t_cose` part of the initial attestation
service implements the signature generation and kid creation. But the actual
calculation of token's hash and signature is done by the Crypto service in the
device. System integrators might need to re-implement the following functions
if they want to use initial attestation service with a different cryptographic
library than Crypto service:
- ``t_cose_crypto_pub_key_sign()``: Calculates the signature over a hash value.
- ``t_cose_crypto_get_ec_pub_key()``: Get the public key to create the key
identifier.
- ``t_cose_crypto_hash_start()``: Start a multipart hash operation.
- ``t_cose_crypto_hash_update()``: Add a message fragment to a multipart hash
operation.
- ``t_cose_crypto_hash_finish()``:Finish the calculation of the hash of a
message.
Interface needed by verification code:
- ``t_cose_crypto_pub_key_verify()``: Verify the signature over a hash value.
Key handling
------------
The provisioning of the initial attestation key is out of scope of the service
and this document. It is assumed that device maker provisions the unique
asymmetric key pair during the manufacturing process. The following API is
defined to retrieve the attestation key pair from platform layer. Software
integrators **must** port this interface according to their SoC design and make
sure that key pair is available by Crypto service:
- ``tfm_plat_get_initial_attest_key()``: Retrieve the initial attestation key
pair from platform layer.
In TF-M project the attestation key is retrieved by initial attestation service.
The key is registered and unregistered to the Crypto service by attestation
service with ``psa_import_key()`` and ``psa_destroy_key()`` API calls for
further usage. See in ``attestation_key.c``. In other implementation if the
attestation key is directly retrieved by the Crypto service then this key
handling is not necessary.
--------------
*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*

116
docs/user_guides/services/tfm_audit_integration_guide.md
View File

@ -1,116 +0,0 @@
# TF-M Audit Logging Service Integration Guide
## Introduction
TF-M Audit logging service allows secure services in the system to log critical
system events and information that have security implications. This is required
to post analyse the system behaviour, system events and triage system issues
offline. This offers a mitigation against the repudiation threat.
The types of information that can be logged are the ID of the entity that
originated a secure service request, or the relevant output or data
associated to the authentication mechanism that the requesting service
has performed on the entity that originated the request. The possible types of
information that can be logged can be easily extended to accomodate various
requirements from other secure services.
## Current service limitations
**Policy manager** - Currently, there is no policy manager implemented, which
means that there are no restrictions on the entities which can add or remove
items from the log. Also, the item replacement in the log is just replacing
older elements first.
**Encryption** - Support for encryption and authentication is not available yet.
**Permanent storage** - Currently the Audit Logging service supports only a RAM
based storage of the log, permanent storage is not supported yet.
## Code structure
The PSA interfaces for the Audit logging service are located in
`interface/include`.
The TF-M Audit logging service source files are located in
`secure_fw/services/audit_logging`.
### PSA interfaces
The TF-M Audit logging service exposes the following PSA interfaces:
- `enum psa_audit_err psa_audit_retrieve_record(const uint32_t record_index,
const uint32_t buffer_size, const uint8_t *token, const uint32_t token_size,
uint8_t *buffer, uint32_t *record_size);`
- `enum psa_audit_err psa_audit_get_info(uint32_t *num_records, uint32_t
*size);`
- `enum psa_audit_err psa_audit_get_record_info(const uint32_t record_index,
uint32_t *size);`
- `enum psa_audit_err psa_audit_delete_record(const uint32_t record_index,
const uint8_t *token, const uint32_t token_size);`
The TF-M Audit logging service exposes an additional PSA interface which can
only be called from secure services:
- `enum psa_audit_err psa_audit_add_record(const struct psa_audit_record
*record);`
### Service source files
- `audit_core.c` : This file implements core functionalities such as log
management, record addition and deletion and extraction of record information;
- `audit_wrappers.c` : This file implements TF-M compatible wrappers in
case they are needed by the functions exported by the core.
## Audit logging service integration guide
In this section, a brief description of each field of a log record is given,
with an example on how to perform a logging request from a secure service.
The secure service that requests the addition of a record to the log has to
provide data as described by the `psa_audit_record` type, defined in
`interface\include\psa_audit_defs.h`:
```
/*!
* \struct psa_audit_record
*
* \brief This structure contains the record that is added to the audit log
* by the requesting secure service
*/
struct psa_audit_record {
uint32_t size; /*!< Size in bytes of the id and payload fields */
uint32_t id; /*!< ID of the record */
uint8_t payload[]; /*!< Flexible array member for payload */
};
```
Each field is described as follows:
- `size` - This is the size, in bytes, of the `id` and `payload[]` fields that
follow. Given that the `payload[]` field is optional, in the current
implementation the minimum value to be provided in `size` is 4 bytes;
- `id` - This field is meant to be used to store an ID of the log record from
the requesting service;
- `payload[]` - The payload is an optional content which can be made of one or
more Type-Length-Value entries as described by the following type:
```
/*!
* \struct audit_tlv_entry
*
* \brief TLV entry structure with a flexible
* array member
*/
struct audit_tlv_entry {
enum audit_tlv_type type;
uint32_t length;
uint8_t value[];
};
```
The possible TLV types described by `enum audit_tlv_type` can be extended by
system integrators modifying `audit_core.h` as needed.
A logging request is performed by a secure service which calls the Secure-only
API function `psa_audit_add_record()`.
--------------
*Copyright (c) 2018, Arm Limited. All rights reserved.*

134
docs/user_guides/services/tfm_audit_integration_guide.rst Normal file
View File

@ -0,0 +1,134 @@
############################################
TF-M Audit Logging Service Integration Guide
############################################
************
Introduction
************
TF-M Audit logging service allows secure services in the system to log critical
system events and information that have security implications. This is required
to post analyse the system behaviour, system events and triage system issues
offline. This offers a mitigation against the repudiation threat.
The types of information that can be logged are the ID of the entity that
originated a secure service request, or the relevant output or data
associated to the authentication mechanism that the requesting service
has performed on the entity that originated the request. The possible types of
information that can be logged can be easily extended to accommodate various
requirements from other secure services.
***************************
Current service limitations
***************************
- **Policy manager** - Currently, there is no policy manager implemented, which
means that there are no restrictions on the entities which can add or remove
items from the log. Also, the item replacement in the log is just replacing
older elements first.
- **Encryption** - Support for encryption and authentication is not available
yet.
- **Permanent storage** - Currently the Audit Logging service supports only a
RAM based storage of the log, permanent storage is not supported yet.
**************
Code structure
**************
The PSA interfaces for the Audit logging service are located in
``interface/include``.
The TF-M Audit logging service source files are located in
``secure_fw/services/audit_logging``.
PSA interfaces
==============
The TF-M Audit logging service exposes the following PSA interfaces:
.. code-block:: c
enum psa_audit_err psa_audit_retrieve_record(const uint32_t record_index,
const uint32_t buffer_size, const uint8_t *token, const uint32_t token_size,
uint8_t *buffer, uint32_t *record_size);
enum psa_audit_err psa_audit_get_info(uint32_t *num_records, uint32_t
*size);
enum psa_audit_err psa_audit_get_record_info(const uint32_t record_index,
uint32_t *size);
enum psa_audit_err psa_audit_delete_record(const uint32_t record_index,
const uint8_t *token, const uint32_t token_size);
The TF-M Audit logging service exposes an additional PSA interface which can
only be called from secure services:
.. code-block:: c
enum psa_audit_err psa_audit_add_record(const struct psa_audit_record
*record);
Service source files
====================
- ``audit_core.c`` : This file implements core functionalities such as log
management, record addition and deletion and extraction of record information.
- ``audit_wrappers.c`` : This file implements TF-M compatible wrappers in case
they are needed by the functions exported by the core.
***************************************
Audit logging service integration guide
***************************************
In this section, a brief description of each field of a log record is given,
with an example on how to perform a logging request from a secure service.
The secure service that requests the addition of a record to the log has to
provide data as described by the ``psa_audit_record`` type, defined in
``interface\include\psa_audit_defs.h``:
.. code-block:: c
/*!
* \struct psa_audit_record
*
* \brief This structure contains the record that is added to the audit log
* by the requesting secure service
*/
struct psa_audit_record {
uint32_t size; /*!< Size in bytes of the id and payload fields */
uint32_t id; /*!< ID of the record */
uint8_t payload[]; /*!< Flexible array member for payload */
};
Each field is described as follows:
- ``size`` - This is the size, in bytes, of the ``id`` and ``payload[]`` fields
that follow. Given that the ``payload[]`` field is optional, in the current
implementation the minimum value to be provided in ``size`` is 4 bytes;
- ``id`` - This field is meant to be used to store an ID of the log record from
the requesting service
- ``payload[]`` - The payload is an optional content which can be made
of one or more Type-Length-Value entries as described by the following type:
.. code-block:: c
/*!
* \struct audit_tlv_entry
*
* \brief TLV entry structure with a flexible
* array member
*/
struct audit_tlv_entry {
enum audit_tlv_type type;
uint32_t length;
uint8_t value[];
};
The possible TLV types described by ``enum audit_tlv_type`` can be extended by
system integrators modifying ``audit_core.h`` as needed. A logging request is
performed by a secure service which calls the
Secure-only API function ``psa_audit_add_record()``.
--------------
*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*

86
docs/user_guides/services/tfm_crypto_integration_guide.md
View File

@ -1,86 +0,0 @@
# TF-M Crypto Service Integration Guide
## Introduction
TF-M Crypto service allows application to use cryptography primitives such as
symmetric and asymmetric ciphers, hash, message authentication codes (MACs) and
authenticated encryption with associated data (AEAD).
## Code structure
The PSA interfaces for the Crypto service are located in `interface\include`.
The only header to be included by applications that want to use functions from
the PSA API is `psa_crypto.h`.
The TF-M Crypto service source files are located in `secure_fw\services\crypto`.
### PSA interfaces
The TF-M Crypto service exposes the PSA interfaces detailed in the header
`psa_crypto.h`. There are two additional header files, named
`psa_crypto_extra.h` and `psa_crypto_platform.h`, which are meant to be included
only by the `psa_crypto.h` header itself, that specify, respectively, extensions
to the API that are vendor specific, and provide definitions and types which are
platform specific. For a detailed description of the PSA API interface, please
refer to the comments in the `psa_crypto.h` header itself.
### Service source files
- `crypto_cipher.c` : This file implements functionalities related to the
ciphering module;
- `crypto_hash.c` : This file implements functionalities related to the
hashing module;
- `crypto_init.c` : This file provides basic functions to initialise the
secure service during TF-M boot;
- `crypto_key.c` : This file implements functionalities related to the key
management module. The `TFM_CRYPTO_KEY_STORAGE_NUM` determines how many key
stores are available, while the `TFM_CRYPTO_MAX_KEY_LENGTH` defines the
maximum allowed key length in bytes supported in a key storage. These two
items can be modfied at the build configuration step by defining the
following variables, `-DCRYPTO_KEY_STORAGE_NUM=<value>` and the
`-DCRYPTO_KEY_MAX_KEY_LENGTH=<value>`;
- `crypto_alloc.c` : This file implements extensions to the PSA interface
which are specifically required by the TF-M Crypto service, in particular
related to the allocation and deallocation of crypto operation contexts in
the secure world. The `TFM_CRYPTO_CONC_OPER_NUM`, defined in this file,
determines how many concurrent contexts are supported (8 for the current
implementation). For multipart cipher/hash/MAC operations, a context is
associated to the handle provided during the setup phase, and is explicitly
cleared only following a successful termination or an abort;
- `crypto_engine.c` : This file implements the layer which the other modules
use to interact with the cryptography primitives available (in SW or HW). The
`TFM_CRYPTO_ENGINE_BUF_SIZE` determines the size in bytes of the static scratch
buffer used by this layer for its internal allocations. This item can be
modified at the build configuration step by defining
`-DCRYPTO_ENGINE_BUF_SIZE=<value>`. The current implementation provides only SW
primitives based on Mbed TLS functions;
- `crypto_mac.c` : This file implements functionalities related to the
MAC (Message Authentication Code) module;
- `crypto_aead.c` : This file implements functionalities related to the AEAD
(Authenticated Encryption with Associated Data) module.
## Crypto service integration guide
In this section, a brief description of the required flow of operation for the
functionalities exported by the PSA Crypto interface is given, with particular
focus on the TF-M Crypto service specific operations. For the details of the
generic PSA Crypto interface operations, please refer directly to the header
`psa_crypto.h`.
Most of the PSA Crypto APIs require an operation context to be allocated by the
application and then to be passed as a pointer during the following API calls.
These operation contexts are of four main types describes below:
- `psa_key_policy_t` - Operation context to be used when setting key policies;
- `psa_hash_operation_t` - Operation context for multipart hash operations;
- `psa_mac_operation_t` - Operation context for multipart MAC operations;
- `psa_cipher_operation_t` - Operation context for multipart cipher operations.
The user applications are not allowed to make any assumption about the original
types behind these typedefs, which are defined inside `psa_crypto.h`.
In the scope of the TF-M Crypto service, these types are regarded as
handles to the corresponding implementation defined structures which are stored
in the Secure world.
--------------
*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*

92
docs/user_guides/services/tfm_crypto_integration_guide.rst Normal file
View File

@ -0,0 +1,92 @@
#####################################
TF-M Crypto Service Integration Guide
#####################################
************
Introduction
************
TF-M Crypto service allows application to use cryptography primitives such as
symmetric and asymmetric ciphers, hash, message authentication codes (MACs) and
authenticated encryption with associated data (AEAD).
**************
Code structure
**************
The PSA interfaces for the Crypto service are located in ``interface\include``.
The only header to be included by applications that want to use functions from
the PSA API is ``psa_crypto.h``.
The TF-M Crypto service source files are located in
``secure_fw\services\crypto``.
PSA interfaces
==============
The TF-M Crypto service exposes the PSA interfaces detailed in the header
``psa_crypto.h``. There are two additional header files, named
``psa_crypto_extra.h`` and ``psa_crypto_platform.h``, which are meant to be
included only by the ``psa_crypto.h`` header itself, that specify, respectively,
extensions to the API that are vendor specific, and provide definitions and
types which are platform specific. For a detailed description of the PSA API
interface, please refer to the comments in the ``psa_crypto.h`` header itself.
Service source files
====================
- ``crypto_cipher.c`` : This file implements functionalities related to the
ciphering module
- ``crypto_hash.c`` : This file implements functionalities related to
the hashing module
- ``crypto_init.c`` : This file provides basic functions to initialise
the secure service during TF-M boot;
- ``crypto_key.c`` : This file implements functionalities related to
the key management module. The ``TFM_CRYPTO_KEY_STORAGE_NUM`` determines how
many key stores are available, while the ``TFM_CRYPTO_MAX_KEY_LENGTH`` defines
the maximum allowed key length in bytes supported in a key storage. These
two items can be modfied at the build configuration step by defining the
following variables, ``-DCRYPTO_KEY_STORAGE_NUM=<value>`` and the
``-DCRYPTO_KEY_MAX_KEY_LENGTH=<value>``
- ``crypto_alloc.c`` : This file implements extensions to the PSA interface
which are specifically required by the TF-M Crypto service, in particular
related to the allocation and deallocation of crypto operation contexts in
the secure world. The ``TFM_CRYPTO_CONC_OPER_NUM``, defined in this file,
determines how many concurrent contexts are supported (8 for the current
implementation). For multipart cipher/hash/MAC operations, a context is
associated to the handle provided during the setup phase, and is explicitly
cleared only following a successful termination or an abort
- ``crypto_engine.c`` : This file implements the layer which the other
modules use to interact with the cryptography primitives available (in SW or
HW). The ``TFM_CRYPTO_ENGINE_BUF_SIZE`` determines the size in bytes of the
static scratch buffer used by this layer for its internal allocations. This
item can be modified at the build configuration step by defining
``-DCRYPTO_ENGINE_BUF_SIZE=<value>``. The current implementation provides only
SW primitives based on Mbed TLS functions
- ``crypto_mac.c`` : This file implements functionalities related to the
MAC (Message Authentication Code) module
- ``crypto_aead.c`` : This file implements functionalities related to the AEAD
(Authenticated Encryption with Associated Data) module.
********************************
Crypto service integration guide
********************************
n this section, a brief description of the required flow of operation for the
functionalities exported by the PSA Crypto interface is given, with particular
focus on the TF-M Crypto service specific operations. For the details of the
generic PSA Crypto interface operations, please refer directly to the header
``psa_crypto.h``.
Most of the PSA Crypto APIs require an operation context to be allocated by the
application and then to be passed as a pointer during the following API calls.
These operation contexts are of four main types describes below:
- ``psa_key_policy_t`` - Operation context to be used when setting key policies
- ``psa_hash_operation_t`` - Operation context for multipart hash operations
- ``psa_mac_operation_t`` - Operation context for multipart MAC operations
- ``psa_cipher_operation_t`` - Operation context for multipart cipher operations
The user applications are not allowed to make any assumption about the original
types behind these typedefs, which are defined inside ``psa_crypto.h``.
In the scope of the TF-M Crypto service, these types are regarded as handles to
the corresponding implementation defined structures which are stored in the
Secure world.
--------------
*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*

100
docs/user_guides/services/tfm_platform_integration_guide.md
View File

@ -1,100 +0,0 @@
# TF-M Platform Service Integration Guide
## Introduction
TF-M Platform service is a trusted service which allows secure partitions and
non-secure applications to interact with some platform-specific components.
There are a number of features which requires some interaction with
platform-specific components which are at the same time essential for the
security of the system.
Therefore, those components need to be handled by a secure partition which is
part of the trusted compute base.
These platform-specific components include system reset, power management,
Debug, GPIO, etc.
## TF-M Platform interfaces
The TF-M interfaces for the Platform service are located in
`interface/include/`.
The TF-M Platform service source files are located in
`secure_fw/services/platform`.
## TF-M Platform service
The Platform service exposes the following interfaces:
- `enum tfm_platform_err_t tfm_platform_system_reset(void)`
The Platform service interfaces and types are defined and documented in
`interface/include/tfm_platform_api.h`
- `platform_sp.h/c` : These files define and implement functionalities related
to the platform service;
- `tfm_platform_secure_api.c` : This file implements `tfm_platform_api.h`
functions to be called from the secure partitions. This is the entry point when
the secure partitions request an action to the Platform service
(e.g system reset).
## Platform HAL system reset
The Platform service service relies on a platform-specific implementation to
perform some functionalities (e.g. system reset). The platform-specific
implementation of those APIs will be located in the platform service code
section (TF-M level 3 isolation) in order to protect it from a direct call from
other secure partitions.
For API specification, please check:
`platform/include/tfm_platform_system.h`
An implementation is provided in all the supported platforms. Please,
check `platform/ext/target/<SPECIFIC_TARGET_FOLDER>/tfm_platform_system.c`
The API **must** be implemented by the system integrators for their targets.
## Platform pin service
This service is designed to perform secure pin services of the platform
(e.g alternate function setting, pin mode setting, etc).
The veneer implementation follows IOVEC API implementation, which allows
the NS application to pack many pin service requests into one service call
to reduce the overhead of the Secure-Non-Secure context switch.
Since packing many service requests into one call is application and use-case
specific, the API implementations in tfm_platform_api.c and
tfm_platform_secure_api.c follow the one service in one veneer call design but
the service implementation in tfm_platform_system.c is prepared to serve packed
requests.
## Current Service Limitations
The system reset functionality is only supported in isolation level 1.
Currently, the mechanism by which PRoT services should run in privileged mode in
level 3, it is not in place due to an ongoing work in TF-M Core. So, the
NVIC_SystemReset call performed by the service, it is expected to generate a
memory fault when it tries to access the SCB->AIRCR register in level 3
isolation.
## Debug authentication settings
A platform may provide the option to configure debug authentication. TF-M core
calls the HAL function `void tfm_spm_hal_init_debug(void)` which configures
debug outhentication based on the following defines:
- `DAUTH_NONE`: Debugging the system is not enabled.
- `DAUTH_NS_ONLY`: Invasive and non invasive debugging of non-secure code is
enabled.
- `DAUTH_FULL`: Invasive and non-invasive debugging of non-secure and secure
code is enabled.
- `DAUTH_CHIP_DEFAULT`: The debug auhentication options are used that are set
by the chip vendor.
The desired debug authentication configuration can be selected by setting one of
the options above to the cmake command with the
`-DDEBUG_AUTHENTICATION="<define>"` option. The default value of
`DEBUG_AUTHENTICATION` is `DAUTH_CHIP_DEFAULT`.
*Note*: `void tfm_spm_hal_init_debug(void)` is called during the TF-M core
initialisation phase, before initialising secure partition. This means that BL2
runs with the chip default setting.
--------------
*Copyright (c) 2019, Arm Limited. All rights reserved.*

117
docs/user_guides/services/tfm_platform_integration_guide.rst Normal file
View File

@ -0,0 +1,117 @@
#######################################
TF-M Platform Service Integration Guide
#######################################
************
Introduction
************
TF-M Platform service is a trusted service which allows secure partitions and
non-secure applications to interact with some platform-specific components.
There are a number of features which requires some interaction with
platform-specific components which are at the same time essential for the
security of the system.
Therefore, those components need to be handled by a secure partition which is
part of the trusted compute base.
These platform-specific components include system reset, power management,
Debug, GPIO, etc.
************************
TF-M Platform interfaces
************************
The TF-M interfaces for the Platform service are located in
``interface/include/``.
The TF-M Platform service source files are located in
``secure_fw/services/platform``.
*********************
TF-M Platform service
*********************
The Platform service exposes the following interfaces:
.. code-block:: c
enum tfm_platform_err_t tfm_platform_system_reset(void)
The Platform service interfaces and types are defined and documented in
``interface/include/tfm_platform_api.h``
- ``platform_sp.h/c`` : These files define and implement functionalities related
to the platform service
- ``tfm_platform_secure_api.c`` : This file implements ``tfm_platform_api.h``
functions to be called from the secure partitions. This is the entry point
when the secure partitions request an action to the Platform service
(e.g system reset).
*************************
Platform HAL system reset
*************************
The Platform service service relies on a platform-specific implementation to
perform some functionalities (e.g. system reset). The platform-specific
implementation of those APIs will be located in the platform service code
section (TF-M level 3 isolation) in order to protect it from a direct call from
other secure partitions.
For API specification, please check: ``platform/include/tfm_platform_system.h``
An implementation is provided in all the supported platforms. Please,
check ``platform/ext/target/<SPECIFIC_TARGET_FOLDER>/tfm_platform_system.c``
The API **must** be implemented by the system integrators for their targets.
The API **must** be implemented by the system integrators for their
targets.
********************
Platform pin service
********************
This service is designed to perform secure pin services of the platform
(e.g alternate function setting, pin mode setting, etc).
The veneer implementation follows IOVEC API implementation, which allows
the NS application to pack many pin service requests into one service call
to reduce the overhead of the Secure-Non-Secure context switch.
Since packing many service requests into one call is application and use-case
specific, the API implementations in ``tfm_platform_api.c`` and
```tfm_platform_secure_api.c`` follow the one service in one veneer call design
but the service implementation in tfm_platform_system.c is prepared to serve
packed requests.
***************************
Current Service Limitations
***************************
- **system reset** - The system reset functionality is only supported in
isolation level 1. Currently, the mechanism by which PRoT services should run
in privileged mode in level 3, it is not in place due to an ongoing work in
TF-M Core. So, the ``NVIC_SystemReset`` call performed by the service, is
expected to generate a memory fault when it tries to access the ``SCB->AIRCR``
register in level 3 isolation.
*****************************
Debug authentication settings
*****************************
A platform may provide the option to configure debug authentication. TF-M core
calls the HAL function ``void tfm_spm_hal_init_debug(void)`` which configures
debug authentication based on the following defines:
- `DAUTH_NONE`: Debugging the system is not enabled.
- `DAUTH_NS_ONLY`: Invasive and non invasive debugging of non-secure code is
enabled.
- `DAUTH_FULL`: Invasive and non-invasive debugging of non-secure and secure
code is enabled.
- `DAUTH_CHIP_DEFAULT`: The debug auhentication options are used that are set
by the chip vendor.
The desired debug authentication configuration can be selected by setting one of
the options above to the cmake command with the
`-DDEBUG_AUTHENTICATION="<define>"` option. The default value of
`DEBUG_AUTHENTICATION` is `DAUTH_CHIP_DEFAULT`.
.. Note::
`void tfm_spm_hal_init_debug(void)` is called during the TF-M core
initialisation phase, before initialising secure partition. This means that BL2
runs with the chip default setting.
--------------
*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*

360
docs/user_guides/services/tfm_sst_integration_guide.md
View File

@ -1,360 +0,0 @@
# TF-M Secure Storage Service Integration Guide
## Introduction
TF-M secure storage (SST) service implements PSA Protected Storage APIs.
The service is backed by hardware isolation of the flash access domain and, in
the current version, relies on hardware to isolate the flash area from
non-secure access. In absence of hardware level isolation, the secrecy and
integrity of data is still maintained.
The current SST service design relies on hardware abstraction level provided
by TF-M. The SST service provides a non-hierarchical storage model, as a
filesystem, where all the assets are managed by linearly indexed list of
metadata.
The SST service implements an AES-GCM based AEAD encryption policy, as a
reference, to protect data integrity and authenticity.
The design addresses the following high level requirements as well:
**Confidentiality** - Resistance to unauthorised accesses through
hardware/software attacks.
**Access Authentication** - Mechanism to establish requester's identity (a
non-secure entity, secure entity, or a remote server).
**Integrity** - Resistant to tampering by either the normal users of a product,
package, or system or others with physical access to it. If the content of the
secure storage is changed maliciously, the service is able to detect it.
**Reliability** - Resistant to power failure scenarios and
incomplete write cycles.
**Configurability** - High level configurability to scale up/down memory
footprint to cater for a variety of devices with varying security requirements.
**Performance** - Optimized to be used for resource constrained devices with
very small silicon footprint, the PPA (power, performance, area) should be
optimal.
## Current SST Service Limitations
**Fragmentation** - The current design does not support fragmentation, as an
asset is stored in a contiguous space in a block. This means that the maximum
asset size can only be up-to a block size. Detailed information about the
maximum asset size can be found in the section `Maximum asset size` below.
Each block can potentially store multiple assets.
A delete operation implicitly moves all the assets towards the top of the block
to avoid fragmentation within block. However, this may also result in unutilized
space at the end of each block.
**Asset size limitation** - An asset is stored in a contiguous space in a
block/sector. Hence, the maximum asset size can be up-to the size of the
data block/sector. Detailed information about the maximum asset size can be
found in the section `Maximum asset size` below.
**Non-hierarchical storage model** - The current design uses a non-hierarchical
storage model, as a filesystem, where all the assets are managed by a linearly
indexed list of metadata. This model locates the metadata in blocks which are
always stored in the same flash location. That increases the number of writes
in a specific flash location as every change in the storage area requires a
metadata update.
**PSA internal trusted storage API** - In the current design, the service does
not use the PSA Internal Trusted Storage API to write the rollback protection
values stored in the internal storage. The PSA Internal Trusted Storage API is
not supported in TF-M yet.
**Protection against physical storage medium failure** - Complete handling of
inherent failures of storage mediums (e.g. bad blocks in a NAND based device)
is not supported by the current design.
**Key diversification** - In a more robust design, each asset would be encrypted
through a different key.
**Lifecycle management** - Currently, it does not support any subscription based
keys and certificates required in a secure lifecycle management. Hence, an
asset's validity time-stamp can not be invalidated based on the system time.
**Provisioning vs user/device data** - In the current design, all assets are
treated in the same manner. In an alternative design, it may be required to
create separate partitions for provisioning content and user/device generated
content. This is to allow safe update of provisioning data during firmware
updates without the need to wipe out the user/device generated data.
## Code Structure
Secure storage service code is located in `secure_fw/services/secure_storage/`
and is divided as follows:
- Core files
- Flash filesystem interfaces
- Flash interfaces
- Cryptographic interfaces
- Non-volatile (NV) counters interfaces
The PSA PS interfaces for SST service are located in `interface/include`
### PSA Protected Storage Interfaces
The SST service exposes the following mandatory PSA PS interfaces version 1.0:
- `psa_ps_status_t psa_ps_set(psa_ps_uid_t uid, uint32_t data_length, const void *p_data, psa_ps_create_flags_t create_flags)`
- `psa_ps_status_t psa_ps_get(psa_ps_uid_t uid, uint32_t data_offset, uint32_t data_length, void *p_data)`
- `psa_ps_status_t psa_ps_get_info(psa_ps_uid_t uid, struct psa_ps_info_t *p_info)`
- `psa_ps_status_t psa_ps_remove(psa_ps_uid_t uid)`
- `uint32_t psa_ps_get_support(void)`
For the moment, it does not support the extended version of those APIs.
These PSA PS interfaces and SST TF-M types are defined and documented in
`interface/include/psa_protected_storage.h` and
`interface/include/tfm_sst_defs.h`
### Core Files
`tfm_sst_req_mngr.c` - Contains the SST request manager implementation which
handles all requests which arrive to the service. This layer extracts the
arguments from the input and output vectors, and it calls the protected storage
layer with the provided parameters.
`tfm_protected_storage.c` - Contains the TF-M protected storage API
implementations which are the entry points to the SST service.
`sst_object_system.c` - Contains the object system implementation to manage
all objects in SST area.
`sst_object_table.c` - Contains the object system table implementation which
complements the object system to manage all object in the SST area.
The object table has an entry for each object stored in the object system
and keeps track of its version and owner.
`sst_encrypted_object.c` - Contains an implementation to manipulate
encrypted objects in the SST object system.
`sst_utils.c` - Contains common and basic functionalities used across the
SST service code.
### Flash Filesystem Interface
`flash_fs/sst_flash_fs.h` - Abstracts the flash filesystem operations used by
the secure storage service. The purpose of this abstraction is to have the
ability to plug-in other filesystems or filesystem proxys (supplicant).
`flash_fs/sst_flash_fs.c` - Contains the `sst_flash_fs` implementation for
the required interfaces.
`flash_fs/sst_flash_fs_mbloc.c` - Contains the metadata block manipulation
functions required to implement the `sst_flash_fs` interfaces in
`flash_fs/sst_flash_fs.c`.
`flash_fs/sst_flash_fs_mbloc.c` - Contains the data block manipulation
functions required to implement the `sst_flash_fs` interfaces in
`flash_fs/sst_flash_fs.c`.
The system integrator **may** replace this implementation with its own
flash filesystem implementation or filesystem proxy (supplicant).
### Flash Interface
`flash/sst_flash.h` - Abstracts the flash operations for the secure storage
service. It also defines the block size and number of blocks used by the SST
service.
`flash/sst_flash.c` - Contains the `sst_flash` implementation which sits on
top of CMSIS flash interface implemented by the target.
The CMSIS flash interface **must** be implemented for each target based on
its flash controller.
The block size (`SST_SECTOR_SIZE`) and number of blocks
(`SST_NBR_OF_SECTORS`) used by the secure storage area, are defined in
`flash_layout.h` located in `platform/ext/target/<TARGET_NAME>/partition`.
Those values **must** be defined in that header file based on flash
specifications and vendor specific considerations.
It is also required to define the `SST_FLASH_AREA_ADDR` which defines the
address of the first sector to be used as secure storage. The sectors reserved
to be used as secure storage **must** be contiguous sectors starting at
`SST_FLASH_AREA_ADDR`.
### Cryptographic Interface
`crypto/sst_crypto_interface.h` - Abstracts the cryptographic operations for
the secure storage service.
`crypto/sst_crypto_interface.c` - Currently, it implements the SST service
cryptographic operations using Mbed TLS library. The system integrator **may**
replace this implementation with calls to another service, crypto library or
hardware crypto unit.
### Non-volatile (NV) Counters Interface
The current SST service provides rollback protection based on NV counters.
SST defines and implements the following NV counters functionalities:
`nv_counters/sst_nv_counters.h` - Abstracts SST non-volatile counters
operations. This API detaches the use of NV counters from the TF-M NV counters
implementation, provided by the platform, and provides a mechanism to compile
in a different API implementation for test purposes. A SST test suite **may**
provide its own custom implementation to be able to test different SST service
use cases.
`nv_counters/sst_nv_counters.c` - Implements the SST NV counters interfaces
based on TF-M NV counters implementation provided by the platform.
## SST Service Integration Guide
This section describes mandatory (i.e. **must** implement) or optional
(i.e. **may** implement) interfaces which the system integrator have to take
in to account in order to integrate the secure storage service in a new
platform.
### Maximum Asset Size
An asset is stored in a contiguous space in a block/sector. The maximum
size of an asset can be up-to the size of the data block/sector minus the object
header size (`SST_OBJECT_HEADER_SIZE`) which is defined in `sst_object_defs.h`.
The `SST_OBJECT_HEADER_SIZE` changes based on the `SST_ENCRYPTION` flag status.
### Secure Storage Service Definitions
The SST service requires the following platform definitions:
- `SST_FLASH_AREA_ADDR`
Defines the flash address where the secure store area starts.
- `SST_SECTOR_SIZE`
Defines the size of the flash sectors.
- `SST_NBR_OF_SECTORS`
Defines the number of sectors available for the secure area. The sectors must
be consecutive.
- `SST_FLASH_DEV_NAME`
Specifies the flash device used by SST to store the data.
- `SST_FLASH_PROGRAM_UNIT`
Defines the smallest flash programmable unit in bytes.
Currently, SST supports 1, 2, 4 and 8.
- `SST_MAX_ASSET_SIZE`
Defines the maximum asset size to be stored in the SST area. This size is
used to define the temporary buffers used by SST to read/write the asset
content from/to flash. The memory used by the temporary buffers is allocated
statically as SST does not use dynamic memory allocation.
- `SST_NUM_ASSETS`
Defines the maximum number of assets to be stored in the SST area. This
number is used to dimension statically the object table size in RAM
(fast access) and flash (persistent storage). The memory used by the
object table is allocated statically as SST does not use dynamic memory
allocation.
Target must provide a header file, called `flash_layout.h`, which defines the
information explained above. The defines must be named as they are specified
above.
More information about the `flash_layout.h` content, not SST related, is
available in `platform/ext/readme.md` along with other platform information.
### TF-M NV Counter Interface
To have a platform independent way to access the NV counters, TF-M defines a
platform NV counter interface. For API specification, please check:
`platform/include/tfm_plat_nv_counters.h`
The system integrators **may** implement this interface based on the target
capabilities and set the `SST_ROLLBACK_PROTECTION` flag to compile in
the rollback protection code.
### Secret Platform Unique Key
The encryption policy relies on a secret hardware unique key (HUK) per device.
It is system integrator's responsibility to provide an implementation which
**must** be a non-mutable target implementation.
For API specification, please check:
`platform/include/tfm_plat_crypto_keys.h`
A stub implementation is provided in
`platform/ext/<target>/dummy_crypto_keys.c`
### Flash Interface
For SST service operations, a contiguous set of blocks must be earmarked for
the secure storage area. The design requires either 2 blocks, or any number of
blocks greater than or equal to 4. Total number of blocks can not be 0, 1 or 3.
This is a design choice limitation to provide power failure safe update
operations.
For API specification, please check:
`secure_fw/services/secure_storage/flash/sst_flash.h`
### Non-Secure Identity Manager
TF-M core tracks the current client IDs running in the secure or non-secure
processing environment. It provides a dedicated API to retrieve the client ID
which performs the service request.
[NS client identification documentation](../tfm_ns_client_identification.md)
provides further details on how client identification works.
SST service uses that TF-M core API to retrieve the client ID and associate it
as the owner of an asset. Only the owner can read, write or delete that asset
based on the creation flags.
The [integration guide](../tfm_integration_guide.md) provides further
details of non-secure implementation requirements for TF-M.
### Cryptographic Interface
The reference encryption policy is built on AES-GCM, and it **may** be replaced
by a vendor specific implementation.
The SST service abstracts all the cryptographic requirements and specifies the
required cryptographic interface in
`secure_fw/services/secure_storage/crypto/sst_crypto_interface.h`
Currently, the SST service cryptographic operations are implemented in
`secure_fw/services/secure_storage/crypto/sst_crypto_interface.c`, using
Mbed TLS library.
### SST Service Features Flags
SST service defines a set of flags that can be used to compile in/out certain
SST service features. The `CommonConfig.cmake` file sets the default values
of those flags. However, those flags values can be overwritten by setting them
in `platform/ext/<TARGET_NAME>.cmake` based on the target capabilities or needs.
The list of SST services flags are:
- `SST_ENCRYPTION`: this flag allows to enable/disable encryption option to
encrypt the secure storage data.
- `SST_CREATE_FLASH_LAYOUT`: this flag indicates that it is required to
create a SST flash layout. If this flag is set, SST service will generate an
empty and valid SST flash layout to store assets. It will erase all data
located in the assigned SST memory area before generating the SST layout.
This flag is required to be set if the SST memory area is located in a
non-persistent memory.
This flag can be set if the SST memory area is located in a persistent
memory without a valid SST flash layout in it. That is the case when
it is the first time in the device life that the SST service is executed.
- `SST_VALIDATE_METADATA_FROM_FLASH`: this flag allows to enable/disable the
validation mechanism to check the metadata store in flash every time the
flash data is read from flash. This validation is required if the flash is
not hardware protected against malicious writes. In case the flash is
protected against malicious writes (i.e embedded flash, etc), this validation
can be disabled in order to reduce the validation overhead.
- `SST_ROLLBACK_PROTECTION`: this flag allows to enable/disable rollback
protection in secure storage service. This flag takes effect only if the
target has non-volatile counters and `SST_ENCRYPTION` flag is on.
- `SST_RAM_FS`: this flag allows to enable/disable the use of RAM instead
of the flash to store the FS in secure storage service. This flag is set
by default in the regression tests, if it is not defined by the platform.
The SST regression tests reduce the life of the flash memory as they
write/erase multiple times in the memory.
- `SST_TEST_NV_COUNTERS`: this flag enables the virtual implementation of the
SST NV counters interface in `test/suites/sst/secure/nv_counters`, which
emulates NV counters in RAM, and disables the hardware implementation of NV
counters provided by the secure service. This flag is enabled by default when
building the regression tests and disabled by default otherwise.
- This flag can be overridden to `OFF` when building the regression tests. In
this case, the SST rollback protection test suite will not be built, as it
relies on extra functionality provided by the virtual NV counters to
simulate different rollback scenarios. The remainder of the SST test suites
will run using the hardware NV counters. Please note that running the tests
in this configuration will quickly increase the hardware NV counter values,
which cannot be decreased again.
- Overriding this flag from its default value of `OFF` when not building the
regression tests is not currently supported.
--------------
*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*

377
docs/user_guides/services/tfm_sst_integration_guide.rst Normal file
View File

@ -0,0 +1,377 @@
#############################################
TF-M Secure Storage Service Integration Guide
#############################################
************
Introduction
************
TF-M secure storage (SST) service implements PSA Protected Storage APIs.
The service is backed by hardware isolation of the flash access domain and, in
the current version, relies on hardware to isolate the flash area from
non-secure access. In absence of hardware level isolation, the secrecy and
integrity of data is still maintained.
The current SST service design relies on hardware abstraction level provided
by TF-M. The SST service provides a non-hierarchical storage model, as a
filesystem, where all the assets are managed by linearly indexed list of
metadata.
The SST service implements an AES-GCM based AEAD encryption policy, as a
reference, to protect data integrity and authenticity.
The design addresses the following high level requirements as well:
- **Confidentiality** - Resistance to unauthorised accesses through
hardware/software attacks.
- **Access Authentication** - Mechanism to establish requester's identity (a
non-secure entity, secure entity, or a remote server).
- **Integrity** - Resistant to tampering by either the normal users of a product,
package, or system or others with physical access to it. If the content of the
secure storage is changed maliciously, the service is able to detect it.
- **Reliability** - Resistant to power failure scenarios and incomplete write
cycles.
- **Configurability** - High level configurability to scale up/down memory
footprint to cater for a variety of devices with varying security
requirements.
- **Performance** - Optimized to be used for resource constrained devices with
very small silicon footprint, the PPA (power, performance, area) should be
optimal.
*******************************
Current SST Service Limitations
*******************************
- **Fragmentation** - The current design does not support fragmentation, as an
asset is stored in a contiguous space in a block. This means that the maximum
asset size can only be up-to a block size. Detailed information about the
maximum asset size can be found in the section `Maximum asset size` below.
Each block can potentially store multiple assets.
A delete operation implicitly moves all the assets towards the top of the block
to avoid fragmentation within block. However, this may also result in
unutilized space at the end of each block.
- **Asset size limitation** - An asset is stored in a contiguous space in a
block/sector. Hence, the maximum asset size can be up-to the size of the
data block/sector. Detailed information about the maximum asset size can be
found in the section `Maximum asset size` below.
- **Non-hierarchical storage model** - The current design uses a
non-hierarchical storage model, as a filesystem, where all the assets are
managed by a linearly indexed list of metadata. This model locates the
metadata in blocks which are always stored in the same flash location. That
increases the number of writes in a specific flash location as every change in
the storage area requires a metadata update.
- **PSA internal trusted storage API** - In the current design, the service does
not use the PSA Internal Trusted Storage API to write the rollback protection
values stored in the internal storage. The PSA Internal Trusted Storage API is
not supported in TF-M yet.
- **Protection against physical storage medium failure** - Complete handling of
inherent failures of storage mediums (e.g. bad blocks in a NAND based device)
is not supported by the current design.
- **Key diversification** - In a more robust design, each asset would be
encrypted through a different key.
- **Lifecycle management** - Currently, it does not support any subscription
based keys and certificates required in a secure lifecycle management. Hence,
an asset's validity time-stamp can not be invalidated based on the system
time.
- **Provisioning vs user/device data** - In the current design, all assets are
treated in the same manner. In an alternative design, it may be required to
create separate partitions for provisioning content and user/device generated
content. This is to allow safe update of provisioning data during firmware
updates without the need to wipe out the user/device generated data.
**************
Code Structure
**************
Secure storage service code is located in ``secure_fw/services/secure_storage/``
and is divided as follows:
- Core files
- Flash filesystem interfaces
- Flash interfaces
- Cryptographic interfaces
- Non-volatile (NV) counters interfaces
The PSA PS interfaces for SST service are located in ``interface/include``
PSA Protected Storage Interfaces
================================
The SST service exposes the following mandatory PSA PS interfaces
version 1.0:
.. code-block:: c
psa_ps_status_t psa_ps_set(psa_ps_uid_t uid, uint32_t data_length, const void *p_data, psa_ps_create_flags_t create_flags);
psa_ps_status_t psa_ps_get(psa_ps_uid_t uid, uint32_t data_offset, uint32_t data_length, void *p_data);
psa_ps_status_t psa_ps_get_info(psa_ps_uid_t uid, struct psa_ps_info_t *p_info);
psa_ps_status_t psa_ps_remove(psa_ps_uid_t uid);
uint32_t psa_ps_get_support(void);
For the moment, it does not support the extended version of those APIs.
These PSA PS interfaces and SST TF-M types are defined and documented in
``interface/include/psa_protected_storage.h`` and
``interface/include/tfm_sst_defs.h``
Core Files
==========
- ``tfm_sst_req_mngr.c`` - Contains the SST request manager implementation which
handles all requests which arrive to the service. This layer extracts the
arguments from the input and output vectors, and it calls the protected
storage layer with the provided parameters.
- ``tfm_protected_storage.c`` - Contains the TF-M protected storage API
implementations which are the entry points to the SST service.
- ``sst_object_system.c`` - Contains the object system implementation to manage
all objects in SST area.
- ``sst_object_table.c`` - Contains the object system table implementation which
complements the object system to manage all object in the SST area.
The object table has an entry for each object stored in the object system
and keeps track of its version and owner.
- ``sst_encrypted_object.c`` - Contains an implementation to manipulate
encrypted objects in the SST object system.
- ``sst_utils.c`` - Contains common and basic functionalities used across the
SST service code.
Flash Filesystem Interface
==========================
- ``flash_fs/sst_flash_fs.h`` - Abstracts the flash filesystem operations used
by the secure storage service. The purpose of this abstraction is to have the
ability to plug-in other filesystems or filesystem proxys (supplicant).
- ``flash_fs/sst_flash_fs.c`` - Contains the ``sst_flash_fs`` implementation for
the required interfaces.
- ``flash_fs/sst_flash_fs_mbloc.c`` - Contains the metadata block manipulation
functions required to implement the ``sst_flash_fs`` interfaces in
``flash_fs/sst_flash_fs.c``.
- ``flash_fs/sst_flash_fs_dbloc.c`` - Contains the data block manipulation
functions required to implement the ``sst_flash_fs`` interfaces in
``flash_fs/sst_flash_fs.c``.
The system integrator **may** replace this implementation with its own
flash filesystem implementation or filesystem proxy (supplicant).
Flash Interface
===============
- ``flash/sst_flash.h`` - Abstracts the flash operations for the secure storage
service. It also defines the block size and number of blocks used by the SST
service.
- ``flash/sst_flash.c`` - Contains the ``sst_flash`` implementation which sits
on top of CMSIS flash interface implemented by the target.
The CMSIS flash interface **must** be implemented for each target based on
its flash controller.
The block size (``SST_SECTOR_SIZE``) and number of blocks
(``SST_NBR_OF_SECTORS``) used by the secure storage area, are defined in
``flash_layout.h`` located in ``platform/ext/target/<TARGET_NAME>/partition``.
Those values **must** be defined in that header file based on flash
specifications and vendor specific considerations.
It is also required to define the ``SST_FLASH_AREA_ADDR`` which defines the
address of the first sector to be used as secure storage. The sectors reserved
to be used as secure storage **must** be contiguous sectors starting at
``SST_FLASH_AREA_ADDR``.
Cryptographic Interface
=======================
-``crypto/sst_crypto_interface.h`` - Abstracts the cryptographic
operations for the secure storage service.
- ``crypto/sst_crypto_interface.c`` - Currently, it implements the SST
service cryptographic operations using Mbed TLS library. The system integrator
**may** replace this implementation with calls to another service, crypto
library or hardware crypto unit.
Non-volatile (NV) Counters Interface
====================================
The current SST service provides rollback protection based on NV
counters.
SST defines and implements the following NV counters functionalities:
- ``nv_counters/sst_nv_counters.h`` - Abstracts SST non-volatile
counters operations. This API detaches the use of NV counters from the TF-M NV
counters implementation, provided by the platform, and provides a mechanism to
compile in a different API implementation for test purposes. A SST test suite
**may** provide its own custom implementation to be able to test different SST
service use cases.
- ``nv_counters/sst_nv_counters.c`` - Implements the SST NV counters interfaces
based on TF-M NV counters implementation provided by the platform.
*****************************
SST Service Integration Guide
*****************************
This section describes mandatory (i.e. **must** implement) or optional
(i.e. **may** implement) interfaces which the system integrator have to take
in to account in order to integrate the secure storage service in a new
platform.
Maximum Asset Size
==================
An asset is stored in a contiguous space in a block/sector. The maximum
size of an asset can be up-to the size of the data block/sector minus the object
header size (``SST_OBJECT_HEADER_SIZE``) which is defined in
``sst_object_defs.h``. The ``SST_OBJECT_HEADER_SIZE`` changes based on the
``SST_ENCRYPTION`` flag status.
Secure Storage Service Definitions
==================================
The SST service requires the following platform definitions:
- ``SST_FLASH_AREA_ADDR`` - Defines the flash address where the secure store
area starts.
- ``SST_SECTOR_SIZE`` - Defines the size of the flash sectors.
- ``SST_NBR_OF_SECTORS`` - Defines the number of sectors available for the
secure area. The sectors must be consecutive.
- ``SST_FLASH_DEV_NAME`` - Specifies the flash device used by SST to store the
data.
- ``SST_FLASH_PROGRAM_UNIT`` - Defines the smallest flash programmable unit in
bytes. Currently, SST supports 1, 2, 4 and 8.
- ``SST_MAX_ASSET_SIZE`` - Defines the maximum asset size to be stored in the
SST area. This size is used to define the temporary buffers used by SST to
read/write the asset content from/to flash. The memory used by the temporary
buffers is allocated statically as SST does not use dynamic memory allocation.
- ``SST_NUM_ASSETS`` - Defines the maximum number of assets to be stored in the
SST area. This number is used to dimension statically the object table size in
RAM (fast access) and flash (persistent storage). The memory used by the
object table is allocated statically as SST does not use dynamic memory
allocation.
Target must provide a header file, called ``flash_layout.h``, which defines the
information explained above. The defines must be named as they are specified
above.
More information about the ``flash_layout.h`` content, not SST related, is
available in :doc:`platform readme </platform/ext/readme>` along with other
platform information.
TF-M NV Counter Interface
=========================
To have a platform independent way to access the NV counters, TF-M defines a
platform NV counter interface. For API specification, please check:
``platform/include/tfm_plat_nv_counters.h``
The system integrators **may** implement this interface based on the target
capabilities and set the ``SST_ROLLBACK_PROTECTION`` flag to compile in
the rollback protection code.
Secret Platform Unique Key
==========================
The encryption policy relies on a secret hardware unique key (HUK) per device.
It is system integrator's responsibility to provide an implementation which
**must** be a non-mutable target implementation.
For API specification, please check:
``platform/include/tfm_plat_crypto_keys.h``
A stub implementation is provided in
``platform/ext/<target>/dummy_crypto_keys.c``
Flash Interface
===============
For SST service operations, a contiguous set of blocks must be earmarked for
the secure storage area. The design requires either 2 blocks, or any number of
blocks greater than or equal to 4. Total number of blocks can not be 0, 1 or 3.
This is a design choice limitation to provide power failure safe update
operations.
For API specification, please check:
``secure_fw/services/secure_storage/flash/sst_flash.h``
Non-Secure Identity Manager
===========================
TF-M core tracks the current client IDs running in the secure or non-secure
processing environment. It provides a dedicated API to retrieve the client ID
which performs the service request.
:doc:`NS client identification documentation </docs/user_guides/tfm_ns_client_identification>`
provides further details on how client identification works.
SST service uses that TF-M core API to retrieve the client ID and associate it
as the owner of an asset. Only the owner can read, write or delete that asset
based on the creation flags.
The :doc:`integration guide </docs/user_guides/tfm_integration_guide>` provides further
details of non-secure implementation requirements for TF-M.
Cryptographic Interface
=======================
The reference encryption policy is built on AES-GCM, and it **may** be replaced
by a vendor specific implementation.
The SST service abstracts all the cryptographic requirements and specifies the
required cryptographic interface in
``secure_fw/services/secure_storage/crypto/sst_crypto_interface.h``
Currently, the SST service cryptographic operations are implemented in
``secure_fw/services/secure_storage/crypto/sst_crypto_interface.c``, using
Mbed TLS library.
SST Service Features Flags
==========================
SST service defines a set of flags that can be used to compile in/out certain
SST service features. The ``CommonConfig.cmake`` file sets the default values
of those flags. However, those flags values can be overwritten by setting them
in ``platform/ext/<TARGET_NAME>.cmake`` based on the target capabilities or
needs. The list of SST services flags are:
- ``SST_ENCRYPTION``- this flag allows to enable/disable encryption
option to encrypt the secure storage data.
- ``SST_CREATE_FLASH_LAYOUT``- this flag indicates that it is required
to create a SST flash layout. If this flag is set, SST service will
generate an empty and valid SST flash layout to store assets. It will
erase all data located in the assigned SST memory area before generating
the SST layout. This flag is required to be set if the SST memory area
is located in a non-persistent memory. This flag can be set if the SST
memory area is located in a persistent memory without a valid SST flash
layout in it. That is the case when it is the first time in the device
life that the SST service is executed.
- ``SST_VALIDATE_METADATA_FROM_FLASH``- this flag allows to
enable/disable the validation mechanism to check the metadata store in flash
every time the flash data is read from flash. This validation is required
if the flash is not hardware protected against malicious writes. In case
the flash is protected against malicious writes (i.e embedded flash, etc),
this validation can be disabled in order to reduce the validation overhead.
- ``SST_ROLLBACK_PROTECTION``- this flag allows to enable/disable
rollback protection in secure storage service. This flag takes effect only
if the target has non-volatile counters and ``SST_ENCRYPTION`` flag is on.
- ``SST_RAM_FS``- this flag allows to enable/disable the use of RAM
instead of the flash to store the FS in secure storage service. This flag
is set by default in the regression tests, if it is not defined by the
platform. The SST regression tests reduce the life of the flash memory
as they write/erase multiple times in the memory.
- ``SST_TEST_NV_COUNTERS``- this flag enables the virtual
implementation of the SST NV counters interface in
``test/suites/sst/secure/nv_counters``, which emulates NV counters in
RAM, and disables the hardware implementation of NV counters provided by
the secure service. This flag is enabled by default when building the
regression tests and disabled by default otherwise. This flag can be
overridden to ``OFF`` when building the regression tests. In this case,
the SST rollback protection test suite will not be built, as it relies
on extra functionality provided by the virtual NV counters to simulate
different rollback scenarios. The remainder of the SST test suites will
run using the hardware NV counters. Please note that running the tests in
this configuration will quickly increase the hardware NV counter values,
which cannot be decreased again.
Overriding this flag from its default value of ``OFF`` when not
building the regression tests is not currently supported.
--------------
*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*

183
docs/user_guides/tfm_build_instruction.md
View File

@ -1,183 +0,0 @@
# TF-M build instruction
Please make sure you have all required software installed as explained in the
[software requirements](tfm_sw_requirement.md).
## TF-M build steps
TF-M uses [cmake](https://cmake.org/overview/) to provide an out-of-tree build
environment. The instructions are below.
*Note:* In the cmake configuration step, to enable debug symbols, the following
option should be added:
`-DCMAKE_BUILD_TYPE=Debug`
*Note:* `-DCMAKE_BUILD_TYPE=Debug` only enables debug symbols for TF-M code. To
enable debug symbols for the Mbed TLS library, add the following option to the
CMake command:
`-DMBEDTLS_DEBUG=ON`
### External dependency
* CMSIS_5 is used to import RTX for the example non-secure app
* Mbed TLS is used as a crypto library on the secure side
Both need to be cloned manually in the current release.
### Build steps for the AN521 target platform:
```
cd <TF-M base folder>
git clone https://git.trustedfirmware.org/trusted-firmware-m.git
git clone https://github.com/ARMmbed/mbedtls.git -b mbedtls-2.7.9
git clone https://github.com/ARM-software/CMSIS_5.git -b 5.2.0
cd trusted-firmware-m
mkdir cmake_build
cd cmake_build
cmake ../ -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG
cmake --build ./ -- install
```
### Concept of build config files
The build configuration for TF-M is provided to the build system by three
different components:
* The way applications are built is specified by providing one of the
`Config<APP_NAME>.cmake` files to the build system. This can be done by adding
the `` -DPROJ_CONFIG=<absolute file path> `` i.e. on Linux:
`` -DPROJ_CONFIG=`readlink -f ../ConfigRegression.cmake` `` parameter to the
cmake command. (See examples below.)
* The target platform can be specified by adding the
`-DTARGET_PLATFORM=<target platform name>` option to the cmake command (See
examples below.)
* Supported platforms:
* Cortex-M33 SSE-200 subsystem for MPS2+ (AN521)
`-DTARGET_PLATFORM=AN521`
* Cortex-M23 IoT Kit subsystem for MPS2+ (AN519)
`-DTARGET_PLATFORM=AN519`
* Musca-A test chip board (Cortex-M33 SSE-200 subsystem)
`-DTARGET_PLATFORM=MUSCA_A`
* Musca-B1 test chip board (Cortex-M33 SSE-200 subsystem)
`-DTARGET_PLATFORM=MUSCA_B1`
* The compiler toolchain to be used for the build must be specified by adding
the `-DCOMPILER=<compiler name>` option to the cmake command (See examples
below.) The possible values are
- ARMCLANG
- GNUARM
*Note* Follow [secure boot](./tfm_secure_boot.md) to build the binaries with or
without BL2 bootloader.
### Regression Tests for the AN521 target platform
The default option build doesn't include regression tests. Procedure for
building the regression tests is below. Compiling for other target hardware
is possible by selecting a different build config file.
`It is recommended that tests are built in a different directory.`
*TF-M build regression tests on Linux*
```
cd <TF-M base folder>
cd trusted-firmware-m
mkdir cmake_test
cd cmake_test
cmake -G"Unix Makefiles" -DPROJ_CONFIG=`readlink -f ../ConfigRegression.cmake` -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG ../
cmake --build ./ -- install
```
*TF-M build regression tests on Windows*
```
cd <TF-M base folder>
cd trusted-firmware-m
mkdir cmake_test
cd cmake_test
cmake -G"Unix Makefiles" -DPROJ_CONFIG=`cygpath -m ../ConfigRegression.cmake` -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG ../
cmake --build ./ -- install
```
## Location of build artefacts
The build system defines an API which allow easy usage of build artefacts. The
`install` build target copies all files which might be needed as a dependency by
external tools or build systems to the `<build_dir>/install/outputs` directory,
with the following directory hierarchy:
```
<build_dir>/install/outputs/fvp/
<build_dir>/install/outputs/<target_platform>/
```
There is one folder for FVP testing, with more elaborate naming and there is an
other for testing on target hardware platform (AN521, etc.), where naming
convention is aligned with 8.3 format. The dependency tree of `install` build
target ensures a proper update (i.e. build) of all output files before the
actual installation step takes place. As such it is suggested to use this build
target to build TF-M.
## Export dependency files for NS applications
An NS application requires a number of files to interface with TF-M. The build
system exports these files as part of the `install` target and places them in to
a single directory, `<build_dir>/install/export/tfm`. Further details on how to
integrate a new NS app with TF-M are available in the
[integration guide](tfm_integration_guide.md).
## Build for PSA API compliance tests
The build system provides the support for linking with prebuilt PSA API
compliance NS test libraries when using the `ConfigPsaApiTest.cmake` config
file. The build system assumes that the PSA API compliance test suite is
checked out at the same level of the TF-M root folder and the default name for
the build folder has been used when compiling the PSA API compliance tests. Each
set of tests for the Secure Storage, Crypto and Attestation services needs to be
enabled at the build configuration step by defining
`-DPSA_API_TEST_SECURE_STORAGE`, `-DPSA_API_TEST_CRYPTO`,
`-DPSA_API_TEST_ATTESTATION`, respectively for the corresponding service. For
example, to enable the PSA API tests for the Crypto service only:
```
...
cmake -G"Unix Makefiles" -DPROJ_CONFIG=`readlink -f ../ConfigPsaApiTest.cmake` -DPSA_API_TEST_CRYPTO -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG ../
cmake --build ./ -- install
```
## Building the Reference Manual
Please ensure the dependencies for building the firmware and the documentation
are installed as explained in the [software requirements](tfm_sw_requirement.md).
*Note* For building the documentation all tools needed to build the firmware
must be available.
~~~
cd <TF-M base folder>
mkdir cmake_doc
cd cmake_doc
cmake ../ -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG
cmake --build ./ -- install_doc
~~~
The documentation files will be available under the directory:
~~~
cmake_doc/install/doc/reference_manual
~~~
## Building the User Guide
Please ensure the dependencies for building the firmware and the documentation
are installed as explained in the [software requirements](tfm_sw_requirement.md).
*Note* For building the documentation all tools needed to build the firmware
must be available.
~~~
cd <TF-M base folder>
mkdir cmake_doc
cd cmake_doc
cmake ../ -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG
cmake --build ./ -- install_userguide
~~~
The documentation files will be available under the directory:
~~~
cmake_doc/install/doc/user_guide
~~~
--------------
*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*

217
docs/user_guides/tfm_build_instruction.rst Normal file
View File

@ -0,0 +1,217 @@
######################
TF-M build instruction
######################
Please make sure you have all required software installed as explained in the
:doc:`software requirements <tfm_sw_requirement>`.
*********************
Configuring the build
*********************
The build configuration for TF-M is provided to the build system using command
line arguments:
.. list-table::
:widths: 20 80
* - -DPROJ_CONFIG=<file>
- Specifies the way the application is built.
| <file> is the absolute path to configurations file
named as ``Config<APP_NAME>.cmake``.
| i.e. On Linux:
``-DPROJ_CONFIG=`readlink -f ../ConfigRegression.cmake```
* - -DTARGET_PLATFORM=<target platform name>
- Specifies the target platform.
Supported platforms:
- Cortex-M33 SSE-200 subsystem for MPS2+ (AN521)
``-DTARGET_PLATFORM=AN521``
- Cortex-M23 IoT Kit subsystem for MPS2+ (AN519)
``-DTARGET_PLATFORM=AN519``
- Musca-A1 test chip board (Cortex-M33 SSE-200 subsystem)
``-DTARGET_PLATFORM=MUSCA_A``
- Musca-B1 test chip board (Cortex-M33 SSE-200 subsystem)
``-DTARGET_PLATFORM=MUSCA_B1``
* - -DCOMPILER=<compiler name>
- Specifies the compiler toolchain
The possible values are:
- ``ARMCLANG``
- ``GNUARM``
* - -DCMAKE_BUILD_TYPE=<build type>
- Configures debugging support.
The possible values are:
- ``Debug``
- ``Release``
- ``Relwithdebinfo``
- ``Minsizerel``
* - -DMBEDTLS_DEBUG=<ON|OFF>
- To enables debug symbols for the Mbed TLS library.
.. Note::
Follow :doc:`secure boot <./tfm_secure_boot>` to build the binaries with or
without BL2 bootloader.
*******************
External dependency
*******************
- CMSIS_5 is used to import RTX for the example non-secure app
- Mbed TLS is used as a crypto library on the secure side
****************
TF-M build steps
****************
TF-M uses `cmake <https://cmake.org/overview/>`__ to provide an out-of-source
build environment. The instructions are below.
.. Note::
It is recommended to build each different build configurations in separate
directories.
Getting the source-code
=======================
.. code-block:: bash
cd <TF-M base folder>
git clone https://git.trustedfirmware.org/trusted-firmware-m.git
git clone https://github.com/ARMmbed/mbedtls.git -b mbedtls-2.7.9
git clone https://github.com/ARM-software/CMSIS_5.git -b 5.2.0
Build steps for the AN521 target platform:
==========================================
.. code-block:: bash
cd <TF-M base folder>
cd trusted-firmware-m
mkdir cmake_build
cd cmake_build
cmake ../ -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG
cmake --build ./ -- install
Regression Tests for the AN521 target platform
==============================================
*TF-M build regression tests on Linux*
.. code-block:: bash
cd <TF-M base folder>
cd trusted-firmware-m
mkdir cmake_test
cd cmake_test
cmake -G"Unix Makefiles" -DPROJ_CONFIG=`readlink -f ../ConfigRegression.cmake` -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG ../
cmake --build ./ -- install
*TF-M build regression tests on Windows*
.. code-block:: bash
cd <TF-M base folder>
cd trusted-firmware-m
mkdir cmake_test
cd cmake_test
cmake -G"Unix Makefiles" -DPROJ_CONFIG=`cygpath -am ../ConfigRegression.cmake` -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG ../
cmake --build ./ -- install
Build for PSA API compliance tests
==================================
The build system provides the support for linking with prebuilt PSA API
compliance NS test libraries when using the ``ConfigPsaApiTest.cmake``
config file. The build system assumes that the PSA API compliance test suite
is checked out at the same level of the TF-M root folder and the default
name for the build folder has been used when compiling the PSA API compliance
tests. Each set of tests for the Secure Storage, Crypto and Attestation services
needs to be enabled at the build configuration step by defining::
-DPSA_API_TEST_SECURE_STORAGE -DPSA_API_TEST_CRYPTO -DPSA_API_TEST_ATTESTATION
respectively for the corresponding service. For example, to enable the PSA API
tests for the Crypto service only:
.. code-block:: bash
cd <TF-M base folder>
cd trusted-firmware-m
mkdir cmake_psa_test
cd cmake_psa_test
cmake -G"Unix Makefiles" -DPROJ_CONFIG=`readlink -f ../ConfigPsaApiTest.cmake` -DPSA_API_TEST_CRYPTO -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG ../
cmake --build ./ -- install
Location of build artifacts
===========================
The build system defines an API which allow easy usage of build
artifacts. The ``install`` build target copies all files which might be needed
as a dependency by external tools or build systems to the
``<build_dir>/install/outputs``
directory, with the following directory hierarchy:
::
<build_dir>/install/outputs/fvp/
<build_dir>/install/outputs/<target_platform>/
There is one folder for FVP testing, with more elaborate naming and
there is an other for testing on target hardware platform (AN521, etc.), where
naming convention is aligned with 8.3 format. The dependency tree of
``install`` build target ensures a proper update (i.e. build) of all output
files before the actual installation step takes place. As such it is suggested
to use this build target to build TF-M.
Export dependency files for NS applications
-------------------------------------------
An NS application requires a number of files to interface with TF-M.
The build system exports these files as part of the ``install`` target and
places them in to a single directory::
<build_dir>/install/export/tfm
Further details on how to integrate a new NS app with TF-M are available in the
:doc:`integration guide <tfm_integration_guide>`.
Building the documentation
==========================
Please ensure the dependencies for building the firmware and the
documentation are installed as explained in the
:doc:`software requirements <tfm_sw_requirement>`.
Building PDF output is optional and can be disabled by removing LaTex from the
PATH.
.. Note::
For building the documentation all tools needed to build the firmware must
be available.
Building the Reference Manual
-----------------------------
.. code-block:: bash
cd <TF-M base folder>
mkdir cmake_doc
cd cmake_doc
cmake ../ -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=GNUARM
cmake --build ./ -- install_doc
The documentation files will be available under the directory::
cmake_doc/install/doc/reference_manual
Building the User Guide
-----------------------
.. code-block:: bash
cd <TF-M base folder>
mkdir cmake_doc
cd cmake_doc
cmake ../ -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG
cmake --build ./ -- install_userguide
The documentation files will be available under the directory::
cmake_doc/install/doc/user_guide
--------------
*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*

100
docs/user_guides/tfm_integration_guide.md
View File

@ -1,100 +0,0 @@
# TF-M integration guide
The purpose of this document is to provide a guide on how to integrate TF-M with
other hardware platforms and operating systems.
## How to build TF-M
Follow the [Build instructions](tfm_build_instruction.md).
## How to export files for building non-secure applications
Explained in the [Build instructions](tfm_build_instruction.md).
## How to add a new platform
The hardware platforms currently supported are:
* Soft Macro Model (SMM) Cortex-M33 SSE-200 subsystem for MPS2+ (AN521)
* Cortex-M23 IoT Kit subsystem for MPS2+ (AN519)
* Musca-A test chip board (Cortex-M33 SSE-200 subsystem)
* Musca-B1 test chip board (Cortex-M33 SSE-200 subsystem)
The files related to the supported platforms are contained under the `platform`
subfolder. The platform specific files are under `platform/ext/target`, which is
organized by boards (e.g. `platform/ext/target/mps2`), while the folder
`platform/ext/common` is used to store source and header files which are
platform generic.
More information about subsystems supported by the MPS2+ board can be found in:
[MPS2+ homepage](https://developer.arm.com/products/system-design/development-boards/fpga-prototyping-boards/mps2)
More information about the Musca-A test chip board can be found in:
[Musca-A homepage](https://developer.arm.com/products/system-design/development-boards/iot-test-chips-and-boards/musca-a-test-chip-board)
More information about the Musca-B1 test chip board can be found in:
[Musca-B1 homepage](https://www.arm.com/products/development-tools/development-boards/musca-b1-iot)
#### generic drivers and startup/scatter files
The addition of a new platform means the creation of a new subfolder inside
`target/<board_name>` to provide an implementation of the drivers currently used
by TF-M, in particular MPC, PPC, and USART drivers. In addition to the drivers,
startup and scatter files need to be provided for the supported toolchains.
There are also board specific drivers which are used by the board platform to
interact with the external world, for example during tests, that have to be
provided, e.g. to blink LEDs or count time in the MPS2 board.
`Note: Currently SST and BL2 bootloader use different flash interface`
#### target configuration files
Inside the base root folder of the selected target, each implementation has to
provide its own copy of `target_cfg.c/.h`. This file has target specific
configuration functions and settings that are called by the TF-M during the
platform configuration step during TF-M boot. Examples of the configurations
performed during this phase are the MPC configuration, the SAU configuration,
or eventually PPC configuration if supported by the hardware platform.
Similarly, the `uart_stdout.c` is used to provide functions needed to redirect
the stdout on UART (this is currently used by TF-M to log messages).
#### platform retarget files
An important part that each new platform has to provide is the set of retarget
files which are contained inside the `retarget` folder. These files define the
peripheral base addresses for the platform, both for the secure and non-secure
aliases (when available), and bind those addresses to the base addresses used by
the devices available in the hardware platform.
## How to integrate another OS
To work with TF-M, the OS needs to support the Armv8-M architecture and,
in particular, it needs to be able to run in the non-secure world. More
information about OS migration to the Armv8-M architecture can be found in the
[OS requirements](os_migration_guide_armv8m.md). Depending upon the system
configuration this may require configuring drivers to use appropriate address
ranges.
#### interface with TF-M
The files needed for the interface with TF-M are exported at the
`<build_dir>/install/export/tfm` path. The NS side is only allowed to call TF-M
secure functions (veneers) from the NS Thread mode. For this reason, the API is
a collection of functions in the `<build_dir>/install/export/tfm/inc`
directory. For example, the interface for the Secure STorage (SST) service
is described in the file `psa_sst_api.h` as a collection of
functions that call service veneer functions. This API is a wrapper for the
secure veneers, and returns the return value from the service to the caller.
The secure storage service uses a numerical ID, to identify the clients that use
the service. For details see
[ns client identification documentation](tfm_ns_client_identification.md).
#### interface with non-secure world regression tests
A non-secure application that wants to run the non-secure regression tests
needs to call the `tfm_non_secure_client_run_tests()`. This function is
exported into the header file `test_framework_integ_test.h` inside the
`<build_dir>/install` folder structure in the test specific files, i.e.
`<build_dir>/install/export/tfm/test/inc`. The non-secure regression tests are
precompiled and delivered as a static library which is available in
`<build_dir>/install/export/tfm/test/lib`, so that the non-secure application
needs to link against the library to be able to invoke the
`tfm_non_secure_client_run_tests()` function. The SST non-secure side regression
tests rely on some OS functionality e.g. threads, mutexes etc. These functions
comply with CMSIS RTOS2 standard and have been exported as thin wrappers defined
in `os_wrapper.h` contained in `<build_dir>/install/export/tfm/test/inc`. OS
needs to provide the implementation of these wrappers to be able to run the
tests.
#### NS client Identification
See [ns client identification documentation](tfm_ns_client_identification.md).
--------------
*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*

126
docs/user_guides/tfm_integration_guide.rst Normal file
View File

@ -0,0 +1,126 @@
######################
TF-M integration guide
######################
The purpose of this document is to provide a guide on how to integrate TF-M
with other hardware platforms and operating systems.
*****************
How to build TF-M
*****************
Follow the :doc:`Build instructions <tfm_build_instruction>`.
********************************************************
How to export files for building non-secure applications
********************************************************
Explained in the :doc:`Build instructions <tfm_build_instruction>`.
*************************
How to add a new platform
*************************
The hardware platforms currently supported are:
- Soft Macro Model (SMM) Cortex-M33 SSE-200 subsystem for MPS2+ (AN521)
- Cortex-M23 IoT Kit subsystem for MPS2+ (AN519)
- Musca-A1 test chip board (Cortex-M33 SSE-200 subsystem)
- Musca-B1 test chip board (Cortex-M33 SSE-200 subsystem)
The files related to the supported platforms are contained under the
``platform`` subfolder. The platform specific files are under
``platform/ext/target``, which is organised by boards
(e.g. ``platform/ext/target/mps2``), while the folder ``platform/ext/common``
is used to store source and header files which are platform generic.
More information about subsystems supported by the MPS2+ board can be found in:
`MPS2+ homepage <https://developer.arm.com/products/system-design/development-boards/fpga-prototyping-boards/mps2>`__
More information about the Musca-A1 test chip board can be found in:
`Musca-A homepage <https://developer.arm.com/products/system-design/development-boards/iot-test-chips-and-boards/musca-a-test-chip-board>`__
More information about the Musca-B1 test chip board can be found in:
`Musca-B1 homepage <https://www.arm.com/products/development-tools/development-boards/musca-b1-iot>`__
Generic drivers and startup/scatter files
=========================================
The addition of a new platform means the creation of a new subfolder inside
``target/<board_name>`` to provide an implementation of the drivers currently
used by TF-M, in particular MPC, PPC, and USART drivers. In addition to the
drivers, startup and scatter files need to be provided for the supported
toolchains.
There are also board specific drivers which are used by the board
platform to interact with the external world, for example during tests, that
have to be provided, e.g. to blink LEDs or count time in the MPS2 board.
.. Note::
Currently SST and BL2 bootloader use different flash interface
Target configuration files
==========================
Inside the base root folder of the selected target, each implementation has to
provide its own copy of ``target_cfg.c/.h``. This file has target specific
configuration functions and settings that are called by the TF-M during the
platform configuration step during TF-M boot. Examples of the configurations
performed during this phase are the MPC configuration, the SAU configuration,
or eventually PPC configuration if supported by the hardware platform.
Similarly, the ``uart_stdout.c`` is used to provide functions needed to redirect
the stdout on UART (this is currently used by TF-M to log messages).
Platform retarget files
=======================
An important part that each new platform has to provide is the set of retarget
files which are contained inside the ``retarget`` folder. These files define the
peripheral base addresses for the platform, both for the secure and non-secure
aliases (when available), and bind those addresses to the base addresses used by
the devices available in the hardware platform.
***************************
How to integrate another OS
***************************
To work with TF-M, the OS needs to support the Armv8-M architecture and, in
particular, it needs to be able to run in the non-secure world. More
information about OS migration to the Armv8-M architecture can be found in the
:doc:`OS requirements <os_migration_guide_armv8m>`. Depending upon the system
configuration this may require configuring drivers to use appropriate address
ranges.
Interface with TF-M
===================
The files needed for the interface with TF-M are exported at the
``<build_dir>/install/export/tfm`` path. The NS side is only allowed to call
TF-M secure functions (veneers) from the NS Thread mode. For this reason, the
API is a collection of functions in the ``<build_dir>/install/export/tfm/inc``
directory. For example, the interface for the Secure STorage (SST) service
is described in the file ``psa_sst_api.h`` as a collection of functions that
call service veneer functions. This API is a wrapper for the secure veneers,
and returns the return value from the service to the caller.
The secure storage service uses a numerical ID, to identify the clients that use
the service. For details see
:doc:`ns client identification documentation <tfm_ns_client_identification>`.
Interface with non-secure world regression tests
================================================
A non-secure application that wants to run the non-secure regression tests
needs to call the ``tfm_non_secure_client_run_tests()``. This function is
exported into the header file ``test_framework_integ_test.h`` inside the
``<build_dir>/install`` folder structure in the test specific files,
i.e. ``<build_dir>/install/export/tfm/test/inc``. The non-secure regression
tests are precompiled and delivered as a static library which is available in
``<build_dir>/install/export/tfm/test/lib``, so that the non-secure application
needs to link against the library to be able to invoke the
``tfm_non_secure_client_run_tests()`` function. The SST non-secure side
regression tests rely on some OS functionality e.g. threads, mutexes etc. These
functions comply with CMSIS RTOS2 standard and have been exported as thin
wrappers defined in ``os_wrapper.h`` contained in
``<build_dir>/install/export/tfm/test/inc``. OS needs to provide the
implementation of these wrappers to be able to run the tests.
NS client Identification
========================
See
:doc:`ns client identification documentation <tfm_ns_client_identification>`.
--------------
*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*

23
docs/user_guides/tfm_ns_client_identification.md → docs/user_guides/tfm_ns_client_identification.rst
View File

@ -1,5 +1,6 @@
# Non-Secure Identity Manager
###########################
Non-Secure Identity Manager
###########################
The ID of the current application/thread is known by TF-M, and the SST service
queries the ID of the currently running client via a dedicated API.
@ -9,34 +10,34 @@ relies on the services provided by the NS OS.
Tracking of context changes are possible by relying on the NS OS calling the
Thread Context Management for Armv8-M TrustZone APIs, as described
[here](https://www.keil.com/pack/doc/CMSIS/Core/html/group__context__trustzone__functions.html)
`here <https://www.keil.com/pack/doc/CMSIS/Core/html/group__context__trustzone__functions.html>`__
However TF-M needs an extra API, to assign a client ID to the TZ context created
as a result of the
`TZ_MemoryId_t TZ_AllocModuleContext_S (TZ_ModuleId_t module)` call.
``TZ_MemoryId_t TZ_AllocModuleContext_S (TZ_ModuleId_t module)`` call.
To do this, the
`enum tfm_status_e tfm_register_client_id (int32_t ns_client_id)` have to be
``enum tfm_status_e tfm_register_client_id (int32_t ns_client_id)`` have to be
called from an SVC handler, with the client ID of the currently running client.
In the current implementation of TF-M, an SVC call is provided for the NS
clients to be called at the beginning of their main function.
```SVC(SVC_TFM_NSPM_REGISTER_CLIENT_ID);```
``SVC(SVC_TFM_NSPM_REGISTER_CLIENT_ID);``
The SVC call handler of the above SVC maps the name of the current thread to a
hardcoded client id, and sends it to the TF-M core via the earlier discussed
API.
The mapping is implemented in `interface/src/tfm_nspm_svc_handler.c`.
The mapping is implemented in ``interface/src/tfm_nspm_svc_handler.c``.
The system integrators **may** implement the non-secure ID mapping based on
their application/threat model.
In case the NS OS doesn't use the Thread Context Management for Armv8-M TrustZone
APIs, then TF-M considers the NS SW as a single client, and assigns a client ID
to it automatically.
In case the NS OS doesn't use the Thread Context Management for Armv8-M
TrustZone APIs, then TF-M considers the NS SW as a single client, and assigns a
client ID to it automatically.
--------------
*Copyright (c) 2018, Arm Limited. All rights reserved.*
*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*

365
docs/user_guides/tfm_secure_boot.md
View File

@ -1,365 +0,0 @@
# Trusted Firmware M secure boot
For secure devices it is security critical to enforce firmware authenticity to
protect against execution of malicious software. This is implemented by building
a trust chain where each step in the execution chain authenticates the next
step before execution. The chain of trust in based on a "Root of Trust" which
is implemented using asymmetric cryptography. The Root of Trust is a combination
of an immutable bootloader and a public key(ROTPK).
# Second stage bootloader in TF-M
To implement secure boot functionality an external project MCUBoot has been
integrated to TF-M. For further information please refer to the
[MCUBoot homepage](https://www.mcuboot.com/).
Original source-code is available at
[GitHub](https://github.com/runtimeco/mcuboot).
This document contains information about MCUBoot modifications and how MCUBoot
has been integrated to TF-M.
Bootloader is started when CPU is released from reset. It runs in secure mode.
It authenticates the firmware image by hash (SHA-256) and digital signature
(RSA-2048) validation. Public key, that the checks happens against, is built
into the bootloader image. Metadata of the image is delivered together with the
image itself in a header and trailer section. In case of successful
authentication, bootloader passes execution to the secure image. Execution never
returns to bootloader until next reset.
A default RSA key pair is stored in the repository, public key is in `keys.c`
and private key is in `root-rsa-2048.pem`. `DO NOT use them in production code,
they are exclusively for testing!` Private key must be stored in a safe place
outside of the repository. `Imgtool.py` can be used to generate new key pairs.
The bootloader handles the secure and non-secure images as a single blob which
is contiguous in the device memory. At compile time these images are
concatenated and signed with RSA-2048 digital signature. Preparation of payload
is done by Python scripts: `bl2/ext/mcuboot/scripts/`. At the end of a
successful build signed TF-M payload can be found in:
```
<build_dir>/install/outputs/fvp/tfm_sign.bin
```
## Integration with TF-M
MCUBoot assumes a predefined memory layout which is described below
(applicable for AN521). It is mandatory to define slot 0, slot 1 and scratch
partitions, but their size can be changed:
```
- 0x0000_0000 - 0x0007_FFFF: BL2 bootloader - MCUBoot
- 0x0008_0000 - 0x000F_FFFF: Slot 0 : Single binary blob: Secure + Non-Secure
image; Primary memory partition
- 0x0008_0000 - 0x0008_03FF: Common image header
- 0x0008_0400 - 0x0008_xxxx: Secure image
- 0x0008_xxxx - 0x0010_03FF: Padding (with 0xFF)
- 0x0010_0400 - 0x0010_xxxx: Non-secure image
- 0x0010_xxxx - 0x0010_xxxx: Hash value(SHA256) and RSA signature
of combined image
- 0x0018_0000 - 0x0027_FFFF: Slot 1 : Secure + Non-Secure image; Secondary
memory partition, structured identically to slot
0
- 0x0028_0000 - 0x0037_FFFF: Scratch area, used during image swapping
```
## Firmware upgrade operation
MCUBoot handles only the firmware authenticity check after start-up and the
firmware switch part of the firmware update process. Downloading the new version
of the firmware is out-of-scope for MCUBoot. MCUBoot supports two different ways
to switch to the new firmware and it is assumed that firmware images are
executed-in-place (XIP). The default behaviour is the image swapping. In this
case active firmware is always executed from slot 0 and slot 1 is a staging area
for new images. Before executing the new firmware image, the content of the two
memory slots must be physically swapped. The other option is the non-swapping
version, which eliminates the complexity of image swapping and its
administration. Active image can be executed from either memory slot, but new
firmware must be linked to the address space of the proper (currently inactive)
memory slot.
### Swapping operation
Active image is stored in slot 0, and this image is started always by the
bootloader. Therefore images must be linked to slot 0. If the bootloader finds a
valid image in slot 1, which is marked for upgrade, then contents of slot 0 and
slot 1 will be swapped, before starting the new image from slot 0. Scratch area
is used as a temporary storage place during image swapping. Update mark from
slot 1 is removed when the swapping is successful. The boot loader can revert
the swapping as a fall-back mechanism to recover the previous working firmware
version after a faulty update. The swap operation is fail-safe and resistant to
power-cut failures. For more details please refer to the MCUBoot [documentation](https://www.mcuboot.com/mcuboot/design.html).
### Non-swapping operation
This operation can be turned on with `MCUBOOT_NO_SWAP` compile time switch. See
[next chapter](#Build time configuration). When enabling non-swapping operation
then the active image flag is moved between slots during firmware upgrade. If
firmware is executed-in-place (XIP), then two firmware images must be generated.
One of them is linked to be executed from slot 0 memory region and the other
from slot 1. The firmware upgrade client, which downloads the new image, must be
aware, which slot hosts the active firmware and which acts as a staging area and
it is responsible for downloading the proper firmware image. At boot time
MCUBoot inspects the version number in the image header and passes execution to
the newer firmware version. New image must be marked for upgrade which is
automatically done by Python scripts at compile time. Image verification is done
the same way in both operational modes. If new image fails during authentication
then MCUBoot erases the memory slot and starts the other image, after successful
authentication.
At build time automatically two binaries are generated:
```
<build_dir>/install/outputs/fvp/tfm_s_ns_signed_0.bin : Image linked for slot 0
memory partition
<build_dir>/install/outputs/fvp/tfm_s_ns_signed_1.bin : Image linked for slot 1
memory partition
```
### RAM Loading firmware upgrade
Musca-A supports an image upgrade mode that is separate to both the swapping
and non-swapping modes. This is the `RAM loading` mode (please refer to the
table below). Like the non-swapping mode, this selects the newest image by
reading the image version numbers in the image headers, but instead of
executing it in place, the newest image is copied to RAM for execution. The
load address, the location in RAM where the image is copied to, is stored
in the image header.
### Summary of different modes for image upgrade
Different implementations of the image upgrade operation (whether through
swapping, non-swapping, or loading into RAM and executing from there)
are supported by the platforms. The table below shows which of these modes
are supported by which platforms:
| - | Without BL2 <sup>1</sup> | With BL2 <sup>2</sup> | With BL2 <sup>2</sup> | With BL2 <sup>2</sup> |
|:--------:|:------------------------:|:---------------------:|:---------------------:|:------------------------:|
| - | XIP | XIP | XIP | Not XIP |
| - | - | Swap <sup>3</sup> | No-swap <sup>4</sup> | RAM loading <sup>5</sup> |
| AN521 | Yes | Yes | Yes | No |
| AN519 | Yes | Yes | Yes | No |
| Musca-A | No | No | No | Yes |
| Musca-B1 | Yes | No | Yes | No |
(1) To disable BL2, please turn off the `BL2` compiler switch in the
top-level configuration files or in the command line
(2) BL2 is enabled by default
(3) The image executes in-place (XIP) and is in swapping mode for image update
by default
(4) To enable XIP No-swap, set the configuration variable `MCUBOOT_NO_SWAP` to
`True` in the top-level configuration files, or include the `MCUBOOT_NO_SWAP`
macro in the command line
(5) To enable RAM loading, set the configuration variable `MCUBOOT_RAM_LOADING`
to `True` in the top-level configuration files, or include the
`MCUBOOT_RAM_LOADING` macro in the command line
## Build time configuration
MCUBoot related compile time switches can be set in the high level build
configuration files:
```
ConfigDefault.cmake
ConfigCoreTest.cmake
ConfigRegression.cmake
```
Compile time switches:
- BL2 (default: True):
- **True:** TF-M built together with bootloader. MCUBoot is executed after
reset and it authenticates TF-M and starts secure code.
- **False:** TF-M built without bootloader. Secure image linked to the
beginning of the device memory and executed after reset. If it is false then
using any of the further compile time switches are invalid.
- MCUBOOT\_NO\_SWAP (default: False):
- **True:** Activate non-swapping firmware upgrade operation.
- **False:** Original firmware upgrade operation with image swapping.
- MCUBOOT\_RAM\_LOADING (default: False):
- **True:** Activate RAM loading firmware upgrade operation, where latest
image is copied to RAM and runs from there instead of being executed
in-place.
- **False:** Original firmware upgrade operation with image swapping.
### Image versioning
An image version number is written to its header by one of the python scripts,
and this number is used by the bootloader when the non-swapping mode is
enabled.
The version number of the image can manually be passed in through the command
line in the cmake configuration step:
```
cmake -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG -DIMAGE_VERSION=1.2.3+4 ../
```
Alternatively, the version number can be less specific (e.g 1, 1.2, or 1.2.3),
where the missing numbers are automatically set to zero. The image version
number argument is optional, and if it is left out, then the version numbers of
the image(s) being built in the same directory will automatically change. In
this case, the last component (the build number) automatically increments from
the previous one: 0.0.0+1 -> 0.0.0+2, for as many times as the build is re-ran,
**until a number is explicitly provided**. If automatic versioning is in place
and then an image version number is provided for the first time, the new number
will take precedence and be used instead. All subsequent image versions are
then set to the last number that has been specified, and the build number would
stop incrementing. Any new version numbers that are provided will overwrite
the previous one: 0.0.0+1 -> 0.0.0+2. Note: To re-apply automatic image
versioning, please start a clean build without specifying the image version
number at all.
## Testing firmware upgrade
As downloading the new firmware image is out of scope for MCUBoot, the update
process is started from a state where the original and the new image are already
programmed to the appropriate memory slots. To generate the original and a new
firmware package, TF-M is built twice with different build configurations.
### Swapping firmware upgrade
Run TF-M build twice with two different build configuration: default and
regression. Save the artefacts between builds, because second run can overwrite
original binaries. Download default build to slot 0 and regression build to
slot 1.
#### Executing firmware upgrade on FVP\_MPS2\_AEMv8M
```
<DS5_PATH>/sw/models/bin/FVP_MPS2_AEMv8M \
--parameter fvp_mps2.platform_type=2 \
--parameter cpu0.baseline=0 \
--parameter cpu0.INITVTOR_S=0x10000000 \
--parameter cpu0.semihosting-enable=0 \
--parameter fvp_mps2.DISABLE_GATING=0 \
--parameter fvp_mps2.telnetterminal0.start_telnet=1 \
--parameter fvp_mps2.telnetterminal1.start_telnet=0 \
--parameter fvp_mps2.telnetterminal2.start_telnet=0 \
--parameter fvp_mps2.telnetterminal0.quiet=0 \
--parameter fvp_mps2.telnetterminal1.quiet=1 \
--parameter fvp_mps2.telnetterminal2.quiet=1 \
--application cpu0=<build_dir>/bl2/ext/mcuboot/mcuboot.axf \
--data cpu0=<default_build_dir>/install/outputs/fvp/tfm_s_ns_signed.bin@0x10080000 \
--data cpu0=<regresssion_build_dir>/install/outputs/fvp/tfm_s_ns_signed.bin@0x10180000
```
#### Executing firmware upgrade on SSE 200 FPGA on MPS2 board
```
TITLE: Versatile Express Images Configuration File
[IMAGES]
TOTALIMAGES: 3 ;Number of Images (Max: 32)
IMAGE0ADDRESS: 0x00000000
IMAGE0FILE: \Software\mcuboot.axf ; BL2 bootloader
IMAGE1ADDRESS: 0x10080000
IMAGE1FILE: \Software\tfm_sig1.bin ; TF-M example application binary blob
IMAGE2ADDRESS: 0x10180000
IMAGE2FILE: \Software\tfm_sig2.bin ; TF-M regression test binary blob
```
The following message will be shown in case of successful firmware upgrade,
`Swap type: test` indicates that images were swapped:
```
[INF] Image 0: magic=good, copy_done=0xff, image_ok=0xff
[INF] Scratch: magic=bad, copy_done=0x5, image_ok=0xcf
[INF] Boot source: slot 0
[INF] Swap type: test
[INF] Bootloader chainload address offset: 0x80000
[INF] Jumping to the first image slot
[Sec Thread] Secure image initializing!
#### Execute test suites for the secure storage service ####
Running Test Suite SST secure interface tests (TFM_SST_TEST_2XXX)...
...
```
### Non-swapping firmware upgrade
Follow the same instructions as in case of swapping build including these
changes:
- Set MCUBOOT\_NO\_SWAP compile time switch to true before build.
- Increase the image version number between the two build run.
#### Executing firmware upgrade on FVP\_MPS2\_AEMv8M
```
<DS5_PATH>/sw/models/bin/FVP_MPS2_AEMv8M \
--parameter fvp_mps2.platform_type=2 \
--parameter cpu0.baseline=0 \
--parameter cpu0.INITVTOR_S=0x10000000 \
--parameter cpu0.semihosting-enable=0 \
--parameter fvp_mps2.DISABLE_GATING=0 \
--parameter fvp_mps2.telnetterminal0.start_telnet=1 \
--parameter fvp_mps2.telnetterminal1.start_telnet=0 \
--parameter fvp_mps2.telnetterminal2.start_telnet=0 \
--parameter fvp_mps2.telnetterminal0.quiet=0 \
--parameter fvp_mps2.telnetterminal1.quiet=1 \
--parameter fvp_mps2.telnetterminal2.quiet=1 \
--application cpu0=<build_dir>/bl2/ext/mcuboot/mcuboot.axf \
--data cpu0=<default_build_dir>/install/outputs/fvp/tfm_s_ns_signed_0.bin@0x10080000 \
--data cpu0=<regresssion_build_dir>/install/outputs/fvp/tfm_s_ns_signed_1.bin@0x10180000
```
#### Executing firmware upgrade on SSE 200 FPGA on MPS2 board
```
TITLE: Versatile Express Images Configuration File
[IMAGES]
TOTALIMAGES: 3 ;Number of Images (Max: 32)
IMAGE0ADDRESS: 0x00000000
IMAGE0FILE: \Software\mcuboot.axf ; BL2 bootloader
IMAGE1ADDRESS: 0x10080000
IMAGE1FILE: \Software\tfm_sig0.bin ; TF-M example application binary blob
IMAGE2ADDRESS: 0x10180000
IMAGE2FILE: \Software\tfm_sig1.bin ; TF-M regression test binary blob
```
#### Executing firmware upgrade on Musca-B1 board
After two images have been built, they can be concatenated to create the
combined image using `srec_cat`:
- Linux: `srec_cat bl2/ext/mcuboot/mcuboot.bin -Binary -offset 0xA000000 tfm_sign_0.bin -Binary -offset 0xA020000 tfm_sign_1.bin -Binary -offset 0xA0A0000 -o tfm.hex -Intel`
- Windows: `srec_cat.exe bl2\ext\mcuboot\mcuboot.bin -Binary -offset 0xA000000 tfm_sign_0.bin -Binary -offset 0xA020000 tfm_sign_1.bin -Binary -offset 0xA0A0000 -o tfm.hex -Intel`
The following message will be shown in case of successful firmware upgrade,
notice that image with higher version number (`version=1.2.3.5`) is executed:
```
[INF] Starting bootloader
[INF] Image 0: version=1.2.3.4, magic= good, image_ok=0xff
[INF] Image 1: version=1.2.3.5, magic= good, image_ok=0xff
[INF] Booting image from slot 1
[INF] Bootloader chainload address offset: 0x180000
[INF] Jumping to the first image slot
[Sec Thread] Secure image initializing!
#### Execute test suites for the Secure area ####
Running Test Suite SST secure interface tests (TFM_SST_TEST_2XXX)...
...
```
### RAM loading firmware upgrade
To enable RAM loading, please set `MCUBOOT_RAM_LOADING` to True (either in the
configuration file or through the command line), and then specify a destination
load address in RAM where the image can be copied to and executed from. The
`IMAGE_LOAD_ADDRESS` macro must be specified in the target dependent files,
for example with Musca-A, its `flash_layout.h` file in the `platform` folder
should include `#define IMAGE_LOAD_ADDRESS #0x10020000`
#### Executing firmware upgrade on Musca-A board
After two images have been built, they can be concatenated to create the
combined image using `srec_cat`:
```
Windows:
srec_cat.exe bl2\ext\mcuboot\mcuboot.bin -Binary -offset 0x200000
tfm_sign_old.bin -Binary -offset 0x220000 tfm_sign_new.bin -Binary -offset
0x320000 -o tfm.hex -Intel
Linux:
srec_cat bl2/ext/mcuboot/mcuboot.bin -Binary -offset 0x200000 tfm_sign_old.bin
-Binary -offset 0x220000 tfm_sign_new.bin -Binary -offset
0x320000 -o tfm.hex -Intel
```
The following message will be shown in case of successful firmware upgrade when,
RAM loading is enabled, notice that image with higher version number
(`version=0.0.0.2`) is executed:
```
[INF] Image 0: version=0.0.0.1, magic= good, image_ok=0xff
[INF] Image 1: version=0.0.0.2, magic= good, image_ok=0xff
[INF] Image has been copied from slot 1 in flash to SRAM address 0x10020000
[INF] Booting image from SRAM at address 0x10020000
[INF] Bootloader chainload address offset: 0x20000
[INF] Jumping to the first image slot
[Sec Thread] Secure image initializing!
```
--------------
*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*

398
docs/user_guides/tfm_secure_boot.rst Normal file
View File

@ -0,0 +1,398 @@
##############################
Trusted Firmware M secure boot
##############################
For secure devices it is security critical to enforce firmware authenticity to
protect against execution of malicious software. This is implemented by building
a trust chain where each step in the execution chain authenticates the next
step before execution. The chain of trust in based on a "Root of Trust" which
is implemented using asymmetric cryptography. The Root of Trust is a combination
of an immutable bootloader and a public key (ROTPK).
*******************************
Second stage bootloader in TF-M
*******************************
To implement secure boot functionality an external project MCUBoot has been
integrated to TF-M. For further information please refer to the
`MCUBoot homepage <https://www.mcuboot.com/>`__. Original source-code is available at
`GitHub <https://github.com/runtimeco/mcuboot>`__. This document contains
information about MCUBoot modifications and how MCUBoot has been integrated to
TF-M.
Bootloader is started when CPU is released from reset. It runs in secure mode.
It authenticates the firmware image by hash (SHA-256) and digital signature
(RSA-2048) validation. Public key, that the checks happens against, is built
into the bootloader image. Metadata of the image is delivered together with the
image itself in a header and trailer section. In case of successful
authentication, bootloader passes execution to the secure image. Execution never
returns to bootloader until next reset.
A default RSA key pair is stored in the repository, public key is in ``keys.c``
and private key is in ``root-rsa-2048.pem``.
.. Warning::
``DO NOT use them in production code, they are exclusively for testing!``
Private key must be stored in a safe place outside of the repository.
``Imgtool.py`` can be used to generate new key pairs.
The bootloader handles the secure and non-secure images as a single blob which
is contiguous in the device memory. At compile time these images are
concatenated and signed with RSA-2048 digital signature. Preparation of payload
is done by Python scripts: ``bl2/ext/mcuboot/scripts/``. At the end of a
successful build signed TF-M payload can be found in::
<build_dir>/install/outputs/fvp/tfm_sign.bin
*********************
Integration with TF-M
*********************
MCUBoot assumes a predefined memory layout which is described below (applicable
for AN521). It is mandatory to define slot 0, slot 1 and scratch partitions, but
their size can be changed::
- 0x0000_0000 - 0x0007_FFFF: BL2 bootloader - MCUBoot
- 0x0008_0000 - 0x000F_FFFF: Slot 0 : Single binary blob: Secure + Non-Secure
image; Primary memory partition
- 0x0008_0000 - 0x0008_03FF: Common image header
- 0x0008_0400 - 0x0008_xxxx: Secure image
- 0x0008_xxxx - 0x0010_03FF: Padding (with 0xFF)
- 0x0010_0400 - 0x0010_xxxx: Non-secure image
- 0x0010_xxxx - 0x0010_xxxx: Hash value(SHA256) and RSA signature
of combined image
- 0x0018_0000 - 0x0027_FFFF: Slot 1 : Secure + Non-Secure image; Secondary
memory partition, structured identically to slot
0
- 0x0028_0000 - 0x0037_FFFF: Scratch area, used during image swapping
**************************
Firmware upgrade operation
**************************
MCUBoot handles only the firmware authenticity check after start-up and the
firmware switch part of the firmware update process. Downloading the new version
of the firmware is out-of-scope for MCUBoot. MCUBoot supports two different ways
to switch to the new firmware and it is assumed that firmware images are
executed-in-place (XIP). The default behaviour is the image swapping. In this
case active firmware is always executed from slot 0 and slot 1 is a staging area
for new images. Before executing the new firmware image, the content of the two
memory slots must be physically swapped. The other option is the non-swapping
version, which eliminates the complexity of image swapping and its
administration. Active image can be executed from either memory slot, but new
firmware must be linked to the address space of the proper (currently inactive)
memory slot.
Swapping operation
==================
Active image is stored in slot 0, and this image is started always by the
bootloader. Therefore images must be linked to slot 0. If the bootloader finds a
valid image in slot 1, which is marked for upgrade, then contents of slot 0 and
slot 1 will be swapped, before starting the new image from slot 0. Scratch area
is used as a temporary storage place during image swapping. Update mark from
slot 1 is removed when the swapping is successful. The boot loader can revert
the swapping as a fall-back mechanism to recover the previous working firmware
version after a faulty update. The swap operation is fail-safe and resistant to
power-cut failures. For more details please refer to the MCUBoot
`documentation <https://www.mcuboot.com/mcuboot/design.html>`__.
Non-swapping operation
======================
This operation can be turned on with ``MCUBOOT_NO_SWAP`` compile time switch
(see `Build time configuration`_). When enabling non-swapping operation then the
active image flag is moved between slots during firmware upgrade. If firmware is
executed-in-place (XIP), then two firmware images must be generated.
One of them is linked to be executed from slot 0 memory region and the other
from slot 1. The firmware upgrade client, which downloads the new image, must be
aware, which slot hosts the active firmware and which acts as a staging area and
it is responsible for downloading the proper firmware image. At boot time
MCUBoot inspects the version number in the image header and passes execution to
the newer firmware version. New image must be marked for upgrade which is
automatically done by Python scripts at compile time. Image verification is done
the same way in both operational modes. If new image fails during authentication
then MCUBoot erases the memory slot and starts the other image, after successful
authentication.
At build time automatically two binaries are generated::
<build_dir>/install/outputs/fvp/tfm_s_ns_signed_0.bin : Image linked for slot 0
memory partition
<build_dir>/install/outputs/fvp/tfm_s_ns_signed_1.bin : Image linked for slot 1
memory partition
RAM Loading firmware upgrade
============================
Musca A1 supports an image upgrade mode that is separate to both the swapping
and non-swapping modes. This is the ``RAM loading`` mode (please refer to the
table below). Like the non-swapping mode, this selects the newest image by
reading the image version numbers in the image headers, but instead of
executing it in place, the newest image is copied to RAM for execution. The
load address, the location in RAM where the image is copied to, is stored
in the image header.
Summary of different modes for image upgrade
============================================
Different implementations of the image upgrade operation (whether through
swapping, non-swapping, or loading into RAM and executing from there) are
supported by the platforms. The table below shows which of these
modes are supported by which platforms:
+------------+-----------------+--------------+--------------+-----------------+
| | Without BL2 [1]_| With BL2 [2]_| With BL2 [2]_| With BL2 [2]_ |
+============+=================+==============+==============+=================+
| | XIP | XIP | XIP | Not XIP |
+------------+-----------------+--------------+--------------+-----------------+
| | | Swap [3]_ | No-swap [4]_ | RAM loading [5]_|
+------------+-----------------+--------------+--------------+-----------------+
| AN521 | Yes | Yes | Yes | No |
+------------+-----------------+--------------+--------------+-----------------+
| AN519 | Yes | Yes | Yes | No |
+------------+-----------------+--------------+--------------+-----------------+
| Musca-A1 | No | No | No | Yes |
+------------+-----------------+--------------+--------------+-----------------+
| Musca-B1 | Yes | No | Yes | No |
+------------+-----------------+--------------+--------------+-----------------+
.. [1] To disable BL2, please turn off the ``BL2`` compiler switch in the
top-level configuration files or in the command line
.. [2] BL2 is enabled by default
.. [3] The image executes in-place (XIP) and is in swapping mode for image
update by default
.. [4] To enable XIP No-swap, set the configuration variable ``MCUBOOT_NO_SWAP``
to ``True`` in the top-level configuration files, or include the
``MCUBOOT_NO_SWAP`` macro in the command line
.. [5] To enable RAM loading, set the configuration variable
``MCUBOOT_RAM_LOADING`` to ``True`` in the top-level configuration files, or
include the ``MCUBOOT_RAM_LOADING`` macro in the command line
************************
Build time configuration
************************
MCUBoot related compile time switches can be set in the high level build
configuration files::
ConfigDefault.cmake
ConfigCoreTest.cmake
ConfigRegression.cmake
Compile time switches:
- BL2 (default: True):
- **True:** TF-M built together with bootloader. MCUBoot is executed after
reset and it authenticates TF-M and starts secure code.
- **False:** TF-M built without bootloader. Secure image linked to the
beginning of the device memory and executed after reset. If it is false
then using any of the further compile time switches are invalid.
- MCUBOOT_NO_SWAP (default: False):
- **True:** Activate non-swapping firmware upgrade operation.
- **False:** Original firmware upgrade operation with image swapping.
- MCUBOOT_RAM_LOADING (default: False):
- **True:** Activate RAM loading firmware upgrade operation, where latest
image is copied to RAM and runs from there instead of being executed
in-place.
- **False:** Original firmware upgrade operation with image swapping.
Image versioning
================
An image version number is written to its header by one of the python scripts,
and this number is used by the bootloader when the non-swapping mode is
enabled.
The version number of the image can manually be passed in through the command
line in the cmake configuration step::
cmake -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG -DIMAGE_VERSION=1.2.3+4 ../
Alternatively, the version number can be less specific (e.g 1, 1.2, or 1.2.3),
where the missing numbers are automatically set to zero. The image version
number argument is optional, and if it is left out, then the version numbers of
the image(s) being built in the same directory will automatically change. In
this case, the last component (the build number) automatically increments from
the previous one: 0.0.0+1 -> 0.0.0+2, for as many times as the build is re-ran,
**until a number is explicitly provided**. If automatic versioning is in place
and then an image version number is provided for the first time, the new number
will take precedence and be used instead. All subsequent image versions are
then set to the last number that has been specified, and the build number would
stop incrementing. Any new version numbers that are provided will overwrite
the previous one: 0.0.0+1 -> 0.0.0+2. Note: To re-apply automatic image
versioning, please start a clean build without specifying the image version
number at all.
************************
Testing firmware upgrade
************************
As downloading the new firmware image is out of scope for MCUBoot, the update
process is started from a state where the original and the new image are already
programmed to the appropriate memory slots. To generate the original and a new
firmware package, TF-M is built twice with different build configurations.
Swapping firmware upgrade
=========================
Run TF-M build twice with two different build configuration: default and
regression. Save the artefacts between builds, because second run can overwrite
original binaries. Download default build to slot 0 and regression build to
slot 1.
Executing firmware upgrade on FVP_MPS2_AEMv8M
---------------------------------------------
.. code-block:: bash
<DS5_PATH>/sw/models/bin/FVP_MPS2_AEMv8M \
--parameter fvp_mps2.platform_type=2 \
--parameter cpu0.baseline=0 \
--parameter cpu0.INITVTOR_S=0x10000000 \
--parameter cpu0.semihosting-enable=0 \
--parameter fvp_mps2.DISABLE_GATING=0 \
--parameter fvp_mps2.telnetterminal0.start_telnet=1 \
--parameter fvp_mps2.telnetterminal1.start_telnet=0 \
--parameter fvp_mps2.telnetterminal2.start_telnet=0 \
--parameter fvp_mps2.telnetterminal0.quiet=0 \
--parameter fvp_mps2.telnetterminal1.quiet=1 \
--parameter fvp_mps2.telnetterminal2.quiet=1 \
--application cpu0=<build_dir>/bl2/ext/mcuboot/mcuboot.axf \
--data cpu0=<default_build_dir>/install/outputs/fvp/tfm_s_ns_signed.bin@0x10080000 \
--data cpu0=<regresssion_build_dir>/install/outputs/fvp/tfm_s_ns_signed.bin@0x10180000
Executing firmware upgrade on SSE 200 FPGA on MPS2 board
--------------------------------------------------------
::
TITLE: Versatile Express Images Configuration File
[IMAGES]
TOTALIMAGES: 3 ;Number of Images (Max: 32)
IMAGE0ADDRESS: 0x00000000
IMAGE0FILE: \Software\mcuboot.axf ; BL2 bootloader
IMAGE1ADDRESS: 0x10080000
IMAGE1FILE: \Software\tfm_sig1.bin ; TF-M example application binary blob
IMAGE2ADDRESS: 0x10180000
IMAGE2FILE: \Software\tfm_sig2.bin ; TF-M regression test binary blob
The following message will be shown in case of successful firmware upgrade,
``Swap type: test`` indicates that images were swapped:
::
[INF] Image 0: magic=good, copy_done=0xff, image_ok=0xff
[INF] Scratch: magic=bad, copy_done=0x5, image_ok=0xcf
[INF] Boot source: slot 0
[INF] Swap type: test
[INF] Bootloader chainload address offset: 0x80000
[INF] Jumping to the first image slot
[Sec Thread] Secure image initializing!
Execute test suites for the secure storage service
--------------------------------------------------
Running Test Suite SST secure interface tests (TFM_SST_TEST_2XXX)....
Non-swapping firmware upgrade
=============================
Follow the same instructions as in case of swapping build including these
changes:
- Set MCUBOOT_NO_SWAP compile time switch to true before build.
- Increase the image version number between the two build run.
Executing firmware upgrade on FVP_MPS2_AEMv8M
---------------------------------------------
.. code-block:: bash
<DS5_PATH>/sw/models/bin/FVP_MPS2_AEMv8M \
--parameter fvp_mps2.platform_type=2 \
--parameter cpu0.baseline=0 \
--parameter cpu0.INITVTOR_S=0x10000000 \
--parameter cpu0.semihosting-enable=0 \
--parameter fvp_mps2.DISABLE_GATING=0 \
--parameter fvp_mps2.telnetterminal0.start_telnet=1 \
--parameter fvp_mps2.telnetterminal1.start_telnet=0 \
--parameter fvp_mps2.telnetterminal2.start_telnet=0 \
--parameter fvp_mps2.telnetterminal0.quiet=0 \
--parameter fvp_mps2.telnetterminal1.quiet=1 \
--parameter fvp_mps2.telnetterminal2.quiet=1 \
--application cpu0=<build_dir>/bl2/ext/mcuboot/mcuboot.axf \
--data cpu0=<default_build_dir>/install/outputs/fvp/tfm_s_ns_signed_0.bin@0x10080000 \
--data cpu0=<regresssion_build_dir>/install/outputs/fvp/tfm_s_ns_signed_1.bin@0x10180000
Executing firmware upgrade on SSE 200 FPGA on MPS2 board
--------------------------------------------------------
::
TITLE: Versatile Express Images Configuration File
[IMAGES]
TOTALIMAGES: 3 ;Number of Images (Max: 32)
IMAGE0ADDRESS: 0x00000000
IMAGE0FILE: \Software\mcuboot.axf ; BL2 bootloader
IMAGE1ADDRESS: 0x10080000
IMAGE1FILE: \Software\tfm_sig0.bin ; TF-M example application binary blob
IMAGE2ADDRESS: 0x10180000
IMAGE2FILE: \Software\tfm_sig1.bin ; TF-M regression test binary blob
Executing firmware upgrade on Musca-B1 board
--------------------------------------------
After two images have been built, they can be concatenated to create the
combined image using ``srec_cat``:
- Linux::
srec_cat bl2/ext/mcuboot/mcuboot.bin -Binary -offset 0xA000000 tfm_sign_0.bin -Binary -offset 0xA020000 tfm_sign_1.bin -Binary -offset 0xA0A0000 -o tfm.hex -Intel
- Windows::
srec_cat.exe bl2\ext\mcuboot\mcuboot.bin -Binary -offset 0xA000000 tfm_sign_0.bin -Binary -offset 0xA020000 tfm_sign_1.bin -Binary -offset 0xA0A0000 -o tfm.hex -Intel
The following message will be shown in case of successful firmware upgrade,
notice that image with higher version number (``version=1.2.3.5``) is executed:
::
[INF] Starting bootloader
[INF] Image 0: version=1.2.3.4, magic= good, image_ok=0xff
[INF] Image 1: version=1.2.3.5, magic= good, image_ok=0xff
[INF] Booting image from slot 1
[INF] Bootloader chainload address offset: 0x180000
[INF] Jumping to the first image slot
[Sec Thread] Secure image initializing!
Execute test suites for the Secure area
---------------------------------------
Running Test Suite SST secure interface tests (TFM_SST_TEST_2XXX)...
RAM loading firmware upgrade
============================
To enable RAM loading, please set ``MCUBOOT_RAM_LOADING`` to True (either in the
configuration file or through the command line), and then specify a destination
load address in RAM where the image can be copied to and executed from. The
``IMAGE_LOAD_ADDRESS`` macro must be specified in the target dependent files,
for example with Musca A1, its ``flash_layout.h`` file in the ``platform``
folder should include ``#define IMAGE_LOAD_ADDRESS #0x10020000``
Executing firmware upgrade on Musca-A1 board
--------------------------------------------
After two images have been built, they can be concatenated to create the
combined image using ``srec_cat``:
- Linux:
srec_cat bl2/ext/mcuboot/mcuboot.bin -Binary -offset 0x200000 tfm_sign_old.bin -Binary -offset 0x220000 tfm_sign_new.bin -Binary -offset 0x320000 -o tfm.hex -Intel
- Windows::
srec_cat.exe bl2\ext\mcuboot\mcuboot.bin -Binary -offset 0x200000 tfm_sign_old.bin -Binary -offset 0x220000 tfm_sign_new.bin -Binary -offset 0x320000 -o tfm.hex -Intel
The following message will be shown in case of successful firmware upgrade when,
RAM loading is enabled, notice that image with higher version number
(``version=0.0.0.2``) is executed:
::
[INF] Image 0: version=0.0.0.1, magic= good, image_ok=0xff
[INF] Image 1: version=0.0.0.2, magic= good, image_ok=0xff
[INF] Image has been copied from slot 1 in flash to SRAM address 0x10020000
[INF] Booting image from SRAM at address 0x10020000
[INF] Bootloader chainload address offset: 0x20000
[INF] Jumping to the first image slot
[Sec Thread] Secure image initializing!
--------------
*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*

302
docs/user_guides/tfm_sw_requirement.md
View File

@ -1,302 +0,0 @@
# TF-M Software requirements
## Supported build environments
TF-M officially supports a limited set of build environments and setups. In
this context, official support means that the environments listed below
are actively used by team members and active developers hence users should
be able to recreate the same configurations by following the instructions
described below. In case of problems, the TF-M team provides support only for
these environments, but building in other environments can still be possible.
The following environments are supported:
- Windows 10 x64 + Cygwin x64 (example configuration is provided for this
Windows setup only).
- Windows 10 x64 + msys2 x64.
- Windows 10 x65 + git-bash (MinGW) + gnumake from DS-5 or msys2.
- Ubuntu 16.04 x64
- Ubuntu 18.04 x64
## Supported C compilers
To compile TF-M code, at least one of the supported compiler toolchains have to
be available in the build environment.
The currently supported compiler versions are:
- Arm Compiler v6.7.1
- Arm Compiler v6.9
- Arm Compiler v6.10
- Arm Compiler v6.11
- GNU Arm compiler v6.3.1
- GNU Arm compiler v7.3
**Notes:**
- The Arm compilers above are provided via Keil uVision v5.24.1 or greater,
DS-5 v5.27.1 or greater, and Development Studio 2018.0, or they can be
downloaded as standalone packages from [here](https://developer.arm.com/products/software-development-tools/compilers/arm-compiler/downloads/version-6).
- Arm compiler specific environment variable may need updating based
on specific products and licenses as explained in
[product-and-toolkit-configuration](https://developer.arm.com/products/software-development-tools/license-management/resources/product-and-toolkit-configuration).
- The GNU Arm compiler can be downloaded from [here](https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads).
On the page select *GNU Arm Embedded Toolchain: 6-2017-q1-update* or
*GNU Arm Embedded Toolchain: 7-2018-q2-update*
## Supported CMake versions
The build-system is CMake based and supports the following versions:
- 3.7
- 3.10
- 3.11
- 3.12
- 3.13
- 3.14
Please use the latest build version available (i.e. 3.7.2 instead of 3.7.0).
While it is preferable to use the newest version this is not required and any
version from the above list should work.
Recent versions of CMake can be downloaded from https://cmake.org/download/, and
older releases are available from https://cmake.org/files.
## Supported GNU make versions
The TF-M team builds using the "Unix Makefiles" generator of CMake and thus
GNU make is needed for the build. On Linux please use the version
available from the official repository of your distribution.
On Windows the following binaries are supported:
- GNU make v4.2.1 executable from Cygwin
- GNU make v4.2.1 executable from msys2
- GNU make v4.2 executable from DS5 v5.29.1 (see <DS-5_PATH>/bin)
CMake is quiet tolerant to GNU make versions and basically any "reasonably
recent" GNU make version shall work.
CMake generators other than "Unix Makefiles" may work, but are not officially
supported.
## Example setups
This section lists dependencies and some exact and tested steps to set-up a
TF-M-m build environment under various OSes.
### Ubuntu
- DS-5 v5.27.1.
- Git tools v2.10.0
- CMake (see the "Supported CMake versions" chapter)
- GNU Make (see the "Supported make versions" chapter)
- Python3, with the following libraries:
- pycrypto
- pyasn1
- yaml
- jinja2 v2.10
- sudo apt-get install python3-crypto python3-pyasn1 python3-yaml python3-jinja2
- SRecord v1.58 (for Musca test chip boards)
#### Setup a shell to enable compiler toolchain and CMake after installation.
To import Arm Compiler v6.7.1 in your bash shell console:
**Note:** Arm compiler specific environment variable may need updating based
on specific products and licenses as explained in
[product-and-toolkit-configuration](https://developer.arm.com/products/software-development-tools/license-management/resources/product-and-toolkit-configuration).
~~~
export PATH=<DS-5_PATH>/sw/ARMCompiler6.7.1/bin:$PATH
export ARM_TOOL_VARIANT="ult"
export ARM_PRODUCT_PATH="<DS-5_PATH>/sw/mappings"
export ARMLMD_LICENSE_FILE="<LICENSE_FILE_PATH>"
~~~
To import CMake in your bash shell console:
~~~
export PATH=<CMAKE_PATH>/bin:$PATH
~~~
To import GNU Arm in your bash shell console:
~~~
export PATH=<GNU_ARM_PATH>/bin:$PATH
~~~
### Windows + Cygwin
- uVision v5.24.1 or DS-5 v5.27.1 (DS-5 Ultimate Edition) which provides the
Arm Compiler v6.7.1 compiler or GNU Arm compiler v6.3.1.
- Git client latest version (https://git-scm.com/download/win)
- CMake (see the "Supported CMake versions" chapter)
- [Cygwin]( https://www.cygwin.com/ ). Tests done with version 2.877 (64 bits)
- GNU make should be installed by selecting appropriate package during cygwin
installation.
- Python3 [(native Windows version)](https://www.python.org/downloads/), with the following libraries:
- pycryptodome (pip3 install --user pycryptodome)
- pyasn1 (pip3 install --user pyasn1)
- pyyaml (pip3 install --user pyyaml)
- jinja2 (pip3 install --user jinja2)
- Python3 pip
- [SRecord v1.63](https://sourceforge.net/projects/srecord/) (for Musca test chip boards)
#### Setup Cygwin to enable a compiler toolchain and CMake after installation.
If applicable, import Arm Compiler v6.7.1 in your shell console. To make this
change permanent, add the command line into ~/.bashrc
**DS-5**
**Notes:**
- Arm compiler specific environment variable may need updating based
on specific products and licenses as explained in
[product-and-toolkit-configuration](https://developer.arm.com/products/software-development-tools/license-management/resources/product-and-toolkit-configuration).
- Arm licensing related environment variables must use Windows paths,
and not the Cygwin specific one relative to */cygrive*.
~~~
export PATH="/cygdrive/c/<DS-5_PATH>/sw/ARMCompiler6.7.1/bin":$PATH
export ARM_PRODUCT_PATH="C:/<DS-5_PATH>/sw/mappings"
export ARM_TOOL_VARIANT="ult"
export ARMLMD_LICENSE_FILE="<LICENSE_FILE_PATH>"
~~~
**Keil MDK Arm**
**Notes:**
- Arm compiler specific environment variable may need updating based
on specific products and licenses as explained in
[product-and-toolkit-configuration](https://developer.arm.com/products/software-development-tools/license-management/resources/product-and-toolkit-configuration).
~~~
export PATH="/cygdrive/c/<uVision path>/ARM/ARMCLANG/bin":$PATH
~~~
If applicable, import GNU Arm compiler v6.3.1 in your shell console. To make
this change permanent, add the command line into ~/.bashrc
**GNU Arm**
~~~
export PATH=<GNU_ARM_PATH>/bin:$PATH
~~~
To import CMake in your bash shell console:
**CMake**
~~~
export PATH=/cygdrive/c/<CMAKE_PATH>/bin:$PATH
~~~
### Building documentation
The build system is prepared to support generation of two documents. The
Reference Manual which is Doxygen based, and the User Guide which is Sphinx
based.
Both document can be generated in HTML and PDF format.
*Note* support for document generation in the build environment is not
mandatory. Missing document generation tools will not block building the TF-M
firmware.
#### To compile the TF-M Reference Manual
The following additional tools are needed:
- Doxygen v1.8.0 or later
- Graphviz dot v2.38.0 or later
- PlantUML v1.2018.11 or later
- Java runtime environment 1.8 or later (for running PlantUML)
For PDF generation the following tools are needed in addition to the above list:
- LaTeX
- PdfLaTeX
##### Set-up the needed tools
###### Linux
- sudo apt-get install -y doxygen graphviz default-jre
- mkdir ~/plantuml; curl -L http://sourceforge.net/projects/plantuml/files/plantuml.jar/download --output ~/plantuml/plantuml.jar
For PDF generation:
- sudo apt-get install -y doxygen-latex
###### Windows
- [Doxygen 1.8.8](https://sourceforge.net/projects/doxygen/files/snapshots/doxygen-1.8-svn/windows/doxygenw20140924_1_8_8.zip/download)
- [Graphviz 2.38](https://graphviz.gitlab.io/_pages/Download/windows/graphviz-2.38.msi)
- The Java runtime is part of the DS5 installation or can be
[downloaded from here](https://www.java.com/en/download/)
- [PlantUML](http://sourceforge.net/projects/plantuml/files/plantuml.jar/download)
For PDF generation:
- [MikTeX](https://miktex.org/download)
*Note* When building the documentation the first time, MikTeX might prompt for
installing missing LaTeX components. Please allow the MikTeX package manager to
set-up these.
###### Configure the shell
####### Linux
~~~
export PLANTUML_JAR_PATH="~/plantuml/plantuml.jar"
~~~
####### Windows + Cygwin
Assumptions for the settings below:
- plantuml.jar is available at c:\plantuml\plantuml.jar
- doxygen, dot, and MikTeX binaries are available on the PATH.
~~~
export PLANTUML_JAR_PATH="c:/plantuml/plantuml.jar"
export PATH=$PATH:/cygdrive/c/<DS-5 path>/sw/java/bin
~~~
#### To compile the TF-M User Guide
The following additional tools are needed:
- Python3 and the following modules:
- Sphinx v1.7.9
- m2r v0.2.0
- Graphviz dot v2.38.0 or later
- PlantUML v1.2018.11 or later
- Java runtime environment 1.8 or later (for running PlantUML)
For PDF generation the following tools are needed in addition to the above list:
- LaTeX
- PdfLaTeX
##### Set-up the needed tools
###### Linux
- sudo apt-get install -y python3 graphviz default-jre
- pip --user install m2r Sphinx sphinx-rtd-theme
- mkdir ~/plantuml; curl -L http://sourceforge.net/projects/plantuml/files/plantuml.jar/download --output ~/plantuml/plantuml.jar
For PDF generation:
- sudo apt-get install -y doxygen-latex
###### Windows
- Python3 [(native Windows version)](https://www.python.org/downloads/)
- pip --user install m2r Sphinx sphinx-rtd-theme
- [Graphviz 2.38](https://graphviz.gitlab.io/_pages/Download/windows/graphviz-2.38.msi)
- The Java runtime is part of the DS5 installation or can be
[downloaded from here](https://www.java.com/en/download/)
- [PlantUML](http://sourceforge.net/projects/plantuml/files/plantuml.jar/download)
For PDF generation:
- [MikTeX](https://miktex.org/download)
*Note* When building the documentation the first time, MikTeX might prompt for
installing missing LaTeX components. Please allow the MikTeX package manager to
set-up these.
##### Configure the shell
###### Linux
~~~
export PLANTUML_JAR_PATH="~/plantuml/plantuml.jar"
~~~
###### Windows + Cygwin
Assumptions for the settings below:
- plantuml.jar is available at c:\plantuml\plantuml.jar
- doxygen, dot, and MikTeX binaries are available on the PATH.
~~~
export PLANTUML_JAR_PATH="c:/plantuml/plantuml.jar"
export PATH=$PATH:/cygdrive/c/<DS-5 path>/sw/java/bin
~~~
--------------
*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*

501
docs/user_guides/tfm_sw_requirement.rst Normal file
View File

@ -0,0 +1,501 @@
##########################
TF-M Software requirements
##########################
To build the TF-M firmware the following tools are needed:
.. csv-table:: Tool dependencies
:header: "Name", "Version", "Component"
"C compiler",See `Supported C compilers`_,"Firmware"
"CMake",See `Supported CMake versions`_,
"GNU Make",See `Supported GNU make versions`_,
"Python",3.x,"Firmware, User Guide"
"yaml",,"Firmware"
"pyasn1",,"Firmware"
"jinja2",,"Firmware"
"pycrypto",,"Firmware"
"Doxygen",">1.8","Reference manual"
"Sphinx",">1.4","User Guide"
"sphinxcontrib-plantuml",,"User Guide"
"sphinx-trd-theme",,"User Guide"
"Git",,
"PlantUML",">v1.2018.11","Reference Manual, User Guide"
"Graphviz dot",">v2.38.0","Reference manual"
"Java runtime environment (JRE)",">1.8","Reference Manual, User Guide"
"LaTex",,"pdf version of Reference Manual and User Guide"
"PdfLaTex",,"pdf version of Reference Manual and User Guide"
Dependency chain:
.. uml::
@startuml
skinparam state {
BackgroundColor #92AEE0
FontColor black
FontSize 16
AttributeFontColor black
AttributeFontSize 16
BackgroundColor<<pdf>> #A293E2
BackgroundColor<<doc>> #90DED6
}
state fw as "Firmware" : TF-M binary
state c_comp as "C Compiler" : C99
state gmake as "GNU make"
state u_guide as "User Guide" <<doc>>
state refman as "Reference Manual" <<doc>>
state rtd_theme as "sphinx-rtd-theme" <<doc>>
state sphnix_puml as "sphinxcontrib-plantuml" <<doc>>
state JRE as "JRE" <<doc>> : Java Runtime Environment
state gwiz as "Graphwiz dot" <<doc>>
state Sphinx as "Sphinx" <<doc>>
state m2r as "m2r" <<doc>>
state PlantUML as "PlantUML" <<doc>>
state LaTex as "LaTex" <<pdf>>
state PdfLaTex as "PdfLaTex" <<<<pdf>>>>
state Doxygen as "Doxygen" <<doc>>
[*] --> fw
fw --> c_comp
fw --> CMake
CMake --> gmake
fw --> pycrypto
fw --> pyasn1
fw --> yaml
fw --> jinja2
pycrypto --> Python3
pyasn1 --> Python3
yaml --> Python3
jinja2 --> Python3
[*] --> u_guide
u_guide --> Sphinx
Sphinx --> m2r
Sphinx --> rtd_theme
Sphinx --> sphnix_puml
m2r --> Python3
rtd_theme --> Python3
sphnix_puml --> Python3
Sphinx --> PlantUML
PlantUML --> JRE
PlantUML --> gwiz
Sphinx --> LaTex
LaTex --> PdfLaTex
[*] --> refman
refman --> Doxygen
Doxygen --> PlantUML
Doxygen --> LaTex
state Legend {
state x as "For PDF generation only" <<pdf>>
state y as "For document generation only" <<doc>>
state z as "Mandatory"
}
@enduml
****************************
Supported build environments
****************************
TF-M officially supports a limited set of build environments and setups. In
this context, official support means that the environments listed below
are actively used by team members and active developers hence users should
be able to recreate the same configurations by following the instructions
described below. In case of problems, the TF-M team provides support
only for these environments, but building in other environments can still be
possible.
The following environments are supported:
- Windows 10 x64 + Cygwin x64 (example configuration is provided for
this Windows setup only).
- Windows 10 x64 + msys2 x64.
- Windows 10 x65 + git-bash (MinGW) + gnumake from DS-5 or msys2.
- Ubuntu 16.04 x64
- Ubuntu 18.04 x64
*********************
Supported C compilers
*********************
To compile TF-M code, at least one of the supported compiler toolchains have to
be available in the build environment. The currently supported compiler
versions are:
- Arm Compiler v6.7.1
- Arm Compiler v6.9
- Arm Compiler v6.10
- Arm Compiler v6.11
- GNU Arm compiler v6.3.1
- GNU Arm compiler v7.3
.. Note::
- The Arm compilers above are provided via Keil uVision v5.24.1 or
greater, DS-5 v5.27.1 or greater, and Development Studio 2018.0, or they can
be downloaded as standalone packages from
`here <https://developer.arm.com/products/software-development-tools/compilers/arm-compiler/downloads/version-6>`__.
- Arm compiler specific environment variable may need updating based
on specific products and licenses as explained in
`product-and-toolkit-configuration <https://developer.arm.com/products/software-development-tools/license-management/resources/product-and-toolkit-configuration>`__.
- The GNU Arm compiler can be downloaded from
`here <https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads>`__.
On the page select *GNU Arm Embedded Toolchain: 6-2017-q1-update*
or *GNU Arm Embedded Toolchain: 7-2018-q2-update*
************************
Supported CMake versions
************************
The build-system is CMake based and supports the following versions:
- 3.7
- 3.10
- 3.11
- 3.12
- 3.13
- 3.14
.. Note::
- Please use the latest build version available (i.e. 3.7.2 instead of
3.7.0).
While it is preferable to use the newest version this is not required
and any version from the above list should work.
- Recent versions of CMake can be downloaded from
https://cmake.org/download/, and older releases are available from
https://cmake.org/files.
***************************
Supported GNU make versions
***************************
The TF-M team builds using the "Unix Makefiles" generator of CMake and
thus GNU make is needed for the build. On Linux please use the version
available from the official repository of your distribution.
On Windows the following binaries are supported:
- GNU make v4.2.1 executable from Cygwin
- GNU make v4.2.1 executable from msys2
- GNU make v4.2 executable from DS5 v5.29.1 (see <DS5 install root>/bin)
CMake is quiet tolerant to GNU make versions and basically any
"reasonably recent" GNU make version shall work.
CMake generators other than "Unix Makefiles" may work, but are not
officially supported.
**************
Example setups
**************
This section lists dependencies and some exact and tested steps to set-up a
TF-M-m build environment under various OSes.
Ubuntu
======
- DS-5 v5.27.1.
- Git tools v2.10.0
- CMake (see the "Supported CMake versions" chapter)
- GNU Make (see the "Supported make versions" chapter)
- Python3, with the following libraries:
- pycrypto
- pyasn1
- yaml
- jinja2 v2.10
- sudo apt-get install python3-crypto python3-pyasn1 python3-yaml
python3-jinja2
- SRecord v1.58 (for Musca test chip boards)
Setup a shell to enable compiler toolchain and CMake after installation.
------------------------------------------------------------------------
To import Arm Compiler v6.7.1 in your bash shell console:
.. Warning::
Arm compiler specific environment variable may need updating based on
specific products and licenses as explained in
`product-and-toolkit-configuration <https://developer.arm.com/products/software-development-tools/license-management/resources/product-and-toolkit-configuration>`__.
.. code-block:: bash
export PATH=<DS-5_PATH>/sw/ARMCompiler6.7.1/bin:$PATH
export ARM_TOOL_VARIANT="ult"
export ARM_PRODUCT_PATH="<DS-5_PATH>/sw/mappings"
export ARMLMD_LICENSE_FILE="<LICENSE_FILE_PATH>"
To import CMake in your bash shell console:
.. code-block:: bash
export PATH=/bin:$PATH
To import GNU Arm in your bash shell console:
.. code-block:: bash
export PATH=/bin:$PATH
Windows + Cygwin
================
- uVision v5.24.1 or DS-5 v5.27.1 (DS-5 Ultimate Edition) which
provides the
Arm Compiler v6.7.1 compiler or GNU Arm compiler v6.3.1.
- Git client latest version (https://git-scm.com/download/win)
- CMake (see the "Supported CMake versions" chapter)
- `Cygwin <https://www.cygwin.com/>`__. Tests done with version 2.877
(64 bits)
- GNU make should be installed by selecting appropriate package during
cygwin
installation.
- Python3 `(native Windows
version) <https://www.python.org/downloads/>`__, with the following
libraries:
- pycryptodome (pip3 install --user pycryptodome)
- pyasn1 (pip3 install --user pyasn1)
- pyyaml (pip3 install --user pyyaml)
- jinja2 (pip3 install --user jinja2)
- Python3 pip
- `SRecord v1.63 <https://sourceforge.net/projects/srecord/>`__ (for
Musca-A1 test chip board)
Setup Cygwin to enable a compiler toolchain and CMake after installation.
-------------------------------------------------------------------------
If applicable, import Arm Compiler v6.7.1 in your shell console. To make this
change permanent, add the command line into ~/.bashrc
Armclang + DS-5
^^^^^^^^^^^^^^^
.. Note::
- Arm compiler specific environment variable may need updating based on
specific products and licenses as explained in
`product-and-toolkit-configuration <https://developer.arm.com/products/software-development-tools/license-management/resources/product-and-toolkit-configuration>`__.
- Arm licensing related environment variables must use Windows paths, and not
the Cygwin specific one relative to */cygrive*.
.. code-block:: bash
export PATH="/cygdrive/c/<DS-5_PATH>/sw/ARMCompiler6.7.1/bin":$PATH
export ARM_PRODUCT_PATH="C:/<DS-5_PATH>/sw/mappings"
export ARM_TOOL_VARIANT="ult"
export ARMLMD_LICENSE_FILE="<LICENSE_FILE_PATH>"
Armclang + Keil MDK Arm
^^^^^^^^^^^^^^^^^^^^^^^
.. Note::
- Arm compiler specific environment variable may need updating based
on specific products and licenses as explained in
`product-and-toolkit-configuration <https://developer.arm.com/products/software-development-tools/license-management/resources/product-and-toolkit-configuration>`__.
.. code-block:: bash
export PATH="/cygdrive/c/<uVision path>/ARM/ARMCLANG/bin":$PATH
GNU Arm
^^^^^^^
If applicable, import GNU Arm compiler v6.3.1 in your shell console. To make
this change permanent, add the command line into ~/.bashrc
.. code-block:: bash
export PATH=<GNU Arm path>/bin:$PATH
CMake
^^^^^
To import CMake in your bash shell console:
.. code-block:: bash
export PATH=/cygdrive/c/<CMake path>/bin:$PATH
Building the documentation
==========================
The build system is prepared to support generation of two documents.
The Reference Manual which is Doxygen based, and the User Guide which is
Sphinx based. Both document can be generated in HTML and PDF format.
.. Note::
Support for document generation in the build environment is not mandatory.
Missing document generation tools will not block building the TF-M
firmware.
To compile the TF-M Reference Manual
------------------------------------
The following additional tools are needed:
- Doxygen v1.8.0 or later
- Graphviz dot v2.38.0 or later
- PlantUML v1.2018.11 or later
- Java runtime environment 1.8 or later (for running PlantUML)
For PDF generation the following tools are needed in addition to the
above list:
- LaTeX
- PdfLaTeX
Set-up the needed tools
^^^^^^^^^^^^^^^^^^^^^^^
Linux
"""""
.. code-block:: bash
sudo apt-get install -y doxygen graphviz default-jre
mkdir ~/plantuml
curl -L http://sourceforge.net/projects/plantuml/files/plantuml.jar/download --output ~/plantuml/plantuml.jar
For PDF generation:
.. code-block:: bash
sudo apt-get install -y doxygen-latex
Windows + Cygwin
""""""""""""""""
Download and install the following tools:
- `Doxygen
1.8.8 <https://sourceforge.net/projects/doxygen/files/snapshots/doxygen-1.8-svn/windows/doxygenw20140924_1_8_8.zip/download>`__
- `Graphviz
2.38 <https://graphviz.gitlab.io/_pages/Download/windows/graphviz-2.38.msi>`__
- The Java runtime is part of the DS5 installation or can be
`downloaded from here <https://www.java.com/en/download/>`__
- `PlantUML <http://sourceforge.net/projects/plantuml/files/plantuml.jar/download>`__
For PDF generation:
- `MikTeX <https://miktex.org/download>`__
.. Note::
When building the documentation the first time, MikTeX might prompt for
installing missing LaTeX components. Please allow the MikTeX package
manager to set-up these.
Configure the shell
^^^^^^^^^^^^^^^^^^^
Linux
"""""
::
export PLANTUML_JAR_PATH="~/plantuml/plantuml.jar"
Windows + Cygwin
""""""""""""""""
Assumptions for the settings below:
- plantuml.jar is available at c:\\plantuml\\plantuml.jar
- doxygen, dot, and MikTeX binaries are available on the PATH.
- Java JVM is used from DS5 installation.
::
export PLANTUML_JAR_PATH="c:/plantuml/plantuml.jar"
export PATH=$PATH:/cygdrive/c/<DS-5 path>/sw/java/bin
To compile the TF-M User Guide
------------------------------
The following additional tools are needed:
- Python3 and the following modules:
- Sphinx v1.7.9
- m2r v0.2.0
- sphinxcontrib-plantuml
- sphinx-rtd-theme
- Graphviz dot v2.38.0 or later
- PlantUML v1.2018.11 or later
- Java runtime environment 1.8 or later (for running PlantUML)
For PDF generation the following tools are needed in addition to the
above list:
- LaTeX
- PdfLaTeX
Set-up the needed tools
^^^^^^^^^^^^^^^^^^^^^^^
Linux
"""""
.. code-block:: bash
sudo apt-get install -y python3 graphviz default-jre
pip --user install m2r Sphinx sphinx-rtd-theme sphinxcontrib-plantuml
mkdir ~/plantuml
curl -L http://sourceforge.net/projects/plantuml/files/plantuml.jar/download --output ~/plantuml/plantuml.jar
For PDF generation:
.. code-block:: bash
sudo apt-get install -y doxygen-latex
Windows + Cygwin
""""""""""""""""
Download and install the following tools:
- Python3 `(native Windows version) <https://www.python.org/downloads/>`__
- Pip packages *m2r, Sphinx, sphinx-rtd-theme sphinxcontrib-plantuml*
.. code-block:: bash
pip --user install m2r Sphinx sphinx-rtd-theme sphinxcontrib-plantuml
- `Graphviz 2.38 <https://graphviz.gitlab.io/_pages/Download/windows/graphviz-2.38.msi>`__
- The Java runtime is part of the DS5 installation or can be
`downloaded from here <https://www.java.com/en/download/>`__
- `PlantUML <http://sourceforge.net/projects/plantuml/files/plantuml.jar/download>`__
For PDF generation:
- `MikTeX <https://miktex.org/download>`__
.. Note::
When building the documentation the first time, MikTeX might
prompt for installing missing LaTeX components. Please allow the MikTeX
package manager to set-up these.
Configure the shell
^^^^^^^^^^^^^^^^^^^
Linux
"""""
.. code-block:: bash
export PLANTUML_JAR_PATH="~/plantuml/plantuml.jar"
Windows + Cygwin
""""""""""""""""
Assumptions for the settings below:
- plantuml.jar is available at c:\\plantuml\\plantuml.jar
- doxygen, dot, and MikTeX binaries are available on the PATH.
- Java JVM is used from DS5 installation.
.. code-block:: bash
export PLANTUML_JAR_PATH="c:/plantuml/plantuml.jar"
export PATH=$PATH:/cygdrive/c/<DS-5 path>/sw/java/bin
--------------
*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*

289
docs/user_guides/tfm_user_guide.md
View File

@ -1,289 +0,0 @@
# Trusted Firmware M user guide
How to compile and run TF-M and example test application for CoreLink SSE-200
subsystem on the MPS2 board and on the Fast Model(FVP).
Follow [build instruction](./tfm_build_instruction.md) to build the binaries.
Follow [secure boot](./tfm_secure_boot.md) to build the binaries with or without
BL2 bootloader.
## Execute TF-M example and regression tests on MPS2 boards and FVP ##
The BL2 bootloader and TF-M example application and tests run correctly on
SMM-SSE-200 for MPS2 (AN521) and on the Fixed Virtual Platform model
FVP_MPS2_AEMv8M version 11.2.23.
### To run the example code on FVP_MPS2_AEMv8M
Using FVP_MPS2_AEMv8M provided by DS-5 v5.27.1.
*FVP reference guide can be found
[here](https://developer.arm.com/docs/100966/latest)*
#### Example application and regression tests without BL2 bootloader
Add `tfm_s.axf` and `tfm_ns.axf` to symbol files in Debug Configuration menu.
```
<DS5_PATH>/sw/models/bin/FVP_MPS2_AEMv8M \
--parameter fvp_mps2.platform_type=2 \
--parameter cpu0.baseline=0 \
--parameter cpu0.INITVTOR_S=0x10000000 \
--parameter cpu0.semihosting-enable=0 \
--parameter fvp_mps2.DISABLE_GATING=0 \
--parameter fvp_mps2.telnetterminal0.start_telnet=1 \
--parameter fvp_mps2.telnetterminal1.start_telnet=0 \
--parameter fvp_mps2.telnetterminal2.start_telnet=0 \
--parameter fvp_mps2.telnetterminal0.quiet=0 \
--parameter fvp_mps2.telnetterminal1.quiet=1 \
--parameter fvp_mps2.telnetterminal2.quiet=1 \
--application cpu0=<build_dir>/install/outputs/fvp/tfm_s.axf \
--data cpu0=<build_dir>/install/outputs/fvp/tfm_ns.bin@0x00100000
```
#### Example application and regression tests with BL2 bootloader
To test TF-M with bootloader, one must apply the following changes:
* Add `mcuboot.axf` to symbol files in DS-5 in Debug Configuration menu.
* Replace the last two lines of the previous command with this:
```
--application cpu0=<build_dir>/install/outputs/fvp/mcuboot.axf \
--data cpu0=<build_dir>/install/outputs/fvp/tfm_s_ns_signed.bin@0x10080000
```
#### Test software upgrade with BL2 bootloader
BL2 bootloader is mandatory to test software update. Furthermore two TF-M blob
must be built. Outputs of example application and regression test can be used to
test it. Load output of example application to slot 0 (0x10080000) and output of
regression test to slot 1 (0x10180000). Add the following line to the
end of the previous chapter:
```
--data cpu0=<build_dir>/install/outputs/fvp/tfm_s_ns_signed.bin@0x10180000
```
### To run the example code on SSE 200 FPGA on MPS2 board
FPGA image is available to download [here](https://developer.arm.com/products/system-design/development-boards/cortex-m-prototyping-systems/mps2)
To run BL2 bootloader and TF-M example application and tests in the MPS2 board,
it is required to have SMM-SSE-200 for MPS2 (AN521) image in the MPS2 board
SD card. The image should be located in
`<MPS2 device name>/MB/HBI0263<board revision letter>/AN521`
The MPS2 board tested is HBI0263C referred also as MPS2+.
`Note: If you change the exe names, MPS2 expects file names in 8.3 format.`
#### Example application
1. Copy `mcuboot.bin` and `tfm_sign.bin` files from
`<build_dir>/install/outputs/AN521/` to `<MPS2 device name>/SOFTWARE/`
2. Open `<MPS2 device name>/MB/HBI0263C/AN521/images.txt`
3. Update the `AN521/images.txt` file as follows:
```
TITLE: Versatile Express Images Configuration File
[IMAGES]
TOTALIMAGES: 2 ;Number of Images (Max: 32)
IMAGE0ADDRESS: 0x10000000
IMAGE0FILE: \Software\mcuboot.bin ; BL2 bootloader
IMAGE1ADDRESS: 0x10080000
IMAGE1FILE: \Software\tfm_sign.bin ; TF-M example application binary blob
```
4. Close `<MPS2 device name>/MB/HBI0263C/AN521/images.txt`
5. Unmount/eject the `<MPS2 device name>` unit
6. Reset the board to execute the TF-M example application
7. After completing the procedure you should be able to visualize on the serial
port (baud 115200 8n1) the following messages:
```
[INF] Starting bootloader
[INF] Image 0: magic=good, copy_done=0xff, image_ok=0xff
[INF] Scratch: magic=bad, copy_done=0x5, image_ok=0xcf
[INF] Boot source: slot 0
[INF] Swap type: none
[INF] Bootloader chainload address offset: 0x80000
[INF] Jumping to the first image slot
[Sec Thread] Secure image initializing!
```
#### Regression tests
After completing the procedure you should be able to visualize on the serial
port (baud 115200 8n1) the following messages:
```
[INF] Starting bootloader
[INF] Image 0: magic=good, copy_done=0xff, image_ok=0xff
[INF] Scratch: magic=bad, copy_done=0x5, image_ok=0xcf
[INF] Boot source: slot 0
[INF] Swap type: none
[INF] Bootloader chainload address offset: 0x80000
[INF] Jumping to the first image slot
[Sec Thread] Secure image initializing!
#### Execute test suites for the secure storage service ####
Running Test Suite SST secure interface tests (TFM_SST_TEST_2XXX)...
> Executing 'TFM_SST_TEST_2001'
Description: 'Create interface'
TEST PASSED!
> Executing 'TFM_SST_TEST_2002'
Description: 'Get handle interface (DEPRECATED)'
This test is DEPRECATED and the test execution was SKIPPED
TEST PASSED!
> Executing 'TFM_SST_TEST_2003'
Description: 'Get handle with null handle pointer (DEPRECATED)'
This test is DEPRECATED and the test execution was SKIPPED
TEST PASSED!
> Executing 'TFM_SST_TEST_2004'
Description: 'Write interface'
TEST PASSED!
> Executing 'TFM_SST_TEST_2005'
Description: 'Read interface'
....
```
Note: SST reliability tests take a few minutes to run on the MPS2.
#### Example application without BL2 bootloader
1. Copy `tfm_s.bin` and `tfm_ns.bin` files from
`<build_dir>/install/outputs/AN521/` to `<MPS2 device name>/SOFTWARE/`
2. Open `<MPS2 device name>/MB/HBI0263C/AN521/images.txt`
3. Update the `AN521/images.txt` file as follows:
```
TITLE: Versatile Express Images Configuration File
[IMAGES]
TOTALIMAGES: 2 ;Number of Images (Max: 32)
IMAGE0ADDRESS: 0x10000000
IMAGE0FILE: \Software\tfm_s.bin ; Secure code
IMAGE1ADDRESS: 0x00100000
IMAGE1FILE: \Software\tfm_ns.bin ; Non-secure code
```
4. Close `<MPS2 device name>/MB/HBI0263C/AN521/images.txt`
5. Unmount/eject the `<MPS2 device name>` unit
6. Reset the board to execute the TF-M example application
7. After completing the procedure you should be able to visualize on the serial
port (baud 115200 8n1) the following messages:
```
[Sec Thread] Secure image initializing!
```
#### Regression tests without BL2 bootloader
After completing the procedure you should be able to visualize on the serial
port (baud 115200 8n1) the following messages:
```
[Sec Thread] Secure image initializing!
#### Execute test suites for the secure storage service ####
Running Test Suite SST secure interface tests (TFM_SST_TEST_2XXX)...
> Executing 'TFM_SST_TEST_2001'
Description: 'Create interface'
TEST PASSED!
> Executing 'TFM_SST_TEST_2002'
Description: 'Get handle interface (DEPRECATED)'
This test is DEPRECATED and the test execution was SKIPPED
TEST PASSED!
> Executing 'TFM_SST_TEST_2003'
Description: 'Get handle with null handle pointer (DEPRECATED)'
This test is DEPRECATED and the test execution was SKIPPED
TEST PASSED!
> Executing 'TFM_SST_TEST_2004'
Description: 'Write interface'
TEST PASSED!
> Executing 'TFM_SST_TEST_2005'
Description: 'Read interface'
....
```
## Execute TF-M example and regression tests on Musca test chip boards ##
Note: Before executing any images on Musca-B1 board, please check the readme
under platform/ext/target/musca_b1 to have the correct setup.
#### Example application with BL2 bootloader
1. Create a unified hex file comprising of both `mcuboot.bin` and `tfm_sign.bin`
* For Musca-A
* Windows
`srec_cat.exe bl2\ext\mcuboot\mcuboot.bin -Binary -offset 0x200000 tfm_sign.bin -Binary -offset 0x220000 -o tfm.hex -Intel`
* Linux
`srec_cat bl2/ext/mcuboot/mcuboot.bin -Binary -offset 0x200000 tfm_sign.bin -Binary -offset 0x220000 -o tfm.hex -Intel`
* For Musca-B1
* Windows
`srec_cat.exe bl2\ext\mcuboot\mcuboot.bin -Binary -offset 0xA000000 tfm_sign.bin -Binary -offset 0xA020000 -o tfm.hex -Intel`
* Linux
`srec_cat bl2/ext/mcuboot/mcuboot.bin -Binary -offset 0xA000000 tfm_sign.bin -Binary -offset 0xA020000 -o tfm.hex -Intel`
2. Power up the Musca board by connecting it to a computer with a USB lead.
Press the `PBON` button if the green `ON` LED does not immediately come on.
The board should appear as a USB drive.
3. Copy `tfm.hex` to the USB drive. The orange `PWR` LED should start blinking.
4. Once the `PWR` LED stops blinking, power cycle or reset the board to boot
from the new image.
5. After completing the procedure you should see the following messages on the
DAPLink UART (baud 115200 8n1):
```
[INF] Starting bootloader
[INF] Image 0: magic=good, copy_done=0xff, image_ok=0xff
[INF] Scratch: magic=bad, copy_done=0x5, image_ok=0xd9
[INF] Boot source: slot 0
[INF] Swap type: none
[INF] Bootloader chainload address offset: 0x20000
[INF] Jumping to the first image slot
[Sec Thread] Secure image initializing!
```
#### Regression tests with BL2 bootloader
After completing the procedure you should see the following messages on the
DAPLink UART (baud 115200 8n1):
```
[INF] Starting bootloader
[INF] Image 0: magic=good, copy_done=0xff, image_ok=0xff
[INF] Scratch: magic=bad, copy_done=0x5, image_ok=0x9
[INF] Boot source: slot 0
[INF] Swap type: none
[INF] Bootloader chainload address offset: 0x20000
[INF] Jumping to the first image slot
[Sec Thread] Secure image initializing!
#### Execute test suites for the secure storage service ####
Running Test Suite SST secure interface tests (TFM_SST_TEST_2XXX)...
> Executing 'TFM_SST_TEST_2001'
Description: 'Create interface'
TEST PASSED!
> Executing 'TFM_SST_TEST_2002'
Description: 'Get handle interface (DEPRECATED)'
This test is DEPRECATED and the test execution was SKIPPED
TEST PASSED!
> Executing 'TFM_SST_TEST_2003'
Description: 'Get handle with null handle pointer (DEPRECATED)'
This test is DEPRECATED and the test execution was SKIPPED
TEST PASSED!
> Executing 'TFM_SST_TEST_2004'
Description: 'Get attributes interface'
TEST PASSED!
> Executing 'TFM_SST_TEST_2005'
Description: 'Get attributes with null attributes struct pointer'
....
```
#### Example application or regression tests on Musca-B1 without BL2 bootloader
Follow the above procedures, but create a unified hex file out of `tfm_s.bin`
and `tfm_ns.bin`:
* Windows
`srec_cat.exe app\secure_fw\tfm_s.bin -Binary -offset 0xA000000 app\tfm_ns.bin -Binary -offset 0xA060000 -o tfm.hex -Intel`
* Linux
`srec_cat app/secure_fw/tfm_s.bin -Binary -offset 0xA000000 app/tfm_ns.bin -Binary -offset 0xA060000 -o tfm.hex -Intel`
## Firmware upgrade and image validation with BL2 bootloader
High level operation of BL2 bootloader and instructions for testing firmware
upgrade is described in [secure boot](tfm_secure_boot.md) document.
--------------
*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*

317
docs/user_guides/tfm_user_guide.rst Normal file
View File

@ -0,0 +1,317 @@
#############################
Trusted Firmware M user guide
#############################
How to compile and run TF-M and example test application for CoreLink
SSE-200 subsystem on the MPS2 board and on the Fast Model(FVP).
Follow :doc:`build instruction <tfm_build_instruction>` to build the binaries.
Follow :doc:`secure boot <tfm_secure_boot>` to build the binaries with or
without BL2 bootloader.
****************************************************************
Execute TF-M example and regression tests on MPS2 boards and FVP
****************************************************************
The BL2 bootloader and TF-M example application and tests run correctly on
SMM-SSE-200 for MPS2 (AN521) and on the Fixed Virtual Platform model
FVP_MPS2_AEMv8M version 11.2.23.
To run the example code on FVP_MPS2_AEMv8M
==========================================
Using FVP_MPS2_AEMv8M provided by DS-5 v5.27.1.
.. Note::
FVP reference guide can be found
`here <https://developer.arm.com/docs/100966/latest>`__
Example application and regression tests without BL2 bootloader
---------------------------------------------------------------
Add ``tfm_s.axf`` and ``tfm_ns.axf`` to symbol files in Debug Configuration
menu.
.. code-block:: bash
<DS5_PATH>/sw/models/bin/FVP_MPS2_AEMv8M \
--parameter fvp_mps2.platform_type=2 \
--parameter cpu0.baseline=0 \
--parameter cpu0.INITVTOR_S=0x10000000 \
--parameter cpu0.semihosting-enable=0 \
--parameter fvp_mps2.DISABLE_GATING=0 \
--parameter fvp_mps2.telnetterminal0.start_telnet=1 \
--parameter fvp_mps2.telnetterminal1.start_telnet=0 \
--parameter fvp_mps2.telnetterminal2.start_telnet=0 \
--parameter fvp_mps2.telnetterminal0.quiet=0 \
--parameter fvp_mps2.telnetterminal1.quiet=1 \
--parameter fvp_mps2.telnetterminal2.quiet=1 \
--application cpu0=<build_dir>/install/outputs/fvp/tfm_s.axf \
--data cpu0=<build_dir>/install/outputs/fvp/tfm_ns.bin@0x00100000
Example application and regression tests with BL2 bootloader
------------------------------------------------------------
To test TF-M with bootloader, one must apply the following changes:
- Add ``mcuboot.axf`` to symbol files in DS-5 in Debug Configuration
menu.
- Replace the last two lines of the previous command with this:
.. code-block:: bash
--application cpu0=<build_dir>/install/outputs/fvp/mcuboot.axf \
--data cpu0=<build_dir>/install/outputs/fvp/tfm_s_ns_signed.bin@0x10080000
Test software upgrade with BL2 bootloader
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
BL2 bootloader is mandatory to test software update. Furthermore two TF-M blob
must be built. Outputs of example application and regression test can be used to
test it. Load output of example application to slot 0 (0x10080000) and output of
regression test to slot 1 (0x10180000). Add the following line to the end of
the previous chapter:
.. code-block:: bash
--data cpu0=<build_dir>/install/outputs/fvp/tfm_s_ns_signed.bin@0x10180000
To run the example code on SSE 200 FPGA on MPS2 board
=====================================================
FPGA image is available to download
`here <https://developer.arm.com/products/system-design/development-boards/cortex-m-prototyping-systems/mps2>`__
To run BL2 bootloader and TF-M example application and tests in the MPS2 board,
it is required to have SMM-SSE-200 for MPS2 (AN521) image in the MPS2 board SD
card. The image should be located in
``<MPS2 device name>/MB/HBI0263<board revision letter>/AN521``
The MPS2 board tested is HBI0263C referred also as MPS2+.
.. Warning::
If you change the exe names, MPS2 expects file names in 8.3 format.
Example application
-------------------
#. Copy ``mcuboot.bin`` and ``tfm_sign.bin`` files from
``<build_dir>/install/outputs/AN521/`` to
``<MPS2 device name>/SOFTWARE/``
#. Open ``<MPS2 device name>/MB/HBI0263C/AN521/images.txt``
#. Update the ``AN521/images.txt`` file as follows::
TITLE: Versatile Express Images Configuration File
[IMAGES]
TOTALIMAGES: 2 ;Number of Images (Max: 32)
IMAGE0ADDRESS: 0x10000000
IMAGE0FILE: \Software\mcuboot.bin ; BL2 bootloader
IMAGE1ADDRESS: 0x10080000
IMAGE1FILE: \Software\tfm_sign.bin ; TF-M example application binary blob
#. Close ``<MPS2 device name>/MB/HBI0263C/AN521/images.txt``
#. Unmount/eject the ``<MPS2 device name>`` unit
#. Reset the board to execute the TF-M example application
#. After completing the procedure you should be able to visualize on the serial
port (baud 115200 8n1) the following messages::
[INF] Starting bootloader
[INF] Image 0: magic=good, copy_done=0xff, image_ok=0xff
[INF] Scratch: magic=bad, copy_done=0x5, image_ok=0xcf
[INF] Boot source: slot 0
[INF] Swap type: none
[INF] Bootloader chainload address offset: 0x80000
[INF] Jumping to the first image slot
[Sec Thread] Secure image initializing!
Regression tests
----------------
After completing the procedure you should be able to visualize on the serial
port (baud 115200 8n1) the following messages::
[INF] Starting bootloader
[INF] Image 0: magic=good, copy_done=0xff, image_ok=0xff
[INF] Scratch: magic=bad, copy_done=0x5, image_ok=0xcf
[INF] Boot source: slot 0
[INF] Swap type: none
[INF] Bootloader chainload address offset: 0x80000
[INF] Jumping to the first image slot
[Sec Thread] Secure image initializing!
#### Execute test suites for the secure storage service ####
Running Test Suite SST secure interface tests (TFM_SST_TEST_2XXX)...
> Executing 'TFM_SST_TEST_2001'
Description: 'Create interface'
TEST PASSED!
> Executing 'TFM_SST_TEST_2002'
Description: 'Get handle interface (DEPRECATED)'
This test is DEPRECATED and the test execution was SKIPPED
TEST PASSED!
> Executing 'TFM_SST_TEST_2003'
Description: 'Get handle with null handle pointer (DEPRECATED)'
This test is DEPRECATED and the test execution was SKIPPED
TEST PASSED!
> Executing 'TFM_SST_TEST_2004'
Description: 'Write interface'
TEST PASSED!
> Executing 'TFM_SST_TEST_2005'
Description: 'Read interface'
....
.. Note::
SST reliability tests take a few minutes to run on the MPS2.
Example application without BL2 bootloader
------------------------------------------
#. Copy ``tfm_s.bin`` and ``tfm_ns.bin`` files from
``<build_dir>/install/outputs/AN521/`` to
``<MPS2 device name>/SOFTWARE/``
#. Open ``<MPS2 device name>/MB/HBI0263C/AN521/images.txt``
#. Update the ``AN521/images.txt`` file as follows::
TITLE: Versatile Express Images Configuration File
[IMAGES]
TOTALIMAGES: 2 ;Number of Images (Max: 32)
IMAGE0ADDRESS: 0x10000000
IMAGE0FILE: \Software\tfm_s.bin ; Secure code
IMAGE1ADDRESS: 0x00100000
IMAGE1FILE: \Software\tfm_ns.bin ; Non-secure code
#. Close ``<MPS2 device name>/MB/HBI0263C/AN521/images.txt``
#. Unmount/eject the ``<MPS2 device name>`` unit
#. Reset the board to execute the TF-M example application
#. After completing the procedure you should be able to visualize on the serial
port (baud 115200 8n1) the following messages::
[Sec Thread] Secure image initializing!
Regression tests without BL2 bootloader
---------------------------------------
After completing the procedure you should be able to visualize on the serial
port (baud 115200 8n1) the following messages::
[Sec Thread] Secure image initializing!
#### Execute test suites for the secure storage service ####
Running Test Suite SST secure interface tests (TFM_SST_TEST_2XXX)...
> Executing 'TFM_SST_TEST_2001'
Description: 'Create interface'
TEST PASSED!
> Executing 'TFM_SST_TEST_2002'
Description: 'Get handle interface (DEPRECATED)'
This test is DEPRECATED and the test execution was SKIPPED
TEST PASSED!
> Executing 'TFM_SST_TEST_2003'
Description: 'Get handle with null handle pointer (DEPRECATED)'
This test is DEPRECATED and the test execution was SKIPPED
TEST PASSED!
> Executing 'TFM_SST_TEST_2004'
Description: 'Write interface'
TEST PASSED!
> Executing 'TFM_SST_TEST_2005'
Description: 'Read interface'
....
*******************************************************************
Execute TF-M example and regression tests on Musca test chip boards
*******************************************************************
.. Note::
Before executing any images on Musca-B1 board, please check the
:doc:`target platform readme </platform/ext/target/musca_b1/readme>`
to have the correct setup.
Example application with BL2 bootloader
=======================================
#. Create a unified hex file comprising of both mcuboot and tfm_sign
binary
- For Musca-A1
- Windows::
srec_cat.exe bl2\ext\mcuboot\mcuboot.bin -Binary -offset 0x200000 tfm_sign.bin -Binary -offset 0x220000 -o tfm.hex -Intel
- Linux::
srec_cat bl2/ext/mcuboot/mcuboot.bin -Binary -offset 0x200000 tfm_sign.bin -Binary -offset 0x220000 -o tfm.hex -Intel
- For Musca-B1
- Windows::
srec_cat.exe bl2\ext\mcuboot\mcuboot.bin -Binary -offset 0xA000000 tfm_sign.bin -Binary -offset 0xA020000 -o tfm.hex -Intel
- Linux::
srec_cat bl2/ext/mcuboot/mcuboot.bin -Binary -offset 0xA000000 tfm_sign.bin -Binary -offset 0xA020000 -o tfm.hex -Intel
#. Plug the Musca board into your computer. The board should appear as a USB
drive
#. Copy ``tfm.hex`` to the USB drive
#. Reset the board to execute the TF-M example application
#. After completing the procedure you should be able to see on the UART0
(baud 115200 8n1) the following messages::
[INF] Starting bootloader
[INF] Image 0: magic=good, copy_done=0xff, image_ok=0xff
[INF] Scratch: magic=bad, copy_done=0x5, image_ok=0xd9
[INF] Boot source: slot 0
[INF] Swap type: none
[INF] Bootloader chainload address offset: 0x20000
[INF] Jumping to the first image slot
[Sec Thread] Secure image initializing!
Regression tests with BL2 bootloader
====================================
After completing the procedure you should see the following messages on the
UART0 (baud 115200 8n1)::
[INF] Starting bootloader
[INF] Image 0: magic=good, copy_done=0xff, image_ok=0xff
[INF] Scratch: magic=bad, copy_done=0x5, image_ok=0x9
[INF] Boot source: slot 0
[INF] Swap type: none
[INF] Bootloader chainload address offset: 0x20000
[INF] Jumping to the first image slot
[Sec Thread] Secure image initializing!
#### Execute test suites for the secure storage service ####
Running Test Suite SST secure interface tests (TFM_SST_TEST_2XXX)...
> Executing 'TFM_SST_TEST_2001'
Description: 'Create interface'
TEST PASSED!
> Executing 'TFM_SST_TEST_2002'
Description: 'Get handle interface (DEPRECATED)'
This test is DEPRECATED and the test execution was SKIPPED
TEST PASSED!
> Executing 'TFM_SST_TEST_2003'
Description: 'Get handle with null handle pointer (DEPRECATED)'
This test is DEPRECATED and the test execution was SKIPPED
TEST PASSED!
> Executing 'TFM_SST_TEST_2004'
Description: 'Get attributes interface'
TEST PASSED!
> Executing 'TFM_SST_TEST_2005'
Description: 'Get attributes with null attributes struct pointer'
....
Example application or regression tests on Musca-B1 without BL2 bootloader
==========================================================================
Follow the above procedures, but create a unified hex file out of ``tfm_s.bin``
and ``tfm_ns.bin``:
- Windows::
srec_cat.exe app\secure_fw\tfm_s.bin -Binary -offset 0xA000000 app\tfm_ns.bin -Binary -offset 0xA060000 -o tfm.hex -Intel
- Linux::
srec_cat app/secure_fw/tfm_s.bin -Binary -offset 0xA000000 app/tfm_ns.bin -Binary -offset 0xA060000 -o tfm.hex -Intel
Firmware upgrade and image validation with BL2 bootloader
=========================================================
High level operation of BL2 bootloader and instructions for testing firmware
upgrade is described in :doc:`secure boot <tfm_secure_boot>`.
--------------
*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*

28
glossary.md
View File

@ -1,28 +0,0 @@
# TF-M glossary of terms and abbreviations
| Term | Abbrev. | Description |
| --- | --- | --- |
| ** TF-M related ** | | |
| Trusted Firmware for M-class | TF-M | ARM TF-M provides a reference implementation of secure world software for ARMv8-M. |
| Trusted Firmware for M-class | TFM | ARM TF-M provides a reference implementation of secure world software for ARMv8-M. |
| Secure Processing Environment | SPE | PSA term. In TF-M this means the secure domain protected by TF-M|
| Non Secure Processing Enviroment| NSPE | PSA term. In TF-M this means non secure domain typically running an OS using services provided by TF-M|
| Secure Service | SS | A component within the TEE that is atomic from a security/trust point of view, i.e. which is viewed as a single entity from a TF-M point of view |
| Secure Partition | SP | A logical container for a single secure service |
| Secure Partition Manager | SPM | The TF-M component responsible for enumeration, management and isolation of multiple Secure Partitions within the TEE |
| Secure Function | SFN | An entry function to a secure service. Multiple SFN per SS are permitted |
| Secure Storage Service | SST | Secure storage service provided by TF-M |
| ** SSE-200 platform ** | | |
| Memory Protection Controller | MPC | Bus slave-side security controller for memory regions |
| Peripheral Protection Controller | PPC | Bus slave-side security controller for peripheral access |
| ** v8M-specific ** | | |
| Secure/Non-secure | S/NS | The separation provided by TrustZone hardware components in the system |
| Secure Attribution Unit | SAU | Hardware component providing isolation between Secure, Non-secure Callable and Non-secure addresses |
| ** M-class Generic ** | | |
| ARM Architecture Procedure Call Standard | AAPCS | The AAPCS defines how subroutines can be separately written, separately compiled, and separately assembled to work together. It describes a contract between a calling routine and a called routine |
| SuperVisor Call | SVC | ARMv7M assembly instruction to call a privileged handler function |
| Memory Protection Unit | MPU | Hardware component providing privilege control |
--------------
*Copyright (c) 2017, Arm Limited. All rights reserved.*

89
glossary.rst Normal file
View File

@ -0,0 +1,89 @@
########################################
TF-M glossary of terms and abbreviations
########################################
************
TF-M related
************
.. glossary::
TF-M
TFM
Trusted Firmware for M-class
ARM TF-M provides a reference implementation of secure world software for ARMv8-M.
SPE : TF-M related
Secure Processing Environment
PSA term. In TF-M this means the secure domain protected by TF-M
NSPE : TF-M related
Non Secure Processing Enviroment
PSA term. In TF-M this means non secure domain typically running an OS using services provided by TF-M
SS : TF-M related
Secure Service
A component within the TEE that is atomic from a security/trust point of view, i.e. which is viewed as a single entity from a TF-M point of view
SP : TF-M related
Secure Partition
A logical container for a single secure service
SPM : TF-M related
Secure Partition Manager
The TF-M component responsible for enumeration, management and isolation of multiple Secure Partitions within the TEE
SFN : TF-M related
Secure Function
An entry function to a secure service. Multiple SFN per SS are permitted
SST : TF-M related
Secure Storage Service
Secure storage service provided by TF-M
****************
SSE-200 platform
****************
.. glossary::
MPC : SSE-200 platform
Memory Protection Controller
Bus slave-side security controller for memory regions
PPC : SSE-200 platform
Peripheral Protection Controller
Bus slave-side security controller for peripheral access
************
v8M-specific
************
.. glossary::
SSE-200 platform
Secure/Non-secure
The separation provided by TrustZone hardware components in the system
SAU
Secure Attribution Unit
Hardware component providing isolation between Secure, Non-secure Callable and Non-secure addresses
***************
M-class Generic
***************
.. glossary::
APCS
ARM Architecture Procedure Call Standard
The AAPCS defines how subroutines can be separately written, separately compiled, and separately assembled to work together. It describes a contract between a calling routine and a called routine
SVC
SuperVisor Call
ARMv7M assembly instruction to call a privileged handler function
MPU
Memory Protection Unit
Hardware component providing privilege control
--------------
*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*

22
license.md → license.rst
View File

@ -1,16 +1,16 @@
Copyright (c) 2017, Arm Limited. All rights reserved.
Copyright (c) 2017-2019, Arm Limited. All rights reserved.
Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this
list of conditions and the following disclaimer in the documentation and/or
other materials provided with the distribution.
- Neither the name of ARM nor the names of its contributors may be used to
endorse or promote products derived from this software without specific prior
written permission.
- Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this
list of conditions and the following disclaimer in the documentation and/or
other materials provided with the distribution.
- Neither the name of ARM nor the names of its contributors may be used to
endorse or promote products derived from this software without specific prior
written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
@ -25,8 +25,8 @@ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
---
*Note*:
Individual files contain the following tag instead of the full license text.
.. note::
Individual files contain the following tag instead of the full license text.

53
maintainers.md
View File

@ -1,53 +0,0 @@
# Trusted Firmware M - Maintainers
Trusted Firmware M is a community maintained project. Contributions can only
be approved and merged by the maintainers listed below.
Sub-maintainers' approval is required for their specific areas of ownership.
Contributions must follow the instructions in
[Contributing Guidelines](contributing.md).
## Maintainers
Abhishek Pandit ([abhishek.pandit@arm.com](abhishek.pandit@arm.com)
, [abhishek-pandit](https://github.com/abhishek-pandit))
Ashutosh Singh ([ashutosh.singh@arm.com](ashutosh.singh@arm.com)
, [ashutoshksingh](https://github.com/ashutoshksingh))
Miklos Balint ([miklos.balint@arm.com](miklos.balint@arm.com)
, [wmnt](https://github.com/wmnt))
## Sub-maintainers
### Bootloader
Tamas Ban ([Tamas.Ban@arm.com](Tamas.Ban@arm.com)
, [tamban01](https://github.com/tamban01))
### Secure Storage
Marc Moreno Berengue ([marc.morenoberengue@arm.com](marc.morenoberengue@arm.com)
, [mmorenobarm](https://github.com/mmorenobarm))
### Crypto
Antonio de Angelis ([Antonio.DeAngelis@arm.com](Antonio.DeAngelis@arm.com)
, [adeaarm](https://github.com/adeaarm))
### SPM & IPC
Ken Liu ([Ken.Liu@arm.com](Ken.Liu@arm.com)
, [KenLSoft](https://github.com/KenLSoft))
Mate Toth-Pal ([Mate.Toth-Pal@arm.com](Mate.Toth-Pal@arm.com)
, [matetothpal](https://github.com/matetothpal))
### Audit Log
Antonio de Angelis ([Antonio.DeAngelis@arm.com](Antonio.DeAngelis@arm.com)
, [adeaarm](https://github.com/adeaarm))
### Attestation
Tamas Ban ([Tamas.Ban@arm.com](Tamas.Ban@arm.com)
, [tamban01](https://github.com/tamban01))
--------------
*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*

77
maintainers.rst Normal file
View File

@ -0,0 +1,77 @@
Trusted Firmware M - Maintainers
================================
Trusted Firmware M is a community maintained project. Contributions can only
be approved and merged by the maintainers listed below.
Sub-maintainers' approval is required for their specific areas of ownership.
Contributions must follow the instructions in
:doc:`Contributing Guidelines </contributing>`.
Maintainers
-----------
Abhishek Pandit
:email: `abhishek.pandit@arm.com <abhishek.pandit@arm.com>`__
:github: `abhishek-pandit <https://github.com/abhishek-pandit>`__
Ashutosh Singh
:email: `ashutosh.singh@arm.com <ashutosh.singh@arm.com>`__
:github: `ashutoshksingh <https://github.com/ashutoshksingh>`__
Miklos Balint
:email: `miklos.balint@arm.com <miklos.balint@arm.com>`__
:github: `wmnt <https://github.com/wmnt>`__
Sub-maintainers
---------------
Bootloader
~~~~~~~~~~
Tamas Ban
:email: `Tamas.Ban@arm.com <Tamas.Ban@arm.com>`__
:github: `tamban01 <https://github.com/tamban01>`__
Secure Storage
~~~~~~~~~~~~~~
Marc Moreno Berengue
:email: `marc.morenoberengue@arm.com <marc.morenoberengue@arm.com>`__
:github: `mmorenobarm <https://github.com/mmorenobarm>`__
Crypto
~~~~~~
Antonio de Angelis
:email: `Antonio.DeAngelis@arm.com <Antonio.DeAngelis@arm.com>`__
:github: `adeaarm <https://github.com/adeaarm>`__
SPM & IPC
~~~~~~~~~
Ken Liu
:email: `Ken.Liu@arm.com <Ken.Liu@arm.com>`__
:github: `KenLSoft <https://github.com/KenLSoft>`__)
Mate Toth-Pal
:email: `Mate.Toth-Pal@arm.com <Mate.Toth-Pal@arm.com>`__
:github: `matetothpal <https://github.com/matetothpal>`__)
Audit Log
~~~~~~~~~
Antonio de Angelis
:email: `Antonio.DeAngelis@arm.com <Antonio.DeAngelis@arm.com>`__
:github: `adeaarm <https://github.com/adeaarm>`__
Attestation
~~~~~~~~~~~
Tamas Ban
:email: `Tamas.Ban@arm.com <Tamas.Ban@arm.com>`__
:github: `tamban01 <https://github.com/tamban01>`__
--------------
*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*

135
platform/ext/readme.md
View File

@ -1,135 +0,0 @@
# Details for the platform/ext folder
This folder has code that has been imported from other projects. This means the
files in this folder and subfolders have Apache 2.0 license which
is different to BSD 3.0 license applied to the parent TF-M project.
`NOTE` This folder is strictly Apache 2.0 with the exception of cmake files.
Maintainers should be consulted if this needs to be revisited.
## Sub-folders
### cmsis
This folder contains core and compiler specific header files imported from the
CMSIS_5 project.
### common
This folder contains stdout redirection to UART, a temporary memory mapped
flash implementation for the bootloader and tfm_mbedtls_config.h for all
the targets.
### drivers
This folder contains the headers with CMSIS compliant driver definitions that
that TF-M project expects a target to provide.
#### target_cfg.h
This file is expected to define the following macros respectively.
- `TFM_DRIVER_STDIO`
This macro should expand to a structure of type `ARM_DRIVER_USART`.
TFM redirects its standard input and output to this instance of USART.
- `NS_DRIVER_STDIO`
This macro should expand to a structure of type `ARM_DRIVER_USART`.
Non-Secure application redirects its standard input and output to this
instance of USART.
### target
This folder contains the files for individual target.
#### Flash layout header file
Target must provide a header file, called flash_layout.h, which defines the
information explained in the follow subsections. The defines must be named
as they are in the subsections.
##### BL2 bootloader
The BL2 bootloader requires the following definitions:
- `FLASH_BASE_ADDRESS`
Defines the first valid address in the flash.
- `FLASH_AREA_BL2_OFFSET`
Defines the offset from the flash base address
where the BL2 - MCUBOOT area starts.
- `FLASH_AREA_BL2_SIZE`
Defines the size of the BL2 area.
- `FLASH_AREA_IMAGE_0_OFFSET`
Defines the offset from the flash base address
where the image 0 area starts, which hosts the
active firmware image.
- `FLASH_AREA_IMAGE_0_SIZE`
Defines the size of the image 0 area.
- `FLASH_AREA_IMAGE_1_OFFSET`
Defines the offset from the flash base address
where the image 1 area starts, which is a placeholder
for new firmware images.
- `FLASH_AREA_IMAGE_1_SIZE`
Defines the size of the image 1 area.
- `FLASH_AREA_IMAGE_SCRATCH_OFFSET`
Defines the offset from the flash base address
where the scratch area starts, which is used during
image swapping.
- `FLASH_AREA_IMAGE_SCRATCH_SIZE`
Defines the size of the scratch area. The minimal size
must be as the biggest sector size in the flash.
- `FLASH_DEV_NAME`
Specifies the flash device used by BL2.
##### Assemble tool
The assemble.py tools is used to concatenate secure and non-secure
binary to a single binary blob. It requires the following definitions:
- `SECURE_IMAGE_OFFSET`
Defines the offset from the single binary blob base address,
where the secure image starts.
- `SECURE_IMAGE_MAX_SIZE`
Defines the maximum size of the secure image area.
- `NON_SECURE_IMAGE_OFFSET`
Defines the offset from the single binary blob base address,
where the non-secure image starts.
- `NON_SECURE_IMAGE_MAX_SIZE`
Defines the maximum size of the non-secure image area.
##### Secure Storage (SST) Service definitions
The SST service requires the following definitions:
- `SST_FLASH_AREA_ADDR`
Defines the flash area address where the secure
store area starts.
- `SST_SECTOR_SIZE`
Defines the size of the flash sectors.
- `SST_NBR_OF_SECTORS`
Defines the number of sectors available for
the secure area.
- `SST_FLASH_DEV_NAME`
Specifies the flash device used by SST to store the data.
- `SST_FLASH_PROGRAM_UNIT`
Defines the smallest flash programmable unit in bytes.
- `SST_MAX_ASSET_SIZE`
Defines the maximum asset size to be stored in the SST area.
- `SST_NUM_ASSETS`
Defines the maximum number of assets to be stored in the SST area.
**Note**: The sectors must be consecutive.
## Expose target support for HW components
Services may require HW components to be supported by the target
to enable some features (e.g. SST service with rollback protection, etc).
The following definitions need to be set in the <TARGET_NAME>.cmake file if the
target has the following HW components:
- `TARGET_NV_COUNTERS_ENABLE`
Specifies that the target has non-volatile (NV) counters.
--------------
*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*

121
platform/ext/readme.rst Normal file
View File

@ -0,0 +1,121 @@
###################################
Details for the platform/ext folder
###################################
This folder has code that has been imported from other projects. This means the
files in this folder and subfolders have Apache 2.0 license which is different
to BSD 3.0 license applied to the parent TF-M project.
.. Note::
This folder is strictly Apache 2.0 with the exception of cmake files.
Maintainers should be consulted if this needs to be revisited.
***********
Sub-folders
***********
cmsis
=====
This folder contains core and compiler specific header files imported from the
``CMSIS_5`` project.
common
======
This folder contains stdout redirection to UART, a temporary memory mapped flash
implementation for the bootloader and tfm\_mbedtls\_config.h for all the
targets.
drivers
=======
This folder contains the headers with CMSIS compliant driver definitions that
that TF-M project expects a target to provide.
target_cfg.h
------------
This file is expected to define the following macros respectively.
- ``TFM_DRIVER_STDIO`` - This macro should expand to a structure of type
``ARM_DRIVER_USART``. TFM redirects its standard input and output to this
instance of USART.
- ``NS_DRIVER_STDIO`` - This macro should expand to a structure of type
``ARM_DRIVER_USART``. Non-Secure application redirects its standard input and
output to this instance of USART.
target
======
This folder contains the files for individual target.
Flash layout header file
------------------------
Target must provide a header file, called ``flash_layout.h``, which defines the
information explained in the follow subsections. The defines must be named
as they are in the subsections.
BL2 bootloader
^^^^^^^^^^^^^^
The BL2 bootloader requires the following definitions:
- ``FLASH_BASE_ADDRESS`` - Defines the first valid address in the flash.
- ``FLASH_AREA_BL2_OFFSET`` - Defines the offset from the flash base address
where the BL2 - MCUBOOT area starts.
- ``FLASH_AREA_BL2_SIZE`` - Defines the size of the BL2 area.
- ``FLASH_AREA_IMAGE_0_OFFSET`` - Defines the offset from the flash base address
where the image 0 area starts, which hosts the active firmware image.
- ``FLASH_AREA_IMAGE_0_SIZE`` - Defines the size of the image 0 area.
- ``FLASH_AREA_IMAGE_1_OFFSET`` - Defines the offset from the flash base address
where the image 1 area starts, which is a placeholder for new firmware images.
- ``FLASH_AREA_IMAGE_1_SIZE`` - Defines the size of the image 1 area.
- ``FLASH_AREA_IMAGE_SCRATCH_OFFSET`` - Defines the offset from the flash base
address where the scratch area starts, which is used during image swapping.
- ``FLASH_AREA_IMAGE_SCRATCH_SIZE`` - Defines the size of the scratch area. The
minimal size must be as the biggest sector size in the flash.
- ``FLASH_DEV_NAME`` - Specifies the flash device used by BL2.
Assemble tool
^^^^^^^^^^^^^
The ``assemble.py`` tools is used to concatenate secure and non-secure binary
to a single binary blob. It requires the following definitions:
- ``SECURE_IMAGE_OFFSET`` - Defines the offset from the single binary blob base
address, where the secure image starts.
- ``SECURE_IMAGE_MAX_SIZE`` - Defines the maximum size of the secure image area.
- ``NON_SECURE_IMAGE_OFFSET`` - Defines the offset from the single binary blob
base address, where the non-secure image starts.
- ``NON_SECURE_IMAGE_MAX_SIZE`` - Defines the maximum size of the non-secure
image area.
Secure Storage (SST) Service definitions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The SST service requires the following definitions:
- ``SST_FLASH_AREA_ADDR`` - Defines the flash area address where the secure
store area starts.
- ``SST_SECTOR_SIZE`` - Defines the size of the flash sectors.
- ``SST_NBR_OF_SECTORS`` - Defines the number of sectors available for the
secure area.
- ``SST_FLASH_DEV_NAME`` - Specifies the flash device used by SST to store the
data.
- ``SST_FLASH_PROGRAM_UNIT`` - Defines the smallest flash programmable unit in
bytes.
- ``SST_MAX_ASSET_SIZE`` - Defines the maximum asset size to be stored in the
SST area.
- ``SST_NUM_ASSETS`` - Defines the maximum number of assets to be stored in the
SST area.
.. Note::
The sectors must be consecutive.
***************************************
Expose target support for HW components
***************************************
Services may require HW components to be supported by the target to enable some
features (e.g. SST service with rollback protection, etc). The following
definitions need to be set in the .cmake file if the target has the following
HW components:
- ``TARGET_NV_COUNTERS_ENABLE`` - Specifies that the target has non-volatile
(NV) counters.
--------------
*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*

7
platform/ext/target/musca_b1/readme.md
View File

@ -1,7 +0,0 @@
# DAPLink Firmware
The code on Musca-B1 is running from embededed flash.
Make sure that the DAPLink FW for eFlash is downloaded to the board.
You can find it from Arm Community page:
https://community.arm.com/developer/tools-software/oss-platforms/w/docs/425/musca-b1-firmware-update-qspi-boot-recovery
A short description of how to update the DAPLink FW can be found there as well.

15
platform/ext/target/musca_b1/readme.rst Normal file
View File

@ -0,0 +1,15 @@
###########################
Musca-B1 Platform Specifics
###########################
****************
DAPLink Firmware
****************
The code on Musca-B1 is running from embededed flash. Make sure that the DAPLink
FW for eFlash is downloaded to the board. You can find on the
`Arm Community page <https://community.arm.com/developer/tools-software/oss-platforms/w/docs/425/musca-b1-firmware-update-qspi-boot-recovery>`__
A short description of how to update the DAPLink FW can be found there as well.
--------------
*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*

48
platform/readme.md
View File

@ -1,48 +0,0 @@
# Details for the platform folder
`NOTE` This folder and subfolders, especially the target folder, are likely to
be refactored and updated to improve the overall structure of dependencies.
## Interfacing with TF-M core
### platform/ext/target/<target_platform>/tfm_peripherals_def.h
This file should enumerate the hardware peripherals that are available for TF-M
on the platform. The name of the peripheral used by a service is set in its
manifest file. The platform have to provide a macro for each of the provided
peripherals, that is substituted to a pointer to type
`struct tfm_spm_partition_platform_data_t`. The memory that the pointer points
to is allocated by the platform code. The pointer gets stored in the partitions
database in SPM, and it is provided to the SPM HAL functions.
#### Peripherals currently used by the services in TF-M
- `TFM_PERIPHERAL_FPGA_IO` FPGA system control and I/O
- `TFM_PERIPHERAL_UART1` UART1
`NOTE` If a platform doesn't support a peripheral, that is used by a service,
then the service cannot be used on the given platform. Using a peripheral in
TF-M that is not supported by the platform results in compile error.
### platform/include/tfm_spm_hal.h
This file contains the declarations of functions that a platform implementation
has to provide for TF-M. For details see the comments in the file.
### secure_fw/core/tfm_platform_core_api.h
This file contains declarations of functions that can be or have to be called
from platform implementations. For details see the comments in the file.
## Sub-folders
### include
This folder contains the interfaces that TF-M expects every target to provide.
The code in this folder is created as a part of the TF-M project
therefore it adheres to the BSD 3.0 license.
### ext
This folder contains code that has been imported from other projects so it may
have licenses other than the BSD 3.0 used by the TF-M project.
Please see the [readme file the ext folder](ext/readme.md) for details.
--------------
*Copyright (c) 2017-2018, Arm Limited. All rights reserved.*

64
platform/readme.rst Normal file
View File

@ -0,0 +1,64 @@
###############################
Details for the platform folder
###############################
.. Warning::
This folder and subfolders, especially the target folder, are likely to be
refactored and updated to improve the overall structure of dependencies.
**************************
Interfacing with TF-M core
**************************
platformext/target/tfm_peripherals_def.h
========================================
This file should enumerate the hardware peripherals that are available for TF-M
on the platform. The name of the peripheral used by a service is set in its
manifest file. The platform have to provide a macro for each of the provided
peripherals, that is substituted to a pointer to type
``struct tfm_spm_partition_platform_data_t``. The memory that the pointer points
to is allocated by the platform code. The pointer gets stored in the partitions
database in SPM, and it is provided to the SPM HAL functions.
Peripherals currently used by the services in TF-M
--------------------------------------------------
- ``TFM_PERIPHERAL_FPGA_IO`` - FPGA system control and I/O
- ``TFM_PERIPHERAL_UART1``- UART1
.. Note::
If a platform doesn't support a peripheral, that is used by a service, then
the service cannot be used on the given platform. Using a peripheral in
TF-M that is not supported by the platform results in compile error.
platform/include/tfm_spm_hal.h
==============================
This file contains the declarations of functions that a platform implementation
has to provide for TF-M. For details see the comments in the file.
secure_fw/core/tfm_platform_core_api.h
======================================
This file contains declarations of functions that can be or have to be called
from platform implementations. For details see the comments in the file.
***********
Sub-folders
***********
include
=======
This folder contains the interfaces that TF-M expects every target to provide.
The code in this folder is created as a part of the TF-M project therefore it
adheres to the BSD 3.0 license.
ext
===
This folder contains code that has been imported from other projects so it may
have licenses other than the BSD 3.0 used by the TF-M project.
Please see the :doc:`readme file the ext folder <ext/readme>` for details.
--------------
*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*

138
readme.md
View File

@ -1,138 +0,0 @@
# Trusted Firmware M - v1.0-beta
Trusted Firmware M provides a reference implementation of secure world
software for ARMv8-M.
*Note:* The software implementation contained in this project is designed to
be a reference implementation of the Arm Platform Security Architecture (PSA).
It currently does not implement all the features of that architecture, however
we expect the code to evolve along with the specifications.
`Terms 'TFM' and 'TF-M' are commonly used in documents and code and both
refer to Trusted Firmware M.`
[Glossary](glossary.md) has the list of terms and abbreviations.
## License
The software is provided under a BSD-3-Clause [License](license.md).
Contributions to this project are accepted under the same license with developer
sign-off as described in the [Contributing Guidelines](contributing.md).
This project contains code from other projects as listed below. The code from
external projects is limited to `app` and `platform` folders.
The original license text is included in those source files.
* The `platform` folder currently contains drivers imported from external
project and the files have Apache 2.0 license.
* The `app` folder contains files imported from CMSIS_5 project
and the files have Apache 2.0 license.
* The `bl2` folder contains files imported from MCUBoot project and the files
have Apache 2.0 license.
*Note* Any code that has license other than BSD-3-Clause is kept in
specific sub folders named `ext` so that it can isolated if required.
## This Release
This release includes
* A Secure FW with support for PSA Level 1 isolation on ARMv8M.
* The Interfaces exposed by the Secure FW to NS side.
* A blocking secure fw model with NS application example.
* Secure services running within this SPE.
* Secure Storage Service
* Attestation
* Crypto Service
* TF-M Audit Log
* Platform Service
* Secure Storage Service
* Support for ARMv8-M mainline and baseline
* Testcases running baremetal and with RTX to test the functionality.
* Basic support for higher level isolation but it is `in progress with
limited testing`.
* BL2 bootloader for image authentication based on SHA256 and RSA-2048 digital
signature.
* Build system based on cmake, supporting armclang and GNU Arm.
### In progress
* Ongoing and incremental support for PSA features.
* Level 2 and 3 PSA isolation
* PSA IPC support
* Bootloader enhancements
* ...
* OS support and use case examples.
* mbed OS upstream support
* mbed cloud client examples
* ...
* Ongoing security hardening, optimization and quality improvements.
### Platforms
Current release has been tested on
* Cortex M33 based SSE-200 system -
* [FPGA image loaded on MPS2 board.](https://developer.arm.com/products/system-design/development-boards/cortex-m-prototyping-systems/mps2)
* [Fast model FVP_MPS2_AEMv8M.](https://developer.arm.com/products/system-design/fixed-virtual-platforms)
* [Musca-A test chip board.](https://developer.arm.com/products/system-design/development-boards/iot-test-chips-and-boards/musca-a-test-chip-board)
* [Musca-B1 test chip board.](https://developer.arm.com/products/system-design/development-boards/iot-test-chips-and-boards/musca-b-test-chip-board)
* Cortex M23 based IoT Kit system -
* [FPGA image loaded on MPS2 board.](https://developer.arm.com/products/system-design/development-boards/cortex-m-prototyping-systems/mps2)
## Getting Started
### Prerequisite
Trusted Firmware M provides a reference implementation of PSA specifications.
It is assumed that the reader is familiar with PSA concepts and terms.
PSA specifications are currently not available in the public domain.
The current TF-M implementation specifically targets TrustZone for ARMv8-M so a
good understanding of the v8-M architecture is also necessary.
A good place to get started with ARMv8-M is
[developer.arm.com](https://developer.arm.com/technologies/trustzone).
### Really getting started
Trusted Firmware M source code is available on
[trustedfirmware.org](https://git.trustedfirmware.org/trusted-firmware-m.git/)
To build & run TF-M
- Follow the
[SW requirements guide](docs/user_guides/tfm_sw_requirement.md)
to set up your environment
- Follow the
[Build instructions](docs/user_guides/tfm_build_instruction.md)
to compile and build the TF-M source
- Follow the
[User guide](docs/user_guides/tfm_user_guide.md)
for information on running the example
To port TF-M to a another system or OS, follow the
[OS Integration Guide](docs/user_guides/tfm_integration_guide.md)
Please also see the [glossary](glossary.md) of terms used in the project.
[Contributing Guidelines](contributing.md) contains guidance on how to
contribute to this project.
Further documents can be found in the [docs](docs) folder.
## Feedback and support
For this early access release, feedback is requested via email to
[support-trustedfirmware-m@arm.com ](support-trustedfirmware-m@arm.com).
## Version history
| Version | Date | Description |
|---------|------|-------------|
| v1.0-beta | 2019-02-15 | 1.0-beta release |
--------------
*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*

163
readme.rst Normal file
View File

@ -0,0 +1,163 @@
##############################
Trusted Firmware M - v1.0-beta
##############################
Trusted Firmware M provides a reference implementation of secure world software
for ARMv8-M.
.. Note::
The software implementation contained in this project is designed to be a
reference implementation of the Arm Platform Security Architecture (PSA).
It currently does not implement all the features of that architecture,
however we expect the code to evolve along with the specifications.
Terms ``TFM`` and ``TF-M`` are commonly used in documents and code and both
refer to ``Trusted Firmware M.`` :doc:`Glossary </glossary>` has the list
of terms and abbreviations.
#######
License
#######
The software is provided under a BSD-3-Clause :doc:`License </license>`.
Contributions to this project are accepted under the same license with developer
sign-off as described in the :doc:`Contributing Guidelines </contributing>`.
This project contains code from other projects as listed below. The code from
external projects is limited to ``app`` and ``platform`` folders.
The original license text is included in those source files.
- The ``platform`` folder currently contains drivers imported from external
project and the files have Apache 2.0 license.
- The ``app`` folder contains files imported from CMSIS_5 project and the files
have Apache 2.0 license.
- The ``bl2`` folder contains files imported from MCUBoot project and the files
have Apache 2.0 license.
.. Note::
Any code that has license other than BSD-3-Clause is kept in specific sub
folders named ``ext`` so that it can isolated if required.
############
This Release
############
This release includes:
- A Secure FW with support for PSA Level 1 isolation on ARMv8M.
- The Interfaces exposed by the Secure FW to NS side.
- A blocking secure fw model with NS application example.
- Secure services running within this SPE:
- Secure Storage Service
- Attestation
- Crypto Service
- TF-M Audit Log
- Platform Service
- Secure Storage Service
- Support for ARMv8-M mainline and baseline
- Testcases running baremetal and with RTX to test the functionality.
- Basic support for higher level isolation but it is
``in progress with limited testing``.
- BL2 bootloader for image authentication based on SHA256 and RSA-2048
digital signature.
- Build system based on cmake, supporting armclang and GNU Arm.
***********
In progress
***********
- Ongoing and incremental support for PSA features:
- Level 2 and 3 PSA isolation
- PSA IPC support
- Bootloader enhancements
- ...
- OS support and use case examples:
- mbed OS upstream support
- mbed cloud client examples
- ...
- Ongoing security hardening, optimization and quality improvements.
*********
Platforms
*********
Current release has been tested on:
- Cortex M33 based SSE-200 system:
- `FPGA image loaded on MPS2 board.
<https://developer.arm.com/products/system-design/development-boards/cortex-m-prototyping-systems/mps2>`__
- `Fast model FVP_MPS2_AEMv8M.
<https://developer.arm.com/products/system-design/fixed-virtual-platforms>`__
- `Musca-A1 test chip board.
<https://developer.arm.com/products/system-design/development-boards/iot-test-chips-and-boards/musca-a1-test-chip-board>`__
- `Musca-B1 test chip board.
<https://developer.arm.com/products/system-design/development-boards/iot-test-chips-and-boards/musca-b-test-chip-board>`__
- Cortex M23 based IoT Kit system:
- `FPGA image loaded on MPS2 board.
<https://developer.arm.com/products/system-design/development-boards/cortex-m-prototyping-systems/mps2>`__
###############
Getting Started
###############
************
Prerequisite
************
Trusted Firmware M provides a reference implementation of PSA specifications.
It is assumed that the reader is familiar with PSA concepts and terms. PSA
specifications are currently not available in the public domain.
The current TF-M implementation specifically targets TrustZone for ARMv8-M so a
good understanding of the v8-M architecture is also necessary. A good place to
get started with ARMv8-M is
`developer.arm.com <https://developer.arm.com/technologies/trustzone>`__.
**********************
Really getting started
**********************
Trusted Firmware M source code is available on `git.trustedfirmware.org
<https://git.trustedfirmware.org/trusted-firmware-m.git/>`__
To build & run TF-M:
- Follow the :doc:`SW requirements guide </docs/user_guides/tfm_sw_requirement>`
to set up your environment.
- Follow the
:doc:`Build instructions </docs/user_guides/tfm_build_instruction>` to compile
and build the TF-M source.
- Follow the :doc:`User guide </docs/user_guides/tfm_user_guide>` for information
on running the example.
To port TF-M to a another system or OS, follow the
:doc:`OS Integration Guide </docs/user_guides/tfm_integration_guide>`
Please also see the :doc:`glossary </glossary>` of terms used in the project.
:doc:`Contributing Guidelines </contributing>` contains guidance on how to
contribute to this project.
Further documents can be found in the ``docs`` folder.
####################
Feedback and support
####################
For this early access release, feedback is requested via email to
`support-trustedfirmware-m@arm.com <support-trustedfirmware-m@arm.com>`__.
###############
Version history
###############
+-------------+--------------+--------------------+
| Version | Date | Description |
+=============+==============+====================+
| v1.0-beta | 2019-02-15 | 1.0-beta release |
+-------------+--------------+--------------------+
--------------
*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*