From db9783ceb84ae0c99205bc0a8bb3214b2c3a2089 Mon Sep 17 00:00:00 2001 From: Gyorgy Szing Date: Wed, 17 Apr 2019 21:08:48 +0200 Subject: [PATCH] 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 --- cmake/Common/BuildSphinxDoc.cmake | 20 +- cmake/SphinxCopyDoc.cmake | 5 +- contributing.md | 36 -- contributing.rst | 42 ++ docs/_static/css/custom.css | 10 + docs/coding_guide.md | 66 --- docs/coding_guide.rst | 78 +++ docs/conf.py.in | 22 +- docs/dco.rst | 12 + docs/index.rst | 53 +- docs/user_guides/os_migration_guide_armv8m.md | 34 -- .../user_guides/os_migration_guide_armv8m.rst | 42 ++ .../tfm_attestation_integration_guide.md | 396 -------------- .../tfm_attestation_integration_guide.rst | 440 +++++++++++++++ .../services/tfm_audit_integration_guide.md | 116 ---- .../services/tfm_audit_integration_guide.rst | 134 +++++ .../services/tfm_crypto_integration_guide.md | 86 --- .../services/tfm_crypto_integration_guide.rst | 92 ++++ .../tfm_platform_integration_guide.md | 100 ---- .../tfm_platform_integration_guide.rst | 117 ++++ .../services/tfm_sst_integration_guide.md | 360 ------------- .../services/tfm_sst_integration_guide.rst | 377 +++++++++++++ docs/user_guides/tfm_build_instruction.md | 183 ------- docs/user_guides/tfm_build_instruction.rst | 217 ++++++++ docs/user_guides/tfm_integration_guide.md | 100 ---- docs/user_guides/tfm_integration_guide.rst | 126 +++++ ...on.md => tfm_ns_client_identification.rst} | 23 +- docs/user_guides/tfm_secure_boot.md | 365 ------------- docs/user_guides/tfm_secure_boot.rst | 398 ++++++++++++++ docs/user_guides/tfm_sw_requirement.md | 302 ----------- docs/user_guides/tfm_sw_requirement.rst | 501 ++++++++++++++++++ docs/user_guides/tfm_user_guide.md | 289 ---------- docs/user_guides/tfm_user_guide.rst | 317 +++++++++++ glossary.md | 28 - glossary.rst | 89 ++++ license.md => license.rst | 22 +- maintainers.md | 53 -- maintainers.rst | 77 +++ platform/ext/readme.md | 135 ----- platform/ext/readme.rst | 121 +++++ platform/ext/target/musca_b1/readme.md | 7 - platform/ext/target/musca_b1/readme.rst | 15 + platform/readme.md | 48 -- platform/readme.rst | 64 +++ readme.md | 138 ----- readme.rst | 163 ++++++ 46 files changed, 3516 insertions(+), 2903 deletions(-) delete mode 100644 contributing.md create mode 100644 contributing.rst create mode 100644 docs/_static/css/custom.css delete mode 100644 docs/coding_guide.md create mode 100644 docs/coding_guide.rst create mode 100644 docs/dco.rst delete mode 100644 docs/user_guides/os_migration_guide_armv8m.md create mode 100644 docs/user_guides/os_migration_guide_armv8m.rst delete mode 100644 docs/user_guides/services/tfm_attestation_integration_guide.md create mode 100644 docs/user_guides/services/tfm_attestation_integration_guide.rst delete mode 100644 docs/user_guides/services/tfm_audit_integration_guide.md create mode 100644 docs/user_guides/services/tfm_audit_integration_guide.rst delete mode 100644 docs/user_guides/services/tfm_crypto_integration_guide.md create mode 100644 docs/user_guides/services/tfm_crypto_integration_guide.rst delete mode 100644 docs/user_guides/services/tfm_platform_integration_guide.md create mode 100644 docs/user_guides/services/tfm_platform_integration_guide.rst delete mode 100644 docs/user_guides/services/tfm_sst_integration_guide.md create mode 100644 docs/user_guides/services/tfm_sst_integration_guide.rst delete mode 100644 docs/user_guides/tfm_build_instruction.md create mode 100644 docs/user_guides/tfm_build_instruction.rst delete mode 100644 docs/user_guides/tfm_integration_guide.md create mode 100644 docs/user_guides/tfm_integration_guide.rst rename docs/user_guides/{tfm_ns_client_identification.md => tfm_ns_client_identification.rst} (65%) delete mode 100644 docs/user_guides/tfm_secure_boot.md create mode 100644 docs/user_guides/tfm_secure_boot.rst delete mode 100644 docs/user_guides/tfm_sw_requirement.md create mode 100644 docs/user_guides/tfm_sw_requirement.rst delete mode 100644 docs/user_guides/tfm_user_guide.md create mode 100644 docs/user_guides/tfm_user_guide.rst delete mode 100644 glossary.md create mode 100644 glossary.rst rename license.md => license.rst (62%) delete mode 100644 maintainers.md create mode 100644 maintainers.rst delete mode 100644 platform/ext/readme.md create mode 100644 platform/ext/readme.rst delete mode 100644 platform/ext/target/musca_b1/readme.md create mode 100644 platform/ext/target/musca_b1/readme.rst delete mode 100644 platform/readme.md create mode 100644 platform/readme.rst delete mode 100644 readme.md create mode 100644 readme.rst diff --git a/cmake/Common/BuildSphinxDoc.cmake b/cmake/Common/BuildSphinxDoc.cmake index 7287d0588..09bd30c49 100644 --- a/cmake/Common/BuildSphinxDoc.cmake +++ b/cmake/Common/BuildSphinxDoc.cmake @@ -33,10 +33,11 @@ Include(CMakeParseArguments) # SphinxFindTools() # function(SphinxFindTools) + #Find Sphinx find_package(Sphinx) - #Find additional needed python dependencies. - find_package(PythonModules COMPONENTS m2r sphinx-rtd-theme) + #Find additional needed Sphinx dependencies. + find_package(PythonModules COMPONENTS m2r sphinx-rtd-theme sphinxcontrib.plantuml) #Find plantUML find_package(PlantUML) @@ -48,10 +49,11 @@ function(SphinxFindTools) endif() if (SPHINX_FOUND AND PLANTUML_FOUND AND PY_M2R_FOUND - AND PY_SPHINX-RTD-THEME_FOUND) + AND PY_SPHINX-RTD-THEME_FOUND AND PY_SPHINXCONTRIB.PLANTUML) #Export executable locations to global scope. set(SPHINX_EXECUTABLE "${SPHINX_EXECUTABLE}" PARENT_SCOPE) set(PLANTUML_JAR_PATH "${PLANTUML_JAR_PATH}" PARENT_SCOPE) + set(Java_JAVA_EXECUTABLE "${Java_JAVA_EXECUTABLE}" PARENT_SCOPE) set(SPHINX_NODOC False PARENT_SCOPE) else() message(WARNING "Some tools are missing for Sphinx document generation. Document generation target is not created.") @@ -73,8 +75,8 @@ if (NOT SPHINX_NODOC) set(SPHINX_TMP_DOC_DIR "${CMAKE_CURRENT_BINARY_DIR}/doc_sphinx_in") - set(SPHINXCFG_TEMPLATE_FILE "${TFM_ROOT_DIR}/docs/Conf.py.in") - set(SPHINXCFG_CONFIGURED_FILE "${SPHINXCFG_OUTPUT_PATH}/Conf.py") + set(SPHINXCFG_TEMPLATE_FILE "${TFM_ROOT_DIR}/docs/conf.py.in") + set(SPHINXCFG_CONFIGURED_FILE "${SPHINXCFG_OUTPUT_PATH}/conf.py") #Version ID of TF-M. @@ -91,10 +93,14 @@ if (NOT SPHINX_NODOC) VERBATIM ) + add_custom_target(create_sphinx_input + SOURCES "${SPHINX_TMP_DOC_DIR}" + ) + add_custom_command(OUTPUT "${SPHINXCFG_OUTPUT_PATH}/html" COMMAND "${SPHINX_EXECUTABLE}" -c "${SPHINXCFG_OUTPUT_PATH}" -b html "${SPHINX_TMP_DOC_DIR}" "${SPHINXCFG_OUTPUT_PATH}/html" WORKING_DIRECTORY "${TFM_ROOT_DIR}" - DEPENDS "${SPHINX_TMP_DOC_DIR}" + DEPENDS create_sphinx_input COMMENT "Running Sphinx to generate user guide (HTML)." VERBATIM ) @@ -120,7 +126,7 @@ if (NOT SPHINX_NODOC) add_custom_command(OUTPUT "${SPHINXCFG_OUTPUT_PATH}/latex" COMMAND "${SPHINX_EXECUTABLE}" -c "${SPHINXCFG_OUTPUT_PATH}" -b latex "${SPHINX_TMP_DOC_DIR}" "${SPHINXCFG_OUTPUT_PATH}/latex" WORKING_DIRECTORY "${TFM_ROOT_DIR}" - DEPENDS "${SPHINX_TMP_DOC_DIR}" + DEPENDS create_sphinx_input COMMENT "Running Sphinx to generate user guide (LaTeX)." VERBATIM ) diff --git a/cmake/SphinxCopyDoc.cmake b/cmake/SphinxCopyDoc.cmake index c1f7731ac..ff21c8df1 100644 --- a/cmake/SphinxCopyDoc.cmake +++ b/cmake/SphinxCopyDoc.cmake @@ -25,7 +25,7 @@ # | # #Usage: -# cmake -DDST_RIR= -DTFM_ROOT_DIR= \ +# cmake -DDST_DIR= -DTFM_ROOT_DIR= \ # -P SphinxCopyDoc.cmake #Check input parameters @@ -42,7 +42,8 @@ file(GLOB_RECURSE _COPY_FILES LIST_DIRECTORIES false RELATIVE "${TFM_ROOT_DIR}" "${TFM_ROOT_DIR}/*.md" - "${TFM_ROOT_DIR}/*.rst") + "${TFM_ROOT_DIR}/*.rst" + "${TFM_ROOT_DIR}/dco.txt") #Subtract exluded files from copy files list(REMOVE_ITEM _COPY_FILES "docs/index.rst") diff --git a/contributing.md b/contributing.md deleted file mode 100644 index ac5db30c3..000000000 --- a/contributing.md +++ /dev/null @@ -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 - Signed-off-by: Full Name - - 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.* diff --git a/contributing.rst b/contributing.rst new file mode 100644 index 000000000..691dcde15 --- /dev/null +++ b/contributing.rst @@ -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 ` 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 `, Developer + Certificate of Origin, so you must add following fields to your commit + description.:: + + Author: Full Name + Signed-off-by: Full Name + + 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.* diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css new file mode 100644 index 000000000..d975dc083 --- /dev/null +++ b/docs/_static/css/custom.css @@ -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; +} diff --git a/docs/coding_guide.md b/docs/coding_guide.md deleted file mode 100644 index 2c4f6f685..000000000 --- a/docs/coding_guide.md +++ /dev/null @@ -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.* diff --git a/docs/coding_guide.rst b/docs/coding_guide.rst new file mode 100644 index 000000000..166442a9c --- /dev/null +++ b/docs/coding_guide.rst @@ -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 `__ +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 ` 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.* diff --git a/docs/conf.py.in b/docs/conf.py.in index 1caebb23f..b32bbdbd8 100644 --- a/docs/conf.py.in +++ b/docs/conf.py.in @@ -40,16 +40,26 @@ release = '@SPHINXCFG_TFM_VERSION_FULL@' # If your documentation needs a minimal Sphinx version, state it here. # -# needs_sphinx = '1.0' +# needs_sphinx = '1.4' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ 'sphinx.ext.imgmath', - 'm2r', + 'm2r', #Support markdown files. Needed for external code. + 'sphinx.ext.autosectionlabel', #Make sphinx generate a label for each section + 'sphinxcontrib.plantuml' #Add support for PlantUML drawings ] +#Location of PlantUML +plantuml = '@Java_JAVA_EXECUTABLE@ -jar @PLANTUML_JAR_PATH@' + +#Make auso section labals generated be prefixed with file name. +autosectionlabel_prefix_document=True +#Add auso section label for level 1 headers only. +autosectionlabel_maxdepth=1 + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -89,11 +99,11 @@ html_theme = 'sphinx_rtd_theme' # documentation. # # html_theme_options = {} - +# # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +html_static_path = ['@TFM_ROOT_DIR@/docs/_static'] # Custom sidebar templates, must be a dictionary that maps document names # to template names. @@ -108,6 +118,10 @@ html_static_path = ['_static'] #Disable adding conf.py copyright notice to HTML output html_show_copyright = False +#Add custom css for HTML. Used to allow full page width rendering +def setup(app): + app.add_stylesheet('css/custom.css') + # -- Options for HTMLHelp output --------------------------------------------- # Output file base name for HTML help builder. diff --git a/docs/dco.rst b/docs/dco.rst new file mode 100644 index 000000000..7a5a4c325 --- /dev/null +++ b/docs/dco.rst @@ -0,0 +1,12 @@ + +############################### +Developer Certificate of Origin +############################### + +.. include:: /dco.txt + :literal: + + +----------- + +*Copyright (c) 2019, Arm Limited. All rights reserved.* diff --git a/docs/index.rst b/docs/index.rst index f88134a07..f9c128297 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,69 +13,70 @@ Welcome to TF-M's documentation! :maxdepth: 2 :glob: :hidden: - - contributing.md - glossary.md - maintainers.md - docs/user_guides/tfm_sw_requirement.md - docs/user_guides/tfm_build_instruction.md - docs/coding_guide.md - docs/user_guides/tfm_user_guide.md - docs/user_guides/os_migration_guide_armv8m.md - docs/user_guides/tfm_integration_guide.md - docs/user_guides/tfm_ns_client_identification.md - docs/user_guides/tfm_secure_boot.md - + + contributing + docs/dco + glossary + maintainers + docs/user_guides/tfm_sw_requirement + docs/user_guides/tfm_build_instruction + docs/coding_guide + docs/user_guides/tfm_user_guide + docs/user_guides/os_migration_guide_armv8m + docs/user_guides/tfm_integration_guide + docs/user_guides/tfm_ns_client_identification + docs/user_guides/tfm_secure_boot + .. toctree:: :maxdepth: 2 :caption: Secure services :glob: :hidden: - + docs/user_guides/services/* - + .. toctree:: :maxdepth: 2 :caption: Components :glob: :hidden: - + lib/** - + .. toctree:: :maxdepth: 2 :caption: Target platforms :glob: :hidden: - + platform/** - + .. toctree:: :caption: Design documents :maxdepth: 2 :glob: :hidden: - + docs/design_documents/* - + .. toctree:: :caption: Draft design documents :maxdepth: 2 :glob: :hidden: - + docs/design_documents/drafts/* - + .. toctree:: :caption: Rejected design documents :maxdepth: 2 :glob: :hidden: - + docs/design_documents/rejected/* -.. mdinclude:: readme.md +.. include:: readme.rst ----------- -:Copyright: Copyright (c) 2019, Arm Limited. All rights reserved. +*Copyright (c) 2019, Arm Limited. All rights reserved.* diff --git a/docs/user_guides/os_migration_guide_armv8m.md b/docs/user_guides/os_migration_guide_armv8m.md deleted file mode 100644 index 9a140941e..000000000 --- a/docs/user_guides/os_migration_guide_armv8m.md +++ /dev/null @@ -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.* diff --git a/docs/user_guides/os_migration_guide_armv8m.rst b/docs/user_guides/os_migration_guide_armv8m.rst new file mode 100644 index 000000000..752c33284 --- /dev/null +++ b/docs/user_guides/os_migration_guide_armv8m.rst @@ -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 `__ + , 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 `. +- 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.* diff --git a/docs/user_guides/services/tfm_attestation_integration_guide.md b/docs/user_guides/services/tfm_attestation_integration_guide.md deleted file mode 100644 index d6085f466..000000000 --- a/docs/user_guides/services/tfm_attestation_integration_guide.md +++ /dev/null @@ -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.* diff --git a/docs/user_guides/services/tfm_attestation_integration_guide.rst b/docs/user_guides/services/tfm_attestation_integration_guide.rst new file mode 100644 index 000000000..e4d49a2a0 --- /dev/null +++ b/docs/user_guides/services/tfm_attestation_integration_guide.rst @@ -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 `__ 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 `__ +format. The token is encoded according to the +`CBOR `__ format and signed according to +`COSE `__ 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 `__. + - ``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 `__ 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.* diff --git a/docs/user_guides/services/tfm_audit_integration_guide.md b/docs/user_guides/services/tfm_audit_integration_guide.md deleted file mode 100644 index 3bd0ba8af..000000000 --- a/docs/user_guides/services/tfm_audit_integration_guide.md +++ /dev/null @@ -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.* diff --git a/docs/user_guides/services/tfm_audit_integration_guide.rst b/docs/user_guides/services/tfm_audit_integration_guide.rst new file mode 100644 index 000000000..314128d0e --- /dev/null +++ b/docs/user_guides/services/tfm_audit_integration_guide.rst @@ -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.* diff --git a/docs/user_guides/services/tfm_crypto_integration_guide.md b/docs/user_guides/services/tfm_crypto_integration_guide.md deleted file mode 100644 index d60cd6f7a..000000000 --- a/docs/user_guides/services/tfm_crypto_integration_guide.md +++ /dev/null @@ -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=` and the - `-DCRYPTO_KEY_MAX_KEY_LENGTH=`; - - `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=`. 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.* diff --git a/docs/user_guides/services/tfm_crypto_integration_guide.rst b/docs/user_guides/services/tfm_crypto_integration_guide.rst new file mode 100644 index 000000000..82faea960 --- /dev/null +++ b/docs/user_guides/services/tfm_crypto_integration_guide.rst @@ -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=`` and the + ``-DCRYPTO_KEY_MAX_KEY_LENGTH=`` +- ``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=``. 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.* diff --git a/docs/user_guides/services/tfm_platform_integration_guide.md b/docs/user_guides/services/tfm_platform_integration_guide.md deleted file mode 100644 index ab193edf9..000000000 --- a/docs/user_guides/services/tfm_platform_integration_guide.md +++ /dev/null @@ -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//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=""` 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.* diff --git a/docs/user_guides/services/tfm_platform_integration_guide.rst b/docs/user_guides/services/tfm_platform_integration_guide.rst new file mode 100644 index 000000000..a1733a4e1 --- /dev/null +++ b/docs/user_guides/services/tfm_platform_integration_guide.rst @@ -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//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=""` 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.* diff --git a/docs/user_guides/services/tfm_sst_integration_guide.md b/docs/user_guides/services/tfm_sst_integration_guide.md deleted file mode 100644 index fc5cc0fc9..000000000 --- a/docs/user_guides/services/tfm_sst_integration_guide.md +++ /dev/null @@ -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//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//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/.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.* diff --git a/docs/user_guides/services/tfm_sst_integration_guide.rst b/docs/user_guides/services/tfm_sst_integration_guide.rst new file mode 100644 index 000000000..87cf3cea1 --- /dev/null +++ b/docs/user_guides/services/tfm_sst_integration_guide.rst @@ -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//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 ` 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//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 ` +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 ` 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/.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.* diff --git a/docs/user_guides/tfm_build_instruction.md b/docs/user_guides/tfm_build_instruction.md deleted file mode 100644 index 368557aee..000000000 --- a/docs/user_guides/tfm_build_instruction.md +++ /dev/null @@ -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 -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.cmake` files to the build system. This can be done by adding -the `` -DPROJ_CONFIG= `` 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=` 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=` 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 -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 -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 `/install/outputs` directory, -with the following directory hierarchy: -``` -/install/outputs/fvp/ -/install/outputs// -``` -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, `/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 -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 -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.* diff --git a/docs/user_guides/tfm_build_instruction.rst b/docs/user_guides/tfm_build_instruction.rst new file mode 100644 index 000000000..4c180c9c7 --- /dev/null +++ b/docs/user_guides/tfm_build_instruction.rst @@ -0,0 +1,217 @@ +###################### +TF-M build instruction +###################### +Please make sure you have all required software installed as explained in the +:doc:`software requirements `. + +********************* +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= + - Specifies the way the application is built. + + | is the absolute path to configurations file + named as ``Config.cmake``. + | i.e. On Linux: + ``-DPROJ_CONFIG=`readlink -f ../ConfigRegression.cmake``` + + * - -DTARGET_PLATFORM= + - 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= + - Specifies the compiler toolchain + The possible values are: + + - ``ARMCLANG`` + - ``GNUARM`` + * - -DCMAKE_BUILD_TYPE= + - Configures debugging support. + The possible values are: + + - ``Debug`` + - ``Release`` + - ``Relwithdebinfo`` + - ``Minsizerel`` + * - -DMBEDTLS_DEBUG= + - 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 `__ 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 + 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 + 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 + 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 + 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 + 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 +``/install/outputs`` +directory, with the following directory hierarchy: + +:: + + /install/outputs/fvp/ + /install/outputs// + +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:: + + /install/export/tfm + +Further details on how to integrate a new NS app with TF-M are available in the +:doc:`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 `. + +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 + 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 + 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.* diff --git a/docs/user_guides/tfm_integration_guide.md b/docs/user_guides/tfm_integration_guide.md deleted file mode 100644 index 4c028a465..000000000 --- a/docs/user_guides/tfm_integration_guide.md +++ /dev/null @@ -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/` 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 -`/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 `/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 -`/install` folder structure in the test specific files, i.e. -`/install/export/tfm/test/inc`. The non-secure regression tests are -precompiled and delivered as a static library which is available in -`/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 `/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.* diff --git a/docs/user_guides/tfm_integration_guide.rst b/docs/user_guides/tfm_integration_guide.rst new file mode 100644 index 000000000..41f10ed94 --- /dev/null +++ b/docs/user_guides/tfm_integration_guide.rst @@ -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 `. + +******************************************************** +How to export files for building non-secure applications +******************************************************** +Explained in the :doc:`Build instructions `. + +************************* +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 `__ + +More information about the Musca-A1 test chip board can be found in: +`Musca-A homepage `__ + +More information about the Musca-B1 test chip board can be found in: +`Musca-B1 homepage `__ + +Generic drivers and startup/scatter files +========================================= +The addition of a new platform means the creation of a new subfolder inside +``target/`` 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 `. 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 +``/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 ``/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 `. + +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 +``/install`` folder structure in the test specific files, +i.e. ``/install/export/tfm/test/inc``. The non-secure regression +tests are precompiled and delivered as a static library which is available in +``/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 +``/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 `. + +-------------- + +*Copyright (c) 2017-2019, Arm Limited. All rights reserved.* diff --git a/docs/user_guides/tfm_ns_client_identification.md b/docs/user_guides/tfm_ns_client_identification.rst similarity index 65% rename from docs/user_guides/tfm_ns_client_identification.md rename to docs/user_guides/tfm_ns_client_identification.rst index fb6590bd7..9faccfb24 100644 --- a/docs/user_guides/tfm_ns_client_identification.md +++ b/docs/user_guides/tfm_ns_client_identification.rst @@ -1,5 +1,6 @@ -# Non-Secure Identity Manager - +########################### +Non-Secure Identity Manager +########################### The ID of the current application/thread is known by TF-M, and the SST service queries the ID of the currently running client via a dedicated API. @@ -9,34 +10,34 @@ relies on the services provided by the NS OS. Tracking of context changes are possible by relying on the NS OS calling the Thread Context Management for Armv8-M TrustZone APIs, as described -[here](https://www.keil.com/pack/doc/CMSIS/Core/html/group__context__trustzone__functions.html) +`here `__ However TF-M needs an extra API, to assign a client ID to the TZ context created as a result of the -`TZ_MemoryId_t TZ_AllocModuleContext_S (TZ_ModuleId_t module)` call. +``TZ_MemoryId_t TZ_AllocModuleContext_S (TZ_ModuleId_t module)`` call. To do this, the -`enum tfm_status_e tfm_register_client_id (int32_t ns_client_id)` have to be +``enum tfm_status_e tfm_register_client_id (int32_t ns_client_id)`` have to be called from an SVC handler, with the client ID of the currently running client. In the current implementation of TF-M, an SVC call is provided for the NS clients to be called at the beginning of their main function. -```SVC(SVC_TFM_NSPM_REGISTER_CLIENT_ID);``` +``SVC(SVC_TFM_NSPM_REGISTER_CLIENT_ID);`` The SVC call handler of the above SVC maps the name of the current thread to a hardcoded client id, and sends it to the TF-M core via the earlier discussed API. -The mapping is implemented in `interface/src/tfm_nspm_svc_handler.c`. +The mapping is implemented in ``interface/src/tfm_nspm_svc_handler.c``. The system integrators **may** implement the non-secure ID mapping based on their application/threat model. -In case the NS OS doesn't use the Thread Context Management for Armv8-M TrustZone -APIs, then TF-M considers the NS SW as a single client, and assigns a client ID -to it automatically. +In case the NS OS doesn't use the Thread Context Management for Armv8-M +TrustZone APIs, then TF-M considers the NS SW as a single client, and assigns a +client ID to it automatically. -------------- -*Copyright (c) 2018, Arm Limited. All rights reserved.* +*Copyright (c) 2018-2019, Arm Limited. All rights reserved.* diff --git a/docs/user_guides/tfm_secure_boot.md b/docs/user_guides/tfm_secure_boot.md deleted file mode 100644 index 033c4e830..000000000 --- a/docs/user_guides/tfm_secure_boot.md +++ /dev/null @@ -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: -``` -/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: -``` -/install/outputs/fvp/tfm_s_ns_signed_0.bin : Image linked for slot 0 - memory partition -/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 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-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 -``` -/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=/bl2/ext/mcuboot/mcuboot.axf \ ---data cpu0=/install/outputs/fvp/tfm_s_ns_signed.bin@0x10080000 \ ---data cpu0=/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 -``` -/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=/bl2/ext/mcuboot/mcuboot.axf \ ---data cpu0=/install/outputs/fvp/tfm_s_ns_signed_0.bin@0x10080000 \ ---data cpu0=/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.* diff --git a/docs/user_guides/tfm_secure_boot.rst b/docs/user_guides/tfm_secure_boot.rst new file mode 100644 index 000000000..bef546c0f --- /dev/null +++ b/docs/user_guides/tfm_secure_boot.rst @@ -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 `__. Original source-code is available at +`GitHub `__. 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:: + + /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 `__. + +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:: + + /install/outputs/fvp/tfm_s_ns_signed_0.bin : Image linked for slot 0 + memory partition + /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 + + /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=/bl2/ext/mcuboot/mcuboot.axf \ + --data cpu0=/install/outputs/fvp/tfm_s_ns_signed.bin@0x10080000 \ + --data cpu0=/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 + + /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=/bl2/ext/mcuboot/mcuboot.axf \ + --data cpu0=/install/outputs/fvp/tfm_s_ns_signed_0.bin@0x10080000 \ + --data cpu0=/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.* diff --git a/docs/user_guides/tfm_sw_requirement.md b/docs/user_guides/tfm_sw_requirement.md deleted file mode 100644 index d47477055..000000000 --- a/docs/user_guides/tfm_sw_requirement.md +++ /dev/null @@ -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 /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=/sw/ARMCompiler6.7.1/bin:$PATH -export ARM_TOOL_VARIANT="ult" -export ARM_PRODUCT_PATH="/sw/mappings" -export ARMLMD_LICENSE_FILE="" -~~~ -To import CMake in your bash shell console: -~~~ -export PATH=/bin:$PATH -~~~ -To import GNU Arm in your bash shell console: -~~~ -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 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//sw/ARMCompiler6.7.1/bin":$PATH -export ARM_PRODUCT_PATH="C://sw/mappings" -export ARM_TOOL_VARIANT="ult" -export ARMLMD_LICENSE_FILE="" -~~~ - -**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//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=/bin:$PATH -~~~ - -To import CMake in your bash shell console: - -**CMake** - -~~~ -export PATH=/cygdrive/c//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//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//sw/java/bin -~~~ - --------------- - -*Copyright (c) 2017-2019, Arm Limited. All rights reserved.* diff --git a/docs/user_guides/tfm_sw_requirement.rst b/docs/user_guides/tfm_sw_requirement.rst new file mode 100644 index 000000000..be5165f37 --- /dev/null +++ b/docs/user_guides/tfm_sw_requirement.rst @@ -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<> #A293E2 + BackgroundColor<> #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" <> + state refman as "Reference Manual" <> + state rtd_theme as "sphinx-rtd-theme" <> + state sphnix_puml as "sphinxcontrib-plantuml" <> + state JRE as "JRE" <> : Java Runtime Environment + state gwiz as "Graphwiz dot" <> + state Sphinx as "Sphinx" <> + state m2r as "m2r" <> + state PlantUML as "PlantUML" <> + state LaTex as "LaTex" <> + state PdfLaTex as "PdfLaTex" <<<>>> + state Doxygen as "Doxygen" <> + + [*] --> 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" <> + state y as "For document generation only" <> + 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 `__. + + - Arm compiler specific environment variable may need updating based + on specific products and licenses as explained in + `product-and-toolkit-configuration `__. + + - The GNU Arm compiler can be downloaded from + `here `__. + 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 /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 `__. + +.. code-block:: bash + + export PATH=/sw/ARMCompiler6.7.1/bin:$PATH + export ARM_TOOL_VARIANT="ult" + export ARM_PRODUCT_PATH="/sw/mappings" + export ARMLMD_LICENSE_FILE="" + +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 `__. Tests done with version 2.877 + (64 bits) +- GNU make should be installed by selecting appropriate package during + cygwin + installation. +- Python3 `(native Windows + version) `__, 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 `__ (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 `__. + - 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//sw/ARMCompiler6.7.1/bin":$PATH + export ARM_PRODUCT_PATH="C://sw/mappings" + export ARM_TOOL_VARIANT="ult" + export ARMLMD_LICENSE_FILE="" + +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 `__. + +.. code-block:: bash + + export PATH="/cygdrive/c//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=/bin:$PATH + +CMake +^^^^^ + +To import CMake in your bash shell console: + +.. code-block:: bash + + export PATH=/cygdrive/c//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 `__ + - `Graphviz + 2.38 `__ + - The Java runtime is part of the DS5 installation or can be + `downloaded from here `__ + - `PlantUML `__ + +For PDF generation: + + - `MikTeX `__ + + .. 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//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) `__ + - 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 `__ + - The Java runtime is part of the DS5 installation or can be + `downloaded from here `__ + - `PlantUML `__ + +For PDF generation: + +- `MikTeX `__ + +.. 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//sw/java/bin + +-------------- + +*Copyright (c) 2017-2019, Arm Limited. All rights reserved.* diff --git a/docs/user_guides/tfm_user_guide.md b/docs/user_guides/tfm_user_guide.md deleted file mode 100644 index ec4b408ed..000000000 --- a/docs/user_guides/tfm_user_guide.md +++ /dev/null @@ -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. -``` -/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=/install/outputs/fvp/tfm_s.axf \ ---data cpu0=/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=/install/outputs/fvp/mcuboot.axf \ ---data cpu0=/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=/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 -`/MB/HBI0263/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 - `/install/outputs/AN521/` to `/SOFTWARE/` -2. Open `/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 `/MB/HBI0263C/AN521/images.txt` -5. Unmount/eject the `` 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 - `/install/outputs/AN521/` to `/SOFTWARE/` -2. Open `/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 `/MB/HBI0263C/AN521/images.txt` -5. Unmount/eject the `` 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.* diff --git a/docs/user_guides/tfm_user_guide.rst b/docs/user_guides/tfm_user_guide.rst new file mode 100644 index 000000000..c7f902633 --- /dev/null +++ b/docs/user_guides/tfm_user_guide.rst @@ -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 ` to build the binaries. +Follow :doc:`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 `__ + +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 + + /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=/install/outputs/fvp/tfm_s.axf \ + --data cpu0=/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=/install/outputs/fvp/mcuboot.axf \ + --data cpu0=/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=/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 `__ + +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 +``/MB/HBI0263/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 + ``/install/outputs/AN521/`` to + ``/SOFTWARE/`` +#. Open ``/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 ``/MB/HBI0263C/AN521/images.txt`` +#. Unmount/eject the ```` 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 + ``/install/outputs/AN521/`` to + ``/SOFTWARE/`` +#. Open ``/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 ``/MB/HBI0263C/AN521/images.txt`` +#. Unmount/eject the ```` 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 ` + 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 `. + +-------------- + +*Copyright (c) 2017-2019, Arm Limited. All rights reserved.* diff --git a/glossary.md b/glossary.md deleted file mode 100644 index dc9bb8fce..000000000 --- a/glossary.md +++ /dev/null @@ -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.* diff --git a/glossary.rst b/glossary.rst new file mode 100644 index 000000000..b50ba4a10 --- /dev/null +++ b/glossary.rst @@ -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.* diff --git a/license.md b/license.rst similarity index 62% rename from license.md rename to license.rst index f79497275..2f703d5e4 100644 --- a/license.md +++ b/license.rst @@ -1,16 +1,16 @@ -Copyright (c) 2017, Arm Limited. All rights reserved. +Copyright (c) 2017-2019, Arm Limited. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: -- Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. -- Redistributions in binary form must reproduce the above copyright notice, this - list of conditions and the following disclaimer in the documentation and/or - other materials provided with the distribution. -- Neither the name of ARM nor the names of its contributors may be used to - endorse or promote products derived from this software without specific prior - written permission. +- Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. +- Redistributions in binary form must reproduce the above copyright notice, this + list of conditions and the following disclaimer in the documentation and/or + other materials provided with the distribution. +- Neither the name of ARM nor the names of its contributors may be used to + endorse or promote products derived from this software without specific prior + written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED @@ -25,8 +25,8 @@ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. --- -*Note*: -Individual files contain the following tag instead of the full license text. +.. note:: + Individual files contain the following tag instead of the full license text. diff --git a/maintainers.md b/maintainers.md deleted file mode 100644 index 212b57316..000000000 --- a/maintainers.md +++ /dev/null @@ -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.* diff --git a/maintainers.rst b/maintainers.rst new file mode 100644 index 000000000..ec7251a0b --- /dev/null +++ b/maintainers.rst @@ -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 `. + +Maintainers +----------- + +Abhishek Pandit + :email: `abhishek.pandit@arm.com `__ + :github: `abhishek-pandit `__ + +Ashutosh Singh + :email: `ashutosh.singh@arm.com `__ + :github: `ashutoshksingh `__ + +Miklos Balint + :email: `miklos.balint@arm.com `__ + :github: `wmnt `__ + +Sub-maintainers +--------------- + +Bootloader +~~~~~~~~~~ + +Tamas Ban + :email: `Tamas.Ban@arm.com `__ + :github: `tamban01 `__ + +Secure Storage +~~~~~~~~~~~~~~ + +Marc Moreno Berengue + :email: `marc.morenoberengue@arm.com `__ + :github: `mmorenobarm `__ + +Crypto +~~~~~~ + +Antonio de Angelis + :email: `Antonio.DeAngelis@arm.com `__ + :github: `adeaarm `__ + +SPM & IPC +~~~~~~~~~ + +Ken Liu + :email: `Ken.Liu@arm.com `__ + :github: `KenLSoft `__) + +Mate Toth-Pal + :email: `Mate.Toth-Pal@arm.com `__ + :github: `matetothpal `__) + +Audit Log +~~~~~~~~~ + +Antonio de Angelis + :email: `Antonio.DeAngelis@arm.com `__ + :github: `adeaarm `__ + +Attestation +~~~~~~~~~~~ + +Tamas Ban + :email: `Tamas.Ban@arm.com `__ + :github: `tamban01 `__ + +-------------- + +*Copyright (c) 2017-2019, Arm Limited. All rights reserved.* diff --git a/platform/ext/readme.md b/platform/ext/readme.md deleted file mode 100644 index 5558e416e..000000000 --- a/platform/ext/readme.md +++ /dev/null @@ -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 .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.* diff --git a/platform/ext/readme.rst b/platform/ext/readme.rst new file mode 100644 index 000000000..2f939408b --- /dev/null +++ b/platform/ext/readme.rst @@ -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.* diff --git a/platform/ext/target/musca_b1/readme.md b/platform/ext/target/musca_b1/readme.md deleted file mode 100644 index 0894d5fb7..000000000 --- a/platform/ext/target/musca_b1/readme.md +++ /dev/null @@ -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. diff --git a/platform/ext/target/musca_b1/readme.rst b/platform/ext/target/musca_b1/readme.rst new file mode 100644 index 000000000..159af559c --- /dev/null +++ b/platform/ext/target/musca_b1/readme.rst @@ -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 `__ +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.* diff --git a/platform/readme.md b/platform/readme.md deleted file mode 100644 index 6cac5a134..000000000 --- a/platform/readme.md +++ /dev/null @@ -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//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.* diff --git a/platform/readme.rst b/platform/readme.rst new file mode 100644 index 000000000..20e5fbcda --- /dev/null +++ b/platform/readme.rst @@ -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 ` for details. + +-------------- + +*Copyright (c) 2017-2019, Arm Limited. All rights reserved.* diff --git a/readme.md b/readme.md deleted file mode 100644 index 54bb5ef2e..000000000 --- a/readme.md +++ /dev/null @@ -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.* diff --git a/readme.rst b/readme.rst new file mode 100644 index 000000000..0f4eda0af --- /dev/null +++ b/readme.rst @@ -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 ` has the list +of terms and abbreviations. + +####### +License +####### +The software is provided under a BSD-3-Clause :doc:`License `. +Contributions to this project are accepted under the same license with developer +sign-off as described in the :doc:`Contributing Guidelines `. + +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. + `__ + - `Fast model FVP_MPS2_AEMv8M. + `__ + - `Musca-A1 test chip board. + `__ + - `Musca-B1 test chip board. + `__ + + - Cortex M23 based IoT Kit system: + + - `FPGA image loaded on MPS2 board. + `__ + +############### +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 `__. + +********************** +Really getting started +********************** +Trusted Firmware M source code is available on `git.trustedfirmware.org +`__ + +To build & run TF-M: + + - Follow the :doc:`SW requirements guide ` + to set up your environment. + - Follow the + :doc:`Build instructions ` to compile + and build the TF-M source. + - Follow the :doc:`User guide ` for information + on running the example. + +To port TF-M to a another system or OS, follow the +:doc:`OS Integration Guide ` + +Please also see the :doc:`glossary ` of terms used in the project. + +:doc:`Contributing Guidelines ` 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 `__. + +############### +Version history +############### ++-------------+--------------+--------------------+ +| Version | Date | Description | ++=============+==============+====================+ +| v1.0-beta | 2019-02-15 | 1.0-beta release | ++-------------+--------------+--------------------+ + +-------------- + +*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*