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:
parent
74dae3cf92
commit
db9783ceb8
|
@ -33,10 +33,11 @@ Include(CMakeParseArguments)
|
||||||
# SphinxFindTools()
|
# SphinxFindTools()
|
||||||
#
|
#
|
||||||
function(SphinxFindTools)
|
function(SphinxFindTools)
|
||||||
|
#Find Sphinx
|
||||||
find_package(Sphinx)
|
find_package(Sphinx)
|
||||||
|
|
||||||
#Find additional needed python dependencies.
|
#Find additional needed Sphinx dependencies.
|
||||||
find_package(PythonModules COMPONENTS m2r sphinx-rtd-theme)
|
find_package(PythonModules COMPONENTS m2r sphinx-rtd-theme sphinxcontrib.plantuml)
|
||||||
|
|
||||||
#Find plantUML
|
#Find plantUML
|
||||||
find_package(PlantUML)
|
find_package(PlantUML)
|
||||||
|
@ -48,10 +49,11 @@ function(SphinxFindTools)
|
||||||
endif()
|
endif()
|
||||||
|
|
||||||
if (SPHINX_FOUND AND PLANTUML_FOUND AND PY_M2R_FOUND
|
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.
|
#Export executable locations to global scope.
|
||||||
set(SPHINX_EXECUTABLE "${SPHINX_EXECUTABLE}" PARENT_SCOPE)
|
set(SPHINX_EXECUTABLE "${SPHINX_EXECUTABLE}" PARENT_SCOPE)
|
||||||
set(PLANTUML_JAR_PATH "${PLANTUML_JAR_PATH}" 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)
|
set(SPHINX_NODOC False PARENT_SCOPE)
|
||||||
else()
|
else()
|
||||||
message(WARNING "Some tools are missing for Sphinx document generation. Document generation target is not created.")
|
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(SPHINX_TMP_DOC_DIR "${CMAKE_CURRENT_BINARY_DIR}/doc_sphinx_in")
|
||||||
|
|
||||||
set(SPHINXCFG_TEMPLATE_FILE "${TFM_ROOT_DIR}/docs/Conf.py.in")
|
set(SPHINXCFG_TEMPLATE_FILE "${TFM_ROOT_DIR}/docs/conf.py.in")
|
||||||
set(SPHINXCFG_CONFIGURED_FILE "${SPHINXCFG_OUTPUT_PATH}/Conf.py")
|
set(SPHINXCFG_CONFIGURED_FILE "${SPHINXCFG_OUTPUT_PATH}/conf.py")
|
||||||
|
|
||||||
|
|
||||||
#Version ID of TF-M.
|
#Version ID of TF-M.
|
||||||
|
@ -91,10 +93,14 @@ if (NOT SPHINX_NODOC)
|
||||||
VERBATIM
|
VERBATIM
|
||||||
)
|
)
|
||||||
|
|
||||||
|
add_custom_target(create_sphinx_input
|
||||||
|
SOURCES "${SPHINX_TMP_DOC_DIR}"
|
||||||
|
)
|
||||||
|
|
||||||
add_custom_command(OUTPUT "${SPHINXCFG_OUTPUT_PATH}/html"
|
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"
|
COMMAND "${SPHINX_EXECUTABLE}" -c "${SPHINXCFG_OUTPUT_PATH}" -b html "${SPHINX_TMP_DOC_DIR}" "${SPHINXCFG_OUTPUT_PATH}/html"
|
||||||
WORKING_DIRECTORY "${TFM_ROOT_DIR}"
|
WORKING_DIRECTORY "${TFM_ROOT_DIR}"
|
||||||
DEPENDS "${SPHINX_TMP_DOC_DIR}"
|
DEPENDS create_sphinx_input
|
||||||
COMMENT "Running Sphinx to generate user guide (HTML)."
|
COMMENT "Running Sphinx to generate user guide (HTML)."
|
||||||
VERBATIM
|
VERBATIM
|
||||||
)
|
)
|
||||||
|
@ -120,7 +126,7 @@ if (NOT SPHINX_NODOC)
|
||||||
add_custom_command(OUTPUT "${SPHINXCFG_OUTPUT_PATH}/latex"
|
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"
|
COMMAND "${SPHINX_EXECUTABLE}" -c "${SPHINXCFG_OUTPUT_PATH}" -b latex "${SPHINX_TMP_DOC_DIR}" "${SPHINXCFG_OUTPUT_PATH}/latex"
|
||||||
WORKING_DIRECTORY "${TFM_ROOT_DIR}"
|
WORKING_DIRECTORY "${TFM_ROOT_DIR}"
|
||||||
DEPENDS "${SPHINX_TMP_DOC_DIR}"
|
DEPENDS create_sphinx_input
|
||||||
COMMENT "Running Sphinx to generate user guide (LaTeX)."
|
COMMENT "Running Sphinx to generate user guide (LaTeX)."
|
||||||
VERBATIM
|
VERBATIM
|
||||||
)
|
)
|
||||||
|
|
|
@ -25,7 +25,7 @@
|
||||||
# |
|
# |
|
||||||
#
|
#
|
||||||
#Usage:
|
#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
|
# -P SphinxCopyDoc.cmake
|
||||||
|
|
||||||
#Check input parameters
|
#Check input parameters
|
||||||
|
@ -42,7 +42,8 @@ file(GLOB_RECURSE _COPY_FILES
|
||||||
LIST_DIRECTORIES false
|
LIST_DIRECTORIES false
|
||||||
RELATIVE "${TFM_ROOT_DIR}"
|
RELATIVE "${TFM_ROOT_DIR}"
|
||||||
"${TFM_ROOT_DIR}/*.md"
|
"${TFM_ROOT_DIR}/*.md"
|
||||||
"${TFM_ROOT_DIR}/*.rst")
|
"${TFM_ROOT_DIR}/*.rst"
|
||||||
|
"${TFM_ROOT_DIR}/dco.txt")
|
||||||
|
|
||||||
#Subtract exluded files from copy files
|
#Subtract exluded files from copy files
|
||||||
list(REMOVE_ITEM _COPY_FILES "docs/index.rst")
|
list(REMOVE_ITEM _COPY_FILES "docs/index.rst")
|
||||||
|
|
|
@ -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.*
|
|
|
@ -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.*
|
|
@ -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;
|
||||||
|
}
|
|
@ -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.*
|
|
|
@ -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.*
|
|
@ -40,16 +40,26 @@ release = '@SPHINXCFG_TFM_VERSION_FULL@'
|
||||||
|
|
||||||
# If your documentation needs a minimal Sphinx version, state it here.
|
# 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
|
# Add any Sphinx extension module names here, as strings. They can be
|
||||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||||
# ones.
|
# ones.
|
||||||
extensions = [
|
extensions = [
|
||||||
'sphinx.ext.imgmath',
|
'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.
|
# Add any paths that contain templates here, relative to this directory.
|
||||||
templates_path = ['_templates']
|
templates_path = ['_templates']
|
||||||
|
|
||||||
|
@ -89,11 +99,11 @@ html_theme = 'sphinx_rtd_theme'
|
||||||
# documentation.
|
# documentation.
|
||||||
#
|
#
|
||||||
# html_theme_options = {}
|
# html_theme_options = {}
|
||||||
|
#
|
||||||
# Add any paths that contain custom static files (such as style sheets) here,
|
# 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,
|
# relative to this directory. They are copied after the builtin static files,
|
||||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
# 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
|
# Custom sidebar templates, must be a dictionary that maps document names
|
||||||
# to template names.
|
# to template names.
|
||||||
|
@ -108,6 +118,10 @@ html_static_path = ['_static']
|
||||||
#Disable adding conf.py copyright notice to HTML output
|
#Disable adding conf.py copyright notice to HTML output
|
||||||
html_show_copyright = False
|
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 ---------------------------------------------
|
# -- Options for HTMLHelp output ---------------------------------------------
|
||||||
|
|
||||||
# Output file base name for HTML help builder.
|
# Output file base name for HTML help builder.
|
||||||
|
|
|
@ -0,0 +1,12 @@
|
||||||
|
|
||||||
|
###############################
|
||||||
|
Developer Certificate of Origin
|
||||||
|
###############################
|
||||||
|
|
||||||
|
.. include:: /dco.txt
|
||||||
|
:literal:
|
||||||
|
|
||||||
|
|
||||||
|
-----------
|
||||||
|
|
||||||
|
*Copyright (c) 2019, Arm Limited. All rights reserved.*
|
|
@ -13,69 +13,70 @@ Welcome to TF-M's documentation!
|
||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
:glob:
|
:glob:
|
||||||
:hidden:
|
:hidden:
|
||||||
|
|
||||||
contributing.md
|
contributing
|
||||||
glossary.md
|
docs/dco
|
||||||
maintainers.md
|
glossary
|
||||||
docs/user_guides/tfm_sw_requirement.md
|
maintainers
|
||||||
docs/user_guides/tfm_build_instruction.md
|
docs/user_guides/tfm_sw_requirement
|
||||||
docs/coding_guide.md
|
docs/user_guides/tfm_build_instruction
|
||||||
docs/user_guides/tfm_user_guide.md
|
docs/coding_guide
|
||||||
docs/user_guides/os_migration_guide_armv8m.md
|
docs/user_guides/tfm_user_guide
|
||||||
docs/user_guides/tfm_integration_guide.md
|
docs/user_guides/os_migration_guide_armv8m
|
||||||
docs/user_guides/tfm_ns_client_identification.md
|
docs/user_guides/tfm_integration_guide
|
||||||
docs/user_guides/tfm_secure_boot.md
|
docs/user_guides/tfm_ns_client_identification
|
||||||
|
docs/user_guides/tfm_secure_boot
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
:caption: Secure services
|
:caption: Secure services
|
||||||
:glob:
|
:glob:
|
||||||
:hidden:
|
:hidden:
|
||||||
|
|
||||||
docs/user_guides/services/*
|
docs/user_guides/services/*
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
:caption: Components
|
:caption: Components
|
||||||
:glob:
|
:glob:
|
||||||
:hidden:
|
:hidden:
|
||||||
|
|
||||||
lib/**
|
lib/**
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
:caption: Target platforms
|
:caption: Target platforms
|
||||||
:glob:
|
:glob:
|
||||||
:hidden:
|
:hidden:
|
||||||
|
|
||||||
platform/**
|
platform/**
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:caption: Design documents
|
:caption: Design documents
|
||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
:glob:
|
:glob:
|
||||||
:hidden:
|
:hidden:
|
||||||
|
|
||||||
docs/design_documents/*
|
docs/design_documents/*
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:caption: Draft design documents
|
:caption: Draft design documents
|
||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
:glob:
|
:glob:
|
||||||
:hidden:
|
:hidden:
|
||||||
|
|
||||||
docs/design_documents/drafts/*
|
docs/design_documents/drafts/*
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:caption: Rejected design documents
|
:caption: Rejected design documents
|
||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
:glob:
|
:glob:
|
||||||
:hidden:
|
:hidden:
|
||||||
|
|
||||||
docs/design_documents/rejected/*
|
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.*
|
||||||
|
|
|
@ -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.*
|
|
|
@ -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.*
|
|
@ -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.*
|
|
|
@ -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.*
|
|
@ -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.*
|
|
|
@ -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.*
|
|
@ -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.*
|
|
|
@ -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.*
|
|
@ -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.*
|
|
|
@ -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.*
|
|
@ -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.*
|
|
|
@ -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.*
|
|
@ -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.*
|
|
|
@ -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.*
|
|
@ -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.*
|
|
|
@ -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.*
|
|
@ -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
|
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.
|
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
|
Tracking of context changes are possible by relying on the NS OS calling the
|
||||||
Thread Context Management for Armv8-M TrustZone APIs, as described
|
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
|
However TF-M needs an extra API, to assign a client ID to the TZ context created
|
||||||
as a result of the
|
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
|
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.
|
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
|
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.
|
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
|
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
|
hardcoded client id, and sends it to the TF-M core via the earlier discussed
|
||||||
API.
|
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
|
The system integrators **may** implement the non-secure ID mapping based on
|
||||||
their application/threat model.
|
their application/threat model.
|
||||||
|
|
||||||
In case the NS OS doesn't use the Thread Context Management for Armv8-M TrustZone
|
In case the NS OS doesn't use the Thread Context Management for Armv8-M
|
||||||
APIs, then TF-M considers the NS SW as a single client, and assigns a client ID
|
TrustZone APIs, then TF-M considers the NS SW as a single client, and assigns a
|
||||||
to it automatically.
|
client ID to it automatically.
|
||||||
|
|
||||||
--------------
|
--------------
|
||||||
|
|
||||||
*Copyright (c) 2018, Arm Limited. All rights reserved.*
|
*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*
|
|
@ -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.*
|
|
|
@ -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.*
|
|
@ -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.*
|
|
|
@ -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.*
|
|
@ -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.*
|
|
|
@ -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
28
glossary.md
|
@ -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.*
|
|
|
@ -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.*
|
|
@ -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,
|
Redistribution and use in source and binary forms, with or without modification,
|
||||||
are permitted provided that the following conditions are met:
|
are permitted provided that the following conditions are met:
|
||||||
|
|
||||||
- Redistributions of source code must retain the above copyright notice, this
|
- Redistributions of source code must retain the above copyright notice, this
|
||||||
list of conditions and the following disclaimer.
|
list of conditions and the following disclaimer.
|
||||||
- Redistributions in binary form must reproduce the above copyright notice, this
|
- Redistributions in binary form must reproduce the above copyright notice, this
|
||||||
list of conditions and the following disclaimer in the documentation and/or
|
list of conditions and the following disclaimer in the documentation and/or
|
||||||
other materials provided with the distribution.
|
other materials provided with the distribution.
|
||||||
- Neither the name of ARM nor the names of its contributors may be used to
|
- 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
|
endorse or promote products derived from this software without specific prior
|
||||||
written permission.
|
written permission.
|
||||||
|
|
||||||
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
|
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
|
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*:
|
.. note::
|
||||||
Individual files contain the following tag instead of the full license text.
|
Individual files contain the following tag instead of the full license text.
|
||||||
|
|
||||||
|
|
||||||
|
|
|
@ -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.*
|
|
|
@ -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.*
|
|
@ -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.*
|
|
|
@ -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.*
|
|
@ -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.
|
|
|
@ -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.*
|
|
@ -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.*
|
|
|
@ -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
138
readme.md
|
@ -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.*
|
|
|
@ -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.*
|
Loading…
Reference in New Issue